dsh-realtime-agent 0.2.6 → 0.2.8

package/README.md

@@ -75,6 +75,44 @@ A session is opened only when `autoStart` is set. `maxTranscriptChars` bounds th
 on each request: it is the **oldest** lines that are dropped, and the most recent line is always kept,
 because a buffer that can hold nothing can answer nothing.
 
+## What can be changed while it runs
+
+`docs/control-plane-fields.md` is the gate, and it classifies this plugin's fields in three ways.
+`delegationTimeoutMs` and `maxTranscriptChars` are **live**: read at the moment they are used, so the
+seam's settings surface changes them without a restart, and a change lands on the next delegation.
+
+```
+set realtime-agent.delegationTimeoutMs=90000
+set realtime-agent.maxTranscriptChars=12000
+```
+
+`provider`, `model`, `voice` and `instructions` are **session-bound** — they travelled in the
+provider's `session.start`, so only a new session can carry new ones, and the UI that offers them must
+say *reconnect* rather than pretending an instant change is possible.
+
+`autoStart` is **restart-bound**, and this is a correction rather than a convenience: its only read site
+is the boot, so nothing a running process could do would honour a change. A `set` on it is refused with
+the restart it needs — `realtime-agent.autoStart` is claimed when the plugin loads, so restart to change
+it — rather than accepted and quietly ignored.
+
+## Asking it what it is doing
+
+Two of this plugin's three session events **return** what they did, so a caller that is waiting can have
+the answer while a caller that only emits is unaffected:
+
+- `realtime-agent/status` — a query. `{open, provider, model, voice?, sessionId?}`, read from the session
+  the provider actually accepted while one is open, and from what a start *would* use while none is. A
+  mounted agent always answers, so `undefined` from the dispatch means the row is absent — which is a
+  different fact from a session that is merely closed.
+- `realtime-agent/start` / `realtime-agent/stop` — the transport emits these and ignores the result; the
+  control channel dispatches them with `serial` and answers with the **outcome**: `{ok, voice, refusal?}`
+  rather than an acknowledgement that the request was made. A `start` that replied *requested* while the
+  open silently failed is exactly the collapse this project has already paid for once.
+
+A failed request carries a **structured refusal** — the seam's machine code and the `remedy` written to be
+relayed verbatim — and never the failure's message. This plugin holds no credential to redact against; the
+adapter does, and that is why its journal records the class of a session failure rather than the text.
+
 ## How answers are kept deliverable
 
 - **A long answer is cut, not rejected.** The seam bounds an append at 2000 characters and *throws*

package/lib/index.d.ts

@@ -22,10 +22,10 @@
  */
 import Schema from '@deepseek-ai/schemastery';
 import type { Context } from '@deepseek-ai/cordis';
-import type { RealtimeDelegationSettlement, RealtimeSession, RealtimeSessionHandlers } from 'dsh-realtime';
+import type { RealtimeDelegationProgress, RealtimeDelegationSettlement, RealtimeSession, RealtimeSessionHandlers } from 'dsh-realtime';
 import { type DelegationAppend, type DelegationAsker } from './bridge.ts';
 import { TranscriptBuffer } from './transcript.ts';
-import type { DelegationAnswer, DelegationRequest, RealtimeAgentConfig } from './types.ts';
+import type { DelegationAnswer, DelegationRequest, RealtimeAgentConfig, RealtimeSessionRequestOutcome, RealtimeVoiceStatus } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Events {
         /**
@@ -52,6 +52,18 @@ declare module '@deepseek-ai/cordis' {
          * user's ear without any of them re-deriving why the turn produced nothing.
          */
         'realtime-agent/delegation-settled'(settlement: RealtimeDelegationSettlement): void;
+        /**
+         * One step of a delegated turn, on its way to an ear or to the model's own context.
+         *
+         * Emitted by whichever application is running the turn, as the steps happen — it is the only thing that
+         * knows what the turn is doing. This plugin appends it, because it holds the session: `commentary` is
+         * spoken aloud, `thinking` is carried silently, and the choice is the emitter's.
+         *
+         * A step for a delegation this plugin is **not** waiting on is dropped rather than appended: the
+         * provider only accepts an append for a delegation it knows, and a finished turn's words must not be
+         * spoken into a conversation that has moved on.
+         */
+        'realtime-agent/delegation-progress'(progress: RealtimeDelegationProgress): void;
         /**
          * Output audio: PCM16 in the session's declared output format.
          *
@@ -74,15 +86,27 @@ declare module '@deepseek-ai/cordis' {
          * Emitted by a transport when an authenticated client arrives, so that connecting a microphone is
          * enough to be heard — with no profile option and no dependence on a model choosing to call
          * `voice_start`. The session belongs to the agent, so the transport asks rather than opens one itself.
+         *
+         * Returns the request's **outcome** so a caller that is waiting for the answer can have it —
+         * `ctx.serial` from the control channel — while the transport, which only *emits*, is unaffected.
          */
-        'realtime-agent/start'(): void;
+        'realtime-agent/start'(): RealtimeSessionRequestOutcome | undefined | Promise<RealtimeSessionRequestOutcome | undefined>;
         /**
          * Close the voice session.
          *
          * Emitted by a transport when its last client goes away, including when the transport itself is
          * disposed — a session outliving the microphone that asked for it is a socket nobody is listening to.
+         * Returns the outcome, for the same reason `realtime-agent/start` does.
          */
-        'realtime-agent/stop'(): void;
+        'realtime-agent/stop'(): RealtimeSessionRequestOutcome | undefined | Promise<RealtimeSessionRequestOutcome | undefined>;
+        /**
+         * The voice session's state — a **query**, so nothing emits it.
+         *
+         * `undefined` means no listener answered, which is the honest answer for a composition with no agent
+         * row: it is distinguishable from a session that is merely closed, because the agent that is mounted
+         * always answers.
+         */
+        'realtime-agent/status'(): RealtimeVoiceStatus | undefined | Promise<RealtimeVoiceStatus | undefined>;
     }
 }
 export * from './types.ts';
@@ -125,8 +149,14 @@ export interface HandlerDeps {
     readonly session: () => RealtimeSession | undefined;
     /** How to reach a responder. */
     readonly ask: DelegationAsker;
-    /** Bound on waiting for one. */
-    readonly timeoutMs: number;
+    /**
+     * Bound on waiting for one, read at the moment the delegation is answered.
+     *
+     * An accessor because `delegationTimeoutMs` is a **live** field: the window the voice model waits in
+     * can be changed while the plugin runs, and the change must apply to the next delegation rather than
+     * to the next boot.
+     */
+    readonly timeoutMs: () => number;
     /** Called when the session ended, so the caller can drop its reference. */
     readonly onClosed: () => void;
     /** Where a session-scoped failure is reported. */
@@ -140,6 +170,13 @@ export interface HandlerDeps {
      * whether a speaker ever rendered it. See the seam's session contract and invariant 6.
      */
     readonly onAcknowledged: (append: DelegationAppend, delegationId: string) => void;
+    /**
+     * Called once a delegation arrives, before it is answered, with the session it is being answered on — so
+     * a caller can tell which turns are still waiting, and *where* each one is waiting.
+     */
+    readonly onDelegationStarted?: (delegationId: string, session: RealtimeSession) => void;
+    /** Called once a delegation has finished, however it ended. */
+    readonly onDelegationSettled?: (delegationId: string) => void;
 }
 /**
  * Build the session handlers.

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAsB,4BAA4B,EAAE,eAAe,EAAE,uBAAuB,EAAsB,MAAM,cAAc,CAAA;AAClJ,OAAO,EAAoB,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAE3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAE1F,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,MAAM;QACd;;;;;;WAMG;QACH,2BAA2B,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAA;QAC7H,2EAA2E;QAC3E,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;QAC1C;;;;;;;;;;;;WAYG;QACH,mCAAmC,CAAC,UAAU,EAAE,4BAA4B,GAAG,IAAI,CAAA;QACnF;;;;;;WAMG;QACH,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;QAC/C;;;;;;WAMG;QACH,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;QAC7C;;;;;;WAMG;QACH,sBAAsB,IAAI,IAAI,CAAA;QAC9B;;;;;WAKG;QACH,qBAAqB,IAAI,IAAI,CAAA;KAC9B;CACF;AAED,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AACpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAA;AAErE,wDAAwD;AACxD,eAAO,MAAM,IAAI,mBAAmB,CAAA;AAEpC,sFAAsF;AACtF,eAAO,MAAM,MAAM,UAAwB,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;aAQjB,CAAA;AAEF,yGAAyG;AACzG,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAA;IACrC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,eAAe,GAAG,SAAS,CAAA;IACnD,gCAAgC;IAChC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAC/C,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;CAClF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,uBAAuB,CAyBzE;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAwHrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -21,6 +21,7 @@
  * @module dsh-realtime-agent
  */
 import Schema from '@deepseek-ai/schemastery';
+import { REALTIME_ERROR_CODES, RealtimeError } from 'dsh-realtime';
 import { answerDelegation } from './bridge.js';
 import { voiceToolDefinitions } from './tools.js';
 import { TranscriptBuffer } from './transcript.js';
@@ -64,34 +65,109 @@ export function createHandlers(deps) {
             // would be a failure raised from inside a handler, which is the worst place to raise one.
             if (session === undefined)
                 return;
+            // Marked waiting before the answer is dispatched, so a step that arrives while the turn is running is
+            // appended rather than dropped for having beaten this line.
+            deps.onDelegationStarted?.(delegation.id, session);
             // Handlers are synchronous, so the answer is dispatched rather than awaited. A rejection is
             // reported rather than thrown: an unanswered delegation is already the failure path.
-            void answerDelegation(session, delegation, deps.transcript.lines(), deps.ask, deps.timeoutMs, deps.onAcknowledged).catch(deps.onSessionError);
+            void answerDelegation(session, delegation, deps.transcript.lines(), deps.ask, deps.timeoutMs(), deps.onAcknowledged).catch(deps.onSessionError).finally(() => { deps.onDelegationSettled?.(delegation.id); });
         },
         onAudio: (pcm16) => { deps.onAudio(pcm16); },
         onClosed: () => { deps.onClosed(); },
         onError: (error) => { deps.onSessionError(error); },
     };
 }
+/**
+ * A count this plugin can actually be run with: a whole, positive number.
+ *
+ * Local to the plugin rather than shared from the seam, deliberately: the reason text is part of this
+ * plugin's own onboarding, and the seam has no business knowing that this plugin measures a timeout in
+ * milliseconds and a transcript in characters.
+ * @param field - the setting's own name, for the reason.
+ * @param value - the proposed value.
+ * @returns the value, when it is usable.
+ */
+function requireCount(field, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new RealtimeError(`${field} must be a positive whole number`, REALTIME_ERROR_CODES.INVALID_SETTING);
+    }
+    return value;
+}
 /**
  * Hold a session and bridge what the voice model delegates.
  * @param ctx - the Cordis context, which must already provide the `realtime` service.
  * @param config - validated configuration.
  */
 export function apply(ctx, config) {
-    const transcript = new TranscriptBuffer(config.maxTranscriptChars);
-    // This plugin owns the session, so it is the only one that can honestly write these entries. The audio
-    // route emits a *request* to open a session and deliberately records nothing for it: recording a
-    // request as an event is how a journal starts lying.
     const journal = ctx.realtime.journal;
+    /**
+     * The two fields this plugin reads at the moment of use.
+     *
+     * `autoStart` is deliberately **not** here as a changeable value. Its only read site is the boot
+     * below, so a running process has nothing that could honour a change; the gate was corrected to say
+     * so, and it is registered below as restart-bound — which is what makes that correction bite rather
+     * than merely being written down.
+     */
+    const live = { delegationTimeoutMs: config.delegationTimeoutMs, maxTranscriptChars: config.maxTranscriptChars };
+    const transcript = new TranscriptBuffer(() => live.maxTranscriptChars);
     let session;
+    // The live fields `docs/control-plane-fields.md` lists for this plugin, plus the one it reclassified:
+    // `autoStart` is registered without a setter, so a change to it is refused with the restart it needs
+    // instead of being accepted and quietly ignored.
+    ctx.effect(function* () {
+        const release = ctx.realtime.settings.register(name, [
+            {
+                field: 'delegationTimeoutMs',
+                kind: 'number',
+                scope: 'live',
+                describe: 'How long the voice model waits for a responder',
+                get: () => live.delegationTimeoutMs,
+                set: (value) => { live.delegationTimeoutMs = requireCount('delegationTimeoutMs', value); },
+            },
+            {
+                field: 'maxTranscriptChars',
+                kind: 'number',
+                scope: 'live',
+                describe: 'Character budget for the transcript carried on a delegation',
+                get: () => live.maxTranscriptChars,
+                set: (value) => { live.maxTranscriptChars = requireCount('maxTranscriptChars', value); },
+            },
+            {
+                field: 'autoStart',
+                kind: 'boolean',
+                scope: 'restart',
+                describe: 'Open a session as soon as the plugin mounts',
+                get: () => config.autoStart,
+            },
+        ]);
+        yield () => { release(); };
+    }, 'realtime-agent.settings');
+    /**
+     * The one place an acknowledgement can honestly be recorded: the seam's appends resolve on the provider's
+     * confirmation, not on the send. Note what is deliberately absent beside it — no entry anywhere claims the
+     * audio was heard, which is the pair invariant 6 exists to keep apart. Shared with the narration path, so
+     * a spoken step and an answer are accounted for by the same rule.
+     */
+    const onAcknowledged = (append, delegationId) => {
+        journal.record('append.acknowledged', { append, delegationId });
+    };
+    /**
+     * The delegations still waiting for an answer, with the session each one is being answered on.
+     *
+     * The session is stored *with* the id rather than read back from the plugin when a step arrives, and that
+     * is not a micro-optimisation: it collapses two conditions into one. "Nothing is waiting on this" and
+     * "there is no session to speak into" cannot drift apart into two guards, one of which — the session
+     * dropped while its id is still waiting — no sequence of events can actually produce.
+     */
+    const waiting = new Map();
     const handlers = createHandlers({
         transcript,
         session: () => session,
         ask: request => ctx.serial('realtime-agent/delegation', request),
-        timeoutMs: config.delegationTimeoutMs,
+        timeoutMs: () => live.delegationTimeoutMs,
         onClosed: () => {
             session = undefined;
+            waiting.clear();
             journal.record('session.closed', {});
         },
         onSessionError: (error) => {
@@ -106,13 +182,37 @@ export function apply(ctx, config) {
             // Handed to the transport: all the host can observe, and no more (invariant 6).
             journal.record('speech.sent', { bytes: String(pcm16.byteLength) });
         },
-        onAcknowledged: (append, delegationId) => {
-            // The one place an acknowledgement can honestly be recorded: the seam's appends resolve on the
-            // provider's confirmation, not on the send. Note what is deliberately absent beside it — no entry
-            // anywhere claims the audio was heard, which is the pair invariant 6 exists to keep apart.
-            journal.record('append.acknowledged', { append, delegationId });
-        },
+        onDelegationStarted: (delegationId, current) => { waiting.set(delegationId, current); },
+        onDelegationSettled: (delegationId) => { waiting.delete(delegationId); },
+        onAcknowledged,
     });
+    /**
+     * Narrate a delegated turn's steps, on the session that is running it.
+     *
+     * A contribution like any other, so the fiber that registered it releases it. The emitter decides whether
+     * a step is spoken or silent — this half only carries it, because the session belongs here and nowhere
+     * else does.
+     *
+     * A failed append is a **dropped step**, not a broken turn: it is recorded so it is not silent, and it
+     * must not be confused with an answer that never arrived.
+     */
+    ctx.effect(function* () {
+        const dispose = ctx.on('realtime-agent/delegation-progress', (progress) => {
+            // One condition, not two: the session a turn is waiting on *is* the authorisation to speak into it, and
+            // it travels with the delegation. A step for anything else has nowhere to go — the provider refuses an
+            // append for an id it does not know, and a finished turn's words must not be spoken into the next one.
+            const current = waiting.get(progress.id);
+            if (current === undefined)
+                return;
+            const append = progress.channel === 'commentary'
+                ? current.appendCommentary(progress.text, progress.id)
+                : current.appendThinking(progress.text, progress.id);
+            void append
+                .then(() => { onAcknowledged(progress.channel, progress.id); })
+                .catch(() => { journal.record('progress.dropped', { id: progress.id, channel: progress.channel }); });
+        });
+        yield () => { dispose(); };
+    }, 'realtime-agent.progress');
     /**
      * Open a session, or return the one already open.
      *
@@ -145,6 +245,70 @@ export function apply(ctx, config) {
         session = undefined;
         await current?.close();
     };
+    /**
+     * The session's state, as only this plugin can report it.
+     *
+     * With nothing open it answers with what a start *would* use, rather than with nothing: "no session,
+     * and it would be `openai-live`/`gpt-live-1`" is a different — and more useful — answer than an
+     * absence, and it is the one a status surface needs to render a sensible control.
+     */
+    const status = () => {
+        const current = session;
+        if (current === undefined) {
+            return {
+                open: false,
+                provider: config.provider,
+                model: config.model,
+                ...config.voice === undefined ? {} : { voice: config.voice },
+            };
+        }
+        return {
+            open: true,
+            provider: current.started.provider,
+            model: current.started.model,
+            ...current.started.voice === undefined ? {} : { voice: current.started.voice },
+            sessionId: current.id,
+        };
+    };
+    /**
+     * Classify a failed request, carrying what a caller can act on and never the message.
+     *
+     * A seam failure carries its machine code and the remedy written to be relayed; anything else carries
+     * its **class** alone. The message is deliberately dropped: a provider error is exactly where a key
+     * turns up, and this plugin holds no credential to redact against — the same reason its journal
+     * records the class of a session failure rather than the text.
+     * @param error - whatever the attempt threw.
+     * @returns the structured refusal.
+     */
+    const refusalFor = (error) => {
+        if (error instanceof RealtimeError) {
+            return {
+                code: error.code,
+                ...error.detail?.remedy === undefined ? {} : { remedy: error.detail.remedy },
+            };
+        }
+        return { class: error instanceof Error ? error.name : typeof error };
+    };
+    /**
+     * Run a session request and report what it produced.
+     *
+     * The result is **returned as well as** reported on the bus, because a caller may be waiting for it:
+     * the control channel dispatches these with `serial`, so `start` can answer with the session that
+     * opened rather than with an acknowledgement that it asked. The failure still goes onto the bus, so a
+     * transport that merely emits keeps the behaviour it always had.
+     * @param attempt - the request to run.
+     * @returns whether it achieved what it asked for, and the state afterwards.
+     */
+    const requestSession = async (attempt) => {
+        try {
+            await attempt();
+            return { ok: true, voice: status() };
+        }
+        catch (error) {
+            ctx.emit('realtime-agent/error', error);
+            return { ok: false, voice: status(), refusal: refusalFor(error) };
+        }
+    };
     // Tools are an effect, like every other contribution this plugin makes: the fiber that mounted them
     // releases them, so there is no separate teardown path to forget.
     ctx.effect(function* () {
@@ -176,17 +340,16 @@ export function apply(ctx, config) {
         yield () => { dispose(); };
     }, 'realtime-agent.mic');
     // Session requests from the transport. The route knows when an authenticated client connects and the
-    // agent owns the session, so one event is the whole of the wiring between them.
+    // agent owns the session, so one event is the whole of the wiring between them. Each listener returns
+    // its outcome: `emit` ignores it, `serial` waits for it, and that is how the control channel can
+    // answer *what happened* rather than *that it was asked*.
     ctx.effect(function* () {
         const disposers = [
-            ctx.on('realtime-agent/start', () => {
-                // Fire-and-forget for the same reason `autoStart` is: a listener has no caller to catch a
-                // rejection, and the failure is reported on the bus rather than thrown into one.
-                void open().catch((error) => { ctx.emit('realtime-agent/error', error); });
-            }),
-            ctx.on('realtime-agent/stop', () => {
-                void stop().catch((error) => { ctx.emit('realtime-agent/error', error); });
-            }),
+            ctx.on('realtime-agent/start', () => requestSession(() => open())),
+            ctx.on('realtime-agent/stop', () => requestSession(() => stop())),
+            // A query, and the only listener that answers one. A mounted agent always answers, so a caller
+            // that gets `undefined` from the dispatch learns the agent row is absent rather than guessing.
+            ctx.on('realtime-agent/status', () => status()),
         ];
         yield () => { for (const dispose of disposers)
             dispose(); };

package/lib/index.js.map

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

package/lib/transcript.d.ts

@@ -12,11 +12,16 @@ export declare class TranscriptBuffer {
     private readonly buffered;
     private chars;
     /**
-     * @param maxChars - character budget. Every value is accepted: a budget smaller than one line
-     *   degrades to keeping exactly the most recent line rather than to keeping nothing, because a
-     *   buffer that can hold nothing cannot answer any delegation at all.
+     * @param maxChars - character budget, read at every eviction.
+     *
+     * An accessor rather than a number because `maxTranscriptChars` is a **live** field
+     * (`docs/control-plane-fields.md`): the budget can change while the conversation runs, and a copy
+     * taken at construction would make the change look applied while the buffer kept the old one.
+     * Every value is accepted: a budget smaller than one line degrades to keeping exactly the most recent
+     * line rather than to keeping nothing, because a buffer that can hold nothing cannot answer any
+     * delegation at all.
      */
-    constructor(maxChars: number);
+    constructor(maxChars: () => number);
     /**
      * Record one fragment.
      * @param kind - which side spoke.

package/lib/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAQrD;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IASf,OAAO,CAAC,QAAQ,CAAC,QAAQ;IARrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,KAAK,CAAI;IAEjB;;;;OAIG;IACH,YAA6B,QAAQ,EAAE,MAAM,EAAI;IAEjD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAanE;IAED;;;OAGG;IACH,KAAK,IAAI,mBAAmB,EAAE,CAE7B;IAED,yFAAyF;IACzF,OAAO,CAAC,KAAK;CAOd"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAQrD;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAcf,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAbrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,KAAK,CAAI;IAEjB;;;;;;;;;OASG;IACH,YAA6B,QAAQ,EAAE,MAAM,MAAM,EAAI;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAanE;IAED;;;OAGG;IACH,KAAK,IAAI,mBAAmB,EAAE,CAE7B;IAED,yFAAyF;IACzF,OAAO,CAAC,KAAK;CAQd"}

package/lib/transcript.js

@@ -11,9 +11,14 @@ export class TranscriptBuffer {
     buffered = [];
     chars = 0;
     /**
-     * @param maxChars - character budget. Every value is accepted: a budget smaller than one line
-     *   degrades to keeping exactly the most recent line rather than to keeping nothing, because a
-     *   buffer that can hold nothing cannot answer any delegation at all.
+     * @param maxChars - character budget, read at every eviction.
+     *
+     * An accessor rather than a number because `maxTranscriptChars` is a **live** field
+     * (`docs/control-plane-fields.md`): the budget can change while the conversation runs, and a copy
+     * taken at construction would make the change look applied while the buffer kept the old one.
+     * Every value is accepted: a budget smaller than one line degrades to keeping exactly the most recent
+     * line rather than to keeping nothing, because a buffer that can hold nothing cannot answer any
+     * delegation at all.
      */
     constructor(maxChars) {
         this.maxChars = maxChars;
@@ -47,7 +52,8 @@ export class TranscriptBuffer {
     }
     /** Drop the oldest lines until the budget is met, never dropping the most recent one. */
     evict() {
-        while (this.chars > this.maxChars && this.buffered.length > 1) {
+        const budget = this.maxChars();
+        while (this.chars > budget && this.buffered.length > 1) {
             // The loop condition proves a first element exists, so this assertion is an invariant rather
             // than a hope — and it leaves no unreachable branch for the coverage gate to flag.
             this.chars -= this.buffered.shift().text.length;

package/lib/transcript.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IASE,QAAQ;IARpB,QAAQ,GAAmB,EAAE,CAAA;IACtC,KAAK,GAAG,CAAC,CAAA;IAEjB;;;;OAIG;IACH,YAA6B,QAAgB;wBAAhB,QAAQ;IAAW,CAAC;IAEjD;;;;;OAKG;IACH,MAAM,CAAC,IAAwB,EAAE,IAAY,EAAE,KAAc;QAC3D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAC7B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAA;QAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACpD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAA;YACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACrB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;QACnD,CAAC;QAED,IAAI,CAAC,KAAK,EAAE,CAAA;IACd,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IAC1E,CAAC;IAED,yFAAyF;IACjF,KAAK;QACX,OAAO,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9D,6FAA6F;YAC7F,mFAAmF;YACnF,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAG,CAAC,IAAI,CAAC,MAAM,CAAA;QAClD,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IAcE,QAAQ;IAbpB,QAAQ,GAAmB,EAAE,CAAA;IACtC,KAAK,GAAG,CAAC,CAAA;IAEjB;;;;;;;;;OASG;IACH,YAA6B,QAAsB;wBAAtB,QAAQ;IAAiB,CAAC;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,IAAwB,EAAE,IAAY,EAAE,KAAc;QAC3D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAC7B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAA;QAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACpD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAA;YACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACrB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;QACnD,CAAC;QAED,IAAI,CAAC,KAAK,EAAE,CAAA;IACd,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IAC1E,CAAC;IAED,yFAAyF;IACjF,KAAK;QACX,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;QAC9B,OAAO,IAAI,CAAC,KAAK,GAAG,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvD,6FAA6F;YAC7F,mFAAmF;YACnF,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAG,CAAC,IAAI,CAAC,MAAM,CAAA;QAClD,CAAC;IACH,CAAC;CACF"}

package/lib/types.d.ts

@@ -68,4 +68,60 @@ export interface RealtimeAgentConfig {
     /** Character budget for the transcript carried on a delegation request. */
     maxTranscriptChars: number;
 }
+/**
+ * The voice session's state, as the plugin that owns it is the only one able to report it.
+ *
+ * A **query's** answer rather than an event's payload: nothing emits this, and a caller that needs it
+ * asks through `realtime-agent/status` — which is also what makes "is voice live" answerable without
+ * opening anything to find out.
+ */
+export interface RealtimeVoiceStatus {
+    /** Whether a provider session is open now. */
+    readonly open: boolean;
+    /**
+     * The registered route the session is on — or, when none is open, the one a start *would* use.
+     *
+     * Read from the session the provider actually accepted when there is one, because a provider may
+     * alias what was asked for.
+     */
+    readonly provider: string;
+    /** The model the provider accepted, or the one configured when nothing is open. */
+    readonly model: string;
+    /** The output voice, when one has been settled. */
+    readonly voice?: string;
+    /** The provider's own session id. Present only while a session is open. */
+    readonly sessionId?: string;
+}
+/**
+ * Why a session request did not succeed, in the shape a caller can act on.
+ *
+ * **Never the failure's message**, and that is a deliberate limitation rather than an oversight: the
+ * plugin that holds the credential is the adapter, and this one holds none to redact against — which is
+ * the same rule its journal follows, where a session failure is recorded as its *class*. What it can
+ * carry instead is more useful than the message: the seam's own machine code, and the `remedy` written
+ * to be relayed verbatim, both of which name a *setting* rather than its value.
+ */
+export interface RealtimeSessionRefusal {
+    /** The seam's machine code, when the failure was one of its classified ones (`NOT_CONFIGURED`, `RATE_LIMITED`, …). */
+    readonly code?: string;
+    /** What to do about it, written to be relayed verbatim to whoever is trying to use the feature. */
+    readonly remedy?: string;
+    /** The failing class, when there was no code to carry. A class, never an instance's message. */
+    readonly class?: string;
+}
+/**
+ * What a request to open or close the voice session produced.
+ *
+ * The **outcome**, not an acknowledgement, because the two are the difference between "asked" and "it
+ * worked" — and collapsing them is the failure this project has already paid for once: a `start` that
+ * replied *requested* while the open silently failed teaches a user that the plugin is broken.
+ */
+export interface RealtimeSessionRequestOutcome {
+    /** Whether the request achieved what it asked for. */
+    readonly ok: boolean;
+    /** The state **after** the attempt. */
+    readonly voice: RealtimeVoiceStatus;
+    /** Present exactly when `ok` is false. */
+    readonly refusal?: RealtimeSessionRefusal;
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAA;IACxB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,0FAA0F;IAC1F,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC1C,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAA;IAClB,wGAAwG;IACxG,mBAAmB,EAAE,MAAM,CAAA;IAC3B,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAA;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAA;IACxB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,0FAA0F;IAC1F,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC1C,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAA;IAClB,wGAAwG;IACxG,mBAAmB,EAAE,MAAM,CAAA;IAC3B,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,sHAAsH;IACtH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,mGAAmG;IACnG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAA;CAC1C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime-agent",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Delegation bridge for the dsh-realtime seam: answers what the voice model delegates, or says plainly that it cannot.",
   "type": "module",
   "main": "lib/index.js",
@@ -42,7 +42,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "dsh-realtime": "^0.2.2"
+    "dsh-realtime": "^0.2.4"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",

package/src/index.ts

@@ -23,11 +23,12 @@
 
 import Schema from '@deepseek-ai/schemastery'
 import type { Context } from '@deepseek-ai/cordis'
-import type { RealtimeDelegation, RealtimeDelegationSettlement, RealtimeSession, RealtimeSessionHandlers, RealtimeTranscript } from 'dsh-realtime'
+import type { RealtimeDelegation, RealtimeDelegationProgress, RealtimeDelegationSettlement, RealtimeSession, RealtimeSessionHandlers, RealtimeTranscript } from 'dsh-realtime'
+import { REALTIME_ERROR_CODES, RealtimeError } from 'dsh-realtime'
 import { answerDelegation, type DelegationAppend, type DelegationAsker } from './bridge.ts'
 import { voiceToolDefinitions } from './tools.ts'
 import { TranscriptBuffer } from './transcript.ts'
-import type { DelegationAnswer, DelegationRequest, RealtimeAgentConfig } from './types.ts'
+import type { DelegationAnswer, DelegationRequest, RealtimeAgentConfig, RealtimeSessionRefusal, RealtimeSessionRequestOutcome, RealtimeVoiceStatus } from './types.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Events {
@@ -55,6 +56,18 @@ declare module '@deepseek-ai/cordis' {
      * user's ear without any of them re-deriving why the turn produced nothing.
      */
     'realtime-agent/delegation-settled'(settlement: RealtimeDelegationSettlement): void
+    /**
+     * One step of a delegated turn, on its way to an ear or to the model's own context.
+     *
+     * Emitted by whichever application is running the turn, as the steps happen — it is the only thing that
+     * knows what the turn is doing. This plugin appends it, because it holds the session: `commentary` is
+     * spoken aloud, `thinking` is carried silently, and the choice is the emitter's.
+     *
+     * A step for a delegation this plugin is **not** waiting on is dropped rather than appended: the
+     * provider only accepts an append for a delegation it knows, and a finished turn's words must not be
+     * spoken into a conversation that has moved on.
+     */
+    'realtime-agent/delegation-progress'(progress: RealtimeDelegationProgress): void
     /**
      * Output audio: PCM16 in the session's declared output format.
      *
@@ -77,15 +90,27 @@ declare module '@deepseek-ai/cordis' {
      * Emitted by a transport when an authenticated client arrives, so that connecting a microphone is
      * enough to be heard — with no profile option and no dependence on a model choosing to call
      * `voice_start`. The session belongs to the agent, so the transport asks rather than opens one itself.
+     *
+     * Returns the request's **outcome** so a caller that is waiting for the answer can have it —
+     * `ctx.serial` from the control channel — while the transport, which only *emits*, is unaffected.
      */
-    'realtime-agent/start'(): void
+    'realtime-agent/start'(): RealtimeSessionRequestOutcome | undefined | Promise<RealtimeSessionRequestOutcome | undefined>
     /**
      * Close the voice session.
      *
      * Emitted by a transport when its last client goes away, including when the transport itself is
      * disposed — a session outliving the microphone that asked for it is a socket nobody is listening to.
+     * Returns the outcome, for the same reason `realtime-agent/start` does.
+     */
+    'realtime-agent/stop'(): RealtimeSessionRequestOutcome | undefined | Promise<RealtimeSessionRequestOutcome | undefined>
+    /**
+     * The voice session's state — a **query**, so nothing emits it.
+     *
+     * `undefined` means no listener answered, which is the honest answer for a composition with no agent
+     * row: it is distinguishable from a session that is merely closed, because the agent that is mounted
+     * always answers.
      */
-    'realtime-agent/stop'(): void
+    'realtime-agent/status'(): RealtimeVoiceStatus | undefined | Promise<RealtimeVoiceStatus | undefined>
   }
 }
 
@@ -125,8 +150,14 @@ export interface HandlerDeps {
   readonly session: () => RealtimeSession | undefined
   /** How to reach a responder. */
   readonly ask: DelegationAsker
-  /** Bound on waiting for one. */
-  readonly timeoutMs: number
+  /**
+   * Bound on waiting for one, read at the moment the delegation is answered.
+   *
+   * An accessor because `delegationTimeoutMs` is a **live** field: the window the voice model waits in
+   * can be changed while the plugin runs, and the change must apply to the next delegation rather than
+   * to the next boot.
+   */
+  readonly timeoutMs: () => number
   /** Called when the session ended, so the caller can drop its reference. */
   readonly onClosed: () => void
   /** Where a session-scoped failure is reported. */
@@ -140,6 +171,13 @@ export interface HandlerDeps {
    * whether a speaker ever rendered it. See the seam's session contract and invariant 6.
    */
   readonly onAcknowledged: (append: DelegationAppend, delegationId: string) => void
+  /**
+   * Called once a delegation arrives, before it is answered, with the session it is being answered on — so
+   * a caller can tell which turns are still waiting, and *where* each one is waiting.
+   */
+  readonly onDelegationStarted?: (delegationId: string, session: RealtimeSession) => void
+  /** Called once a delegation has finished, however it ended. */
+  readonly onDelegationSettled?: (delegationId: string) => void
 }
 
 /**
@@ -157,6 +195,9 @@ export function createHandlers(deps: HandlerDeps): RealtimeSessionHandlers {
       // A delegation cannot be answered into a session that is gone. Speaking into a closed transport
       // would be a failure raised from inside a handler, which is the worst place to raise one.
       if (session === undefined) return
+      // Marked waiting before the answer is dispatched, so a step that arrives while the turn is running is
+      // appended rather than dropped for having beaten this line.
+      deps.onDelegationStarted?.(delegation.id, session)
       // Handlers are synchronous, so the answer is dispatched rather than awaited. A rejection is
       // reported rather than thrown: an unanswered delegation is already the failure path.
       void answerDelegation(
@@ -164,9 +205,9 @@ export function createHandlers(deps: HandlerDeps): RealtimeSessionHandlers {
         delegation,
         deps.transcript.lines(),
         deps.ask,
-        deps.timeoutMs,
+        deps.timeoutMs(),
         deps.onAcknowledged,
-      ).catch(deps.onSessionError)
+      ).catch(deps.onSessionError).finally(() => { deps.onDelegationSettled?.(delegation.id) })
     },
     onAudio: (pcm16: Uint8Array): void => { deps.onAudio(pcm16) },
     onClosed: (): void => { deps.onClosed() },
@@ -174,26 +215,104 @@ export function createHandlers(deps: HandlerDeps): RealtimeSessionHandlers {
   }
 }
 
+/**
+ * A count this plugin can actually be run with: a whole, positive number.
+ *
+ * Local to the plugin rather than shared from the seam, deliberately: the reason text is part of this
+ * plugin's own onboarding, and the seam has no business knowing that this plugin measures a timeout in
+ * milliseconds and a transcript in characters.
+ * @param field - the setting's own name, for the reason.
+ * @param value - the proposed value.
+ * @returns the value, when it is usable.
+ */
+function requireCount(field: string, value: number): number {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RealtimeError(`${field} must be a positive whole number`, REALTIME_ERROR_CODES.INVALID_SETTING)
+  }
+  return value
+}
+
 /**
  * Hold a session and bridge what the voice model delegates.
  * @param ctx - the Cordis context, which must already provide the `realtime` service.
  * @param config - validated configuration.
  */
 export function apply(ctx: Context, config: RealtimeAgentConfig): void {
-  const transcript = new TranscriptBuffer(config.maxTranscriptChars)
-  // This plugin owns the session, so it is the only one that can honestly write these entries. The audio
-  // route emits a *request* to open a session and deliberately records nothing for it: recording a
-  // request as an event is how a journal starts lying.
   const journal = ctx.realtime.journal
+
+  /**
+   * The two fields this plugin reads at the moment of use.
+   *
+   * `autoStart` is deliberately **not** here as a changeable value. Its only read site is the boot
+   * below, so a running process has nothing that could honour a change; the gate was corrected to say
+   * so, and it is registered below as restart-bound — which is what makes that correction bite rather
+   * than merely being written down.
+   */
+  const live = { delegationTimeoutMs: config.delegationTimeoutMs, maxTranscriptChars: config.maxTranscriptChars }
+
+  const transcript = new TranscriptBuffer(() => live.maxTranscriptChars)
   let session: RealtimeSession | undefined
 
+  // The live fields `docs/control-plane-fields.md` lists for this plugin, plus the one it reclassified:
+  // `autoStart` is registered without a setter, so a change to it is refused with the restart it needs
+  // instead of being accepted and quietly ignored.
+  ctx.effect(function* () {
+    const release = ctx.realtime.settings.register(name, [
+      {
+        field: 'delegationTimeoutMs',
+        kind: 'number',
+        scope: 'live',
+        describe: 'How long the voice model waits for a responder',
+        get: () => live.delegationTimeoutMs,
+        set: (value: number) => { live.delegationTimeoutMs = requireCount('delegationTimeoutMs', value) },
+      },
+      {
+        field: 'maxTranscriptChars',
+        kind: 'number',
+        scope: 'live',
+        describe: 'Character budget for the transcript carried on a delegation',
+        get: () => live.maxTranscriptChars,
+        set: (value: number) => { live.maxTranscriptChars = requireCount('maxTranscriptChars', value) },
+      },
+      {
+        field: 'autoStart',
+        kind: 'boolean',
+        scope: 'restart',
+        describe: 'Open a session as soon as the plugin mounts',
+        get: () => config.autoStart,
+      },
+    ])
+    yield () => { release() }
+  }, 'realtime-agent.settings')
+
+  /**
+   * The one place an acknowledgement can honestly be recorded: the seam's appends resolve on the provider's
+   * confirmation, not on the send. Note what is deliberately absent beside it — no entry anywhere claims the
+   * audio was heard, which is the pair invariant 6 exists to keep apart. Shared with the narration path, so
+   * a spoken step and an answer are accounted for by the same rule.
+   */
+  const onAcknowledged = (append: DelegationAppend, delegationId: string): void => {
+    journal.record('append.acknowledged', { append, delegationId })
+  }
+
+  /**
+   * The delegations still waiting for an answer, with the session each one is being answered on.
+   *
+   * The session is stored *with* the id rather than read back from the plugin when a step arrives, and that
+   * is not a micro-optimisation: it collapses two conditions into one. "Nothing is waiting on this" and
+   * "there is no session to speak into" cannot drift apart into two guards, one of which — the session
+   * dropped while its id is still waiting — no sequence of events can actually produce.
+   */
+  const waiting = new Map<string, RealtimeSession>()
+
   const handlers = createHandlers({
     transcript,
     session: () => session,
     ask: request => ctx.serial('realtime-agent/delegation', request),
-    timeoutMs: config.delegationTimeoutMs,
+    timeoutMs: () => live.delegationTimeoutMs,
     onClosed: () => {
       session = undefined
+      waiting.clear()
       journal.record('session.closed', {})
     },
     onSessionError: (error) => {
@@ -208,14 +327,38 @@ export function apply(ctx: Context, config: RealtimeAgentConfig): void {
       // Handed to the transport: all the host can observe, and no more (invariant 6).
       journal.record('speech.sent', { bytes: String(pcm16.byteLength) })
     },
-    onAcknowledged: (append, delegationId) => {
-      // The one place an acknowledgement can honestly be recorded: the seam's appends resolve on the
-      // provider's confirmation, not on the send. Note what is deliberately absent beside it — no entry
-      // anywhere claims the audio was heard, which is the pair invariant 6 exists to keep apart.
-      journal.record('append.acknowledged', { append, delegationId })
-    },
+    onDelegationStarted: (delegationId, current) => { waiting.set(delegationId, current) },
+    onDelegationSettled: (delegationId) => { waiting.delete(delegationId) },
+    onAcknowledged,
   })
 
+  /**
+   * Narrate a delegated turn's steps, on the session that is running it.
+   *
+   * A contribution like any other, so the fiber that registered it releases it. The emitter decides whether
+   * a step is spoken or silent — this half only carries it, because the session belongs here and nowhere
+   * else does.
+   *
+   * A failed append is a **dropped step**, not a broken turn: it is recorded so it is not silent, and it
+   * must not be confused with an answer that never arrived.
+   */
+  ctx.effect(function* () {
+    const dispose = ctx.on('realtime-agent/delegation-progress', (progress: RealtimeDelegationProgress) => {
+      // One condition, not two: the session a turn is waiting on *is* the authorisation to speak into it, and
+      // it travels with the delegation. A step for anything else has nowhere to go — the provider refuses an
+      // append for an id it does not know, and a finished turn's words must not be spoken into the next one.
+      const current = waiting.get(progress.id)
+      if (current === undefined) return
+      const append = progress.channel === 'commentary'
+        ? current.appendCommentary(progress.text, progress.id)
+        : current.appendThinking(progress.text, progress.id)
+      void append
+        .then(() => { onAcknowledged(progress.channel, progress.id) })
+        .catch(() => { journal.record('progress.dropped', { id: progress.id, channel: progress.channel }) })
+    })
+    yield () => { dispose() }
+  }, 'realtime-agent.progress')
+
   /**
    * Open a session, or return the one already open.
    *
@@ -249,6 +392,72 @@ export function apply(ctx: Context, config: RealtimeAgentConfig): void {
     await current?.close()
   }
 
+  /**
+   * The session's state, as only this plugin can report it.
+   *
+   * With nothing open it answers with what a start *would* use, rather than with nothing: "no session,
+   * and it would be `openai-live`/`gpt-live-1`" is a different — and more useful — answer than an
+   * absence, and it is the one a status surface needs to render a sensible control.
+   */
+  const status = (): RealtimeVoiceStatus => {
+    const current = session
+    if (current === undefined) {
+      return {
+        open: false,
+        provider: config.provider,
+        model: config.model,
+        ...config.voice === undefined ? {} : { voice: config.voice },
+      }
+    }
+    return {
+      open: true,
+      provider: current.started.provider,
+      model: current.started.model,
+      ...current.started.voice === undefined ? {} : { voice: current.started.voice },
+      sessionId: current.id,
+    }
+  }
+
+  /**
+   * Classify a failed request, carrying what a caller can act on and never the message.
+   *
+   * A seam failure carries its machine code and the remedy written to be relayed; anything else carries
+   * its **class** alone. The message is deliberately dropped: a provider error is exactly where a key
+   * turns up, and this plugin holds no credential to redact against — the same reason its journal
+   * records the class of a session failure rather than the text.
+   * @param error - whatever the attempt threw.
+   * @returns the structured refusal.
+   */
+  const refusalFor = (error: unknown): RealtimeSessionRefusal => {
+    if (error instanceof RealtimeError) {
+      return {
+        code: error.code,
+        ...error.detail?.remedy === undefined ? {} : { remedy: error.detail.remedy },
+      }
+    }
+    return { class: error instanceof Error ? error.name : typeof error }
+  }
+
+  /**
+   * Run a session request and report what it produced.
+   *
+   * The result is **returned as well as** reported on the bus, because a caller may be waiting for it:
+   * the control channel dispatches these with `serial`, so `start` can answer with the session that
+   * opened rather than with an acknowledgement that it asked. The failure still goes onto the bus, so a
+   * transport that merely emits keeps the behaviour it always had.
+   * @param attempt - the request to run.
+   * @returns whether it achieved what it asked for, and the state afterwards.
+   */
+  const requestSession = async (attempt: () => Promise<unknown>): Promise<RealtimeSessionRequestOutcome> => {
+    try {
+      await attempt()
+      return { ok: true, voice: status() }
+    } catch (error) {
+      ctx.emit('realtime-agent/error', error as Error)
+      return { ok: false, voice: status(), refusal: refusalFor(error) }
+    }
+  }
+
   // Tools are an effect, like every other contribution this plugin makes: the fiber that mounted them
   // releases them, so there is no separate teardown path to forget.
   ctx.effect(function* () {
@@ -279,17 +488,16 @@ export function apply(ctx: Context, config: RealtimeAgentConfig): void {
   }, 'realtime-agent.mic')
 
   // Session requests from the transport. The route knows when an authenticated client connects and the
-  // agent owns the session, so one event is the whole of the wiring between them.
+  // agent owns the session, so one event is the whole of the wiring between them. Each listener returns
+  // its outcome: `emit` ignores it, `serial` waits for it, and that is how the control channel can
+  // answer *what happened* rather than *that it was asked*.
   ctx.effect(function* () {
     const disposers = [
-      ctx.on('realtime-agent/start', () => {
-        // Fire-and-forget for the same reason `autoStart` is: a listener has no caller to catch a
-        // rejection, and the failure is reported on the bus rather than thrown into one.
-        void open().catch((error: Error) => { ctx.emit('realtime-agent/error', error) })
-      }),
-      ctx.on('realtime-agent/stop', () => {
-        void stop().catch((error: Error) => { ctx.emit('realtime-agent/error', error) })
-      }),
+      ctx.on('realtime-agent/start', () => requestSession(() => open())),
+      ctx.on('realtime-agent/stop', () => requestSession(() => stop())),
+      // A query, and the only listener that answers one. A mounted agent always answers, so a caller
+      // that gets `undefined` from the dispatch learns the agent row is absent rather than guessing.
+      ctx.on('realtime-agent/status', () => status()),
     ]
     yield () => { for (const dispose of disposers) dispose() }
   }, 'realtime-agent.session-requests')

package/src/transcript.ts

@@ -19,11 +19,16 @@ export class TranscriptBuffer {
   private chars = 0
 
   /**
-   * @param maxChars - character budget. Every value is accepted: a budget smaller than one line
-   *   degrades to keeping exactly the most recent line rather than to keeping nothing, because a
-   *   buffer that can hold nothing cannot answer any delegation at all.
+   * @param maxChars - character budget, read at every eviction.
+   *
+   * An accessor rather than a number because `maxTranscriptChars` is a **live** field
+   * (`docs/control-plane-fields.md`): the budget can change while the conversation runs, and a copy
+   * taken at construction would make the change look applied while the buffer kept the old one.
+   * Every value is accepted: a budget smaller than one line degrades to keeping exactly the most recent
+   * line rather than to keeping nothing, because a buffer that can hold nothing cannot answer any
+   * delegation at all.
    */
-  constructor(private readonly maxChars: number) {}
+  constructor(private readonly maxChars: () => number) {}
 
   /**
    * Record one fragment.
@@ -56,7 +61,8 @@ export class TranscriptBuffer {
 
   /** Drop the oldest lines until the budget is met, never dropping the most recent one. */
   private evict(): void {
-    while (this.chars > this.maxChars && this.buffered.length > 1) {
+    const budget = this.maxChars()
+    while (this.chars > budget && this.buffered.length > 1) {
       // The loop condition proves a first element exists, so this assertion is an invariant rather
       // than a hope — and it leaves no unreachable branch for the coverage gate to flag.
       this.chars -= this.buffered.shift()!.text.length

package/src/types.ts

@@ -72,3 +72,62 @@ export interface RealtimeAgentConfig {
   /** Character budget for the transcript carried on a delegation request. */
   maxTranscriptChars: number
 }
+
+/**
+ * The voice session's state, as the plugin that owns it is the only one able to report it.
+ *
+ * A **query's** answer rather than an event's payload: nothing emits this, and a caller that needs it
+ * asks through `realtime-agent/status` — which is also what makes "is voice live" answerable without
+ * opening anything to find out.
+ */
+export interface RealtimeVoiceStatus {
+  /** Whether a provider session is open now. */
+  readonly open: boolean
+  /**
+   * The registered route the session is on — or, when none is open, the one a start *would* use.
+   *
+   * Read from the session the provider actually accepted when there is one, because a provider may
+   * alias what was asked for.
+   */
+  readonly provider: string
+  /** The model the provider accepted, or the one configured when nothing is open. */
+  readonly model: string
+  /** The output voice, when one has been settled. */
+  readonly voice?: string
+  /** The provider's own session id. Present only while a session is open. */
+  readonly sessionId?: string
+}
+
+/**
+ * Why a session request did not succeed, in the shape a caller can act on.
+ *
+ * **Never the failure's message**, and that is a deliberate limitation rather than an oversight: the
+ * plugin that holds the credential is the adapter, and this one holds none to redact against — which is
+ * the same rule its journal follows, where a session failure is recorded as its *class*. What it can
+ * carry instead is more useful than the message: the seam's own machine code, and the `remedy` written
+ * to be relayed verbatim, both of which name a *setting* rather than its value.
+ */
+export interface RealtimeSessionRefusal {
+  /** The seam's machine code, when the failure was one of its classified ones (`NOT_CONFIGURED`, `RATE_LIMITED`, …). */
+  readonly code?: string
+  /** What to do about it, written to be relayed verbatim to whoever is trying to use the feature. */
+  readonly remedy?: string
+  /** The failing class, when there was no code to carry. A class, never an instance's message. */
+  readonly class?: string
+}
+
+/**
+ * What a request to open or close the voice session produced.
+ *
+ * The **outcome**, not an acknowledgement, because the two are the difference between "asked" and "it
+ * worked" — and collapsing them is the failure this project has already paid for once: a `start` that
+ * replied *requested* while the open silently failed teaches a user that the plugin is broken.
+ */
+export interface RealtimeSessionRequestOutcome {
+  /** Whether the request achieved what it asked for. */
+  readonly ok: boolean
+  /** The state **after** the attempt. */
+  readonly voice: RealtimeVoiceStatus
+  /** Present exactly when `ok` is false. */
+  readonly refusal?: RealtimeSessionRefusal
+}