@memberjunction/ai-agents 5.40.2 → 5.41.0

package/dist/realtime/realtime-narration.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Shared narration helpers for BOTH realtime topologies.
+ *
+ * Two concerns live here so they exist exactly once:
+ *
+ * 1. **DB template resolution** — {@link ResolveNarrationInstructionsTemplate} looks up the
+ *    seeded `Realtime Co-Agent - Progress Narration` prompt (with the deprecated pre-rename
+ *    fallback) in {@link AIEngine}'s cached prompts. The client-direct path threads the
+ *    template to the browser at session mint; the server-bridged path
+ *    ({@link import('./realtime-session-runner.js').RealtimeSessionRunner}) consumes it directly.
+ * 2. **Instruction building** — {@link BuildServerNarrationInstructions} substitutes the
+ *    template's placeholders (or falls back to the documented built-in first-person wording)
+ *    for the server-bridged runner's spoken progress updates. The Angular voice session has
+ *    its own richer builder (it also chains the model's PRIOR spoken narrations, which only
+ *    the browser can observe); this server-side builder is deliberately compact.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+/**
+ * The seeded name of the `MJ: AI Prompts` row whose `TemplateText` carries the first-person
+ * progress-narration instructions (with a `{{ progressMessage }}` placeholder).
+ */
+export declare const NARRATION_PROMPT_NAME = "Realtime Co-Agent - Progress Narration";
+/**
+ * DEPRECATED legacy name of {@link NARRATION_PROMPT_NAME}, from before the co-agent's rename
+ * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the prompt
+ * seed still carry this name, so {@link ResolveNarrationInstructionsTemplate} falls back to it
+ * (with a deprecation log).
+ */
+export declare const LEGACY_NARRATION_PROMPT_NAME = "Voice Co-Agent - Progress Narration";
+/**
+ * Resolves the DB-driven progress-narration instruction template: the Active `MJ: AI Prompts`
+ * row named {@link NARRATION_PROMPT_NAME}, read from {@link AIEngine}'s cached prompts. When
+ * the current name is absent, falls back to the DEPRECATED {@link LEGACY_NARRATION_PROMPT_NAME}
+ * (pre-rename seed) with a deprecation log. **Tolerant**: returns `null` (never throws) when
+ * neither prompt is present, the text is empty, or the engine cache is unavailable — consumers
+ * fall back to the built-in narration instruction wording.
+ *
+ * @returns The template text (containing a `{{ progressMessage }}` placeholder), or `null`.
+ */
+export declare function ResolveNarrationInstructionsTemplate(): string | null;
+/**
+ * The documented BUILT-IN fallback wording for a server-bridged spoken progress update —
+ * strictly first person (the co-agent owns the work), one short sentence, no repetition.
+ * Used when no DB template resolved for the deployment.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function DefaultServerNarrationInstructions(digest: string, updateNumber: number): string;
+/**
+ * Builds the spoken-update instructions for the server-bridged runner from the DB template
+ * (substituting `{{ progressMessage }}` / `{{ updateNumber }}`, space and no-space variants),
+ * falling back to {@link DefaultServerNarrationInstructions} when the template is absent or
+ * blank. The `{{ priorNarrations }}` placeholder is substituted with a neutral note — the
+ * server-bridged path cannot observe what the model actually SAID (those transcripts ride the
+ * provider socket), unlike the browser host which chains them.
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function BuildServerNarrationInstructions(template: string | null | undefined, digest: string, updateNumber: number): string;
+//# sourceMappingURL=realtime-narration.d.ts.map

package/dist/realtime/realtime-narration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-narration.d.ts","sourceRoot":"","sources":["../../src/realtime/realtime-narration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,2CAA2C,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAOlF;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,IAAI,MAAM,GAAG,IAAI,CAmBpE;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAU/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACrB,MAAM,CAcR"}

package/dist/realtime/realtime-narration.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Shared narration helpers for BOTH realtime topologies.
+ *
+ * Two concerns live here so they exist exactly once:
+ *
+ * 1. **DB template resolution** — {@link ResolveNarrationInstructionsTemplate} looks up the
+ *    seeded `Realtime Co-Agent - Progress Narration` prompt (with the deprecated pre-rename
+ *    fallback) in {@link AIEngine}'s cached prompts. The client-direct path threads the
+ *    template to the browser at session mint; the server-bridged path
+ *    ({@link import('./realtime-session-runner.js').RealtimeSessionRunner}) consumes it directly.
+ * 2. **Instruction building** — {@link BuildServerNarrationInstructions} substitutes the
+ *    template's placeholders (or falls back to the documented built-in first-person wording)
+ *    for the server-bridged runner's spoken progress updates. The Angular voice session has
+ *    its own richer builder (it also chains the model's PRIOR spoken narrations, which only
+ *    the browser can observe); this server-side builder is deliberately compact.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { LogStatus } from '@memberjunction/core';
+import { AIEngine } from '@memberjunction/aiengine';
+/**
+ * The seeded name of the `MJ: AI Prompts` row whose `TemplateText` carries the first-person
+ * progress-narration instructions (with a `{{ progressMessage }}` placeholder).
+ */
+export const NARRATION_PROMPT_NAME = 'Realtime Co-Agent - Progress Narration';
+/**
+ * DEPRECATED legacy name of {@link NARRATION_PROMPT_NAME}, from before the co-agent's rename
+ * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the prompt
+ * seed still carry this name, so {@link ResolveNarrationInstructionsTemplate} falls back to it
+ * (with a deprecation log).
+ */
+export const LEGACY_NARRATION_PROMPT_NAME = 'Voice Co-Agent - Progress Narration';
+/** Placeholder token variants substituted by {@link BuildServerNarrationInstructions}. */
+const PROGRESS_TOKENS = ['{{ progressMessage }}', '{{progressMessage}}'];
+const PRIOR_TOKENS = ['{{ priorNarrations }}', '{{priorNarrations}}'];
+const NUMBER_TOKENS = ['{{ updateNumber }}', '{{updateNumber}}'];
+/**
+ * Resolves the DB-driven progress-narration instruction template: the Active `MJ: AI Prompts`
+ * row named {@link NARRATION_PROMPT_NAME}, read from {@link AIEngine}'s cached prompts. When
+ * the current name is absent, falls back to the DEPRECATED {@link LEGACY_NARRATION_PROMPT_NAME}
+ * (pre-rename seed) with a deprecation log. **Tolerant**: returns `null` (never throws) when
+ * neither prompt is present, the text is empty, or the engine cache is unavailable — consumers
+ * fall back to the built-in narration instruction wording.
+ *
+ * @returns The template text (containing a `{{ progressMessage }}` placeholder), or `null`.
+ */
+export function ResolveNarrationInstructionsTemplate() {
+    try {
+        const current = findActiveNarrationPromptText(NARRATION_PROMPT_NAME);
+        if (current) {
+            return current;
+        }
+        const legacy = findActiveNarrationPromptText(LEGACY_NARRATION_PROMPT_NAME);
+        if (legacy) {
+            LogStatus(`Realtime narration: resolved the narration prompt via its DEPRECATED legacy name ` +
+                `'${LEGACY_NARRATION_PROMPT_NAME}'. Re-sync the prompt seed metadata to rename it to ` +
+                `'${NARRATION_PROMPT_NAME}'.`);
+            return legacy;
+        }
+        return null;
+    }
+    catch {
+        return null; // engine cache unavailable — tolerated, consumers fall back
+    }
+}
+/**
+ * Finds the Active `MJ: AI Prompts` row with the given name (case/whitespace-insensitive) in
+ * {@link AIEngine}'s cached prompts and returns its non-empty `TemplateText`, or `null`.
+ */
+function findActiveNarrationPromptText(promptName) {
+    const wanted = promptName.toLowerCase();
+    const prompt = (AIEngine.Instance.Prompts ?? []).find(p => p.Name?.trim().toLowerCase() === wanted && p.Status === 'Active');
+    const text = prompt?.TemplateText;
+    return text && text.trim().length > 0 ? text : null;
+}
+/** Replaces every occurrence of each token variant with the value. */
+function replaceTokens(text, tokens, value) {
+    let out = text;
+    for (const t of tokens) {
+        out = out.split(t).join(value);
+    }
+    return out;
+}
+/**
+ * The documented BUILT-IN fallback wording for a server-bridged spoken progress update —
+ * strictly first person (the co-agent owns the work), one short sentence, no repetition.
+ * Used when no DB template resolved for the deployment.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export function DefaultServerNarrationInstructions(digest, updateNumber) {
+    return (`Live progress on the work YOU are doing for the user (oldest first): ${digest}. ` +
+        `This is spoken update #${updateNumber} for this task. ` +
+        `Say ONE short, natural sentence in the FIRST PERSON continuing the story of what you are doing ` +
+        `("I'm pulling that up now", "Got the first part — grabbing the rest"). VARY the phrasing across ` +
+        `updates and never repeat information you've already conveyed — only add what's new. Strictly first ` +
+        `person: the words "it" and the agent's name must not be the subject of your sentence, and never say ` +
+        `generic filler like "it's still running in the background".`);
+}
+/**
+ * Builds the spoken-update instructions for the server-bridged runner from the DB template
+ * (substituting `{{ progressMessage }}` / `{{ updateNumber }}`, space and no-space variants),
+ * falling back to {@link DefaultServerNarrationInstructions} when the template is absent or
+ * blank. The `{{ priorNarrations }}` placeholder is substituted with a neutral note — the
+ * server-bridged path cannot observe what the model actually SAID (those transcripts ride the
+ * provider socket), unlike the browser host which chains them.
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export function BuildServerNarrationInstructions(template, digest, updateNumber) {
+    if (!template || template.trim().length === 0) {
+        return DefaultServerNarrationInstructions(digest, updateNumber);
+    }
+    let out = replaceTokens(template, PROGRESS_TOKENS, digest);
+    out = replaceTokens(out, PRIOR_TOKENS, updateNumber <= 1
+        ? 'Nothing yet — this is your first spoken update for this task.'
+        : `You have already spoken ${updateNumber - 1} update(s) for this task — do not repeat yourself; only add what's new.`);
+    out = replaceTokens(out, NUMBER_TOKENS, String(updateNumber));
+    return out;
+}
+//# sourceMappingURL=realtime-narration.js.map

package/dist/realtime/realtime-narration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-narration.js","sourceRoot":"","sources":["../../src/realtime/realtime-narration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,wCAAwC,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,qCAAqC,CAAC;AAElF,0FAA0F;AAC1F,MAAM,eAAe,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AACzE,MAAM,YAAY,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AACtE,MAAM,aAAa,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,UAAU,oCAAoC;IAChD,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,6BAA6B,CAAC,qBAAqB,CAAC,CAAC;QACrE,IAAI,OAAO,EAAE,CAAC;YACV,OAAO,OAAO,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,6BAA6B,CAAC,4BAA4B,CAAC,CAAC;QAC3E,IAAI,MAAM,EAAE,CAAC;YACT,SAAS,CACL,mFAAmF;gBAC/E,IAAI,4BAA4B,sDAAsD;gBACtF,IAAI,qBAAqB,IAAI,CACpC,CAAC;YACF,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC,CAAC,4DAA4D;IAC7E,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAS,6BAA6B,CAAC,UAAkB;IACrD,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CACjD,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CACxE,CAAC;IACF,MAAM,IAAI,GAAG,MAAM,EAAE,YAAY,CAAC;IAClC,OAAO,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AAED,sEAAsE;AACtE,SAAS,aAAa,CAAC,IAAY,EAAE,MAAgB,EAAE,KAAa;IAChE,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACrB,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC,CAAC,MAAc,EAAE,YAAoB;IACnF,OAAO,CACH,wEAAwE,MAAM,IAAI;QAClF,0BAA0B,YAAY,kBAAkB;QACxD,iGAAiG;QACjG,kGAAkG;QAClG,qGAAqG;QACrG,sGAAsG;QACtG,6DAA6D,CAChE,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gCAAgC,CAC5C,QAAmC,EACnC,MAAc,EACd,YAAoB;IAEpB,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,OAAO,kCAAkC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;IAC3D,GAAG,GAAG,aAAa,CACf,GAAG,EACH,YAAY,EACZ,YAAY,IAAI,CAAC;QACb,CAAC,CAAC,+DAA+D;QACjE,CAAC,CAAC,2BAA2B,YAAY,GAAG,CAAC,yEAAyE,CAC7H,CAAC;IACF,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/realtime/realtime-session-runner.d.ts

@@ -0,0 +1,383 @@
+/**
+ * @fileoverview Dependency-injected orchestrator that drives a `BaseRealtimeModel` session for
+ * the {@link RealtimeAgentType} (Realtime Co-Agent).
+ *
+ * The {@link RealtimeSessionRunner} owns the lifecycle of a single full-duplex
+ * {@link IRealtimeSession}: it opens the session, registers a **stable, target-independent** tool
+ * set (always including `invoke-target-agent`), wires the provider event handlers, routes tool
+ * calls (invoke-target → delegate to the target agent; others → an injected tool executor),
+ * persists each transcript turn as a conversation detail, accumulates usage and checkpoints it on
+ * a debounced cadence, and aborts any in-flight delegated run on barge-in.
+ *
+ * **Why dependency injection.** Every collaborator that would otherwise pull in `BaseAgent`,
+ * metadata, or the database is injected via {@link RealtimeSessionRunnerDeps}. That keeps the
+ * runner fully unit-testable against a mock realtime model and mock collaborators (this is the
+ * P2b-i deliverable). In P2b-ii, `BaseAgent` supplies the real implementations (model resolution
+ * from agent metadata, the `ExecuteSubAgent`-backed delegate, `ConversationDetail` persistence,
+ * and the `AIPromptRun` usage checkpoint).
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { BaseRealtimeModel, RealtimeSessionParams, RealtimeTranscript, RealtimeToolCall, RealtimeUsage, RealtimeToolDefinition } from '@memberjunction/ai';
+import { INVOKE_TARGET_AGENT_TOOL_NAME, DelegateToTargetRequest, DelegatedResult, ToolExecutionResult, RealtimeStatusLogger, RealtimeErrorLogger } from './realtime-tool-broker.js';
+export { INVOKE_TARGET_AGENT_TOOL_NAME, DelegateToTargetRequest, DelegatedResult, ToolExecutionResult, RealtimeStatusLogger, RealtimeErrorLogger };
+/**
+ * The injected collaborators that drive a realtime session.
+ *
+ * Each member is a seam that decouples the runner from `BaseAgent`/metadata/DB so it can be
+ * exercised with mocks. `BaseAgent` supplies the production implementations in P2b-ii.
+ */
+export interface RealtimeSessionRunnerDeps {
+    /**
+     * The resolved realtime model whose {@link 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.
+     */
+    Model: BaseRealtimeModel;
+    /**
+     * 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 {@link RealtimeSessionParams.Tools} with
+     * the `invoke-target-agent` tool.
+     */
+    SessionParams: RealtimeSessionParams;
+    /**
+     * 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
+     * {@link INVOKE_TARGET_AGENT_TOOL_NAME}). Optional.
+     */
+    ExtraTools?: RealtimeToolDefinition[];
+    /**
+     * Server-executed tool definitions contributed by the session's **server-side interactive
+     * channels** (`BaseRealtimeChannelServer.GetServerToolDefinitions`, aggregated by
+     * `RealtimeChannelServerHost.GetSessionServerTools`). Registered alongside
+     * {@link RealtimeSessionRunnerDeps.ExtraTools} and the stable target tool; when the model invokes
+     * one, the runner routes it to {@link RealtimeSessionRunnerDeps.ExecuteServerChannelTool} BEFORE
+     * the generic {@link 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.
+     */
+    ServerChannelTools?: RealtimeToolDefinition[];
+    /**
+     * Executes ONE server-channel tool call (a tool whose name was contributed via
+     * {@link 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 {@link RealtimeSessionRunnerDeps.ExecuteTool}.
+     */
+    ExecuteServerChannelTool?: (call: RealtimeToolCall) => Promise<ToolExecutionResult>;
+    /**
+     * 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
+     * {@link DelegateToTargetRequest.AbortSignal}; barge-in aborts it. In production this is
+     * backed by `BaseAgent.ExecuteSubAgent` (top-level target only — sub-agents are not exposed).
+     */
+    DelegateToTarget: (request: DelegateToTargetRequest) => Promise<DelegatedResult>;
+    /**
+     * 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.
+     */
+    ExecuteTool: (call: RealtimeToolCall) => Promise<ToolExecutionResult>;
+    /**
+     * Persists a transcript turn as a `ConversationDetail` stamped with the session ID. In
+     * production this writes the durable transcript; in tests, a spy.
+     */
+    PersistTranscript: (transcript: RealtimeTranscript) => Promise<void>;
+    /**
+     * 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.
+     */
+    CheckpointUsage: (usage: RealtimeUsage) => Promise<void>;
+    /** Optional debounce window (ms) for usage checkpoints. Defaults to 5000ms. */
+    UsageCheckpointDebounceMs?: number;
+    /**
+     * 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`.
+     */
+    NarrationInstructionsTemplate?: string | null;
+    /**
+     * 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.
+     */
+    NarrationPaceMs?: number | null;
+    /** Optional verbose-aware status logger. */
+    LogStatus?: RealtimeStatusLogger;
+    /** Optional error logger. */
+    LogError?: RealtimeErrorLogger;
+}
+/**
+ * The outcome of a completed realtime session run.
+ */
+export interface RealtimeSessionResult {
+    /** Whether the session ran to a clean close. */
+    Success: boolean;
+    /** The final accumulated usage that was checkpointed at close. */
+    FinalUsage: RealtimeUsage;
+    /** Total transcript turns persisted during the session. */
+    TranscriptTurnCount: number;
+    /** An error message if the session failed to start or finalize. */
+    ErrorMessage?: string;
+}
+/**
+ * Orchestrates a single `BaseRealtimeModel` duplex session for the Realtime agent type.
+ *
+ * Construct with a fully-populated {@link RealtimeSessionRunnerDeps}, then call {@link Run} to
+ * drive the session to completion, or {@link Start}/{@link Stop} to control it explicitly.
+ */
+export declare class RealtimeSessionRunner {
+    /** First spoken update fires no earlier than this long after a delegation burst starts. */
+    private static readonly FirstNarrationDelayMs;
+    /** Minimum gap between SUBSEQUENT spoken updates (floods aggregate into one digest). */
+    private static readonly NarrationIntervalMs;
+    /** Max progress messages aggregated into one spoken digest. */
+    private static readonly MaxDigestMessages;
+    /**
+     * Progress steps worth narrating — mirrors the client-direct resolver's filter so both
+     * topologies narrate the same signal and drop the same initialization/finalization noise.
+     */
+    private static readonly SignificantProgressSteps;
+    private deps;
+    private session;
+    /** Accumulated usage across all `OnUsage` deltas, flushed to the checkpoint on debounce/close. */
+    private accumulatedUsage;
+    /** Whether there is accumulated usage that has not yet been checkpointed. */
+    private usageDirty;
+    /** Pending debounce timer handle for usage checkpoints. */
+    private usageDebounceTimer;
+    /** Count of delegations currently in flight (anchors the narration burst lifecycle). */
+    private activeDelegations;
+    /** Epoch ms when the current delegation burst began (first in-flight delegation). */
+    private narrationBurstStartedAt;
+    /** Epoch ms of the last spoken update; 0 = never. SESSION-global spacing floor. */
+    private lastNarrationAt;
+    /** Spoken updates so far in the current burst (1-based numbering for the instructions). */
+    private narrationCount;
+    /** Aggregation buffer: distinct progress messages since the last spoken update (oldest first). */
+    private pendingNarrationMessages;
+    /** Tail message of the last digest, so an identical trailing progress event isn't re-buffered. */
+    private lastNarratedTail;
+    /** Pending deferred-narration timer; cancelled when the delegation finishes / barge-in lands. */
+    private narrationTimer;
+    /**
+     * The shared, topology-agnostic tool-execution path. The runner delegates all tool-call routing,
+     * abort-controller ownership, and result/error serialization to this broker so the server-bridged
+     * path executes a tool call identically to the client-direct relay path.
+     */
+    private toolBroker;
+    /**
+     * Names of the contributed server-channel tools ({@link RealtimeSessionRunnerDeps.ServerChannelTools}),
+     * used to route a non-target tool call to the channel handler. Empty when no channels contributed.
+     */
+    private readonly serverChannelToolNames;
+    /** Count of transcript turns persisted, surfaced in the result. */
+    private transcriptTurnCount;
+    /** Whether {@link Stop} has been initiated, to make finalization idempotent. */
+    private stopped;
+    /**
+     * @param deps The injected collaborators that drive the session.
+     */
+    constructor(deps: RealtimeSessionRunnerDeps);
+    /**
+     * Routes a non-target tool call: a contributed server-channel tool goes to the channel handler
+     * ({@link RealtimeSessionRunnerDeps.ExecuteServerChannelTool}); everything else goes to the
+     * generic {@link RealtimeSessionRunnerDeps.ExecuteTool}. When a tool is a server-channel tool but
+     * no channel handler is wired, it falls through to the generic executor (defensive).
+     *
+     * @param call The non-target tool call emitted by the model.
+     * @returns The tool execution result.
+     */
+    private executeNonTargetTool;
+    /**
+     * The debounce window (ms) for usage checkpoints, defaulting to 5000ms.
+     */
+    private get debounceMs();
+    /**
+     * Builds the realtime tool set registered with the provider.
+     *
+     * Always includes the stable, target-independent {@link INVOKE_TARGET_AGENT_TOOL_NAME} tool,
+     * followed by any {@link RealtimeSessionRunnerDeps.ExtraTools} and then any contributed
+     * {@link RealtimeSessionRunnerDeps.ServerChannelTools} (the server-side interactive channels'
+     * dynamic vocabulary). This is the full set the provider sees — everything target-specific runs
+     * *inside* the delegated agent's own run and is never registered on the realtime socket.
+     *
+     * @returns The ordered tool definitions to register.
+     */
+    BuildToolSet(): RealtimeToolDefinition[];
+    /**
+     * Opens the session, registers tools, and wires all provider event handlers.
+     *
+     * Idempotent guard: throws if the session is already started. After this resolves, the session
+     * is live and streaming; call {@link Stop} (or {@link Run}, which awaits closure) to finalize.
+     *
+     * @throws If the model fails to start a session.
+     */
+    Start(): Promise<void>;
+    /**
+     * Registers the provider event handlers on the live session.
+     *
+     * @param session The active session to wire.
+     */
+    private wireHandlers;
+    /**
+     * Handles a session error per the {@link IRealtimeSession.OnError} fatality contract:
+     * - `Fatal: true` (transport/socket failure, credential expiry, unexpected close) — the
+     *   session is unusable, so the runner finalizes cleanly via {@link Stop} (final usage
+     *   flush, delegated-run abort, idempotent teardown) instead of idling on a dead socket.
+     * - `Fatal: false` — a provider-reported, recoverable error frame; logged, session
+     *   continues.
+     *
+     * @param error The error surfaced by the live session.
+     */
+    private handleSessionError;
+    /**
+     * Persists a transcript turn via the injected persistence collaborator.
+     *
+     * @param transcript The transcript event (partial or final) emitted by the model.
+     */
+    private handleTranscript;
+    /**
+     * Routes a tool call through the shared {@link RealtimeToolBroker} and feeds its serialized
+     * result back to the model.
+     *
+     * The broker performs identical routing for both topologies (`invoke-target-agent` → delegate;
+     * everything else → the tool executor), owns the per-call abort controller, and serializes the
+     * success/error result. The runner only relays the broker's `ResultJson` over the live session
+     * via {@link IRealtimeSession.SendToolResult}.
+     *
+     * @param call The tool-call request emitted by the model.
+     */
+    private handleToolCall;
+    /**
+     * Sends a serialized tool result to the live session, logging (but not rethrowing) any failure.
+     *
+     * @param callID The originating tool call's id.
+     * @param resultJson The JSON-stringified result to send.
+     * @param operation A short description of the send operation, used in error logging.
+     */
+    private dispatchToolResult;
+    /**
+     * Accumulates a usage delta and schedules a debounced checkpoint.
+     *
+     * @param usage The incremental usage update reported by the provider.
+     */
+    private handleUsage;
+    /**
+     * Schedules a single debounced usage checkpoint. Repeated calls within the window coalesce
+     * into one flush, bounding write frequency during a token-heavy turn.
+     */
+    private scheduleUsageCheckpoint;
+    /**
+     * Flushes the accumulated usage to the checkpoint collaborator if there is anything new.
+     *
+     * Sends a snapshot of the *cumulative* total (matching the plan's "finalize from the
+     * last-persisted values" contract) and clears the dirty flag.
+     */
+    private flushUsage;
+    /**
+     * Handles a provider-detected interruption (barge-in).
+     *
+     * Aborts the in-flight delegated run's controller (if any) so a stale delegated result is
+     * never narrated into a conversation that has moved on. Turn detection / VAD and stopping the
+     * model's current turn are owned by the provider; the consequence for delegated work is ours.
+     */
+    private handleInterruption;
+    /**
+     * Runs one delegated call through the injected delegate while owning the NARRATION burst
+     * around it: progress events are threaded back via {@link DelegateToTargetRequest.OnProgress},
+     * and when the delegation finishes (success, failure, or abort) any still-pending spoken
+     * update is cancelled — the final tool result is about to be voiced, so an interim "still
+     * working…" line is moot.
+     */
+    private runDelegateWithNarration;
+    /**
+     * Anchors a fresh narration burst when no other delegation is in flight. Deliberately NOT
+     * reset across bursts: {@link lastNarrationAt} (the ~8s spacing floor is SESSION-global, so
+     * sequential tool calls seconds apart can never narrate faster than the interval).
+     */
+    private beginDelegationBurst;
+    /** Closes one delegation; when none remain in flight, pending narration is cancelled. */
+    private endDelegation;
+    /**
+     * Consumes one delegated-run progress event:
+     *  - significant steps only (mirrors the client-direct resolver's filter);
+     *  - the message is ALWAYS injected as a background context note (feature-detected —
+     *    {@link IRealtimeSession.SendContextNote} is an optional capability) so the model can
+     *    draw on it whenever it next speaks;
+     *  - a THROTTLED spoken update is scheduled (feature-detected —
+     *    {@link IRealtimeSession.RequestSpokenUpdate} is optional): first at ~5s into the burst,
+     *    then every ~8s, with floods aggregated into ONE digest. Collision with an in-flight
+     *    model response is the DRIVER's obligation (queue or skip) per the
+     *    `RequestSpokenUpdate` contract, so the runner does not gate on busy state.
+     */
+    private handleDelegationProgress;
+    /** Adds a progress message to the digest buffer (deduped, capped, oldest-first). */
+    private bufferNarrationMessage;
+    /**
+     * ms until the next spoken update is allowed. Two constraints, BOTH enforced:
+     * - first update of a burst: no earlier than ~5s after the burst started;
+     * - ~8s since the last spoken update, SESSION-global.
+     */
+    private nextNarrationDelayMs;
+    /**
+     * The effective spoken-update spacing: the deps' configuration-driven
+     * {@link RealtimeSessionRunnerDeps.NarrationPaceMs} when it is a positive finite number,
+     * else the built-in {@link RealtimeSessionRunner.NarrationIntervalMs} default.
+     */
+    private narrationIntervalMs;
+    /**
+     * Speaks the aggregated progress digest — unless the work already finished (buffer cancelled)
+     * or the session is gone. Per-turn collision safety is the driver's `RequestSpokenUpdate`
+     * obligation (queue or skip), so no busy gate is needed here.
+     */
+    private fireDeferredNarration;
+    /** Cancels any deferred spoken update and drops the digest buffer. */
+    private cancelPendingNarration;
+    /**
+     * Closes the session and finalizes usage. Idempotent: a second call is a no-op.
+     *
+     * Cancels any pending debounce timer, performs a final synchronous-cadence usage flush so no
+     * partial usage is lost, closes the underlying session, and returns the run result.
+     *
+     * @returns The final {@link RealtimeSessionResult}.
+     */
+    Stop(): Promise<RealtimeSessionResult>;
+    /**
+     * Builds the run result from the current accumulated state.
+     *
+     * @param success Whether the session is considered successful.
+     * @param errorMessage Optional error message to attach.
+     * @returns The result object.
+     */
+    private buildResult;
+    /**
+     * Convenience lifecycle: starts the session and immediately finalizes it.
+     *
+     * This is primarily useful for tests and for callers that drive the session entirely through
+     * the injected handlers (which fire between {@link Start} and {@link Stop}). Most real callers
+     * will use {@link Start} then later {@link Stop} when the user hangs up or the session times
+     * out. If start fails, a failed result is returned with the error.
+     *
+     * @returns The final {@link RealtimeSessionResult}.
+     */
+    Run(): Promise<RealtimeSessionResult>;
+    /**
+     * Logs an error via the injected logger (if any), prefixed with the failing operation.
+     *
+     * @param error The thrown error or message.
+     * @param operation A short description of what was being attempted.
+     */
+    private logError;
+}
+//# sourceMappingURL=realtime-session-runner.d.ts.map

package/dist/realtime/realtime-session-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-session-runner.d.ts","sourceRoot":"","sources":["../../src/realtime/realtime-session-runner.ts"],"names":[],"mappings":"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"}