RPC contracts - Scenaro

Frontend tool execution uses Transport RPC (LiveKit RPC today). Method names and timeouts are defined in @scenaro/sdk/protocol.

import {
  RPC_METHODS,
  RPC_TIMEOUTS,
  resolveRpcMethodName,
} from '@scenaro/sdk/protocol';

Built-in RPC methods

Constant	Method name	Timeout
`UI_ACTIVITY_CHECK`	`scenaro__ui_activity_check`	3000ms
`COMPOSER_START_DICTATION`	`composer_start_dictation`	10000ms
`COMPOSER_END_DICTATION`	`composer_end_dictation`	15000ms
`COMPOSER_CANCEL_DICTATION`	`composer_cancel_dictation`	8000ms

Timeout constants

export const RPC_TIMEOUTS = {
  AGENT_DEFAULT_MS: 8000,
  FRONTEND_TOOL_MS: 10000,
  UI_ACTIVITY_MS: 3000,
  COMPOSER_START_MS: 10000,
  COMPOSER_END_MS: 15000,
  COMPOSER_CANCEL_MS: 8000,
} as const;

Frontend tool handlers must respond within FRONTEND_TOOL_MS (10s) or the agent receives a timeout error.

Tool method resolution

Cockpit can override the RPC method name per tool:

resolveRpcMethodName({
  name: 'search_collection_items',
  frontend_method: 'custom_search_rpc', // optional override
});
// → 'custom_search_rpc' or 'search_collection_items'

The SDK registers RPC methods dynamically from the config payload — via session tools (useScenaroSession({ tools })) or FeatureProvider / local feature runtime.

Request / response shapes

RpcToolRequest (inbound)

interface RpcToolRequest {
  requestId: string;
  tool?: string;
  args?: Record<string, unknown>;
  sentAt?: number;
}

RpcToolResponse (outbound)

interface RpcToolResponse {
  requestId?: string;
  code: 'SUCCESS' | 'ERROR' | 'TIMEOUT' | 'CANCELLED' | string;
  data?: unknown;
}

Example handler

async function searchHandler(requestId, args, settings, collections) {
  const items = await searchAPI(args.query, settings);
  return {
    requestId,
    response: { code: 'SUCCESS', data: { items: itemsForLLM } },
    componentData: { items: itemsForUI, searchQuery: args.query },
  };
}

The response.data is sent back to the agent. componentData updates the feature UI via FeatureProvider.

Agent-side RPC

The voice agent may also call built-in methods like scenaro__ui_activity_check to verify the user is interacting with feature panels. The SDK’s ui-activity-tracker responds automatically during an active session.

​Built-in RPC methods

​Timeout constants

​Tool method resolution

​Request / response shapes

​RpcToolRequest (inbound)

​RpcToolResponse (outbound)

​Example handler

​Agent-side RPC