@pellux/goodvibes-sdk 1.0.0 → 1.2.0

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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"}

package/dist/platform/voice/spoken-turn/controller.js

@@ -0,0 +1,448 @@
+import { summarizeError } from '../../utils/index.js';
+import { TtsTextChunker } from './text-chunker.js';
+/**
+ * How many synthesis requests may sit in the pipeline at once (synthesizing,
+ * waiting to play, or playing). 2 = the chunk being played plus ONE prefetch,
+ * so the next audio is ready the moment the current sink drains. Bounding
+ * this is what keeps a streaming answer from bursting N concurrent requests
+ * at the voice provider — ElevenLabs plans allow as few as 3 concurrent, and
+ * an unbounded burst 429s the whole turn. The SDK config schema has no tts.*
+ * key for pipeline tuning, so this is a constant by design.
+ */
+const SYNTHESIS_PIPELINE_WINDOW = 2;
+/**
+ * Upper bound for one merged synthesis request's text. The ElevenLabs
+ * provider passes request text through verbatim (no cap of its own); the API
+ * caps text per request by plan — 2,500 chars on the lowest tiers, 5,000 on
+ * most others. 1,500 stays safely under every plan while still folding a
+ * multi-paragraph answer into one or two requests.
+ */
+const SYNTHESIS_MERGE_MAX_CHARS = 1500;
+/**
+ * Backoff schedule for transient synthesis failures (429 rate/concurrency
+ * limits, transient 5xx, network drops): first retry after 1s, second after
+ * 2.5s, then the chunk is skipped honestly and the turn continues. The SDK's
+ * provider errors are plain Error strings with the HTTP status embedded — no
+ * Retry-After header is exposed — so the schedule is fixed, not server-driven.
+ */
+const SYNTHESIS_RETRY_DELAYS_MS = [1000, 2500];
+/**
+ * Source label attached to every synthesis request's metadata. Consumers may
+ * override it so provider-side telemetry attributes requests to the right
+ * surface (TUI, agent, webui).
+ */
+const DEFAULT_SYNTHESIS_SOURCE = 'goodvibes-sdk';
+/**
+ * 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 class SpokenTurnController {
+    pendingPrompt = null;
+    activeTurnId = null;
+    chunker = null;
+    chunkSequence = 0;
+    playbackChain = Promise.resolve();
+    abortControllers = new Set();
+    timer = null;
+    errorReportedForTurn = false;
+    noSinkNoticed = false;
+    /** Chunker output waiting to be merged into a synthesis request. */
+    pendingTexts = [];
+    /** Requests currently in the pipeline (synthesizing / waiting / playing). */
+    pipelineDepth = 0;
+    /** Bumped on every teardown so stale pipeline releases are ignored. */
+    pipelineGeneration = 0;
+    pumpScheduled = false;
+    /** Set when TURN_COMPLETED arrives; the turn releases once the pipeline drains. */
+    completedTurnId = null;
+    voiceService;
+    configManager;
+    sink;
+    notify;
+    source;
+    now;
+    setIntervalImpl;
+    clearIntervalImpl;
+    setTimeoutImpl;
+    clearTimeoutImpl;
+    constructor(options) {
+        this.voiceService = options.voiceService;
+        this.configManager = options.configManager;
+        this.sink = options.sink;
+        this.notify = options.notify;
+        this.source = options.source ?? DEFAULT_SYNTHESIS_SOURCE;
+        this.now = options.now ?? (() => Date.now());
+        this.setIntervalImpl = options.setInterval ?? setInterval;
+        this.clearIntervalImpl = options.clearInterval ?? clearInterval;
+        this.setTimeoutImpl = options.setTimeout ?? setTimeout;
+        this.clearTimeoutImpl = options.clearTimeout ?? clearTimeout;
+    }
+    submitNextTurn(prompt) {
+        const normalized = prompt.trim();
+        if (!normalized)
+            return false;
+        this.stop();
+        if (!this.sink.available) {
+            if (!this.noSinkNoticed) {
+                this.noSinkNoticed = true;
+                this.notify?.('[TTS] Text response will continue, but live audio is unavailable. Install mpv or ffplay.');
+            }
+            return false;
+        }
+        // Reset the no-sink notice if the sink becomes available again.
+        this.noSinkNoticed = false;
+        this.pendingPrompt = normalized;
+        return true;
+    }
+    /**
+     * 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) {
+        const wasActive = this.pendingPrompt !== null || this.activeTurnId !== null
+            || this.chunker !== null || this.abortControllers.size > 0;
+        this.pendingPrompt = null;
+        this.activeTurnId = null;
+        this.chunker?.reset();
+        this.chunker = null;
+        this.stopTimer();
+        this.resetPipeline();
+        for (const controller of this.abortControllers)
+            controller.abort();
+        this.abortControllers.clear();
+        this.sink.stop();
+        this.playbackChain = Promise.resolve();
+        this.errorReportedForTurn = false;
+        if (message && wasActive)
+            this.notify?.(`[TTS] ${message}`);
+        return wasActive;
+    }
+    /**
+     * 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.
+     */
+    async stopForExit(drainTimeoutMs = 2000) {
+        this.pendingPrompt = null;
+        this.activeTurnId = null;
+        this.chunker?.reset();
+        this.chunker = null;
+        this.stopTimer();
+        this.resetPipeline();
+        // Cancel chunks that have not started playing; the chunk currently in the
+        // sink is not in this set (its controller is released before playback).
+        for (const controller of this.abortControllers)
+            controller.abort();
+        this.abortControllers.clear();
+        await this.sink.waitForDrain(drainTimeoutMs);
+        // Backstop: anything still alive after the window is torn down hard.
+        this.stop();
+    }
+    handleTurnEvent(event) {
+        if (event.type === 'TURN_SUBMITTED') {
+            this.maybeStartTurn(event.turnId, event.prompt);
+            return;
+        }
+        if (!this.activeTurnId || event.turnId !== this.activeTurnId)
+            return;
+        if (event.type === 'STREAM_DELTA') {
+            this.queueTexts(this.chunker?.push(event.content) ?? []);
+            return;
+        }
+        if (event.type === 'STREAM_END') {
+            return;
+        }
+        if (event.type === 'TURN_COMPLETED') {
+            this.finishTurn(event.turnId);
+            return;
+        }
+        if (event.type === 'TURN_CANCEL' || event.type === 'TURN_ERROR' || event.type === 'PREFLIGHT_FAIL') {
+            this.stop(event.type === 'TURN_CANCEL' ? 'Spoken output stopped.' : 'Spoken output stopped because the turn did not complete.');
+        }
+    }
+    maybeStartTurn(turnId, prompt) {
+        if (!this.pendingPrompt)
+            return;
+        if (prompt.trim() !== this.pendingPrompt)
+            return;
+        this.pendingPrompt = null;
+        this.activeTurnId = turnId;
+        this.chunkSequence = 0;
+        this.errorReportedForTurn = false;
+        this.chunker = new TtsTextChunker({ now: this.now });
+        this.playbackChain = Promise.resolve();
+        this.resetPipeline();
+        this.startTimer();
+        this.notify?.(`[TTS] Live playback queued through ${this.sink.label}.`);
+    }
+    finishTurn(turnId) {
+        if (turnId !== this.activeTurnId)
+            return;
+        this.queueTexts(this.chunker?.flushAll() ?? []);
+        this.stopTimer();
+        this.completedTurnId = turnId;
+        // Nothing pending and nothing in flight releases immediately; otherwise
+        // the last pipeline slot to free performs the release.
+        this.maybeReleaseTurn();
+    }
+    resetPipeline() {
+        this.pendingTexts = [];
+        this.pipelineDepth = 0;
+        this.pipelineGeneration++;
+        this.completedTurnId = null;
+    }
+    startTimer() {
+        this.stopTimer();
+        this.timer = this.setIntervalImpl(() => {
+            if (!this.activeTurnId || !this.chunker)
+                return;
+            this.queueTexts(this.chunker.flushDue());
+        }, 250);
+    }
+    stopTimer() {
+        if (!this.timer)
+            return;
+        this.clearIntervalImpl(this.timer);
+        this.timer = null;
+    }
+    /**
+     * 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.
+     */
+    queueTexts(chunks) {
+        for (const chunk of chunks) {
+            if (chunk.trim())
+                this.pendingTexts.push(chunk);
+        }
+        if (this.pendingTexts.length > 0)
+            this.schedulePump();
+    }
+    /**
+     * 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.
+     */
+    schedulePump() {
+        if (this.pumpScheduled)
+            return;
+        this.pumpScheduled = true;
+        queueMicrotask(() => {
+            this.pumpScheduled = false;
+            this.pump();
+        });
+    }
+    pump() {
+        while (this.activeTurnId && this.pendingTexts.length > 0 && this.pipelineDepth < SYNTHESIS_PIPELINE_WINDOW) {
+            this.dispatchChunk(this.takeMergedText());
+        }
+        this.maybeReleaseTurn();
+    }
+    /** Merge everything pending into one request, capped at the per-request text limit. */
+    takeMergedText() {
+        let merged = '';
+        while (this.pendingTexts.length > 0) {
+            const next = this.pendingTexts[0];
+            if (!merged && next.length > SYNTHESIS_MERGE_MAX_CHARS) {
+                // A single oversized entry (e.g. a large end-of-turn flush): split at
+                // a word boundary under the per-request cap; the rest stays queued.
+                const cut = findSplitIndex(next, SYNTHESIS_MERGE_MAX_CHARS);
+                this.pendingTexts[0] = next.slice(cut).trim();
+                return next.slice(0, cut).trim();
+            }
+            if (merged && merged.length + 1 + next.length > SYNTHESIS_MERGE_MAX_CHARS)
+                break;
+            merged = merged ? `${merged} ${next}` : next;
+            this.pendingTexts.shift();
+        }
+        return merged;
+    }
+    dispatchChunk(text) {
+        const turnId = this.activeTurnId;
+        if (!turnId || !text.trim())
+            return;
+        const sequence = ++this.chunkSequence;
+        const generation = this.pipelineGeneration;
+        this.pipelineDepth++;
+        const abortController = new AbortController();
+        this.abortControllers.add(abortController);
+        const resultPromise = this.synthesizeWithRetry(text, turnId, sequence, abortController.signal)
+            .then((result) => ({ ok: true, result }))
+            .catch((error) => ({ ok: false, error }));
+        this.playbackChain = this.playbackChain.then(async () => {
+            try {
+                if (abortController.signal.aborted) {
+                    this.abortControllers.delete(abortController);
+                    return;
+                }
+                const result = await resultPromise;
+                this.abortControllers.delete(abortController);
+                // Re-check after the await: an abort that landed while synthesis was
+                // in flight (deliberate stop or exit) makes the rejection expected —
+                // it must not be reported, and it must not hard-stop a sink that may
+                // still be draining the previous chunk.
+                if (abortController.signal.aborted)
+                    return;
+                if (!result.ok) {
+                    // Retries are exhausted (or the failure was not transient). Skip
+                    // just this chunk and keep speaking the rest of the turn — a gap in
+                    // speech beats losing the whole response.
+                    this.reportSkippedChunk(result.error);
+                    return;
+                }
+                await this.sink.play(result.result.chunks, {
+                    format: String(result.result.format ?? 'mp3'),
+                    signal: abortController.signal,
+                });
+            }
+            finally {
+                this.releasePipelineSlot(generation);
+            }
+        }).catch((error) => {
+            this.abortControllers.delete(abortController);
+            this.reportError(error);
+        });
+    }
+    releasePipelineSlot(generation) {
+        if (generation !== this.pipelineGeneration)
+            return;
+        this.pipelineDepth = Math.max(0, this.pipelineDepth - 1);
+        if (this.pendingTexts.length > 0) {
+            this.schedulePump();
+            return;
+        }
+        this.maybeReleaseTurn();
+    }
+    maybeReleaseTurn() {
+        if (!this.completedTurnId || this.completedTurnId !== this.activeTurnId)
+            return;
+        if (this.pendingTexts.length > 0 || this.pipelineDepth > 0 || this.pumpScheduled)
+            return;
+        this.activeTurnId = null;
+        this.completedTurnId = null;
+        this.chunker = null;
+        this.abortControllers.clear();
+    }
+    async synthesizeWithRetry(text, turnId, sequence, signal) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.synthesize(text, turnId, sequence, signal);
+            }
+            catch (error) {
+                const retryable = attempt < SYNTHESIS_RETRY_DELAYS_MS.length
+                    && !signal.aborted
+                    && isTransientSynthesisError(error);
+                if (!retryable)
+                    throw error;
+                await this.delay(SYNTHESIS_RETRY_DELAYS_MS[attempt], signal);
+            }
+        }
+    }
+    /** Abortable backoff sleep — an abort clears the timer and rejects, so a stop mid-backoff leaves nothing running. */
+    delay(ms, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(new Error('Synthesis retry cancelled'));
+                return;
+            }
+            const timer = this.setTimeoutImpl(() => {
+                signal.removeEventListener('abort', onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                this.clearTimeoutImpl(timer);
+                reject(new Error('Synthesis retry cancelled'));
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    synthesize(text, turnId, sequence, signal) {
+        return this.voiceService.synthesizeStream(readOptionalConfigString(this.configManager, 'tts.provider'), {
+            text,
+            voiceId: readOptionalConfigString(this.configManager, 'tts.voice'),
+            format: 'mp3',
+            speed: readOptionalConfigNumber(this.configManager, 'tts.speed'),
+            signal,
+            metadata: {
+                source: this.source,
+                feature: 'live-tts',
+                turnId,
+                sequence,
+            },
+        });
+    }
+    /**
+     * One synthesis request failed after its retries. Report once per turn and
+     * keep going — the rest of the response still plays.
+     */
+    reportSkippedChunk(error) {
+        if (this.errorReportedForTurn)
+            return;
+        this.errorReportedForTurn = true;
+        this.notify?.(`[TTS] Skipping part of the spoken response — synthesis kept failing (${summarizeError(error)}). Playback continues with the rest.`);
+    }
+    reportError(error) {
+        if (this.errorReportedForTurn)
+            return;
+        this.errorReportedForTurn = true;
+        this.activeTurnId = null;
+        this.chunker = null;
+        this.stopTimer();
+        this.resetPipeline();
+        for (const controller of this.abortControllers)
+            controller.abort();
+        this.abortControllers.clear();
+        this.sink.stop();
+        this.playbackChain = Promise.resolve();
+        this.notify?.(`[TTS] Live playback stopped: ${summarizeError(error)}`);
+    }
+}
+/**
+ * Transient = worth a bounded retry: rate/concurrency limits (HTTP 429),
+ * transient server errors (5xx), and network-level drops. The SDK's voice
+ * providers throw plain Error strings with the HTTP status embedded in the
+ * message, so classification is by message content.
+ */
+function isTransientSynthesisError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    if (message.includes('429') || message.includes('rate limit') || message.includes('rate_limit')
+        || message.includes('too many requests') || message.includes('concurrent'))
+        return true;
+    if (/http 5\d\d/.test(message))
+        return true;
+    return message.includes('fetch failed') || message.includes('network')
+        || message.includes('timed out') || message.includes('timeout')
+        || message.includes('econnreset') || message.includes('socket');
+}
+/** Split point at or under `limit`, preferring the last word boundary. */
+function findSplitIndex(text, limit) {
+    const space = text.lastIndexOf(' ', limit);
+    return space > 0 ? space : limit;
+}
+function readOptionalConfigString(configManager, key) {
+    const value = String(configManager.get(key) ?? '').trim();
+    return value || undefined;
+}
+/**
+ * readOptionalConfigNumber — reads a numeric config value by key.
+ *
+ * Accepts a string key and casts it, returning undefined when the value is
+ * absent, zero, or not a finite positive number.
+ */
+function readOptionalConfigNumber(configManager, key) {
+    const raw = configManager.get(key);
+    const value = typeof raw === 'number' ? raw : parseFloat(String(raw ?? ''));
+    return isFinite(value) && value > 0 ? value : undefined;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Spoken-turn — the shared spoken-output (live TTS) policy engine.
+ *
+ * SDK owns POLICY: the sentence chunker, the bounded 2-slot synthesis window
+ * with merge coalescing, the transient-failure retry/backoff with honest
+ * skip-and-continue, and the turn-lifecycle state machine with drain-vs-
+ * interrupt semantics. Consumers own I/O by supplying an {@link AudioSink}
+ * (a terminal subprocess player, a browser Web Audio sink, or a test fake) and,
+ * where they run their own scheduler, injectable clocks/timers.
+ */
+export { SpokenTurnController } from './controller.js';
+export type { SpokenTurnControllerOptions } from './controller.js';
+export { TtsTextChunker, normalizeSpeechText } from './text-chunker.js';
+export type { TtsTextChunkerOptions } from './text-chunker.js';
+export type { AudioSink, AudioSinkPlaybackOptions } from './audio-sink.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/voice/spoken-turn/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/platform/voice/spoken-turn/index.js

@@ -0,0 +1,12 @@
+/**
+ * Spoken-turn — the shared spoken-output (live TTS) policy engine.
+ *
+ * SDK owns POLICY: the sentence chunker, the bounded 2-slot synthesis window
+ * with merge coalescing, the transient-failure retry/backoff with honest
+ * skip-and-continue, and the turn-lifecycle state machine with drain-vs-
+ * interrupt semantics. Consumers own I/O by supplying an {@link AudioSink}
+ * (a terminal subprocess player, a browser Web Audio sink, or a test fake) and,
+ * where they run their own scheduler, injectable clocks/timers.
+ */
+export { SpokenTurnController } from './controller.js';
+export { TtsTextChunker, normalizeSpeechText } from './text-chunker.js';

package/dist/platform/voice/spoken-turn/text-chunker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TtsTextChunker — turns a stream of provider content deltas into speech-sized
+ * chunks at sentence boundaries, with a max-length cut and a latency flush so a
+ * long unpunctuated run still starts speaking. This is pure policy (no I/O, no
+ * timers of its own — the caller drives `flushDue()` on its own clock), so it
+ * lives in the SDK and is shared verbatim by every voice consumer.
+ */
+export interface TtsTextChunkerOptions {
+    readonly minBoundaryChars?: number | undefined;
+    readonly maxChunkChars?: number | undefined;
+    readonly maxLatencyMs?: number | undefined;
+    readonly now?: (() => number) | undefined;
+}
+export declare class TtsTextChunker {
+    private buffer;
+    private firstBufferedAt;
+    private readonly minBoundaryChars;
+    private readonly maxChunkChars;
+    private readonly maxLatencyMs;
+    private readonly now;
+    constructor(options?: TtsTextChunkerOptions);
+    push(delta: string): string[];
+    flushDue(): string[];
+    flushAll(): string[];
+    reset(): void;
+    private drainReady;
+    private findBoundary;
+    private findLatestSentenceBoundary;
+    private findWordBoundaryBefore;
+    private takeChunk;
+}
+export declare function normalizeSpeechText(text: string): string;
+//# sourceMappingURL=text-chunker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"text-chunker.d.ts","sourceRoot":"","sources":["../../../../src/platform/voice/spoken-turn/text-chunker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,OAAO,GAAE,qBAA0B;IAO/C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAO7B,QAAQ,IAAI,MAAM,EAAE;IAMpB,QAAQ,IAAI,MAAM,EAAE;IASpB,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,0BAA0B;IAelC,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,SAAS;CAMlB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD"}