Bodhi Realtime Agent Framework

Appearance

bodhi-realtime-agent / HooksManager

Class: HooksManager ​

Defined in: src/core/hooks.ts:7

Manages registered lifecycle hooks and exposes them as getter accessors. Zero-overhead pattern: callers check if (hooks.onX) hooks.onX(event).

Constructors ​

Constructor ​

new HooksManager(): HooksManager

Returns ​

HooksManager

Accessors ​

onAgentReentry ​

Get Signature ​

get onAgentReentry(): ((event) => void) | undefined

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

Returns ​
Function ​

(event) => void

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

undefined

onAgentTransfer ​

Get Signature ​

get onAgentTransfer(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:51

Returns ​
Function ​

(event) => void

Fires after an agent transfer completes (reconnection included).

Parameters ​
event ​
fromAgent ​

string

reconnectMs ​

number

sessionId ​

string

toAgent ​

string

Returns ​

void

undefined

onBackgroundNotification ​

Get Signature ​

get onBackgroundNotification(): ((event) => void) | undefined

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

Returns ​
Function ​

(event) => void

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

undefined

onBargeInDetected ​

Get Signature ​

get onBargeInDetected(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:33

Returns ​
Function ​

(event) => void

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

undefined

onError ​

Get Signature ​

get onError(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:69

Returns ​
Function ​

(event) => void

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

undefined

onJumpIn ​

Get Signature ​

get onJumpIn(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:39

Returns ​
Function ​

(event) => void

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

undefined

onMemoryExtraction ​

Get Signature ​

get onMemoryExtraction(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:60

Returns ​
Function ​

(event) => void

Fires after the memory distiller extracts facts from conversation.

Parameters ​
event ​
durationMs ​

number

factsExtracted ​

number

userId ​

string

Returns ​

void

undefined

onRealtimeLLMUsage ​

Get Signature ​

get onRealtimeLLMUsage(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:57

Returns ​
Function ​

(event) => void

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

Parameters ​
event ​
agentName ​

string

sessionId ​

string

usage ​

RealtimeLLMUsageEvent

Returns ​

void

undefined

onSessionEnd ​

Get Signature ​

get onSessionEnd(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:18

Returns ​
Function ​

(event) => void

Fires when the session transitions to CLOSED.

Parameters ​
event ​
durationMs ​

number

reason ​

string

sessionId ​

string

Returns ​

void

undefined

onSessionStart ​

Get Signature ​

get onSessionStart(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:15

Returns ​
Function ​

(event) => void

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

Parameters ​
event ​
agentName ​

string

sessionId ​

string

userId ​

string

Returns ​

void

undefined

onSubagentStep ​

Get Signature ​

get onSubagentStep(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:54

Returns ​
Function ​

(event) => void

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

Parameters ​
event ​
stepNumber ​

number

subagentName ​

string

tokensUsed ​

number

toolCalls ​

string[]

Returns ​

void

undefined

onToolCall ​

Get Signature ​

get onToolCall(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:45

Returns ​
Function ​

(event) => void

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

Parameters ​
event ​
agentName ​

string

execution ​

ToolExecution

sessionId ​

string

toolCallId ​

string

toolName ​

string

Returns ​

void

undefined

onToolResult ​

Get Signature ​

get onToolResult(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:48

Returns ​
Function ​

(event) => void

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

Parameters ​
event ​
durationMs ​

number

error? ​

string

status ​

"completed" | "error" | "cancelled"

toolCallId ​

string

Returns ​

void

undefined

onTranscriptReady ​

Get Signature ​

get onTranscriptReady(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:30

Returns ​
Function ​

(event) => void

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

undefined

onTTSSynthesis ​

Get Signature ​

get onTTSSynthesis(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:63

Returns ​
Function ​

(event) => void

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

undefined

onTurnFinalized ​

Get Signature ​

get onTurnFinalized(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:36

Returns ​
Function ​

(event) => void

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

undefined

onTurnLatency ​

Get Signature ​

get onTurnLatency(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:21

Returns ​
Function ​

(event) => void

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

undefined

onTurnLatencyDropped ​

Get Signature ​

get onTurnLatencyDropped(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:24

Returns ​
Function ​

(event) => void

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

undefined

onUserSpeechEnd ​

Get Signature ​

get onUserSpeechEnd(): ((event) => void) | undefined

Defined in: src/core/hooks.ts:27

Returns ​
Function ​

(event) => void

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

undefined

Methods ​

register() ​

register(hooks): void

Defined in: src/core/hooks.ts:11

Register (or overwrite) hook callbacks. Merges with any previously registered hooks.

Parameters ​

hooks ​

FrameworkHooks

Returns ​

void

Built with VitePress