@leiboss/dsh-tts 0.0.0-stage → 0.2.1

package/dist/config.js

@@ -0,0 +1,143 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { ErrorCode, TtsError } from "./errors.js";
+/** Voice Edge-TTS uses when neither config nor the call specifies one. */
+export const DEFAULT_VOICE = 'zh-CN-XiaoxiaoNeural';
+/** Rate Edge-TTS uses when the call omits one. */
+export const DEFAULT_RATE = '+0%';
+/** Per-synthesis subprocess deadline. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** CLI name resolved through PATH unless overridden. */
+export const DEFAULT_EDGE_TTS_BINARY = 'edge-tts';
+/** Subdirectory of `DSH_HOME` that owns every generated audio file. */
+export const OUTPUT_SUBDIR = 'tts-output';
+/** Target characters per chunk, and the one-shot threshold. */
+export const DEFAULT_CHUNK_SIZE = 1_200;
+/** Long texts are chunked by default. */
+export const DEFAULT_CHUNKING_ENABLED = true;
+/** Engines the fallback chain understands, in default priority order. */
+export const DEFAULT_FALLBACK_ORDER = [
+    'edge-tts',
+    'sapi',
+    'speechSynthesis',
+];
+/** Fallback is enabled unless configured otherwise. */
+export const DEFAULT_FALLBACK_ENABLED = true;
+/** Syntheses allowed to run at the same time. */
+export const DEFAULT_MAX_CONCURRENT = 2;
+/** Callers allowed to wait for a synthesis slot. */
+export const DEFAULT_QUEUE_SIZE = 4;
+/** How long a caller may wait for a slot before TTS_BUSY. */
+export const DEFAULT_QUEUE_TIMEOUT_MS = 10_000;
+/** Upper bound for one complete `tts_generate` call, across all chunks. */
+export const DEFAULT_TOTAL_TIMEOUT_MS = 180_000;
+/** Extra Host names accepted by the audio route (reverse proxies). */
+export const DEFAULT_TRUSTED_HOSTS = [];
+/** Narrow an arbitrary config string to a known engine. */
+export function isTtsEngine(value) {
+    return DEFAULT_FALLBACK_ORDER.includes(value);
+}
+/**
+ * Config schema exposed to the DSH configuration layer. Defaults live here (not
+ * in call sites) so the settings surface and runtime behaviour agree.
+ */
+export const Config = z.object({
+    outputDir: z.string(),
+    defaultVoice: z.string().default(DEFAULT_VOICE),
+    timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS),
+    edgeTtsBinary: z.string().default(DEFAULT_EDGE_TTS_BINARY),
+    chunkSize: z.number().default(DEFAULT_CHUNK_SIZE),
+    chunkingEnabled: z.boolean().default(DEFAULT_CHUNKING_ENABLED),
+    fallbackEnabled: z.boolean().default(DEFAULT_FALLBACK_ENABLED),
+    fallbackOrder: z.array(z.string()).default([...DEFAULT_FALLBACK_ORDER]),
+    maxConcurrent: z.number().default(DEFAULT_MAX_CONCURRENT),
+    queueSize: z.number().default(DEFAULT_QUEUE_SIZE),
+    queueTimeoutMs: z.number().default(DEFAULT_QUEUE_TIMEOUT_MS),
+    totalTimeoutMs: z.number().default(DEFAULT_TOTAL_TIMEOUT_MS),
+    trustedHosts: z.array(z.string()).default([...DEFAULT_TRUSTED_HOSTS]),
+    proxy: z.string(),
+});
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * Resolve config defaults without touching the filesystem. A missing
+ * `DSH_HOME` is not fatal here: explicit `outputDir` still works, and the
+ * self-check needs to report the missing value instead of failing to load.
+ */
+export function resolveConfig(raw, env = process.env) {
+    const dshHome = nonEmpty(env.DSH_HOME) ?? '';
+    const configuredDir = nonEmpty(raw?.outputDir);
+    const outputDir = configuredDir
+        ? resolve(configuredDir)
+        : dshHome
+            ? resolve(dshHome, OUTPUT_SUBDIR)
+            : join(homedir(), '.dsh', OUTPUT_SUBDIR);
+    return {
+        dshHome,
+        outputDir,
+        defaultVoice: nonEmpty(raw?.defaultVoice) ?? DEFAULT_VOICE,
+        timeoutMs: raw?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        edgeTtsBinary: nonEmpty(raw?.edgeTtsBinary) ?? DEFAULT_EDGE_TTS_BINARY,
+        chunkSize: raw?.chunkSize ?? DEFAULT_CHUNK_SIZE,
+        chunkingEnabled: raw?.chunkingEnabled ?? DEFAULT_CHUNKING_ENABLED,
+        fallbackEnabled: raw?.fallbackEnabled ?? DEFAULT_FALLBACK_ENABLED,
+        fallbackOrder: raw?.fallbackOrder === undefined
+            ? [...DEFAULT_FALLBACK_ORDER]
+            : raw.fallbackOrder.filter(isTtsEngine),
+        maxConcurrent: raw?.maxConcurrent ?? DEFAULT_MAX_CONCURRENT,
+        queueSize: raw?.queueSize ?? DEFAULT_QUEUE_SIZE,
+        queueTimeoutMs: raw?.queueTimeoutMs ?? DEFAULT_QUEUE_TIMEOUT_MS,
+        totalTimeoutMs: raw?.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS,
+        trustedHosts: (raw?.trustedHosts ?? [...DEFAULT_TRUSTED_HOSTS])
+            .map((host) => host.trim().toLowerCase())
+            .filter((host) => host.length > 0),
+        proxy: nonEmpty(raw?.proxy),
+    };
+}
+/**
+ * Validate the settings a synthesis actually needs. Kept separate from
+ * {@link resolveConfig} so loading the plugin never fails at mount time.
+ */
+export function requireSynthesisConfig(config) {
+    if (!config.outputDir) {
+        throw new TtsError(ErrorCode.DshHomeNotSet, 'No output directory is available: DSH_HOME is not set and `outputDir` is not configured.', 'Set DSH_HOME in the DSH runtime, or set the plugin config field `outputDir`.');
+    }
+    if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+        throw new TtsError(ErrorCode.InvalidConfig, `Invalid config: timeoutMs must be a positive number, got ${JSON.stringify(config.timeoutMs)}.`, 'Set `timeoutMs` to a positive millisecond value (default 30000).');
+    }
+    if (config.chunkingEnabled &&
+        (!Number.isInteger(config.chunkSize) || config.chunkSize <= 0)) {
+        throw new TtsError(ErrorCode.InvalidConfig, `Invalid config: chunkSize must be a positive integer, got ${JSON.stringify(config.chunkSize)}.`, 'Set `chunkSize` to a positive character count (default 1200), or disable chunking.');
+    }
+    if (!Number.isInteger(config.maxConcurrent) ||
+        config.maxConcurrent < 1) {
+        throw new TtsError(ErrorCode.InvalidConfig, `Invalid config: maxConcurrent must be a positive integer, got ${JSON.stringify(config.maxConcurrent)}.`, 'Set `maxConcurrent` to at least 1 (default 2).');
+    }
+    if (!Number.isInteger(config.queueSize) || config.queueSize < 0) {
+        throw new TtsError(ErrorCode.InvalidConfig, `Invalid config: queueSize must be a non-negative integer, got ${JSON.stringify(config.queueSize)}.`, 'Set `queueSize` to 0 or more (default 4).');
+    }
+    if (!Number.isFinite(config.queueTimeoutMs) || config.queueTimeoutMs <= 0) {
+        throw new TtsError(ErrorCode.InvalidConfig, `Invalid config: queueTimeoutMs must be a positive number, got ${JSON.stringify(config.queueTimeoutMs)}.`, 'Set `queueTimeoutMs` to a positive millisecond value (default 10000).');
+    }
+    if (!Number.isFinite(config.totalTimeoutMs) || config.totalTimeoutMs <= 0) {
+        throw new TtsError(ErrorCode.InvalidConfig, `Invalid config: totalTimeoutMs must be a positive number, got ${JSON.stringify(config.totalTimeoutMs)}.`, 'Set `totalTimeoutMs` to a positive millisecond value (default 180000).');
+    }
+    return {
+        outputDir: config.outputDir,
+        timeoutMs: config.timeoutMs,
+        chunkSize: config.chunkSize,
+        chunkingEnabled: config.chunkingEnabled,
+        fallbackEnabled: config.fallbackEnabled,
+        fallbackOrder: config.fallbackOrder,
+        maxConcurrent: config.maxConcurrent,
+        queueSize: config.queueSize,
+        queueTimeoutMs: config.queueTimeoutMs,
+        totalTimeoutMs: config.totalTimeoutMs,
+        trustedHosts: config.trustedHosts,
+        proxy: config.proxy,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/edge-tts.d.ts

@@ -0,0 +1,74 @@
+/** Minimal child-process surface used by the runner, kept injectable for tests. */
+export interface ChildStream {
+    on(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
+}
+/** Structural view of the parts of `ChildProcess` this module relies on. */
+export interface ChildProcessLike {
+    stdout: ChildStream | null;
+    stderr: ChildStream | null;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    kill(signal?: NodeJS.Signals | number): boolean;
+}
+/** Options passed to the injectable spawn implementation. */
+export interface SpawnOptions {
+    stdio: ['ignore', 'pipe', 'pipe'];
+    windowsHide: boolean;
+    env: NodeJS.ProcessEnv;
+}
+/** Injection point for the real `child_process.spawn` (or a test double). */
+export type SpawnFunction = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcessLike;
+/** Captured outcome of one child process. A non-zero exit is not an error here. */
+export interface ProcessResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}
+/** Controls shared by every child-process call. */
+export interface RunProcessOptions {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    spawnImpl?: SpawnFunction;
+}
+/**
+ * Run one child process, consuming stdout and stderr concurrently so neither
+ * pipe can deadlock. Resolves for any completed exit status; throws structured
+ * errors for spawn denial, cancellation, and timeout (killing the child).
+ */
+export declare function runProcess(command: string, args: readonly string[], options: RunProcessOptions): Promise<ProcessResult>;
+/** Settings for one synthesis call. */
+export interface SynthesizeOptions {
+    voice: string;
+    rate: string;
+    /** Pitch adjustment such as `+10Hz`; omitted for Edge-TTS's own default. */
+    pitch?: string;
+    /** Volume adjustment such as `-10%`; omitted for Edge-TTS's own default. */
+    volume?: string;
+    /**
+     * HTTP proxy for the WSS connection, forwarded as `--proxy`. Edge-TTS does
+     * not honour `HTTPS_PROXY`, so this is the only way to route it.
+     */
+    proxy?: string;
+    binary: string;
+    outputDir: string;
+    /** Stable cache key; also names the output file. */
+    hash: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    spawnImpl?: SpawnFunction;
+    /** Injectable clock for deterministic tests. */
+    now?: Date;
+}
+/** Canonical audio description returned to the tool layer. */
+export interface SynthesizedAudio {
+    filePath: string;
+    format: string;
+}
+/**
+ * Invoke the Edge-TTS CLI for `text` and return the finished file. Writes to a
+ * `.partial` sibling and renames on success, so a crashed or concurrent run
+ * never leaves a file that the cache would treat as complete.
+ */
+export declare function synthesize(text: string, options: SynthesizeOptions): Promise<SynthesizedAudio>;
+//# sourceMappingURL=edge-tts.d.ts.map

package/dist/edge-tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-tts.d.ts","sourceRoot":"","sources":["../src/edge-tts.ts"],"names":[],"mappings":"AASA,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,GAAG,OAAO,CAAA;CACvE;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAC1B,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAC1B,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAA;IAC7D,EAAE,CACA,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GACrE,OAAO,CAAA;IACV,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,CAAA;CAChD;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,WAAW,EAAE,OAAO,CAAA;IACpB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CACvB;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,YAAY,KAClB,gBAAgB,CAAA;AAKrB,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,aAAa,CAAA;CAC1B;AAOD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,CAqFxB;AAED,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,gDAAgD;IAChD,GAAG,CAAC,EAAE,IAAI,CAAA;CACX;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAiBD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAyD3B"}

package/dist/edge-tts.js

@@ -0,0 +1,154 @@
+import { spawn } from 'node:child_process';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { AUDIO_FORMAT, outputFilePath } from "./cache.js";
+import { ErrorCode, TtsError, spawnFailure } from "./errors.js";
+/** Upper bound on captured stderr/stdout text, keeping the tail. */
+const MAX_CAPTURE = 8_000;
+const defaultSpawn = (command, args, options) => spawn(command, [...args], options);
+function appendTail(current, chunk) {
+    const next = current + chunk.toString();
+    return next.length > MAX_CAPTURE ? next.slice(next.length - MAX_CAPTURE) : next;
+}
+/**
+ * Run one child process, consuming stdout and stderr concurrently so neither
+ * pipe can deadlock. Resolves for any completed exit status; throws structured
+ * errors for spawn denial, cancellation, and timeout (killing the child).
+ */
+export function runProcess(command, args, options) {
+    const spawnImpl = options.spawnImpl ?? defaultSpawn;
+    const signal = options.signal;
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnImpl(command, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+                env: process.env,
+            });
+        }
+        catch (error) {
+            reject(spawnFailure(error));
+            return;
+        }
+        let settled = false;
+        let timer;
+        let stdout = '';
+        let stderr = '';
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const settle = (code, exitSignal) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve({ code, signal: exitSignal, stdout, stderr });
+        };
+        const stop = () => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // The process already exited; nothing to stop.
+            }
+        };
+        const onAbort = () => {
+            fail(new TtsError(ErrorCode.Aborted, 'Edge-TTS synthesis was aborted.'));
+            stop();
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdout = appendTail(stdout, chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr = appendTail(stderr, chunk);
+        });
+        child.on('error', (error) => fail(spawnFailure(error)));
+        child.on('close', (code, exitSignal) => {
+            if (signal?.aborted) {
+                fail(new TtsError(ErrorCode.Aborted, 'Edge-TTS synthesis was aborted.'));
+                return;
+            }
+            settle(code, exitSignal);
+        });
+        timer = setTimeout(() => {
+            fail(new TtsError(ErrorCode.SynthesisTimeout, `Edge-TTS did not finish within ${options.timeoutMs} ms.`, 'Increase `timeoutMs` or check network connectivity to the Edge-TTS service. 若网络正常但持续超时，请检查是否需要对 speech.platform.bing.com:443 配置代理。注意：环境变量 HTTPS_PROXY 对 edge-tts 的 WSS 连接无效，必须通过本插件的 `proxy` 配置项透传 `--proxy` 参数。详见 README 的「已知限制」章节。'));
+            stop();
+        }, options.timeoutMs);
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+function outputFailure(target, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return new TtsError(ErrorCode.OutputDirNotWritable, `Cannot write the audio file ${target}: ${detail}`, 'Check the DSH sandbox file policy and the output directory permissions. This is a filesystem denial, not a spawn EPERM.', { cause: error });
+}
+function stderrSuffix(stderr) {
+    const trimmed = stderr.trim();
+    return trimmed ? `\nstderr:\n${trimmed}` : '';
+}
+/**
+ * Invoke the Edge-TTS CLI for `text` and return the finished file. Writes to a
+ * `.partial` sibling and renames on success, so a crashed or concurrent run
+ * never leaves a file that the cache would treat as complete.
+ */
+export async function synthesize(text, options) {
+    const filePath = outputFilePath(options.outputDir, options.hash, options.now);
+    const partialPath = `${filePath}.partial`;
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+    }
+    catch (error) {
+        throw outputFailure(dirname(filePath), error);
+    }
+    const args = [
+        `--text=${text}`,
+        `--voice=${options.voice}`,
+        `--rate=${options.rate}`,
+        ...(options.pitch === undefined ? [] : [`--pitch=${options.pitch}`]),
+        ...(options.volume === undefined ? [] : [`--volume=${options.volume}`]),
+        ...(options.proxy === undefined ? [] : [`--proxy=${options.proxy}`]),
+        `--write-media=${partialPath}`,
+    ];
+    try {
+        const result = await runProcess(options.binary, args, {
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            spawnImpl: options.spawnImpl,
+        });
+        if (result.code !== 0) {
+            const status = result.code === null ? 'null' : String(result.code);
+            const signal = result.signal ? ` (signal ${result.signal})` : '';
+            throw new TtsError(ErrorCode.EdgeTtsFailed, `Edge-TTS exited with code ${status}${signal}.${stderrSuffix(result.stderr)}`, 'Check the voice and rate values and network connectivity, then run `tts_self_check`. 若网络正常但持续超时，请检查是否需要对 speech.platform.bing.com:443 配置代理。注意：环境变量 HTTPS_PROXY 对 edge-tts 的 WSS 连接无效，必须通过本插件的 `proxy` 配置项透传 `--proxy` 参数。详见 README 的「已知限制」章节。');
+        }
+        const info = await stat(partialPath).catch(() => undefined);
+        if (!info?.isFile() || info.size === 0) {
+            throw new TtsError(ErrorCode.EmptyAudio, 'Edge-TTS reported success but produced no audio bytes.', 'Retry the call; if it persists, run `tts_self_check` and inspect Edge-TTS output.');
+        }
+        try {
+            await rename(partialPath, filePath);
+        }
+        catch (error) {
+            throw outputFailure(filePath, error);
+        }
+    }
+    catch (error) {
+        await rm(partialPath, { force: true }).catch(() => { });
+        throw error;
+    }
+    return { filePath, format: AUDIO_FORMAT };
+}
+//# sourceMappingURL=edge-tts.js.map

package/dist/edge-tts.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+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 SpawnEperm: "SPAWN_EPERM";
+    readonly SpawnFailed: "SPAWN_FAILED";
+    readonly EdgeTtsFailed: "EDGE_TTS_FAILED";
+    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];
+/**
+ * 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;
+    constructor(code: TtsErrorCode, message: string, suggestion?: string, options?: ErrorOptions);
+}
+/** 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;;;;;;;;;;;;;;;;;;;CAmBZ,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAA;AAErE;;;;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;gBAEhB,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAM7F;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,68 @@
+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',
+    SpawnEperm: 'SPAWN_EPERM',
+    SpawnFailed: 'SPAWN_FAILED',
+    EdgeTtsFailed: 'EDGE_TTS_FAILED',
+    SynthesisTimeout: 'SYNTHESIS_TIMEOUT',
+    EmptyAudio: 'EMPTY_AUDIO',
+    Aborted: 'ABORTED',
+    TtsBusy: 'TTS_BUSY',
+    AllFallbacksFailed: 'ALL_FALLBACKS_FAILED',
+    SpeechSynthesisRequired: 'SPEECH_SYNTHESIS_REQUIRED',
+};
+/**
+ * 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;
+    constructor(code, message, suggestion, options) {
+        super(suggestion ? `${message}\nSuggestion: ${suggestion}` : message, code, options);
+        this.name = 'TtsError';
+        this.detail = message;
+        this.suggestion = suggestion;
+    }
+}
+/** 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":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,SAAS,EAAE,YAAY;IACvB,YAAY,EAAE,eAAe;IAC7B,WAAW,EAAE,cAAc;IAC3B,YAAY,EAAE,eAAe;IAC7B,aAAa,EAAE,gBAAgB;IAC/B,aAAa,EAAE,gBAAgB;IAC/B,aAAa,EAAE,kBAAkB;IACjC,oBAAoB,EAAE,yBAAyB;IAC/C,eAAe,EAAE,oBAAoB;IACrC,UAAU,EAAE,aAAa;IACzB,WAAW,EAAE,cAAc;IAC3B,aAAa,EAAE,iBAAiB;IAChC,gBAAgB,EAAE,mBAAmB;IACrC,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,UAAU;IACnB,kBAAkB,EAAE,sBAAsB;IAC1C,uBAAuB,EAAE,2BAA2B;CAC5C,CAAA;AAIV;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,YAAY;IACxC,sEAAsE;IAC7D,MAAM,CAAQ;IACvB,uEAAuE;IAC9D,UAAU,CAAS;IAE5B,YAAY,IAAkB,EAAE,OAAe,EAAE,UAAmB,EAAE,OAAsB;QAC1F,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,iBAAiB,UAAU,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;QACpF,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAA;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QACnE,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAA;QAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;IAC3C,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC7B,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAErE,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,IAAI,QAAQ,CACjB,SAAS,CAAC,eAAe,EACzB,0BAA0B,MAAM,EAAE,EAClC,qFAAqF,EACrF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,QAAQ,CACjB,SAAS,CAAC,UAAU,EACpB,uEAAuE,MAAM,EAAE,EAC/E,qIAAqI,EACrI,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,OAAO,IAAI,QAAQ,CACjB,SAAS,CAAC,WAAW,EACrB,6BAA6B,IAAI,IAAI,eAAe,MAAM,MAAM,EAAE,EAClE,wEAAwE,EACxE,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;AACH,CAAC"}

package/dist/fallback.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { 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;
+}
+/** Either a produced file or a request for the client to speak the text. */
+export type FallbackOutcome = {
+    kind: 'audio';
+    audio: SynthesizedAudio;
+    engine: TtsEngine;
+    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;
+}
+/** 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>;
+}
+/**
+ * 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,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,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GACvB;IACE,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,gBAAgB,CAAA;IACvB,MAAM,EAAE,SAAS,CAAA;IACjB,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;CACvB;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;CAC/B;AAuBD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAiD1B"}