@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/client/api/state.js

@@ -0,0 +1,29 @@
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Returns the current runtime lifecycle state.
+ *
+ * Safe to call from any lifecycle state — `state()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `resume()`).
+ *
+ * @returns The current lifecycle state:
+ *   - `"active"`: all SDK operations are allowed
+ *   - `"suspending"` | `"suspended"` | `"resuming"`: non-lifecycle operations
+ *     throw `LifecycleOperationBlockedError`
+ *
+ * @throws {InvalidResponseError} When the response envelope does not match the request type.
+ *
+ * @example
+ * // Branch on lifecycle state before issuing work
+ * const current = await state();
+ * if (current !== "active") {
+ *   await resume();
+ * }
+ */
+export async function state() {
+    const response = await send({ type: 'state' });
+    if (response.type !== 'state') {
+        throw new InvalidResponseError('state');
+    }
+    return response.state;
+}

package/dist/src/client/api/subscribe-logs.d.ts

@@ -0,0 +1,28 @@
+import type { LoggingStreamResponse } from '@qvac/inference/surface';
+export type ServerLogHandler = (log: LoggingStreamResponse) => void;
+/**
+ * Subscribes to every server-side log through a single stream: SDK server logs,
+ * per-model addon logs (llamacpp, whispercpp, …) for all loaded models, and RAG
+ * logs — without having to open a {@link loggingStream} per id.
+ *
+ * Each delivered log keeps its origin in `log.id`: `SDK_LOG_ID` for SDK server
+ * logs, the model id for model logs, or the RAG workspace key. Use it to tell the
+ * sources apart.
+ *
+ * Internally this opens a {@link loggingStream} on the reserved `SDK_ALL_LOG_ID`
+ * stream that the worker fans every log into.
+ *
+ * @param handler - called once per log line.
+ * @returns a function that stops the subscription.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeServerLogs((log) => {
+ *   console.log(`[${log.level}] ${log.id} ${log.namespace}: ${log.message}`);
+ * });
+ * // later
+ * unsubscribe();
+ * ```
+ */
+export declare function subscribeServerLogs(handler: ServerLogHandler): () => void;
+//# sourceMappingURL=subscribe-logs.d.ts.map

package/dist/src/client/api/suspend.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Suspends the SDK runtime: pauses all registered Hyperswarm and Corestore
+ * resources and engages the lifecycle gate so non-lifecycle operations are
+ * blocked until `resume()` is called.
+ *
+ * Safe to call from any lifecycle state — `suspend()` is never blocked by the
+ * lifecycle gate (along with `resume()` and `state()`). Idempotent.
+ *
+ * After `suspend()` resolves, runtime state is `"suspended"` and any non-
+ * lifecycle SDK operation throws `LifecycleOperationBlockedError` until
+ * `resume()` is called.
+ *
+ * In-flight operations started before suspend:
+ *   - P2P / Hyperdrive downloads: stall cleanly, continue after `resume()`
+ *   - HTTP downloads: bypass suspend entirely (bytes keep flowing)
+ *   - Local native inference: runs to completion regardless
+ *
+ * @throws {RPCError} When one or more resources fail to suspend. The runtime
+ *   still commits to `"suspended"` so callers can recover with `resume()`.
+ *
+ * @example
+ * // Background handler
+ * await suspend();
+ * console.log(await state()); // "suspended"
+ */
+export declare function suspend(): Promise<void>;
+//# sourceMappingURL=suspend.d.ts.map

package/dist/src/client/api/suspend.js

@@ -0,0 +1,33 @@
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Suspends the SDK runtime: pauses all registered Hyperswarm and Corestore
+ * resources and engages the lifecycle gate so non-lifecycle operations are
+ * blocked until `resume()` is called.
+ *
+ * Safe to call from any lifecycle state — `suspend()` is never blocked by the
+ * lifecycle gate (along with `resume()` and `state()`). Idempotent.
+ *
+ * After `suspend()` resolves, runtime state is `"suspended"` and any non-
+ * lifecycle SDK operation throws `LifecycleOperationBlockedError` until
+ * `resume()` is called.
+ *
+ * In-flight operations started before suspend:
+ *   - P2P / Hyperdrive downloads: stall cleanly, continue after `resume()`
+ *   - HTTP downloads: bypass suspend entirely (bytes keep flowing)
+ *   - Local native inference: runs to completion regardless
+ *
+ * @throws {RPCError} When one or more resources fail to suspend. The runtime
+ *   still commits to `"suspended"` so callers can recover with `resume()`.
+ *
+ * @example
+ * // Background handler
+ * await suspend();
+ * console.log(await state()); // "suspended"
+ */
+export async function suspend() {
+    const response = await send({ type: 'suspend' });
+    if (response.type !== 'suspend') {
+        throw new InvalidResponseError('suspend');
+    }
+}

package/dist/src/client/api/text-to-speech.d.ts

@@ -0,0 +1,74 @@
+import { type TtsClientParamsInput, type RPCOptions, type TtsResponse, type TextToSpeechStreamClientParams, type TextToSpeechStreamSession, type TextToSpeechStreamResult } from '@qvac/inference/surface';
+/**
+ * Fan-out queue that lets multiple consumers iterate the same TTS response
+ * stream independently. Items are retained only until every active subscriber
+ * has consumed them, then trimmed from the queue.
+ *
+ * The source is injected as an `AsyncIterable<TtsResponse>` so this class can
+ * be unit-tested directly against the real implementation (without mocking
+ * the RPC layer). Production callsites adapt `streamRpc(...)` via
+ * `ttsResponseSource()` below.
+ *
+ * Exported for test use; not part of the public SDK surface.
+ */
+export declare class TtsMulticast {
+    private readonly queue;
+    private readonly waiters;
+    private readonly subscriberIndexes;
+    private ended;
+    private fatal;
+    private readonly resolvePumpDone;
+    private readonly rejectPumpDone;
+    readonly done: Promise<boolean>;
+    constructor(source: AsyncIterable<TtsResponse>);
+    subscribe(): AsyncGenerator<TtsResponse>;
+    private notify;
+    private trimConsumed;
+    private unsubscribe;
+    private pump;
+    private drain;
+}
+/**
+ * Converts text to speech audio using a loaded TTS model.
+ *
+ * Three modes selected by `params.stream` and `params.sentenceStream`:
+ *
+ * - `stream: false` (default) — collect all PCM samples and resolve once via
+ *   `result.buffer` (`Promise<number[]>`). `bufferStream` is empty.
+ * - `stream: true` — yield PCM samples through `result.bufferStream`
+ *   (`AsyncGenerator<number>`) as they arrive. `buffer` resolves to an empty
+ *   array.
+ * - `stream: true, sentenceStream: true` — also exposes `result.chunkUpdates`
+ *   (`AsyncGenerator<TtsSentenceChunkUpdate>`) so callers can mux per-sentence
+ *   metadata with the audio. Multiple consumers can iterate the response
+ *   independently via the underlying `TtsMulticast`.
+ *
+ * `result.done` resolves to `true` when synthesis completes cleanly, `false`
+ * if the consumer breaks out before the terminal frame, or rejects on a
+ * pipeline error. Awaiting `done` is safe even when no stream is iterated.
+ *
+ * @param params - TTS request parameters (see `TtsClientParamsInput`).
+ * @param options - Optional RPC options (timeout, profiling, force new connection).
+ * @returns A `TextToSpeechStreamResult` with `bufferStream`, `buffer`, `done`,
+ *          and (when `sentenceStream: true`) `chunkUpdates`.
+ * @throws {TextToSpeechStreamFailedError} When `sentenceStream: true` is paired
+ *         with `stream: false`, or when the underlying RPC stream errors.
+ */
+export declare function textToSpeech(params: TtsClientParamsInput, options?: RPCOptions): TextToSpeechStreamResult;
+export declare function encodeTextToSpeechFragment(textFragment: string | Uint8Array): Uint8Array<ArrayBufferLike>;
+/**
+ * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or
+ * Uint8Array should be a complete UTF-8 fragment. The worker forwards them to the TTS streaming handler
+ * (optional sentence accumulation via request fields). Iterate the session for `TextToSpeechStreamResponse`
+ * lines (PCM in `buffer`, optional `chunkIndex` / `sentenceChunk`) until `done`.
+ *
+ * @param params - The loaded TTS model, input mode, buffering controls, and
+ *   optional voice settings.
+ * @param options - Optional timeout, profiling, and connection settings.
+ * @returns A single-consumer duplex session for writing text fragments and
+ *   iterating PCM response frames.
+ * @throws {TextToSpeechStreamFailedError} When the session is iterated more
+ *   than once, receives a server error, or is written after closing.
+ */
+export declare function textToSpeechStream(params: TextToSpeechStreamClientParams, options?: RPCOptions): Promise<TextToSpeechStreamSession>;
+//# sourceMappingURL=text-to-speech.d.ts.map

package/dist/src/client/api/text-to-speech.js

@@ -0,0 +1,463 @@
+import { textToSpeechStreamResponseSchema, textToSpeechStreamRequestSchema, ttsClientParamsSchema } from '@qvac/inference/surface';
+import { stream as streamRpc, duplex } from '../rpc/rpc-client.js';
+import { getClientLogger } from '../../logging/index.js';
+import { TextToSpeechStreamFailedError } from '../../utils/errors-client.js';
+import { parseClientInput } from '../parse-input.js';
+const logger = getClientLogger();
+/**
+ * Fan-out queue that lets multiple consumers iterate the same TTS response
+ * stream independently. Items are retained only until every active subscriber
+ * has consumed them, then trimmed from the queue.
+ *
+ * The source is injected as an `AsyncIterable<TtsResponse>` so this class can
+ * be unit-tested directly against the real implementation (without mocking
+ * the RPC layer). Production callsites adapt `streamRpc(...)` via
+ * `ttsResponseSource()` below.
+ *
+ * Exported for test use; not part of the public SDK surface.
+ */
+export class TtsMulticast {
+    queue = [];
+    waiters = [];
+    subscriberIndexes = [];
+    ended = false;
+    fatal;
+    resolvePumpDone;
+    rejectPumpDone;
+    done;
+    constructor(source) {
+        let resolve;
+        let reject;
+        this.done = new Promise((r, rj) => {
+            resolve = r;
+            reject = rj;
+        });
+        // Silence unhandled-rejection warnings when the caller never awaits
+        // `done` (e.g. only iterates the buffer stream). Re-awaits still get the
+        // rejection because the underlying promise state is unchanged.
+        this.done.catch(() => { });
+        this.resolvePumpDone = resolve;
+        this.rejectPumpDone = reject;
+        void this.pump(source);
+    }
+    subscribe() {
+        const subIdx = this.subscriberIndexes.length;
+        this.subscriberIndexes.push(0);
+        return this.drain(subIdx);
+    }
+    notify() {
+        for (const fn of this.waiters.splice(0))
+            fn();
+    }
+    trimConsumed() {
+        if (this.subscriberIndexes.length === 0)
+            return;
+        // `Number.POSITIVE_INFINITY` marks an unsubscribed slot; ignore those when
+        // computing how far every live subscriber has advanced.
+        const minIndex = Math.min(...this.subscriberIndexes);
+        if (!Number.isFinite(minIndex))
+            return;
+        if (minIndex > 0) {
+            this.queue.splice(0, minIndex);
+            for (let j = 0; j < this.subscriberIndexes.length; j++) {
+                const v = this.subscriberIndexes[j] ?? 0;
+                if (Number.isFinite(v))
+                    this.subscriberIndexes[j] = v - minIndex;
+            }
+        }
+    }
+    unsubscribe(subIdx) {
+        // Park the slot at +Infinity instead of splicing so every other
+        // subscriber's `subIdx` stays valid. `trimConsumed` filters these out.
+        this.subscriberIndexes[subIdx] = Number.POSITIVE_INFINITY;
+        this.trimConsumed();
+    }
+    async pump(source) {
+        try {
+            for await (const response of source) {
+                // The server owns this response schema; per-frame Zod .parse() adds
+                // non-trivial CPU overhead for large sentences with many PCM frames.
+                // Rely on the discriminated union narrowing at the RPC boundary and
+                // skip re-validation here.
+                this.queue.push(response);
+                this.notify();
+                if (response.done)
+                    break;
+            }
+        }
+        catch (e) {
+            this.fatal = e instanceof Error ? e : new Error(String(e));
+        }
+        finally {
+            this.ended = true;
+            this.notify();
+            if (this.fatal) {
+                // Reject rather than resolving false so callers awaiting `done`
+                // with no iteration — and callers iterating drain() — both see the
+                // real error instead of a silent sentinel.
+                this.rejectPumpDone(this.fatal);
+            }
+            else {
+                this.resolvePumpDone(true);
+            }
+        }
+    }
+    async *drain(subIdx) {
+        // If the consumer breaks out of a `for await` (or calls `.return()` /
+        // throws), this generator's finally block runs; release the slot so it
+        // no longer pins `trimConsumed`'s min-index and the queue can be GC'd.
+        try {
+            while (true) {
+                while ((this.subscriberIndexes[subIdx] ?? 0) < this.queue.length) {
+                    const currentIdx = this.subscriberIndexes[subIdx] ?? 0;
+                    const item = this.queue[currentIdx];
+                    this.subscriberIndexes[subIdx] = currentIdx + 1;
+                    this.trimConsumed();
+                    yield item;
+                }
+                if (this.fatal)
+                    throw this.fatal;
+                if (this.ended)
+                    return;
+                await new Promise((resolve) => {
+                    this.waiters.push(resolve);
+                });
+            }
+        }
+        finally {
+            this.unsubscribe(subIdx);
+        }
+    }
+}
+function buildTtsRequest(params) {
+    return {
+        type: 'textToSpeech',
+        modelId: params.modelId,
+        inputType: params.inputType,
+        text: params.text,
+        stream: params.stream,
+        sentenceStream: params.sentenceStream,
+        ...(params.sentenceStreamLocale !== undefined && {
+            sentenceStreamLocale: params.sentenceStreamLocale
+        }),
+        ...(params.sentenceStreamMaxChunkScalars !== undefined && {
+            sentenceStreamMaxChunkScalars: params.sentenceStreamMaxChunkScalars
+        }),
+        ...(params.description !== undefined && { description: params.description }),
+        ...(params.voiceDescription !== undefined && { voiceDescription: params.voiceDescription }),
+        ...(params.voice !== undefined && { voice: params.voice }),
+        ...(params.emotion !== undefined && { emotion: params.emotion }),
+        ...(params.pitch !== undefined && { pitch: params.pitch }),
+        ...(params.pace !== undefined && { pace: params.pace }),
+        ...(params.expressivity !== undefined && { expressivity: params.expressivity }),
+        ...(params.noise !== undefined && { noise: params.noise }),
+        ...(params.reverb !== undefined && { reverb: params.reverb }),
+        ...(params.quality !== undefined && { quality: params.quality })
+    };
+}
+function buildTextToSpeechStreamRequest(params) {
+    return {
+        type: 'textToSpeechStream',
+        modelId: params.modelId,
+        inputType: params.inputType ?? 'text',
+        ...(params.accumulateSentences !== undefined && {
+            accumulateSentences: params.accumulateSentences
+        }),
+        ...(params.sentenceDelimiterPreset !== undefined && {
+            sentenceDelimiterPreset: params.sentenceDelimiterPreset
+        }),
+        ...(params.maxBufferScalars !== undefined && {
+            maxBufferScalars: params.maxBufferScalars
+        }),
+        ...(params.flushAfterMs !== undefined && {
+            flushAfterMs: params.flushAfterMs
+        }),
+        ...(params.description !== undefined && { description: params.description }),
+        ...(params.voiceDescription !== undefined && { voiceDescription: params.voiceDescription }),
+        ...(params.voice !== undefined && { voice: params.voice }),
+        ...(params.emotion !== undefined && { emotion: params.emotion }),
+        ...(params.pitch !== undefined && { pitch: params.pitch }),
+        ...(params.pace !== undefined && { pace: params.pace }),
+        ...(params.expressivity !== undefined && { expressivity: params.expressivity }),
+        ...(params.noise !== undefined && { noise: params.noise }),
+        ...(params.reverb !== undefined && { reverb: params.reverb }),
+        ...(params.quality !== undefined && { quality: params.quality })
+    };
+}
+/**
+ * Converts text to speech audio using a loaded TTS model.
+ *
+ * Three modes selected by `params.stream` and `params.sentenceStream`:
+ *
+ * - `stream: false` (default) — collect all PCM samples and resolve once via
+ *   `result.buffer` (`Promise<number[]>`). `bufferStream` is empty.
+ * - `stream: true` — yield PCM samples through `result.bufferStream`
+ *   (`AsyncGenerator<number>`) as they arrive. `buffer` resolves to an empty
+ *   array.
+ * - `stream: true, sentenceStream: true` — also exposes `result.chunkUpdates`
+ *   (`AsyncGenerator<TtsSentenceChunkUpdate>`) so callers can mux per-sentence
+ *   metadata with the audio. Multiple consumers can iterate the response
+ *   independently via the underlying `TtsMulticast`.
+ *
+ * `result.done` resolves to `true` when synthesis completes cleanly, `false`
+ * if the consumer breaks out before the terminal frame, or rejects on a
+ * pipeline error. Awaiting `done` is safe even when no stream is iterated.
+ *
+ * @param params - TTS request parameters (see `TtsClientParamsInput`).
+ * @param options - Optional RPC options (timeout, profiling, force new connection).
+ * @returns A `TextToSpeechStreamResult` with `bufferStream`, `buffer`, `done`,
+ *          and (when `sentenceStream: true`) `chunkUpdates`.
+ * @throws {TextToSpeechStreamFailedError} When `sentenceStream: true` is paired
+ *         with `stream: false`, or when the underlying RPC stream errors.
+ */
+export function textToSpeech(params, options) {
+    const parsed = parseClientInput(ttsClientParamsSchema, params);
+    if (parsed.sentenceStream && !parsed.stream) {
+        throw new TextToSpeechStreamFailedError('textToSpeech: `sentenceStream: true` requires `stream: true`');
+    }
+    const request = buildTtsRequest(parsed);
+    if (parsed.stream && parsed.sentenceStream) {
+        return sentenceStreamTts(request, options);
+    }
+    if (parsed.stream) {
+        return plainStreamTts(request, options);
+    }
+    return collectTts(request, options);
+}
+// Adapts the raw RPC stream into the filtered `TtsResponse` source the
+// multicast expects. Kept here (not inlined) so the multicast can be
+// constructed in tests with a hand-rolled source instead.
+async function* ttsResponseSource(request, options) {
+    for await (const response of streamRpc(request, options)) {
+        if (response.type !== 'textToSpeech')
+            continue;
+        yield response;
+    }
+}
+function sentenceStreamTts(request, options) {
+    const multicast = new TtsMulticast(ttsResponseSource(request, options));
+    // Subscribe eagerly, synchronously — before pump() can push its first
+    // item — so both subscribers see the full queue from index 0. If we
+    // deferred subscribing until the generators were iterated, the first
+    // consumer could trim the queue before the second ever registered,
+    // silently dropping earlier frames.
+    const bufferSubscription = multicast.subscribe();
+    const chunkSubscription = multicast.subscribe();
+    return {
+        bufferStream: sentenceBufferStream(bufferSubscription),
+        chunkUpdates: sentenceChunkUpdates(chunkSubscription),
+        buffer: Promise.resolve([]),
+        done: multicast.done
+    };
+}
+async function* sentenceBufferStream(source) {
+    for await (const m of source) {
+        if (m.buffer.length > 0) {
+            yield* m.buffer;
+        }
+        if (m.done)
+            break;
+    }
+}
+async function* sentenceChunkUpdates(source) {
+    for await (const m of source) {
+        const hasAudio = m.buffer.length > 0;
+        const hasMeta = m.chunkIndex !== undefined ||
+            (typeof m.sentenceChunk === 'string' && m.sentenceChunk.length > 0);
+        if (hasAudio || hasMeta) {
+            yield {
+                buffer: hasAudio ? [...m.buffer] : [],
+                ...(m.chunkIndex !== undefined ? { chunkIndex: m.chunkIndex } : {}),
+                ...(typeof m.sentenceChunk === 'string' && m.sentenceChunk.length > 0
+                    ? { sentenceChunk: m.sentenceChunk }
+                    : {})
+            };
+        }
+        if (m.done)
+            break;
+    }
+}
+function plainStreamTts(request, options) {
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+        resolveDone = resolve;
+        rejectDone = reject;
+    });
+    done.catch(() => { });
+    return {
+        bufferStream: plainTtsBufferStream(request, options, resolveDone, rejectDone),
+        buffer: Promise.resolve([]),
+        done
+    };
+}
+async function* plainTtsBufferStream(request, options, resolveDone, rejectDone) {
+    let settled = false;
+    try {
+        for await (const response of streamRpc(request, options)) {
+            if (response.type !== 'textToSpeech')
+                continue;
+            // See TtsMulticast.pump — skip per-frame Zod validation; the server is
+            // the source of truth for this wire shape.
+            if (response.buffer.length > 0) {
+                yield* response.buffer;
+            }
+            if (response.done) {
+                settled = true;
+                resolveDone(true);
+            }
+        }
+    }
+    catch (e) {
+        if (!settled) {
+            settled = true;
+            rejectDone(e);
+        }
+        throw e;
+    }
+    finally {
+        // Consumer broke out of the for-await before `done` arrived; resolve
+        // with `false` so `await result.done` never hangs.
+        if (!settled)
+            resolveDone(false);
+    }
+}
+function collectTts(request, options) {
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+        resolveDone = resolve;
+        rejectDone = reject;
+    });
+    done.catch(() => { });
+    return {
+        bufferStream: emptyBufferStream(),
+        buffer: collectTtsBuffer(request, options, resolveDone, rejectDone),
+        done
+    };
+}
+async function* emptyBufferStream() {
+    // Non-streaming mode exposes no incremental buffer stream.
+}
+async function collectTtsBuffer(request, options, resolveDone, rejectDone) {
+    let buffer = [];
+    try {
+        for await (const response of streamRpc(request, options)) {
+            if (response.type !== 'textToSpeech')
+                continue;
+            buffer = buffer.concat(response.buffer);
+            if (response.done) {
+                resolveDone(true);
+            }
+        }
+        return buffer;
+    }
+    catch (e) {
+        rejectDone(e);
+        throw e;
+    }
+}
+export function encodeTextToSpeechFragment(textFragment) {
+    return typeof textFragment === 'string' ? new TextEncoder().encode(textFragment) : textFragment;
+}
+/**
+ * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or
+ * Uint8Array should be a complete UTF-8 fragment. The worker forwards them to the TTS streaming handler
+ * (optional sentence accumulation via request fields). Iterate the session for `TextToSpeechStreamResponse`
+ * lines (PCM in `buffer`, optional `chunkIndex` / `sentenceChunk`) until `done`.
+ *
+ * @param params - The loaded TTS model, input mode, buffering controls, and
+ *   optional voice settings.
+ * @param options - Optional timeout, profiling, and connection settings.
+ * @returns A single-consumer duplex session for writing text fragments and
+ *   iterating PCM response frames.
+ * @throws {TextToSpeechStreamFailedError} When the session is iterated more
+ *   than once, receives a server error, or is written after closing.
+ */
+export async function textToSpeechStream(params, options) {
+    const request = parseClientInput(textToSpeechStreamRequestSchema, buildTextToSpeechStreamRequest(params));
+    const { requestStream, responseStream } = await duplex(request, options);
+    const responses = parseTextToSpeechStreamLines(responseStream);
+    let consumed = false;
+    // `closed` flips on `end()` or `destroy()`. Without this guard a late
+    // `write()` would propagate a raw Bare/Node "write after end" stream error
+    // to the caller. Throwing a typed SDK error keeps the duplex session
+    // surface predictable.
+    let closed = false;
+    return {
+        write(textFragment) {
+            if (closed) {
+                throw new TextToSpeechStreamFailedError('TextToSpeechStreamSession.write() called after end()/destroy()');
+            }
+            requestStream.write(encodeTextToSpeechFragment(textFragment));
+        },
+        end() {
+            if (closed)
+                return;
+            closed = true;
+            requestStream.end();
+        },
+        destroy() {
+            closed = true;
+            requestStream.destroy();
+            responseStream.destroy();
+        },
+        [Symbol.asyncIterator]() {
+            if (consumed) {
+                // Return an iterator whose first .next() rejects asynchronously so
+                // `for await` surfaces the error in the normal async-iteration
+                // control flow instead of a synchronous throw from the iterator
+                // protocol (which callers commonly forget to wrap in try/catch).
+                return {
+                    next() {
+                        return Promise.reject(new TextToSpeechStreamFailedError('TextToSpeechStreamSession can only be iterated once'));
+                    }
+                };
+            }
+            consumed = true;
+            return responses;
+        }
+    };
+}
+async function* parseTextToSpeechStreamLines(responseStream) {
+    let buf = '';
+    for await (const chunk of responseStream) {
+        buf += chunk.toString();
+        const lines = buf.split('\n');
+        buf = lines.pop() || '';
+        for (const line of lines) {
+            const yielded = processTextToSpeechStreamLine(line);
+            if (yielded === undefined)
+                continue;
+            yield yielded;
+            // Close the stream after the terminal frame so consumers don't
+            // depend on the server closing the socket to stop iteration.
+            if (yielded.done)
+                return;
+        }
+    }
+    if (buf.trim()) {
+        const yielded = processTextToSpeechStreamLine(buf);
+        if (yielded !== undefined) {
+            yield yielded;
+        }
+    }
+}
+function processTextToSpeechStreamLine(line) {
+    if (!line.trim()) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        logger.warn('textToSpeechStream: malformed JSON from server:', line);
+        return undefined;
+    }
+    const obj = parsed;
+    if (obj['type'] === 'error') {
+        throw new TextToSpeechStreamFailedError(obj['message'] ?? 'Unknown server error');
+    }
+    return textToSpeechStreamResponseSchema.parse(parsed);
+}