Interface RealtimeSessionRunnerDeps

Optional abort signal (the agent layer passes the chained caller-token + agent-timeout signal). When it fires, the runner stops + finalizes the session — realtime sessions honor the same cancellation/wall-clock semantics as every other agent run instead of relying on the janitor's coarse staleness sweep. Absent ⇒ prior behavior.

Checkpoints the accumulated usage onto the single long-lived AIPromptRun. The runner accumulates OnUsage deltas and invokes this on a debounced cadence and on close, so a crash-driven janitor close finalizes from the last-persisted values and loses nothing.

Runs the target agent for an invoke-target-agent tool call. The runner creates and owns a fresh AbortController per delegated call and passes its signal in via DelegateToTargetRequest.AbortSignal; barge-in aborts it. In production this is backed by BaseAgent.ExecuteSubAgent (top-level target only — sub-agents are not exposed).

Executes ONE server-channel tool call (a tool whose name was contributed via RealtimeSessionRunnerDeps.ServerChannelTools). In production this is bound to RealtimeChannelServerHost.ExecuteSessionServerTool(sessionID, …). Must resolve with a result (never throw — the broker wraps any throw into a structured error). When omitted, a contributed server-channel tool falls through to the generic RealtimeSessionRunnerDeps.ExecuteTool.

Executes a non-target tool call (any tool other than invoke-target-agent). In production this routes to the co-agent's server/client/UI tool execution under the session's context user.

Extra realtime tools to register in addition to the always-present invoke-target-agent tool — e.g. fixed UI/control tools. These stay target-independent (see INVOKE_TARGET_AGENT_TOOL_NAME). Optional.

Finalizes the recording after the session closes: encode → store to MJStorage → stamp the AIAgentSession recording fields. Invoked once during RealtimeSessionRunner.Stop, after the underlying session is closed. Must never throw (errors are logged, not propagated — a recording failure must not fail the session). Optional (absent ⇒ recording disabled).

Drains any transcript writes still queued by PersistTranscript.

Transcript frames are dispatched FIRE-AND-FORGET (so a slow write can never stall the conversation), which means writes for the final turns of a session can still be in flight when RealtimeSessionRunner.Stop runs. Without this drain those writes land AFTER the runner has returned its result — the turn count can undercount, and a process torn down promptly after the session (serverless / container stop) can lose the tail.

Called during RealtimeSessionRunner.Stop AFTER the provider session is closed (so no new frames can arrive) and BEFORE the result is built. Bounded by TranscriptFlushTimeoutMs — a hung write must never wedge teardown. Optional: when omitted the drain is skipped entirely (existing behavior).

Optional error logger.

Optional verbose-aware status logger.

Maximum bounded RECONNECT attempts after a FATAL transport drop (socket death, credential teardown) before the runner finalizes. Each attempt opens a fresh provider session with the SAME params + tool set, re-wires handlers, and injects a context note so the model knows the line dropped. Accumulated usage/transcripts span the reconnect. Default 1; 0 disables.

The resolved realtime model whose BaseRealtimeModel.StartSession opens the duplex session. In production, resolved from the agent's MJ: AI Models metadata via the ClassFactory; in tests, a mock model.

Optional DB-driven progress-narration instruction template (the Realtime Co-Agent - Progress Narration prompt's TemplateText, containing a {{ progressMessage }} placeholder). When absent/null, the runner falls back to the built-in first-person wording (see BuildServerNarrationInstructions). BaseAgent supplies this via the shared narration lookup in realtime-narration.ts.

Optional narration pace override (ms) — the minimum gap between spoken progress updates, normally sourced from the co-agent's EFFECTIVE realtime configuration (realtime.narration.paceMs: type DefaultConfiguration ← agent TypeConfiguration ← runtime overrides). When absent or not a positive finite number, the runner's built-in default (8000 ms) applies. BaseAgent supplies this on the server-bridged path.

Persists a transcript turn as a ConversationDetail stamped with the session ID. Drives the create-on-start / update-on-complete lifecycle: returns the new detail row's ID when a turn is first created (interim delta, or final with no prior interim) and null when an existing in-flight row is merely updated. The runner uses that to count distinct turns (not events). In production this writes the durable transcript; in tests, a spy.

Optional audio recording controller for the session. When present, the runner stamps its t0 at session start, taps the model's output audio (IRealtimeSession.OnOutput) and the inbound media frames (by wrapping IRealtimeSession.SendInput), accumulating both into one mixed recording. Absent ⇒ no recording. NOTE: server-side capture applies to the server-bridged topology (where audio frames cross the server session); client-direct browser sessions capture audio in the browser.

Server-executed tool definitions contributed by the session's server-side interactive channels (BaseRealtimeChannelServer.GetServerToolDefinitions, aggregated by RealtimeChannelServerHost.GetSessionServerTools). Registered alongside RealtimeSessionRunnerDeps.ExtraTools and the stable target tool; when the model invokes one, the runner routes it to RealtimeSessionRunnerDeps.ExecuteServerChannelTool BEFORE the generic RealtimeSessionRunnerDeps.ExecuteTool, so channel tools execute server-side (a bridged bot has no browser). Optional and additive — absent on the client-direct path and on server-bridged runs without channels, leaving the existing tool set behavior untouched.

This is the deferred "channel tool contribution feeding the runner's tool set" the realtime guide flagged — now driven.

The session parameters (system prompt with companion/"voice for" framing + assembled memory/context, model API name, and optional provider config). The runner adds the stable tool set itself — callers should not pre-populate RealtimeSessionParams.Tools with the invoke-target-agent tool.

Upper bound (ms) on the FlushTranscripts drain during teardown. Defaults to 5000. On expiry the runner logs and finalizes anyway — losing a tail write is strictly better than hanging the session teardown on a stuck database call.

Optional debounce window (ms) for usage checkpoints. Defaults to 5000ms.