@memberjunction/ai-agents 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/realtime/realtime-delegation-narrator.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview `DelegationNarrator` — spoken progress updates while a delegated agent run is in flight, for
+ * every SERVER-held realtime session (the generic session runner, and a bridged phone call).
+ *
+ * While the co-agent hands work to a target agent the caller would otherwise sit in silence. The narrator
+ * receives the delegated run's progress events and:
+ *
+ * - always injects each significant one as a background context note (so the model can draw on it), and
+ * - schedules a THROTTLED spoken update — first ~5 s into a burst, then no more often than every ~8 s, with
+ *   floods aggregated into one digest — built with {@link BuildServerNarrationInstructions}.
+ *
+ * It was extracted from `RealtimeSessionRunner` so a bridged call (which never constructs a runner) speaks
+ * progress identically instead of re-implementing the pacing.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import type { IRealtimeSession } from '@memberjunction/ai';
+import type { DelegatedResult, DelegateToTargetRequest } from './realtime-tool-broker.js';
+/** The collaborators a {@link DelegationNarrator} needs. */
+export interface DelegationNarratorDeps {
+    /** The live session to speak on, or `null` when there is none (a stale event is then dropped). */
+    GetSession: () => IRealtimeSession | null;
+    /** The DB-driven narration instruction template, or `null`/absent for the built-in wording. */
+    NarrationInstructionsTemplate?: string | null;
+    /** Minimum gap (ms) between spoken updates (`realtime.narration.paceMs`); absent/invalid uses the default. */
+    NarrationPaceMs?: number | null;
+}
+/** Narration state and pacing for one realtime session. One instance per session. */
+export declare class DelegationNarrator {
+    private readonly deps;
+    /** 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 defaultIntervalMs;
+    /** 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;
+    /** Count of delegations currently in flight (anchors the burst lifecycle). */
+    private activeDelegations;
+    /** Epoch ms when the current burst began (first in-flight delegation); 0 = no active burst. */
+    private burstStartedAt;
+    /** 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 pendingMessages;
+    /** Tail message of the last digest, so an identical trailing progress event is not re-buffered. */
+    private lastNarratedTail;
+    /** Pending deferred-narration timer; cancelled when the delegation finishes or the user barges in. */
+    private timer;
+    constructor(deps: DelegationNarratorDeps);
+    /**
+     * Runs one delegated call through `delegate` while owning the narration burst around it: progress events are
+     * threaded back through {@link DelegateToTargetRequest.OnProgress}, and when the delegation finishes (success,
+     * failure or abort) any still-pending spoken update is cancelled — the final result is about to be voiced.
+     */
+    Run(request: DelegateToTargetRequest, delegate: (request: DelegateToTargetRequest) => Promise<DelegatedResult>): Promise<DelegatedResult>;
+    /**
+     * Owns the narration burst around any delegated work: anchors a burst when `work` starts and cancels pending
+     * narration when it settles. Use this directly when the caller threads {@link HandleProgress} through as the
+     * delegated run's own progress callback (the bridged-call path), rather than through {@link Run}.
+     */
+    Track<T>(work: () => Promise<T>): Promise<T>;
+    /** Cancels any deferred spoken update, drops the digest buffer and resets the burst-timing state. */
+    Cancel(): void;
+    /**
+     * Consumes one delegated-run progress event: significant steps only; always a context note; and a throttled
+     * spoken update when the provider can voice one.
+     */
+    HandleProgress(progress: {
+        step: string;
+        message: string;
+    }): void;
+    /**
+     * Anchors a fresh burst when nothing else is in flight OR the burst state was reset (by {@link Cancel}) — the
+     * second condition keeps timing correct when a prior delegation failed to honour its abort and left the
+     * counter elevated. {@link lastNarrationAt} is deliberately NOT reset across bursts.
+     */
+    private beginDelegation;
+    /** Closes one delegation; when none remain in flight, pending narration is cancelled. */
+    private endDelegation;
+    /** Adds a progress message to the digest buffer (deduped, capped, oldest-first). */
+    private bufferMessage;
+    /** ms until the next spoken update is allowed: >= ~5 s after the burst began AND >= the interval since the last. */
+    private nextDelayMs;
+    /** The configured pace when it is a positive finite number, else the built-in default. */
+    private intervalMs;
+    /** Speaks the aggregated digest — unless the work already finished or the session is gone. */
+    private fireDeferredNarration;
+}
+//# sourceMappingURL=realtime-delegation-narrator.d.ts.map

package/dist/realtime/realtime-delegation-narrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-delegation-narrator.d.ts","sourceRoot":"","sources":["../../src/realtime/realtime-delegation-narrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAGvF,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACnC,kGAAkG;IAClG,UAAU,EAAE,MAAM,gBAAgB,GAAG,IAAI,CAAC;IAC1C,+FAA+F;IAC/F,6BAA6B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,8GAA8G;IAC9G,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,qFAAqF;AACrF,qBAAa,kBAAkB;IA4Bf,OAAO,CAAC,QAAQ,CAAC,IAAI;IA3BjC,2FAA2F;IAC3F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IACrD,wFAAwF;IACxF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IACjD,+DAA+D;IAC/D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAK;IAC9C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAyF;IAEzI,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB,CAAK;IAC9B,+FAA+F;IAC/F,OAAO,CAAC,cAAc,CAAK;IAC3B,mFAAmF;IACnF,OAAO,CAAC,eAAe,CAAK;IAC5B,2FAA2F;IAC3F,OAAO,CAAC,cAAc,CAAK;IAC3B,kGAAkG;IAClG,OAAO,CAAC,eAAe,CAAgB;IACvC,mGAAmG;IACnG,OAAO,CAAC,gBAAgB,CAAM;IAC9B,sGAAsG;IACtG,OAAO,CAAC,KAAK,CAA8C;gBAE9B,IAAI,EAAE,sBAAsB;IAEzD;;;;OAIG;IACU,GAAG,CAAC,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAItJ;;;;OAIG;IACU,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASzD,qGAAqG;IAC9F,MAAM,IAAI,IAAI;IAWrB;;;OAGG;IACI,cAAc,CAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAkBxE;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAUvB,yFAAyF;IACzF,OAAO,CAAC,aAAa;IAOrB,oFAAoF;IACpF,OAAO,CAAC,aAAa;IAUrB,oHAAoH;IACpH,OAAO,CAAC,WAAW;IAOnB,0FAA0F;IAC1F,OAAO,CAAC,UAAU;IAKlB,8FAA8F;IAC9F,OAAO,CAAC,qBAAqB;CAchC"}

package/dist/realtime/realtime-delegation-narrator.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview `DelegationNarrator` — spoken progress updates while a delegated agent run is in flight, for
+ * every SERVER-held realtime session (the generic session runner, and a bridged phone call).
+ *
+ * While the co-agent hands work to a target agent the caller would otherwise sit in silence. The narrator
+ * receives the delegated run's progress events and:
+ *
+ * - always injects each significant one as a background context note (so the model can draw on it), and
+ * - schedules a THROTTLED spoken update — first ~5 s into a burst, then no more often than every ~8 s, with
+ *   floods aggregated into one digest — built with {@link BuildServerNarrationInstructions}.
+ *
+ * It was extracted from `RealtimeSessionRunner` so a bridged call (which never constructs a runner) speaks
+ * progress identically instead of re-implementing the pacing.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { BuildServerNarrationInstructions } from './realtime-narration.js';
+/** Narration state and pacing for one realtime session. One instance per session. */
+export class DelegationNarrator {
+    /** First spoken update fires no earlier than this long after a delegation burst starts. */
+    static { this.firstNarrationDelayMs = 5000; }
+    /** Minimum gap between SUBSEQUENT spoken updates (floods aggregate into one digest). */
+    static { this.defaultIntervalMs = 8000; }
+    /** Max progress messages aggregated into one spoken digest. */
+    static { this.maxDigestMessages = 4; }
+    /**
+     * 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.
+     */
+    static { this.significantProgressSteps = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing']; }
+    constructor(deps) {
+        this.deps = deps;
+        /** Count of delegations currently in flight (anchors the burst lifecycle). */
+        this.activeDelegations = 0;
+        /** Epoch ms when the current burst began (first in-flight delegation); 0 = no active burst. */
+        this.burstStartedAt = 0;
+        /** Epoch ms of the last spoken update; 0 = never. SESSION-global spacing floor. */
+        this.lastNarrationAt = 0;
+        /** Spoken updates so far in the current burst (1-based numbering for the instructions). */
+        this.narrationCount = 0;
+        /** Aggregation buffer: distinct progress messages since the last spoken update (oldest first). */
+        this.pendingMessages = [];
+        /** Tail message of the last digest, so an identical trailing progress event is not re-buffered. */
+        this.lastNarratedTail = '';
+        /** Pending deferred-narration timer; cancelled when the delegation finishes or the user barges in. */
+        this.timer = null;
+    }
+    /**
+     * Runs one delegated call through `delegate` while owning the narration burst around it: progress events are
+     * threaded back through {@link DelegateToTargetRequest.OnProgress}, and when the delegation finishes (success,
+     * failure or abort) any still-pending spoken update is cancelled — the final result is about to be voiced.
+     */
+    async Run(request, delegate) {
+        return this.Track(() => delegate({ ...request, OnProgress: (progress) => this.HandleProgress(progress) }));
+    }
+    /**
+     * Owns the narration burst around any delegated work: anchors a burst when `work` starts and cancels pending
+     * narration when it settles. Use this directly when the caller threads {@link HandleProgress} through as the
+     * delegated run's own progress callback (the bridged-call path), rather than through {@link Run}.
+     */
+    async Track(work) {
+        this.beginDelegation();
+        try {
+            return await work();
+        }
+        finally {
+            this.endDelegation();
+        }
+    }
+    /** Cancels any deferred spoken update, drops the digest buffer and resets the burst-timing state. */
+    Cancel() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pendingMessages = [];
+        this.burstStartedAt = 0;
+        this.narrationCount = 0;
+        this.lastNarratedTail = '';
+    }
+    /**
+     * Consumes one delegated-run progress event: significant steps only; always a context note; and a throttled
+     * spoken update when the provider can voice one.
+     */
+    HandleProgress(progress) {
+        if (!DelegationNarrator.significantProgressSteps.includes(progress.step)) {
+            return;
+        }
+        const session = this.deps.GetSession();
+        if (!session || this.activeDelegations === 0) {
+            return; // session gone / delegation already finished — stale event
+        }
+        session.SendContextNote?.(`[delegated-agent progress] ${progress.message}`);
+        if (!session.RequestSpokenUpdate) {
+            return; // provider can't voice an instructed one-off update — context note only
+        }
+        this.bufferMessage(progress.message);
+        if (this.pendingMessages.length > 0 && !this.timer) {
+            this.timer = setTimeout(() => this.fireDeferredNarration(), this.nextDelayMs());
+        }
+    }
+    /**
+     * Anchors a fresh burst when nothing else is in flight OR the burst state was reset (by {@link Cancel}) — the
+     * second condition keeps timing correct when a prior delegation failed to honour its abort and left the
+     * counter elevated. {@link lastNarrationAt} is deliberately NOT reset across bursts.
+     */
+    beginDelegation() {
+        if (this.activeDelegations === 0 || this.burstStartedAt === 0) {
+            this.burstStartedAt = Date.now();
+            this.narrationCount = 0;
+            this.pendingMessages = [];
+            this.lastNarratedTail = '';
+        }
+        this.activeDelegations++;
+    }
+    /** Closes one delegation; when none remain in flight, pending narration is cancelled. */
+    endDelegation() {
+        this.activeDelegations = Math.max(0, this.activeDelegations - 1);
+        if (this.activeDelegations === 0) {
+            this.Cancel();
+        }
+    }
+    /** Adds a progress message to the digest buffer (deduped, capped, oldest-first). */
+    bufferMessage(message) {
+        if (message === this.lastNarratedTail || this.pendingMessages.includes(message)) {
+            return;
+        }
+        this.pendingMessages.push(message);
+        if (this.pendingMessages.length > DelegationNarrator.maxDigestMessages) {
+            this.pendingMessages.shift();
+        }
+    }
+    /** ms until the next spoken update is allowed: >= ~5 s after the burst began AND >= the interval since the last. */
+    nextDelayMs() {
+        const now = Date.now();
+        const firstAnchor = this.narrationCount === 0 ? this.burstStartedAt + DelegationNarrator.firstNarrationDelayMs : 0;
+        const spacingFloor = this.lastNarrationAt > 0 ? this.lastNarrationAt + this.intervalMs() : 0;
+        return Math.max(50, Math.max(firstAnchor, spacingFloor) - now);
+    }
+    /** The configured pace when it is a positive finite number, else the built-in default. */
+    intervalMs() {
+        const pace = this.deps.NarrationPaceMs;
+        return typeof pace === 'number' && Number.isFinite(pace) && pace > 0 ? pace : DelegationNarrator.defaultIntervalMs;
+    }
+    /** Speaks the aggregated digest — unless the work already finished or the session is gone. */
+    fireDeferredNarration() {
+        this.timer = null;
+        const session = this.deps.GetSession();
+        if (!session?.RequestSpokenUpdate || this.pendingMessages.length === 0 || this.activeDelegations === 0) {
+            this.pendingMessages = [];
+            return;
+        }
+        const digest = this.pendingMessages.join(' → ');
+        this.lastNarratedTail = this.pendingMessages[this.pendingMessages.length - 1];
+        this.pendingMessages = [];
+        this.narrationCount++;
+        this.lastNarrationAt = Date.now();
+        session.RequestSpokenUpdate(BuildServerNarrationInstructions(this.deps.NarrationInstructionsTemplate, digest, this.narrationCount));
+    }
+}
+//# sourceMappingURL=realtime-delegation-narrator.js.map

package/dist/realtime/realtime-delegation-narrator.js.map

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

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

@@ -194,17 +194,6 @@ export interface RealtimeSessionResult {
 export declare class RealtimeSessionRunner {
     /** Default upper bound (ms) on the teardown transcript drain — see `TranscriptFlushTimeoutMs`. */
     private static readonly defaultTranscriptFlushTimeoutMs;
-    /** 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. */
@@ -219,20 +208,8 @@ export declare class RealtimeSessionRunner {
     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;
+    /** Spoken progress updates while a delegated run is in flight (pacing + digest state live there). */
+    private readonly narrator;
     /**
      * 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
@@ -391,63 +368,6 @@ export declare class RealtimeSessionRunner {
      * 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, drops the digest buffer, and RESETS the burst-timing state
-     * (anchor time, spoken-update count, dedup tail). Callers invoke this exactly when the current
-     * burst is ending or being torn down (delegation done, barge-in, reconnect, Stop), so clearing the
-     * anchor to 0 marks "no active burst" — {@link beginDelegationBurst} then re-anchors the next
-     * delegation cleanly even if {@link activeDelegations} is still elevated by a stuck delegate.
-     */
-    private cancelPendingNarration;
     /**
      * Closes the session and finalizes usage. Idempotent: a second call is a no-op.
      *

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

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

package/dist/realtime/realtime-session-runner.js

@@ -21,7 +21,7 @@
  * @author MemberJunction.com
  */
 import { RealtimeToolBroker, INVOKE_TARGET_AGENT_TOOL_NAME, INVOKE_TARGET_AGENT_DESCRIPTION } from './realtime-tool-broker.js';
-import { BuildServerNarrationInstructions } from './realtime-narration.js';
+import { DelegationNarrator } from './realtime-delegation-narrator.js';
 // Re-surface the shared tool-execution contract under this module so existing consumers and tests
 // keep their import paths. The single source of truth is `realtime-tool-broker.ts`.
 export { INVOKE_TARGET_AGENT_TOOL_NAME, INVOKE_TARGET_AGENT_DESCRIPTION };
@@ -34,20 +34,6 @@ export { INVOKE_TARGET_AGENT_TOOL_NAME, INVOKE_TARGET_AGENT_DESCRIPTION };
 export class RealtimeSessionRunner {
     /** Default upper bound (ms) on the teardown transcript drain — see `TranscriptFlushTimeoutMs`. */
     static { this.defaultTranscriptFlushTimeoutMs = 5000; }
-    // ── Delegated-run progress narration (server-bridged B3) ──────────────────
-    /** First spoken update fires no earlier than this long after a delegation burst starts. */
-    static { this.firstNarrationDelayMs = 5000; }
-    /** Minimum gap between SUBSEQUENT spoken updates (floods aggregate into one digest). */
-    static { this.NarrationIntervalMs = 8000; } // case-violation-ok-legacy-back-compat: the camelCase name is already declared in this class
-    /** Max progress messages aggregated into one spoken digest. */
-    static { this.maxDigestMessages = 4; }
-    /**
-     * 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.
-     */
-    static { this.significantProgressSteps = [
-        'prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'
-    ]; }
     /**
      * @param deps The injected collaborators that drive the session.
      */
@@ -65,30 +51,21 @@ export class RealtimeSessionRunner {
         this.usageDirty = false;
         /** Pending debounce timer handle for usage checkpoints. */
         this.usageDebounceTimer = null;
-        /** Count of delegations currently in flight (anchors the narration burst lifecycle). */
-        this.activeDelegations = 0;
-        /** Epoch ms when the current delegation burst began (first in-flight delegation). */
-        this.narrationBurstStartedAt = 0;
-        /** Epoch ms of the last spoken update; 0 = never. SESSION-global spacing floor. */
-        this.lastNarrationAt = 0;
-        /** Spoken updates so far in the current burst (1-based numbering for the instructions). */
-        this.narrationCount = 0;
-        /** Aggregation buffer: distinct progress messages since the last spoken update (oldest first). */
-        this.pendingNarrationMessages = [];
-        /** Tail message of the last digest, so an identical trailing progress event isn't re-buffered. */
-        this.lastNarratedTail = '';
-        /** Pending deferred-narration timer; cancelled when the delegation finishes / barge-in lands. */
-        this.narrationTimer = null;
         /** Count of transcript turns persisted, surfaced in the result. */
         this.transcriptTurnCount = 0;
         /** Whether {@link Stop} has been initiated, to make finalization idempotent. */
         this.stopped = false;
         this.deps = deps;
+        this.narrator = new DelegationNarrator({
+            GetSession: () => this.session,
+            NarrationInstructionsTemplate: deps.NarrationInstructionsTemplate,
+            NarrationPaceMs: deps.NarrationPaceMs,
+        });
         this.toolBroker = new RealtimeToolBroker({
             // Wrapped so the runner can (a) anchor the narration burst lifecycle around each
             // delegated run and (b) thread its own OnProgress into the delegate — the production
             // delegate (BaseAgent.delegateRealtimeToTarget) passes it into the child RunAgent.
-            DelegateToTarget: (request) => this.runDelegateWithNarration(request),
+            DelegateToTarget: (request) => this.narrator.Run(request, (r) => deps.DelegateToTarget(r)),
             // Route non-target tool calls through the runner so server-channel tools execute via
             // their dedicated handler before falling back to the generic executor.
             ExecuteTool: (call) => this.executeNonTargetTool(call),
@@ -292,13 +269,10 @@ export class RealtimeSessionRunner {
             // SEAM-2: the OLD session is dead — abort any in-flight delegation (its result would
             // otherwise be relayed to the fresh session as a function_call_output carrying a
             // call_id the new provider session never issued) and drop any queued (now-stale)
-            // progress-narration text. We do NOT blanket-reset activeDelegations: each in-flight
-            // delegation frame self-decrements via its own finally (AbortInFlight unwinds them), so
-            // zeroing the shared counter here would corrupt it for a CONCURRENT delegation that
-            // outlives the reconnect (its completion would decrement a count that now belongs to a
-            // newly-started delegation, suppressing the new one's narration).
+            // progress-narration text. The narrator does NOT blanket-reset its in-flight count: each
+            // delegation frame self-decrements via its own finally (AbortInFlight unwinds them).
             this.toolBroker.AbortInFlight();
-            this.cancelPendingNarration();
+            this.narrator.Cancel();
             try {
                 await this.session?.Close();
             }
@@ -516,156 +490,7 @@ export class RealtimeSessionRunner {
         this.deps.LogStatus?.('✋ Barge-in detected — aborting in-flight delegated run if any.', true);
         this.toolBroker.AbortInFlight();
         // The user took the floor — any pending spoken progress update is stale.
-        this.cancelPendingNarration();
-    }
-    // ── Delegated-run progress narration (server-bridged B3) ──────────────────
-    /**
-     * 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.
-     */
-    async runDelegateWithNarration(request) {
-        this.beginDelegationBurst();
-        try {
-            return await this.deps.DelegateToTarget({
-                ...request,
-                OnProgress: (progress) => this.handleDelegationProgress(progress)
-            });
-        }
-        finally {
-            this.endDelegation();
-        }
-    }
-    /**
-     * 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).
-     */
-    beginDelegationBurst() {
-        // Anchor a fresh burst either when nothing else is in flight OR when the burst state was reset
-        // (narrationBurstStartedAt === 0) by a {@link cancelPendingNarration} — e.g. a reconnect that
-        // aborted the prior delegation(s). The second condition matters when a prior delegation FAILED
-        // to honor its abort and left {@link activeDelegations} elevated: without it this new delegation
-        // would inherit the dead burst's stale anchor (collapsing the 5s first-narration delay) and its
-        // climbing update count. Decoupling the re-anchor from the counter keeps burst timing correct
-        // regardless of a stuck delegate.
-        if (this.activeDelegations === 0 || this.narrationBurstStartedAt === 0) {
-            this.narrationBurstStartedAt = Date.now();
-            this.narrationCount = 0;
-            this.pendingNarrationMessages = [];
-            this.lastNarratedTail = '';
-        }
-        this.activeDelegations++;
-    }
-    /** Closes one delegation; when none remain in flight, pending narration is cancelled. */
-    endDelegation() {
-        this.activeDelegations = Math.max(0, this.activeDelegations - 1);
-        if (this.activeDelegations === 0) {
-            this.cancelPendingNarration();
-        }
-    }
-    /**
-     * 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.
-     */
-    handleDelegationProgress(progress) {
-        if (!RealtimeSessionRunner.significantProgressSteps.includes(progress.step)) {
-            return;
-        }
-        const session = this.session;
-        if (!session || this.activeDelegations === 0) {
-            return; // session gone / delegation already finished — stale event
-        }
-        session.SendContextNote?.(`[delegated-agent progress] ${progress.message}`);
-        if (!session.RequestSpokenUpdate) {
-            return; // provider can't voice an instructed one-off update — context note only
-        }
-        this.bufferNarrationMessage(progress.message);
-        if (this.pendingNarrationMessages.length > 0 && !this.narrationTimer) {
-            this.narrationTimer = setTimeout(() => this.fireDeferredNarration(), this.nextNarrationDelayMs());
-        }
-    }
-    /** Adds a progress message to the digest buffer (deduped, capped, oldest-first). */
-    bufferNarrationMessage(message) {
-        if (message === this.lastNarratedTail || this.pendingNarrationMessages.includes(message)) {
-            return;
-        }
-        this.pendingNarrationMessages.push(message);
-        if (this.pendingNarrationMessages.length > RealtimeSessionRunner.maxDigestMessages) {
-            this.pendingNarrationMessages.shift();
-        }
-    }
-    /**
-     * 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.
-     */
-    nextNarrationDelayMs() {
-        const now = Date.now();
-        const firstAnchor = this.narrationCount === 0
-            ? this.narrationBurstStartedAt + RealtimeSessionRunner.firstNarrationDelayMs
-            : 0;
-        const spacingFloor = this.lastNarrationAt > 0
-            ? this.lastNarrationAt + this.narrationIntervalMs()
-            : 0;
-        return Math.max(50, Math.max(firstAnchor, spacingFloor) - now);
-    }
-    /**
-     * 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.
-     */
-    narrationIntervalMs() {
-        const pace = this.deps.NarrationPaceMs;
-        return typeof pace === 'number' && Number.isFinite(pace) && pace > 0
-            ? pace
-            : RealtimeSessionRunner.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.
-     */
-    fireDeferredNarration() {
-        this.narrationTimer = null;
-        const session = this.session;
-        if (!session?.RequestSpokenUpdate || this.pendingNarrationMessages.length === 0 || this.activeDelegations === 0) {
-            this.pendingNarrationMessages = [];
-            return;
-        }
-        const digest = this.pendingNarrationMessages.join(' → ');
-        this.lastNarratedTail = this.pendingNarrationMessages[this.pendingNarrationMessages.length - 1];
-        this.pendingNarrationMessages = [];
-        this.narrationCount++;
-        this.lastNarrationAt = Date.now();
-        session.RequestSpokenUpdate(BuildServerNarrationInstructions(this.deps.NarrationInstructionsTemplate, digest, this.narrationCount));
-    }
-    /**
-     * Cancels any deferred spoken update, drops the digest buffer, and RESETS the burst-timing state
-     * (anchor time, spoken-update count, dedup tail). Callers invoke this exactly when the current
-     * burst is ending or being torn down (delegation done, barge-in, reconnect, Stop), so clearing the
-     * anchor to 0 marks "no active burst" — {@link beginDelegationBurst} then re-anchors the next
-     * delegation cleanly even if {@link activeDelegations} is still elevated by a stuck delegate.
-     */
-    cancelPendingNarration() {
-        if (this.narrationTimer) {
-            clearTimeout(this.narrationTimer);
-            this.narrationTimer = null;
-        }
-        this.pendingNarrationMessages = [];
-        this.narrationBurstStartedAt = 0;
-        this.narrationCount = 0;
-        this.lastNarratedTail = '';
+        this.narrator.Cancel();
     }
     /**
      * Closes the session and finalizes usage. Idempotent: a second call is a no-op.
@@ -692,7 +517,7 @@ export class RealtimeSessionRunner {
         }
         await this.flushUsage();
         // A pending spoken progress update is meaningless on a closing session.
-        this.cancelPendingNarration();
+        this.narrator.Cancel();
         // Abort any still-in-flight delegation before tearing down.
         this.toolBroker.AbortInFlight();
         let errorMessage;