@leiboss/dsh-tts 0.0.0-stage → 0.3.0

package/dist/engine-health.js

@@ -0,0 +1,170 @@
+import { ErrorCode, isProtocolDrift, TtsError } from "./errors.js";
+/** Defaults shared by the config schema and `resolveConfig`. */
+export const DEFAULT_ENGINE_HEALTH = Object.freeze({
+    enabled: true,
+    failureThreshold: 3,
+    driftCooldownMs: 300_000,
+    transientCooldownMs: 60_000,
+    maxCooldownMs: 600_000,
+});
+/** Engines that participate in health tracking, in chain order. */
+const TRACKED_ENGINES = ['edge-tts', 'sapi', 'speechSynthesis'];
+/** Failure codes that say "the engine failed", as opposed to "the caller erred". */
+const COUNTED_FAILURES = new Set([
+    ErrorCode.EdgeTtsFailed,
+    ErrorCode.SynthesisTimeout,
+    ErrorCode.EmptyAudio,
+    ErrorCode.SpawnFailed,
+]);
+/**
+ * Whether a failure should move the circuit. Validation, config, cache and
+ * abort errors describe the request, not the engine; `SPAWN_EPERM` and a
+ * missing binary are environment/install problems that a circuit cannot fix.
+ */
+export function countsAsEngineFailure(error) {
+    if (error instanceof TtsError)
+        return COUNTED_FAILURES.has(error.code);
+    // An engine that threw something unclassified still failed to produce audio.
+    return error instanceof Error;
+}
+function freshRecord(transientCooldownMs) {
+    return {
+        state: 'healthy',
+        consecutiveFailures: 0,
+        cooldownMs: transientCooldownMs,
+        probePending: false,
+    };
+}
+/**
+ * One mutable registry per tool instance. `now` is injectable so tests can
+ * advance the cooldown without sleeping.
+ */
+export class EngineHealthRegistry {
+    #config;
+    #now;
+    #engines = new Map();
+    constructor(config = { ...DEFAULT_ENGINE_HEALTH }, now = () => new Date()) {
+        this.#config = config;
+        this.#now = now;
+    }
+    /** Current state without side effects; unknown engines are `healthy`. */
+    stateOf(engine) {
+        return this.#record(engine).state;
+    }
+    /** Full record, exposed for diagnostics and unit tests. */
+    healthOf(engine) {
+        return this.#record(engine);
+    }
+    /**
+     * Whether `engine` must be skipped for this attempt. When an open circuit's
+     * cooldown has elapsed the call is let through and marked as a probe.
+     */
+    shouldSkip(engine) {
+        if (!this.#config.enabled)
+            return false;
+        const record = this.#record(engine);
+        if (record.state !== 'open')
+            return false;
+        const openedAt = record.openedAt ?? 0;
+        if (this.#nowMs() < openedAt + record.cooldownMs)
+            return true;
+        record.probePending = true;
+        return false;
+    }
+    /**
+     * Plan a whole chain at once. If every engine is open the last one is forced
+     * through: a fully open chain must still attempt something rather than fail
+     * silently with an empty result.
+     */
+    plan(chain) {
+        const observedAt = this.#nowMs();
+        const skip = new Set();
+        if (!this.#config.enabled)
+            return { skip, observedAt };
+        const unique = [...new Set(chain)];
+        for (const engine of unique) {
+            if (this.shouldSkip(engine))
+                skip.add(engine);
+        }
+        if (unique.length > 0 && skip.size === unique.length) {
+            const last = unique[unique.length - 1];
+            if (last !== undefined)
+                skip.delete(last);
+        }
+        return { skip, observedAt };
+    }
+    /** A successful attempt closes the circuit and clears the failure streak. */
+    recordSuccess(engine) {
+        const record = this.#record(engine);
+        record.state = 'healthy';
+        record.consecutiveFailures = 0;
+        record.probePending = false;
+        delete record.openedAt;
+        record.cooldownMs = this.#config.transientCooldownMs;
+    }
+    /**
+     * Record a failed attempt. Drift opens immediately with the long cooldown;
+     * transient failures accumulate until `failureThreshold`. A failed half-open
+     * probe re-opens with a doubled cooldown, capped at `maxCooldownMs`.
+     */
+    recordFailure(engine, error) {
+        if (!this.#config.enabled || !countsAsEngineFailure(error))
+            return;
+        const record = this.#record(engine);
+        const now = this.#nowMs();
+        record.consecutiveFailures += 1;
+        if (error instanceof TtsError)
+            record.lastErrorCode = error.code;
+        if (record.probePending) {
+            record.probePending = false;
+            record.state = 'open';
+            record.openedAt = now;
+            record.cooldownMs = Math.min(record.cooldownMs * 2, this.#config.maxCooldownMs);
+            return;
+        }
+        if (isProtocolDrift(error)) {
+            record.state = 'open';
+            record.openedAt = now;
+            record.cooldownMs = this.#config.driftCooldownMs;
+            return;
+        }
+        if (record.consecutiveFailures >= this.#config.failureThreshold) {
+            record.state = 'open';
+            record.openedAt = now;
+            record.cooldownMs = this.#config.transientCooldownMs;
+            return;
+        }
+        record.state = 'degraded';
+    }
+    /** Snapshot for `tts_self_check`; never performs I/O. */
+    snapshot() {
+        const out = {};
+        for (const engine of TRACKED_ENGINES) {
+            const record = this.#record(engine);
+            out[engine] =
+                record.lastErrorCode === undefined
+                    ? {
+                        state: record.state,
+                        consecutiveFailures: record.consecutiveFailures,
+                    }
+                    : {
+                        state: record.state,
+                        consecutiveFailures: record.consecutiveFailures,
+                        lastErrorCode: record.lastErrorCode,
+                    };
+        }
+        return out;
+    }
+    #nowMs() {
+        return this.#now().getTime();
+    }
+    #record(engine) {
+        let record = this.#engines.get(engine);
+        if (record === undefined) {
+            record = freshRecord(this.#config.transientCooldownMs);
+            this.#engines.set(engine, record);
+        }
+        return record;
+    }
+}
+//# sourceMappingURL=engine-health.js.map

package/dist/engine-health.js.map

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

package/dist/engines/edge-js.d.ts

@@ -0,0 +1,51 @@
+/** One word boundary as Edge reports it. */
+export interface EdgeJsWord {
+    text: string;
+    offsetMs: number;
+    durationMs: number;
+}
+/** One synthesis request. */
+export interface EdgeJsRequest {
+    text: string;
+    voice: string;
+    /** `+0%` style, passed through to SSML. */
+    rate?: string;
+    /** `+0Hz` style. */
+    pitch?: string;
+    /** `+0%` style. */
+    volume?: string;
+    /** Forwarded to the WSS handshake; Edge ignores HTTPS_PROXY. */
+    proxy?: string;
+    timeoutMs?: number;
+}
+/** Audio plus the timing metadata Edge reports for it. */
+export interface EdgeJsResult {
+    audio: Buffer;
+    words: EdgeJsWord[];
+}
+/** The shape `node-edge-tts` exposes; kept structural so the version can drift. */
+interface EdgeJsInstance {
+    streamAudio(text: string): AsyncGenerator<Buffer | {
+        part: string;
+        start: number;
+        end: number;
+    }>;
+    ttsPromise(text: string, audioPath: string): Promise<void>;
+}
+interface EdgeJsModule {
+    EdgeTTS: new (config: Record<string, unknown>) => EdgeJsInstance;
+}
+/** Replace the module loader. Tests inject a fake; production clears it. */
+export declare function setEdgeJsLoader(impl: (() => Promise<unknown>) | undefined): void;
+/** Load the optional dependency, or report that it is not installed. */
+export declare function loadEdgeJsModule(): Promise<EdgeJsModule | undefined>;
+/** Whether the pure-JS backend can be used in this process. */
+export declare function isEdgeJsAvailable(): Promise<boolean>;
+/**
+ * Synthesize once and collect audio plus word boundaries. Word offsets are
+ * absolute from the start of this call's audio, which is what callers need to
+ * shift per chunk.
+ */
+export declare function synthesizeWithEdgeJs(request: EdgeJsRequest): Promise<EdgeJsResult>;
+export {};
+//# sourceMappingURL=edge-js.d.ts.map

package/dist/engines/edge-js.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-js.d.ts","sourceRoot":"","sources":["../../src/engines/edge-js.ts"],"names":[],"mappings":"AAaA,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,6BAA6B;AAC7B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED,mFAAmF;AACnF,UAAU,cAAc;IACtB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3D;AAED,UAAU,YAAY;IACpB,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,cAAc,CAAA;CACjE;AAID,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAEhF;AAED,wEAAwE;AACxE,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAQ1E;AAED,+DAA+D;AAC/D,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAE1D;AA8BD;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAuDxF"}

package/dist/engines/edge-js.js

@@ -0,0 +1,98 @@
+/**
+ * Pure-JS synthesis backend over `node-edge-tts`.
+ *
+ * Why this exists: the CLI backend requires Python, which is the single largest
+ * install obstacle for a DSH plugin. This adapter removes it, and it also
+ * returns word boundaries, which upgrades subtitle timing from "estimated" to
+ * "exact".
+ *
+ * The module is an optional dependency: a host without it still gets the CLI
+ * path, so the import is dynamic and the loader is injectable for tests.
+ */
+import { ErrorCode, looksLikeThrottle, TtsError } from "../errors.js";
+let loader;
+/** Replace the module loader. Tests inject a fake; production clears it. */
+export function setEdgeJsLoader(impl) {
+    loader = impl;
+}
+/** Load the optional dependency, or report that it is not installed. */
+export async function loadEdgeJsModule() {
+    const load = loader ?? (() => import('node-edge-tts'));
+    try {
+        const loaded = (await load());
+        return typeof loaded.EdgeTTS === 'function' ? loaded : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the pure-JS backend can be used in this process. */
+export async function isEdgeJsAvailable() {
+    return (await loadEdgeJsModule()) !== undefined;
+}
+/** Edge-TTS voices are `<lang>-<REGION>-<Name>Neural`; the language is the prefix. */
+function languageOf(voice) {
+    const parts = voice.split('-');
+    return parts.length >= 2 ? `${parts[0]}-${parts[1]}` : 'zh-CN';
+}
+/** Classify a backend failure as protocol drift when the handshake is rejected. */
+function asTtsError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (looksLikeThrottle(detail)) {
+        return new TtsError(ErrorCode.UpstreamThrottled, `The Edge endpoint is throttling requests: ${detail}`, 'Retry shortly. The engine backs off automatically before falling back to another voice engine.', { cause: error });
+    }
+    const drift = /403|handshake|sec-ms-gec|invalid response status/i.test(detail);
+    return new TtsError(ErrorCode.EdgeTtsFailed, `The pure-JS Edge backend failed: ${detail}`, drift
+        ? 'The Edge handshake changed. Upgrade `node-edge-tts`, or pin the CLI backend with engine=edge-py.'
+        : 'Check the network and the configured proxy; run tts_probe_network to test reachability.', { cause: error, protocolDrift: drift });
+}
+/**
+ * Synthesize once and collect audio plus word boundaries. Word offsets are
+ * absolute from the start of this call's audio, which is what callers need to
+ * shift per chunk.
+ */
+export async function synthesizeWithEdgeJs(request) {
+    const module = await loadEdgeJsModule();
+    if (module === undefined) {
+        throw new TtsError(ErrorCode.EngineUnavailable, 'The pure-JS Edge backend is not installed (node-edge-tts is missing).', 'Install it with `npm i node-edge-tts`, or set engine=edge-py to use the CLI backend.');
+    }
+    const instance = new module.EdgeTTS({
+        voice: request.voice,
+        lang: languageOf(request.voice),
+        outputFormat: 'audio-24khz-48kbitrate-mono-mp3',
+        // `saveSubtitles` gates *parsing* of the WordBoundary metadata, not file
+        // writes: `streamAudio()` yields the boundaries and never touches disk.
+        // Without it the generator yields audio only and timing stays estimated.
+        saveSubtitles: true,
+        ...(request.proxy === undefined ? {} : { proxy: request.proxy }),
+        ...(request.rate === undefined ? {} : { rate: request.rate }),
+        ...(request.pitch === undefined ? {} : { pitch: request.pitch }),
+        ...(request.volume === undefined ? {} : { volume: request.volume }),
+        ...(request.timeoutMs === undefined ? {} : { timeout: request.timeoutMs }),
+    });
+    const chunks = [];
+    const words = [];
+    try {
+        for await (const item of instance.streamAudio(request.text)) {
+            if (Buffer.isBuffer(item)) {
+                chunks.push(item);
+                continue;
+            }
+            if (typeof item === 'object' && item !== null && 'part' in item) {
+                const boundary = item;
+                const durationMs = Math.max(0, boundary.end - boundary.start);
+                if (boundary.part.length > 0) {
+                    words.push({ text: boundary.part, offsetMs: boundary.start, durationMs });
+                }
+            }
+        }
+    }
+    catch (error) {
+        throw asTtsError(error);
+    }
+    if (chunks.length === 0) {
+        throw new TtsError(ErrorCode.EmptyAudio, 'The pure-JS Edge backend returned no audio bytes.', 'Retry; if it persists, run tts_self_check and tts_probe_network.');
+    }
+    return { audio: Buffer.concat(chunks), words };
+}
+//# sourceMappingURL=edge-js.js.map

package/dist/engines/edge-js.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+/**
+ * Stable, machine-readable failure codes. Callers route on these codes instead
+ * of parsing human-facing messages.
+ */
+export declare const ErrorCode: {
+    readonly EmptyText: "EMPTY_TEXT";
+    readonly InvalidVoice: "INVALID_VOICE";
+    readonly InvalidRate: "INVALID_RATE";
+    readonly InvalidPitch: "INVALID_PITCH";
+    readonly InvalidVolume: "INVALID_VOLUME";
+    readonly InvalidConfig: "INVALID_CONFIG";
+    readonly DshHomeNotSet: "DSH_HOME_NOT_SET";
+    readonly OutputDirNotWritable: "OUTPUT_DIR_NOT_WRITABLE";
+    readonly EdgeTtsNotFound: "EDGE_TTS_NOT_FOUND";
+    readonly EngineUnavailable: "ENGINE_UNAVAILABLE";
+    readonly SpawnEperm: "SPAWN_EPERM";
+    readonly SpawnFailed: "SPAWN_FAILED";
+    readonly EdgeTtsFailed: "EDGE_TTS_FAILED";
+    readonly UpstreamThrottled: "UPSTREAM_THROTTLED";
+    readonly SynthesisTimeout: "SYNTHESIS_TIMEOUT";
+    readonly EmptyAudio: "EMPTY_AUDIO";
+    readonly Aborted: "ABORTED";
+    readonly TtsBusy: "TTS_BUSY";
+    readonly AllFallbacksFailed: "ALL_FALLBACKS_FAILED";
+    readonly SpeechSynthesisRequired: "SPEECH_SYNTHESIS_REQUIRED";
+};
+export type TtsErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Whether captured subprocess output looks like protocol drift, not jitter. */
+export declare function looksLikeProtocolDrift(text: string): boolean;
+/** Whether captured output looks like upstream throttling. */
+export declare function looksLikeThrottle(text: string): boolean;
+/** Options accepted by {@link TtsError}. */
+export interface TtsErrorOptions extends ErrorOptions {
+    /** Marks a failure caused by upstream protocol drift rather than jitter. */
+    protocolDrift?: boolean;
+}
+/**
+ * Structured plugin error: a routable `code`, a human-readable message, and an
+ * actionable suggestion. Extends the harness error base so the tool registry
+ * can retain the code in its failure metadata.
+ */
+export declare class TtsError extends HarnessError {
+    /** Pre-suggestion message, kept verbatim for structured consumers. */
+    readonly detail: string;
+    /** Action the caller (or the user) can take to resolve the failure. */
+    readonly suggestion?: string;
+    /** Set when the failure is a handshake/protocol rejection, not a timeout. */
+    readonly protocolDrift: boolean;
+    constructor(code: TtsErrorCode, message: string, suggestion?: string, options?: TtsErrorOptions);
+}
+/**
+ * Classify a failure as protocol drift. The explicit flag wins; the text
+ * fallback keeps errors re-wrapped by callers (for example per-chunk failures)
+ * classifiable without extra plumbing.
+ */
+export declare function isProtocolDrift(error: unknown): boolean;
+/** Read a Node `SystemError` code without assuming the thrown value's shape. */
+export declare function errnoCode(error: unknown): string | undefined;
+/**
+ * Translate a failed `spawn()` attempt into a structured error. `EPERM` is
+ * deliberately distinct: it means the sandbox refused process creation, not
+ * that the output directory is unwritable.
+ */
+export declare function spawnFailure(error: unknown): TtsError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;CAqBZ,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAA;AAgBrE,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AASD,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,4EAA4E;IAC5E,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;gBAG7B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,eAAe;CAQ5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGvD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM5D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CA4BrD"}

package/dist/errors.js

@@ -0,0 +1,110 @@
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+/**
+ * Stable, machine-readable failure codes. Callers route on these codes instead
+ * of parsing human-facing messages.
+ */
+export const ErrorCode = {
+    EmptyText: 'EMPTY_TEXT',
+    InvalidVoice: 'INVALID_VOICE',
+    InvalidRate: 'INVALID_RATE',
+    InvalidPitch: 'INVALID_PITCH',
+    InvalidVolume: 'INVALID_VOLUME',
+    InvalidConfig: 'INVALID_CONFIG',
+    DshHomeNotSet: 'DSH_HOME_NOT_SET',
+    OutputDirNotWritable: 'OUTPUT_DIR_NOT_WRITABLE',
+    EdgeTtsNotFound: 'EDGE_TTS_NOT_FOUND',
+    EngineUnavailable: 'ENGINE_UNAVAILABLE',
+    SpawnEperm: 'SPAWN_EPERM',
+    SpawnFailed: 'SPAWN_FAILED',
+    EdgeTtsFailed: 'EDGE_TTS_FAILED',
+    UpstreamThrottled: 'UPSTREAM_THROTTLED',
+    SynthesisTimeout: 'SYNTHESIS_TIMEOUT',
+    EmptyAudio: 'EMPTY_AUDIO',
+    Aborted: 'ABORTED',
+    TtsBusy: 'TTS_BUSY',
+    AllFallbacksFailed: 'ALL_FALLBACKS_FAILED',
+    SpeechSynthesisRequired: 'SPEECH_SYNTHESIS_REQUIRED',
+};
+/**
+ * Substrings that mean the upstream Edge-TTS protocol changed under us: a
+ * rejected WebSocket handshake, a rotated `Sec-MS-GEC` token generation, or a
+ * generic HTTP 403. These are not retryable jitter — the installed edge-tts
+ * version and the service disagree about the handshake.
+ */
+const PROTOCOL_DRIFT_PATTERNS = [
+    /403/,
+    /invalid response status/i,
+    /wsserverhandshakeerror/i,
+    /sec-ms-gec/i,
+    /handshake/i,
+];
+/** Whether captured subprocess output looks like protocol drift, not jitter. */
+export function looksLikeProtocolDrift(text) {
+    return PROTOCOL_DRIFT_PATTERNS.some((pattern) => pattern.test(text));
+}
+/**
+ * Substrings that mean the endpoint is rate limiting us rather than failing.
+ * Throttling is transient and worth a backoff; falling back to another engine
+ * would only hide the load problem and produce worse audio.
+ */
+const THROTTLE_PATTERNS = [/\b429\b/, /too many requests/i, /rate limit/i];
+/** Whether captured output looks like upstream throttling. */
+export function looksLikeThrottle(text) {
+    return THROTTLE_PATTERNS.some((pattern) => pattern.test(text));
+}
+/**
+ * Structured plugin error: a routable `code`, a human-readable message, and an
+ * actionable suggestion. Extends the harness error base so the tool registry
+ * can retain the code in its failure metadata.
+ */
+export class TtsError extends HarnessError {
+    /** Pre-suggestion message, kept verbatim for structured consumers. */
+    detail;
+    /** Action the caller (or the user) can take to resolve the failure. */
+    suggestion;
+    /** Set when the failure is a handshake/protocol rejection, not a timeout. */
+    protocolDrift;
+    constructor(code, message, suggestion, options) {
+        super(suggestion ? `${message}\nSuggestion: ${suggestion}` : message, code, options);
+        this.name = 'TtsError';
+        this.detail = message;
+        this.suggestion = suggestion;
+        this.protocolDrift = options?.protocolDrift === true;
+    }
+}
+/**
+ * Classify a failure as protocol drift. The explicit flag wins; the text
+ * fallback keeps errors re-wrapped by callers (for example per-chunk failures)
+ * classifiable without extra plumbing.
+ */
+export function isProtocolDrift(error) {
+    if (!(error instanceof TtsError))
+        return false;
+    return error.protocolDrift || looksLikeProtocolDrift(error.detail);
+}
+/** Read a Node `SystemError` code without assuming the thrown value's shape. */
+export function errnoCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        const code = error.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    return undefined;
+}
+/**
+ * Translate a failed `spawn()` attempt into a structured error. `EPERM` is
+ * deliberately distinct: it means the sandbox refused process creation, not
+ * that the output directory is unwritable.
+ */
+export function spawnFailure(error) {
+    const code = errnoCode(error);
+    const detail = error instanceof Error ? error.message : String(error);
+    if (code === 'ENOENT') {
+        return new TtsError(ErrorCode.EdgeTtsNotFound, `Cannot start Edge-TTS: ${detail}`, 'Install it with `pip install edge-tts`, or point `edgeTtsBinary` at the executable.', { cause: error });
+    }
+    if (code === 'EPERM') {
+        return new TtsError(ErrorCode.SpawnEperm, `The DSH sandbox denied process creation for Edge-TTS (spawn EPERM): ${detail}`, 'Raise the DSH sandbox process/file policy and retry. This is a sandbox policy denial, not a missing or unwritable output directory.', { cause: error });
+    }
+    return new TtsError(ErrorCode.SpawnFailed, `Failed to spawn Edge-TTS (${code ?? 'unknown error'}): ${detail}`, 'Check that `edgeTtsBinary` names an existing, executable Edge-TTS CLI.', { cause: error });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/fallback.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Fallback chain orchestration: Edge-TTS is the primary engine, and on an
+ * eligible failure the configured chain is tried in order. SAPI is Windows-only;
+ * the browser `speechSynthesis` entry produces a marker instead of a file (the
+ * host cannot produce audio without an engine). A chain with no reachable
+ * engine ends as `ALL_FALLBACKS_FAILED` listing every engine and reason.
+ */
+import type { TtsEngine } from './config.ts';
+import type { SpawnFunction, SynthesizedAudio } from './edge-tts.ts';
+import type { EngineHealthHooks, EngineHealthState } from './engine-health.ts';
+import { TtsError } from './errors.ts';
+import { type SapiOptions } from './sapi-tts.ts';
+/** Whether a failed Edge-TTS attempt is worth retrying with another engine. */
+export declare function isFallbackEligible(error: unknown): error is TtsError;
+/** One engine that was skipped or failed, with a human-readable reason. */
+export interface FallbackAttempt {
+    engine: TtsEngine;
+    reason: string;
+}
+/** Reason recorded when the health circuit skips an engine. */
+export declare const SKIPPED_BY_HEALTH = "skipped: circuit open (cooldown)";
+/** Either a produced file or a request for the client to speak the text. */
+export type FallbackOutcome = {
+    kind: 'audio';
+    audio: SynthesizedAudio;
+    engine: TtsEngine;
+    /** Health of `engine` just before this attempt succeeded. */
+    engineState: EngineHealthState;
+    attempts: FallbackAttempt[];
+} | {
+    kind: 'speechSynthesis';
+    engine: 'speechSynthesis';
+    attempts: FallbackAttempt[];
+};
+export interface FallbackOptions {
+    text: string;
+    rate: string;
+    outputDir: string;
+    hash: string;
+    timeoutMs: number;
+    fallbackOrder: readonly TtsEngine[];
+    signal?: AbortSignal;
+    now?: Date;
+    /** Error thrown by the primary Edge-TTS attempt, kept for the final message. */
+    primaryError?: unknown;
+    /** Why the primary attempt was not made, when its circuit was open. */
+    primaryReason?: string;
+    /**
+     * Engines whose circuit is open. Skipping never reorders the chain; it only
+     * removes an engine from this attempt.
+     */
+    skip?: ReadonlySet<TtsEngine>;
+}
+/** Injection points; production uses the real Windows/ffmpeg binaries. */
+export interface FallbackDependencies {
+    platform?: NodeJS.Platform;
+    spawnImpl?: SpawnFunction;
+    powershellBinary?: string;
+    ffmpegBinary?: string;
+    synthesizeSapiImpl?: (text: string, options: SapiOptions) => Promise<SynthesizedAudio>;
+    /** Health hooks; omitted by direct callers that do not track engines. */
+    health?: EngineHealthHooks;
+}
+/**
+ * Run the configured engines after Edge-TTS already failed. `edge-tts` in
+ * `fallbackOrder` marks the primary attempt rather than a retry.
+ */
+export declare function runFallback(options: FallbackOptions, deps?: FallbackDependencies): Promise<FallbackOutcome>;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../src/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC9E,OAAO,EAAa,QAAQ,EAAqB,MAAM,aAAa,CAAA;AACpE,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,eAAe,CAAA;AAYtB,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAEpE;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,qCAAqC,CAAA;AAEnE,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GACvB;IACE,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,gBAAgB,CAAA;IACvB,MAAM,EAAE,SAAS,CAAA;IACjB,6DAA6D;IAC7D,WAAW,EAAE,iBAAiB,CAAA;IAC9B,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B,GACD;IACE,IAAI,EAAE,iBAAiB,CAAA;IACvB,MAAM,EAAE,iBAAiB,CAAA;IACzB,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B,CAAA;AAEL,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,SAAS,SAAS,EAAE,CAAA;IACnC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,GAAG,CAAC,EAAE,IAAI,CAAA;IACV,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAA;CAC9B;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IAC1B,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kBAAkB,CAAC,EAAE,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,KACjB,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC9B,yEAAyE;IACzE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B;AAuBD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,eAAe,CAAC,CA2D1B"}