Events and listeners

useScenaroSession handles the Transport data channel, config handshake, and tool RPC internally. You consume events through hook callbacks, returned state, and the scoped event bus.

Session events via the hook

import { useScenaroSession } from '@scenaro/sdk/react';

const { status, agentState, messages, config, rawConfig } = useScenaroSession({
  scenario: 'publication-uuid',
  onMessage: (m) => console.log('message', m),
  onError: (e) => console.error(e.code),
  onSessionEnd: (info) => showSummary(info),
});

Field	Description
`messages`	Accumulated conversation — no separate hook needed
`config`	Curated session config after handshake
`rawConfig`	Full wire `ConfigPayload` (`restore_state`, tool wiring)
`status`	`'idle' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'ended'`
`agentState`	`'idle' \| 'listening' \| 'thinking' \| 'speaking'`

Outside React, the headless ScenaroSession class emits the same events: status-change, agent-state, message, config, session-end, error. See the ScenaroSession reference.

Event bus

ScenaroProvider creates one ScenaroEventBus per provider tree. Subscribe with useScenaroEvents():

import { useEffect } from 'react';
import { useScenaroEvents } from '@scenaro/sdk/react';

function DebugPanel() {
  const events = useScenaroEvents();

  useEffect(() => {
    const onConfig = (payload) => console.log('config', payload);
    events.on('config', onConfig);
    return () => events.off('config', onConfig);
  }, [events]);

  return null;
}

Event catalog

Event	Emitter	Payload
`config`	`SessionEventBridge`	Raw `ConfigPayload`
`message:new`	`SessionEventBridge`	`ConversationMessage`
`session:end`	`SessionEventBridge`	`{ reason: string }`
`tool:execute`	`useFeatureToolRpc`	`{ toolName, requestId, args }`
`tool:response`	`FeatureProvider`	`{ requestId, response }`
`tool:error`	`FeatureProvider`	`{ requestId, toolName, error }`
`feature:show`	`FeatureProvider`	`{ reason, toolName, requestId }`
`suggestions:show`	`FeatureProvider`	`{ suggestions }`
`conversation:reset`	Your app (manual)	— triggers `FeatureProvider.reset()`

session.on('config') delivers the curated SessionConfig. events.on('config') delivers the raw wire payload. See Tools and features.

Tool RPC flow

For session tools, declare plain functions on useScenaroSession: For feature tools via FeatureProvider, see Tools and features. RPC timeout for frontend tools: 10 seconds (RPC_TIMEOUTS.FRONTEND_TOOL_MS). The context.signal (AbortSignal) is aborted on timeout or session end.

Text input

Send user text with sendText(text) from the hook. It publishes on the lk.chat topic via the Transport data channel.

Session end detection

The SDK ends the session on:

Transport disconnected event
Agent participant leaving (2s grace period)
session:end data topic

status becomes 'ended' and onSessionEnd fires with the end payload.

Pre-0.3 migration note

useScenarioSession, AgentListener, and useConversationMessages were removed in 0.3.0. Use useScenaroSession for session lifecycle and messages for conversation UI. See the migration guide.

​Session events via the hook

​Event bus

​Event catalog

​Tool RPC flow

​Text input

​Session end detection

​Pre-0.3 migration note

Session events via the hook

Event bus

Event catalog

Tool RPC flow

Text input

Session end detection

Pre-0.3 migration note