@pellux/goodvibes-sdk 1.1.0 → 1.2.0

package/dist/platform/runtime/memory-spine/recall-snapshot.d.ts

@@ -0,0 +1,74 @@
+/**
+ * recall-snapshot.ts — the sync-recall seam for the memory spine.
+ *
+ * THE PROBLEM. Per-turn memory recall wants to inject the recall-eligible records
+ * into the system prompt. But the prompt builder is SYNCHRONOUS
+ * (`Orchestrator.getSystemPrompt()` returns a string, not a promise), while a wire
+ * client's memory reads are ASYNCHRONOUS (a fetch to the adopted daemon). A sync
+ * function cannot await a wire read, so it cannot pull fresh memory over the wire
+ * inline.
+ *
+ * THE DESIGN (cached snapshot, freshness-stamped, honest staleness note). Rather
+ * than make the whole prompt path async (a large, cross-consumer refactor) or open
+ * the store file from a wire client (which would break the single-writer invariant),
+ * the spine maintains a CACHED recall snapshot:
+ *
+ *   1. an ASYNC pre-turn hook calls `MemorySpineClient.refreshRecallSnapshot()` —
+ *      this awaits the wire (or local) honest recall search and stamps the result
+ *      with a capture time and the access mode it came from;
+ *   2. the SYNC prompt builder calls `MemorySpineClient.recallSnapshot()` — this
+ *      returns the cached records immediately, with a freshly-computed age, a
+ *      `stale` flag, and a human-readable `note`.
+ *
+ * HONESTY. The snapshot never lies about its own freshness. If it has never been
+ * refreshed, it returns an EMPTY snapshot whose note says exactly that — never a
+ * silent empty that a reader would misread as "nothing was ever stored". If the last
+ * refresh is older than the staleness window, `stale` is true and the note says so,
+ * so an injector can choose to note the staleness in the prompt rather than present
+ * possibly-old memory as live. The `mode` records WHERE the snapshot was captured
+ * (local host store vs the adopted daemon over the wire), so the note never implies
+ * a wire read happened when it did not.
+ */
+import type { MemoryRecord } from '../../state/memory-store.js';
+import type { HonestMemorySearchResult } from '../../state/memory-recall-contract.js';
+import type { MemoryAccessMode } from './client.js';
+/** Default freshness window: a snapshot older than this reports `stale: true`. */
+export declare const DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS = 30000;
+export interface MemoryRecallRefreshOptions {
+    /**
+     * Apply the recall-injection contract when refreshing (exclude flagged records and
+     * drop sub-floor records, each exclusion counted). Defaults to TRUE — the snapshot
+     * exists for prompt injection, which must honor the recall floor. Pass false to
+     * capture an unfiltered browse set instead.
+     */
+    readonly recall?: boolean | undefined;
+}
+/**
+ * A freshness-stamped, synchronously-readable recall result. `records` is what a
+ * sync prompt builder injects; the rest is the honest receipt.
+ */
+export interface MemoryRecallSnapshot {
+    /** The recall-eligible records captured by the last refresh (empty until first refresh). */
+    readonly records: readonly MemoryRecord[];
+    /** The full honest search envelope the records came from (null until first refresh). */
+    readonly search: HonestMemorySearchResult | null;
+    /** When the snapshot was captured (epoch ms), or null if never refreshed. */
+    readonly capturedAt: number | null;
+    /** Age of the snapshot in ms at read time, or null if never refreshed. */
+    readonly ageMs: number | null;
+    /** True when the snapshot is older than the staleness window (or never captured). */
+    readonly stale: boolean;
+    /** Where the snapshot was captured from — 'client' (over the wire) or 'local'. */
+    readonly mode: MemoryAccessMode;
+    /** An honest, human-readable freshness/degradation note — never silent. */
+    readonly note: string;
+}
+/** The snapshot returned before any refresh has happened — empty, and it says so. */
+export declare function emptyRecallSnapshot(mode: MemoryAccessMode): MemoryRecallSnapshot;
+/**
+ * Build a snapshot from an honest search envelope captured at `capturedAt`, with age
+ * and staleness computed against `now`. The `note` states the source, the age, and
+ * — when stale — that the records may be out of date.
+ */
+export declare function buildRecallSnapshot(search: HonestMemorySearchResult, mode: MemoryAccessMode, capturedAt: number, staleAfterMs: number, now?: number): MemoryRecallSnapshot;
+//# sourceMappingURL=recall-snapshot.d.ts.map

package/dist/platform/runtime/memory-spine/recall-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-snapshot.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/memory-spine/recall-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,kFAAkF;AAClF,eAAO,MAAM,sCAAsC,QAAS,CAAC;AAE7D,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,CAWhF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,GAAG,GAAE,MAAmB,GACvB,oBAAoB,CAqBtB"}

package/dist/platform/runtime/memory-spine/recall-snapshot.js

@@ -0,0 +1,74 @@
+/**
+ * recall-snapshot.ts — the sync-recall seam for the memory spine.
+ *
+ * THE PROBLEM. Per-turn memory recall wants to inject the recall-eligible records
+ * into the system prompt. But the prompt builder is SYNCHRONOUS
+ * (`Orchestrator.getSystemPrompt()` returns a string, not a promise), while a wire
+ * client's memory reads are ASYNCHRONOUS (a fetch to the adopted daemon). A sync
+ * function cannot await a wire read, so it cannot pull fresh memory over the wire
+ * inline.
+ *
+ * THE DESIGN (cached snapshot, freshness-stamped, honest staleness note). Rather
+ * than make the whole prompt path async (a large, cross-consumer refactor) or open
+ * the store file from a wire client (which would break the single-writer invariant),
+ * the spine maintains a CACHED recall snapshot:
+ *
+ *   1. an ASYNC pre-turn hook calls `MemorySpineClient.refreshRecallSnapshot()` —
+ *      this awaits the wire (or local) honest recall search and stamps the result
+ *      with a capture time and the access mode it came from;
+ *   2. the SYNC prompt builder calls `MemorySpineClient.recallSnapshot()` — this
+ *      returns the cached records immediately, with a freshly-computed age, a
+ *      `stale` flag, and a human-readable `note`.
+ *
+ * HONESTY. The snapshot never lies about its own freshness. If it has never been
+ * refreshed, it returns an EMPTY snapshot whose note says exactly that — never a
+ * silent empty that a reader would misread as "nothing was ever stored". If the last
+ * refresh is older than the staleness window, `stale` is true and the note says so,
+ * so an injector can choose to note the staleness in the prompt rather than present
+ * possibly-old memory as live. The `mode` records WHERE the snapshot was captured
+ * (local host store vs the adopted daemon over the wire), so the note never implies
+ * a wire read happened when it did not.
+ */
+/** Default freshness window: a snapshot older than this reports `stale: true`. */
+export const DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS = 30_000;
+const EMPTY_SEARCH_RECORDS = Object.freeze([]);
+/** The snapshot returned before any refresh has happened — empty, and it says so. */
+export function emptyRecallSnapshot(mode) {
+    return {
+        records: EMPTY_SEARCH_RECORDS,
+        search: null,
+        capturedAt: null,
+        ageMs: null,
+        stale: true,
+        mode,
+        note: 'memory recall snapshot not yet captured — no memory injected this turn. '
+            + 'Call refreshRecallSnapshot() in an async pre-turn hook before the synchronous prompt build.',
+    };
+}
+/**
+ * Build a snapshot from an honest search envelope captured at `capturedAt`, with age
+ * and staleness computed against `now`. The `note` states the source, the age, and
+ * — when stale — that the records may be out of date.
+ */
+export function buildRecallSnapshot(search, mode, capturedAt, staleAfterMs, now = Date.now()) {
+    const ageMs = Math.max(0, now - capturedAt);
+    const stale = ageMs > staleAfterMs;
+    const source = mode === 'client' ? 'over the wire from the adopted daemon' : 'from the local store';
+    const freshness = stale
+        ? `STALE — captured ${ageMs}ms ago (older than the ${staleAfterMs}ms freshness window); a refresh is due`
+        : `captured ${ageMs}ms ago`;
+    const degraded = search.indexUnavailableReason
+        ? ` Recall degraded to a literal scan: ${search.indexUnavailableReason}.`
+        : '';
+    const caveat = search.caveat ? ` ${search.caveat}.` : '';
+    return {
+        records: search.records,
+        search,
+        capturedAt,
+        ageMs,
+        stale,
+        mode,
+        note: `memory recall snapshot ${source}, ${freshness}; ${search.records.length} record(s) recall-eligible.`
+            + degraded + caveat,
+    };
+}

package/dist/platform/version.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-let version = '1.1.0';
+let version = '1.2.0';
 try {
     const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf-8'));
     version = pkg.version ?? version;

package/dist/platform/voice/index.d.ts

@@ -4,4 +4,6 @@ export type { VoiceProviderDescriptor } from './provider-registry.js';
 export { VoiceService } from './service.js';
 export type { VoiceServiceStatus } from './service.js';
 export { ensureBuiltinVoiceProviders } from './builtin-providers.js';
+export { SpokenTurnController, TtsTextChunker, normalizeSpeechText } from './spoken-turn/index.js';
+export type { SpokenTurnControllerOptions, TtsTextChunkerOptions, AudioSink, AudioSinkPlaybackOptions, } from './spoken-turn/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/voice/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/voice/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/voice/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAIrE,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnG,YAAY,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,SAAS,EACT,wBAAwB,GACzB,MAAM,wBAAwB,CAAC"}

package/dist/platform/voice/index.js

@@ -1,3 +1,6 @@
 export { VoiceProviderRegistry } from './provider-registry.js';
 export { VoiceService } from './service.js';
 export { ensureBuiltinVoiceProviders } from './builtin-providers.js';
+// Spoken-turn (live TTS) policy engine — shared behavioral contract; consumers
+// inject an AudioSink for I/O. See ./spoken-turn.
+export { SpokenTurnController, TtsTextChunker, normalizeSpeechText } from './spoken-turn/index.js';

package/dist/platform/voice/spoken-turn/audio-sink.d.ts

@@ -0,0 +1,111 @@
+import type { VoiceAudioChunk } from '../types.js';
+/**
+ * AudioSink — the injectable I/O boundary the spoken-turn policy engine plays
+ * through. The SDK owns POLICY (chunking, the bounded synthesis window, merge
+ * coalescing, retry/backoff, the turn state machine); a sink owns I/O (turning
+ * an ordered stream of audio bytes into sound and reporting when it has stopped
+ * making sound). The controller never spawns a process, opens a device, or
+ * touches Web Audio — it only talks to this interface, so the same policy runs
+ * unchanged behind a terminal subprocess player, a browser Web Audio sink, or a
+ * test fake.
+ *
+ * ## Behavioral contract
+ *
+ * The controller depends on these guarantees, not on any implementation detail:
+ *
+ * 1. **Readiness / head survival.** `play()` must not drop the leading bytes of
+ *    the stream while the underlying output is still coming up. A subprocess
+ *    sink holds the first byte until the player has actually exec'd (its spawn
+ *    event); a browser sink holds until the MediaSource `sourceopen` /
+ *    SourceBuffer is ready. The controller writes the whole stream and trusts
+ *    the sink to have played the head — it does not re-send or pre-buffer.
+ *    `available` is the coarse, synchronous readiness signal (is any output
+ *    device usable at all); per-call readiness is internal to `play()`.
+ *
+ * 2. **Natural drain plays everything.** When the input stream ends without an
+ *    abort, `play()` resolves only after the last buffered sample has been
+ *    heard — never at end-of-input. Truncating the tail of a response is the
+ *    bug this contract exists to prevent.
+ *
+ * 3. **Abort cuts immediately.** When `options.signal` aborts (a deliberate
+ *    interrupt — new turn, Ctrl+C, /tts stop, turn cancel), `play()` stops
+ *    emitting sound and resolves promptly; it must NOT wait on a graceful
+ *    drain. `stop()` is the same instant cut driven imperatively rather than by
+ *    a signal.
+ *
+ * 4. **Bounded exit drain.** `waitForDrain(timeoutMs)` resolves when the sound
+ *    currently playing finishes naturally OR after `timeoutMs`, whichever comes
+ *    first, and resolves immediately when nothing is playing. The exit path
+ *    uses this to let the final audio of a finished response play out inside a
+ *    short window instead of being cut mid-word.
+ *
+ * ## Web Audio / browser sink mapping (proof the interface fits a browser)
+ *
+ * A browser sink for the webui voice build implements this same interface over
+ * streaming MP3 into MediaSource; no interface change is required:
+ *
+ * - `available` -> `('MediaSource' in window) && MediaSource.isTypeSupported('audio/mpeg')`
+ *   (fall back to Web Audio `decodeAudioData` where MSE is absent).
+ * - `play(chunks, { format, signal })` ->
+ *     - create a `MediaSource`, attach it to an `HTMLAudioElement` via
+ *       `URL.createObjectURL`, and `await` its `sourceopen` event — this is the
+ *       readiness gate (contract 1);
+ *     - `addSourceBuffer(mimeFor(format))` where `mimeFor('mp3') === 'audio/mpeg'`
+ *       (the same `format` string the controller forwards from the synthesis
+ *       result), then `await audioEl.play()`;
+ *     - `for await (const chunk of chunks)` -> `sourceBuffer.appendBuffer(chunk.data)`,
+ *       awaiting each `updateend`, honoring `signal.aborted` between chunks;
+ *     - on input end without abort: `mediaSource.endOfStream()` and resolve on
+ *       the audio element's `ended` event -> natural drain (contract 2);
+ *     - on `signal` abort: `audioEl.pause()`, `sourceBuffer.abort()`,
+ *       `mediaSource.endOfStream()`, revoke the object URL, resolve now
+ *       (contract 3).
+ * - `stop()` -> the same teardown as the abort branch, driven imperatively.
+ * - `waitForDrain(timeoutMs)` -> resolve on the audio element's `ended` event or
+ *   a `setTimeout(timeoutMs)`, whichever fires first (contract 4).
+ *
+ * `VoiceAudioChunk.data` is a `Uint8Array`, which `appendBuffer` accepts
+ * directly, and the `format` string maps 1:1 to a MediaSource MIME type, so the
+ * byte-and-format shape the controller emits is exactly what a browser sink
+ * consumes. (The subprocess sink — mpv/ffplay over stdin — stays consumer-side
+ * and is not part of the SDK.)
+ */
+export interface AudioSink {
+    /** Human-readable sink name for status lines (e.g. 'mpv', 'web-audio'). */
+    readonly label: string;
+    /**
+     * Coarse, synchronous readiness: is any output device usable at all. When
+     * false the controller arms nothing and reports the graceful-degradation
+     * notice instead of attempting playback.
+     */
+    readonly available: boolean;
+    /**
+     * Play an ordered stream of audio chunks to completion. Resolves after the
+     * final sample is heard on a natural end, or promptly on abort. See the
+     * interface contract above for readiness, drain, and abort obligations.
+     */
+    play(chunks: AsyncIterable<VoiceAudioChunk>, options: AudioSinkPlaybackOptions): Promise<void>;
+    /** Instant cut: stop emitting sound now and release the output. Idempotent; a no-op when idle. */
+    stop(): void;
+    /**
+     * Resolves once the currently playing sound has finished naturally or after
+     * `timeoutMs`, whichever comes first; resolves immediately when nothing is
+     * playing. The bounded exit drain — see contract 4.
+     */
+    waitForDrain(timeoutMs: number): Promise<void>;
+}
+export interface AudioSinkPlaybackOptions {
+    /**
+     * Container/codec hint for the byte stream (e.g. 'mp3'), forwarded verbatim
+     * from the synthesis result's `format`. A subprocess sink maps it to a
+     * demuxer flag; a browser sink maps it to a MediaSource MIME type. Omitted or
+     * a value containing '/' (already a MIME type) leaves the sink on its default.
+     */
+    readonly format?: string | undefined;
+    /**
+     * Deliberate-interrupt signal. When it aborts, playback cuts immediately (no
+     * graceful drain) and `play()` resolves. Absence means "play to natural end".
+     */
+    readonly signal?: AbortSignal | undefined;
+}
+//# sourceMappingURL=audio-sink.d.ts.map

package/dist/platform/voice/spoken-turn/audio-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-sink.d.ts","sourceRoot":"","sources":["../../../../src/platform/voice/spoken-turn/audio-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/F,kGAAkG;IAClG,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C"}

package/dist/platform/voice/spoken-turn/audio-sink.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/voice/spoken-turn/controller.d.ts

@@ -0,0 +1,117 @@
+import type { ConfigManager } from '../../config/index.js';
+import type { TurnEvent } from '../../../events/turn.js';
+import type { VoiceService } from '../service.js';
+import type { AudioSink } from './audio-sink.js';
+export interface SpokenTurnControllerOptions {
+    readonly voiceService: Pick<VoiceService, 'synthesizeStream'>;
+    readonly configManager: Pick<ConfigManager, 'get'>;
+    /** The injectable I/O boundary. See {@link AudioSink}. */
+    readonly sink: AudioSink;
+    readonly notify?: ((message: string) => void) | undefined;
+    /**
+     * Attribution label recorded in each synthesis request's metadata.source
+     * (e.g. 'goodvibes-tui', 'goodvibes-agent', 'goodvibes-webui'). Defaults to
+     * 'goodvibes-sdk'.
+     */
+    readonly source?: string | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly setInterval?: typeof setInterval | undefined;
+    readonly clearInterval?: typeof clearInterval | undefined;
+    /** Injectable clock for retry backoff timers (tests use fakes). */
+    readonly setTimeout?: typeof setTimeout | undefined;
+    readonly clearTimeout?: typeof clearTimeout | undefined;
+}
+/**
+ * SpokenTurnController — the shared spoken-output policy engine. It watches a
+ * turn's lifecycle events, chunks the streamed answer into speech-sized pieces,
+ * merges and dispatches synthesis requests through a bounded 2-slot window with
+ * retry/backoff, and drives an injected {@link AudioSink} with honest
+ * drain-vs-interrupt semantics. All I/O is the sink's; this class is pure
+ * policy and runs unchanged in the terminal, the agent, and the browser.
+ */
+export declare class SpokenTurnController {
+    private pendingPrompt;
+    private activeTurnId;
+    private chunker;
+    private chunkSequence;
+    private playbackChain;
+    private readonly abortControllers;
+    private timer;
+    private errorReportedForTurn;
+    private noSinkNoticed;
+    /** Chunker output waiting to be merged into a synthesis request. */
+    private pendingTexts;
+    /** Requests currently in the pipeline (synthesizing / waiting / playing). */
+    private pipelineDepth;
+    /** Bumped on every teardown so stale pipeline releases are ignored. */
+    private pipelineGeneration;
+    private pumpScheduled;
+    /** Set when TURN_COMPLETED arrives; the turn releases once the pipeline drains. */
+    private completedTurnId;
+    private readonly voiceService;
+    private readonly configManager;
+    private readonly sink;
+    private readonly notify?;
+    private readonly source;
+    private readonly now;
+    private readonly setIntervalImpl;
+    private readonly clearIntervalImpl;
+    private readonly setTimeoutImpl;
+    private readonly clearTimeoutImpl;
+    constructor(options: SpokenTurnControllerOptions);
+    submitNextTurn(prompt: string): boolean;
+    /**
+     * Returns whether speech was actually ACTIVE when stopped. The notice only
+     * prints in that case — stop() on an idle controller used to notify anyway,
+     * spamming "[TTS] Spoken output stopped." on every Ctrl+C (an earlier replay
+     * fix); callers use the return to decide whether the press "did a
+     * job" (see handleCtrlC's consume-on-speech-stop).
+     */
+    stop(message?: string): boolean;
+    /**
+     * Exit-path teardown: drops everything not yet audible (pending arm,
+     * buffered text, queued chunks) but lets the audio the user is already
+     * hearing finish naturally, capped at `drainTimeoutMs`, before the hard
+     * stop. Deliberate interrupts (Ctrl+C, /tts stop, turn cancel) keep their
+     * instant path through stop(); this is only for exiting the app while the
+     * final audio of a completed response is still draining.
+     */
+    stopForExit(drainTimeoutMs?: number): Promise<void>;
+    handleTurnEvent(event: TurnEvent): void;
+    private maybeStartTurn;
+    private finishTurn;
+    private resetPipeline;
+    private startTimer;
+    private stopTimer;
+    /**
+     * Chunker output does NOT map 1:1 to synthesis requests. Text queues here
+     * and the pump merges everything pending into one request whenever a
+     * pipeline slot is free — so the request count tracks how often the model
+     * out-paces the audio, not how many sentences it wrote. A short answer that
+     * arrives before the first pump tick is exactly one request.
+     */
+    private queueTexts;
+    /**
+     * Deferred one tick so text delivered in the same synchronous burst (fast
+     * deltas, or a turn that completes instantly) coalesces into a single
+     * request instead of firing per sentence boundary.
+     */
+    private schedulePump;
+    private pump;
+    /** Merge everything pending into one request, capped at the per-request text limit. */
+    private takeMergedText;
+    private dispatchChunk;
+    private releasePipelineSlot;
+    private maybeReleaseTurn;
+    private synthesizeWithRetry;
+    /** Abortable backoff sleep — an abort clears the timer and rejects, so a stop mid-backoff leaves nothing running. */
+    private delay;
+    private synthesize;
+    /**
+     * One synthesis request failed after its retries. Report once per turn and
+     * keep going — the rest of the response still plays.
+     */
+    private reportSkippedChunk;
+    private reportError;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/platform/voice/spoken-turn/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../../src/platform/voice/spoken-turn/controller.ts"],"names":[],"mappings":"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"}