Bodhi Realtime Agent Framework

Appearance

bodhi-realtime-agent / FrameworkHooks

Interface: FrameworkHooks ​

Defined in: src/types/hooks.ts:40

Optional lifecycle hooks for observability, logging, and metrics. All hooks are synchronous and fire-and-forget — exceptions are caught and logged. Register hooks via VoiceSessionConfig or HooksManager.register().

Methods ​

onAgentReentry()? ​

optional onAgentReentry(event): void

Defined in: src/types/hooks.ts:140

Fires when the agent re-enters with audio after yielding to a barge-in. reentryMs is the pause between the interrupt and the next agent audio (human baseline ≈ 200ms).

Parameters ​

event ​
reentryMs ​

number

sessionId ​

string

Returns ​

void

onAgentTransfer()? ​

optional onAgentTransfer(event): void

Defined in: src/types/hooks.ts:160

Fires after an agent transfer completes (reconnection included).

Parameters ​

event ​
fromAgent ​

string

reconnectMs ​

number

sessionId ​

string

toAgent ​

string

Returns ​

void

onBackgroundNotification()? ​

optional onBackgroundNotification(event): void

Defined in: src/types/hooks.ts:210

Fires once per background notification, after NotificationActor flushes it to its subscribers. Driven by the built-in NotificationHooksObserverActor (a default subscriber). Useful for end-to-end tracing of background tool completions, interactive subagent questions, and wall-clock / external producer events. deferredMs reports the time the notification spent in the queue (0 for immediate-deliver paths).

Actor mode only — only fires when orchestrationMode: 'actor'.

Parameters ​

event ​
correlationId? ​

string

deferredMs ​

number

deliveredAtMs ​

number

id ​

string

label ​

string

priority ​

"high" | "normal"

publishedAtMs ​

number

sessionId ​

string

Returns ​

void

onBargeInDetected()? ​

optional onBargeInDetected(event): void

Defined in: src/types/hooks.ts:107

Fires when a client-VAD barge-in is detected over assistant audio. Cancel latency is cancelRequestedAtMs - detectedAtMs (detection → actuation), NOT anything involving speech end. successful is false when the barge-in was detected but declined (below threshold / no active audio). All timestamps come from the session metric clock.

Parameters ​

event ​
audioStoppedAtMs? ​

number

cancelRequestedAtMs ​

number

detectedAtMs ​

number

latencyMs ​

number

sessionId ​

string

speechStartedAtMs ​

number

successful ​

boolean

Returns ​

void

onError()? ​

optional onError(event): void

Defined in: src/types/hooks.ts:222

Fires on any framework error. Use for centralized error logging/alerting.

Parameters ​

event ​
component ​

string

error ​

Error

sessionId? ​

string

severity ​

"error" | "warn" | "fatal"

Returns ​

void

onJumpIn()? ​

optional onJumpIn(event): void

Defined in: src/types/hooks.ts:133

Fires when the agent's audio starts while the user is still actively speaking — a "jump-in" / false turn-end (the agent took the floor prematurely). Jump-in rate = jump-ins / turns.

Parameters ​

event ​
sessionId ​

string

turnId? ​

string

Returns ​

void

onMemoryExtraction()? ​

optional onMemoryExtraction(event): void

Defined in: src/types/hooks.ts:183

Fires after the memory distiller extracts facts from conversation.

Parameters ​

event ​
durationMs ​

number

factsExtracted ​

number

userId ​

string

Returns ​

void

onRealtimeLLMUsage()? ​

optional onRealtimeLLMUsage(event): void

Defined in: src/types/hooks.ts:176

Fires when a realtime LLM transport reports provider usage (tokens or duration).

Parameters ​

event ​
agentName ​

string

sessionId ​

string

usage ​

RealtimeLLMUsageEvent

Returns ​

void

onSessionEnd()? ​

optional onSessionEnd(event): void

Defined in: src/types/hooks.ts:49

Fires when the session transitions to CLOSED.

Parameters ​

event ​
durationMs ​

number

reason ​

string

sessionId ​

string

Returns ​

void

onSessionStart()? ​

optional onSessionStart(event): void

Defined in: src/types/hooks.ts:42

Fires when the Gemini connection becomes ACTIVE for the first time.

Parameters ​

event ​
agentName ​

string

sessionId ​

string

userId ​

string

Returns ​

void

onSubagentStep()? ​

optional onSubagentStep(event): void

Defined in: src/types/hooks.ts:168

Fires after each step of a background subagent's LLM execution.

Parameters ​

event ​
stepNumber ​

number

subagentName ​

string

tokensUsed ​

number

toolCalls ​

string[]

Returns ​

void

onToolCall()? ​

optional onToolCall(event): void

Defined in: src/types/hooks.ts:143

Fires when Gemini requests a tool invocation (before execution).

Parameters ​

event ​
agentName ​

string

execution ​

ToolExecution

sessionId ​

string

toolCallId ​

string

toolName ​

string

Returns ​

void

onToolResult()? ​

optional onToolResult(event): void

Defined in: src/types/hooks.ts:152

Fires after a tool completes, is cancelled, or errors.

Parameters ​

event ​
durationMs ​

number

error? ​

string

status ​

"completed" | "error" | "cancelled"

toolCallId ​

string

Returns ​

void

onTranscriptReady()? ​

optional onTranscriptReady(event): void

Defined in: src/types/hooks.ts:93

Fires when the user transcript for a turn is finalized (STT commit). Paired with onUserSpeechEnd, the delta gives stop-to-transcript (S2T). Carries textLength only — never the transcript text (privacy, see design §6).

Parameters ​

event ​
atMs ​

number

sessionId ​

string

textLength ​

number

turnId? ​

string

Returns ​

void

onTTSSynthesis()? ​

optional onTTSSynthesis(event): void

Defined in: src/types/hooks.ts:190

Fires after each TTS synthesis request completes.

Parameters ​

event ​
audioMs ​

number

durationMs ​

number

provider ​

string

requestId ​

number

sessionId ​

string

textLength ​

number

ttfbMs ​

number

Returns ​

void

onTurnFinalized()? ​

optional onTurnFinalized(event): void

Defined in: src/types/hooks.ts:122

Fires once when any turn is finalized — clean or interrupted. Gives the agent-interruption rate (interrupted / total) and the denominator for barge-in recovery rate.

Parameters ​

event ​
interrupted ​

boolean

sessionId ​

string

turnId ​

string

Returns ​

void

onTurnLatency()? ​

optional onTurnLatency(event): void

Defined in: src/types/hooks.ts:58

Fires at the end of each turn with segment-level latency breakdown. Emitted by the TurnLatencyTracker on its drain tick — asynchronously, ≈ one macrotask after the turn finalizes.

Parameters ​

event ​
segments ​

TurnLatencySegments

sessionId ​

string

turnId ​

string

Returns ​

void

onTurnLatencyDropped()? ​

optional onTurnLatencyDropped(event): void

Defined in: src/types/hooks.ts:66

Fires when a turn produced no latency sample, with the reason — makes measurement gaps observable instead of silent (design §11).

Parameters ​

event ​
reason ​

TurnLatencyDropReason

sessionId ​

string

turnId? ​

string

Returns ​

void

onUserSpeechEnd()? ​

optional onUserSpeechEnd(event): void

Defined in: src/types/hooks.ts:81

Fires when end-of-user-speech is detected — the anchor for stop-to-first-audio (S2FA) and stop-to-transcript (S2T). Fires once per detecting source: client-vad carries the detected end edge; provider (OpenAI/Qwen speech_stopped) carries receipt time and fills the quiet-mic coverage gap. turnId is usually undefined — the turn is not born until the model responds; correlate sequentially, not by id. atMs is on the session metric clock (see VoiceSessionConfig.nowMs).

Parameters ​

event ​
atMs ​

number

sessionId ​

string

source? ​

"provider" | "client-vad"

turnId? ​

string

Returns ​

void

Built with VitePress