@nanhara/hara 0.122.3 → 0.122.4

package/dist/gateway/telegram.js

@@ -2,8 +2,78 @@
 // fetch, zero new dep). Token from HARA_TELEGRAM_TOKEN. The generic `ChatAdapter` shape is what WeChat(iLink)
 // / Feishu plug into next.
 import { InboundMediaBudget, savePrivateResponse } from "./media.js";
+import { gatewayRuntimeScope } from "./runtime-state.js";
 const API = "https://api.telegram.org";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const processOutboundTails = new Map();
+/** Keeps each logical outbound message/file atomic within one credential-scoped chat while unrelated chats
+ * stay concurrent. The map is process-global rather than adapter-local because cron/flow delivery constructs
+ * short-lived adapters; those instances must not interleave chunks with the long-lived gateway adapter. */
+export class PerChatOutboundLane {
+    scope;
+    constructor(platform = "gateway", connectionIdentity = "default") {
+        // `gatewayRuntimeScope` hashes the credential identity. Raw tokens/app ids never enter map keys, logs, or
+        // persisted state, while two adapters for the same bot still share one lane.
+        this.scope = gatewayRuntimeScope(platform, connectionIdentity);
+    }
+    run(chatId, task) {
+        const key = `${this.scope}\0${String(chatId)}`;
+        const previous = processOutboundTails.get(key) ?? Promise.resolve();
+        const operation = previous.then(task, task);
+        // A failure is returned to its caller but cannot poison later sends in the same chat.
+        const tail = operation.then(() => undefined, () => undefined);
+        processOutboundTails.set(key, tail);
+        void tail.then(() => {
+            if (processOutboundTails.get(key) === tail)
+                processOutboundTails.delete(key);
+        });
+        return operation;
+    }
+}
+const DEFAULT_TEXT_TRANSFER_TIMEOUT_MS = 30_000;
+const DEFAULT_FILE_TRANSFER_TIMEOUT_MS = 120_000;
+const MAX_OUTBOUND_TRANSFER_TIMEOUT_MS = 120_000;
+const MIN_OUTBOUND_TRANSFER_TIMEOUT_MS = 50;
+/** Operator/test override remains bounded: outbound transport can never disable or exceed the hard ceiling. */
+export function outboundTransferTimeoutMs(kind, value = process.env.HARA_GATEWAY_OUTBOUND_TIMEOUT_MS) {
+    const fallback = kind === "file" ? DEFAULT_FILE_TRANSFER_TIMEOUT_MS : DEFAULT_TEXT_TRANSFER_TIMEOUT_MS;
+    if (value === undefined || value === "")
+        return fallback;
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed)
+        ? Math.max(MIN_OUTBOUND_TRANSFER_TIMEOUT_MS, Math.min(MAX_OUTBOUND_TRANSFER_TIMEOUT_MS, Math.trunc(parsed)))
+        : fallback;
+}
+/** Cooperative cancellation plus a hard caller deadline. The hard race is intentional: some transports
+ * ignore AbortSignal, but shutdown must still settle promptly. Adapters place this deadline outside their
+ * process-global lane so an ambiguous late transfer remains quarantined until it really settles. */
+export async function withOutboundDeadline(label, parentSignal, timeoutMs, transfer) {
+    if (parentSignal?.aborted)
+        throw new Error(`${label} cancelled`);
+    const controller = new AbortController();
+    let rejectStopped;
+    const stopped = new Promise((_resolve, reject) => { rejectStopped = reject; });
+    let stoppedOnce = false;
+    const stop = (reason) => {
+        if (stoppedOnce)
+            return;
+        stoppedOnce = true;
+        controller.abort(reason);
+        rejectStopped(reason);
+    };
+    const onParentAbort = () => stop(new Error(`${label} cancelled`));
+    parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+    const timer = setTimeout(() => stop(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    try {
+        // Starting through a microtask turns synchronous SDK throws into the same bounded promise path.
+        const running = Promise.resolve().then(() => transfer(controller.signal));
+        return await Promise.race([running, stopped]);
+    }
+    finally {
+        clearTimeout(timer);
+        parentSignal?.removeEventListener("abort", onParentAbort);
+    }
+}
 /** Extract an InboundMsg from a Telegram getUpdates result item (pure). Accepts text and photo messages
  *  (photo → caption or a "[图片]" marker; the image itself is downloaded in start()). null otherwise. */
 export function parseTelegramUpdate(u) {
@@ -19,6 +89,8 @@ export function parseTelegramUpdate(u) {
         userId: m.from?.id ?? 0,
         userName: m.from?.username || m.from?.first_name || String(m.from?.id ?? ""),
         text: text || "[图片]",
+        ...(Number.isSafeInteger(u?.update_id) ? { messageId: String(u.update_id) } : {}),
+        ...(Number.isFinite(Number(m.date)) && Number(m.date) > 0 ? { createdAtMs: Math.trunc(Number(m.date) * 1_000) } : {}),
         ...(m.chat?.type === "private" ? { chatType: "p2p" } : ["group", "supergroup"].includes(m.chat?.type) ? { chatType: "group" } : {}),
     };
 }
@@ -44,19 +116,114 @@ async function downloadTelegramFile(base, token, fileId, options) {
         return null;
     }
 }
-/** Split text into chunks ≤ max (Telegram caps a message at 4096 chars) (pure). */
+let messageSegmenter;
+function messageGraphemes(text) {
+    // Keep user-perceived characters (ZWJ emoji, flags, combining marks, CRLF) together. The fallback still
+    // protects surrogate pairs on runtimes without full ICU, although supported Hara runtimes provide it.
+    if (messageSegmenter === undefined) {
+        messageSegmenter = typeof Intl.Segmenter === "function"
+            ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+            : null;
+    }
+    return messageSegmenter
+        ? Array.from(messageSegmenter.segment(text), (entry) => entry.segment)
+        : Array.from(text);
+}
+function splitOversizedGrapheme(grapheme, max) {
+    const pieces = [];
+    let piece = "";
+    for (const point of grapheme) {
+        if (point.length > max) {
+            if (piece) {
+                pieces.push(piece);
+                piece = "";
+            }
+            // Only possible when max=1 and the code point is an astral character. The platform's UTF-16 bound is
+            // non-negotiable, so this is the sole case where even a code point must be split into code units.
+            for (let at = 0; at < point.length; at += max)
+                pieces.push(point.slice(at, at + max));
+            continue;
+        }
+        if (piece.length + point.length > max) {
+            pieces.push(piece);
+            piece = point;
+        }
+        else {
+            piece += point;
+        }
+    }
+    if (piece)
+        pieces.push(piece);
+    return pieces;
+}
+/** Split text into chunks whose JavaScript UTF-16 length is ≤ max (pure). */
 export function chunkText(text, max = 4000) {
+    if (!Number.isSafeInteger(max) || max < 1)
+        throw new RangeError("chunk size must be a positive integer");
     if (text.length <= max)
         return [text];
+    const units = messageGraphemes(text).flatMap((grapheme) => {
+        // A maliciously huge combining sequence cannot bypass the service limit. Splitting such a single cluster
+        // is the only case where both the hard platform bound and grapheme integrity cannot be satisfied.
+        return grapheme.length <= max ? [grapheme] : splitOversizedGrapheme(grapheme, max);
+    });
+    const widths = units.map((unit) => unit.length);
     const out = [];
-    for (let i = 0; i < text.length; i += max)
-        out.push(text.slice(i, i + max));
+    let start = 0;
+    while (start < units.length) {
+        let end = start;
+        let width = 0;
+        while (end < units.length && width + widths[end] <= max)
+            width += widths[end++];
+        if (end < units.length) {
+            const softFloor = Math.max(1, Math.floor(max / 2));
+            let breakAt = -1;
+            // Paragraph/line boundaries preserve the shape of long agent replies. Whitespace is the fallback;
+            // CJK prose without either still gets a safe hard grapheme boundary.
+            let candidateWidth = width;
+            for (let i = end - 1; i >= start; i--) {
+                if (candidateWidth < softFloor)
+                    break;
+                if (units[i].includes("\n")) {
+                    breakAt = i + 1;
+                    break;
+                }
+                candidateWidth -= widths[i];
+            }
+            if (breakAt < 0) {
+                candidateWidth = width;
+                for (let i = end - 1; i >= start; i--) {
+                    if (candidateWidth < softFloor)
+                        break;
+                    if (/^\s+$/u.test(units[i])) {
+                        breakAt = i + 1;
+                        break;
+                    }
+                    candidateWidth -= widths[i];
+                }
+            }
+            if (breakAt > start)
+                end = breakAt;
+        }
+        out.push(units.slice(start, end).join(""));
+        start = end;
+    }
     return out;
 }
 export function telegramAdapter(token) {
     const base = `${API}/bot${token}`;
-    const request = async (method, init) => {
-        const response = await fetch(`${base}/${method}`, init);
+    const outbound = new PerChatOutboundLane("telegram", token);
+    const request = async (method, init, signal) => {
+        let response;
+        try {
+            response = await fetch(`${base}/${method}`, { ...init, signal });
+        }
+        catch {
+            if (signal.aborted && signal.reason instanceof Error)
+                throw signal.reason;
+            // Never let a fetch implementation echo the bot-token URL/body through gateway logs or owner replies.
+            throw new Error(`Telegram ${method} transport failed`);
+        }
         let body;
         try {
             body = await response.json();
@@ -71,39 +238,103 @@ export function telegramAdapter(token) {
     };
     return {
         name: "telegram",
-        async send(chatId, text) {
-            for (const part of chunkText(text || "(empty)")) {
-                await request("sendMessage", {
-                    method: "POST",
-                    headers: { "content-type": "application/json" },
-                    body: JSON.stringify({ chat_id: chatId, text: part }),
+        async send(chatId, text, signal) {
+            await withOutboundDeadline("Telegram send", signal, outboundTransferTimeoutMs("text"), async (transferSignal) => {
+                return outbound.run(chatId, async () => {
+                    if (transferSignal.aborted) {
+                        throw transferSignal.reason instanceof Error ? transferSignal.reason : new Error("Telegram send cancelled");
+                    }
+                    for (const part of chunkText(text || "(empty)")) {
+                        await request("sendMessage", {
+                            method: "POST",
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify({ chat_id: chatId, text: part }),
+                        }, transferSignal);
+                    }
                 });
-            }
+            });
         },
-        async sendFile(chatId, file) {
-            // images → sendPhoto (inline preview); everything else → sendDocument (keeps the filename)
-            const name = file.safeName;
-            const isImg = /\.(png|jpe?g|gif|webp)$/i.test(name);
-            const form = new FormData();
-            form.append("chat_id", String(chatId));
-            form.append(isImg ? "photo" : "document", new Blob([new Uint8Array(file.bytes)]), name);
-            await request(isImg ? "sendPhoto" : "sendDocument", { method: "POST", body: form });
+        async sendFile(chatId, file, signal) {
+            await withOutboundDeadline("Telegram upload", signal, outboundTransferTimeoutMs("file"), async (transferSignal) => {
+                return outbound.run(chatId, async () => {
+                    if (transferSignal.aborted) {
+                        throw transferSignal.reason instanceof Error ? transferSignal.reason : new Error("Telegram upload cancelled");
+                    }
+                    // images → sendPhoto (inline preview); everything else → sendDocument (keeps the filename)
+                    const name = file.safeName;
+                    const isImg = /\.(png|jpe?g|gif|webp)$/i.test(name);
+                    const form = new FormData();
+                    form.append("chat_id", String(chatId));
+                    form.append(isImg ? "photo" : "document", new Blob([new Uint8Array(file.bytes)]), name);
+                    await request(isImg ? "sendPhoto" : "sendDocument", { method: "POST", body: form }, transferSignal);
+                });
+            });
         },
         async start(onMessage, signal, shouldDownload) {
             let offset = 0;
+            let consecutiveFailures = 0;
+            let outageAlerted = false;
+            const postAck = new Array();
             while (!signal.aborted) {
                 try {
-                    const res = await fetch(`${base}/getUpdates?timeout=30&offset=${offset}`, { signal });
-                    if (!res.ok) {
-                        await sleep(2000);
-                        continue;
+                    // Telegram's `timeout=30` is only a server-side long-poll hint. A half-open proxy/socket can ignore
+                    // it indefinitely, so the client adds a hard margin and aborts the actual fetch after 40 seconds.
+                    const acknowledgedCount = postAck.length;
+                    const j = await withOutboundDeadline("Telegram poll", signal, 40_000, async (pollSignal) => {
+                        let response;
+                        try {
+                            response = await fetch(`${base}/getUpdates?timeout=30&offset=${offset}`, { signal: pollSignal });
+                        }
+                        catch {
+                            if (pollSignal.aborted && pollSignal.reason instanceof Error)
+                                throw pollSignal.reason;
+                            // Fetch/proxy errors can include the complete request URL; never let the bot token reach logs.
+                            throw new Error("Telegram getUpdates transport failed");
+                        }
+                        if (!response.ok)
+                            throw new Error(`Telegram getUpdates failed: HTTP ${response.status}`);
+                        try {
+                            // Keep body consumption inside the hard deadline too. Receiving headers is not completion: a
+                            // half-open peer can otherwise leave response.json() pending forever after the timer is cleared.
+                            return await response.json();
+                        }
+                        catch {
+                            if (pollSignal.aborted && pollSignal.reason instanceof Error)
+                                throw pollSignal.reason;
+                            throw new Error("Telegram getUpdates returned an invalid response");
+                        }
+                    });
+                    // This successful request carried the offset advanced by the previous iteration, so Telegram has
+                    // now durably forgotten those updates. Only then may their private execution markers be removed.
+                    const acknowledged = postAck.splice(0, acknowledgedCount);
+                    for (const entry of acknowledged) {
+                        try {
+                            await entry.cleanup();
+                        }
+                        catch {
+                            entry.failures++;
+                            if (entry.failures === 1) {
+                                console.error("hara telegram: acknowledged-event cleanup failed; private marker will retry");
+                            }
+                            if (entry.failures >= 5) {
+                                console.error("hara telegram: ALERT acknowledged-event cleanup suspended after 5 failures; private marker retained for manual recovery");
+                            }
+                            else {
+                                postAck.push(entry);
+                            }
+                        }
                     }
-                    const j = (await res.json());
                     for (const u of j.result ?? []) {
-                        offset = Math.max(offset, (u.update_id ?? 0) + 1);
+                        const updateId = Number(u?.update_id);
+                        if (!Number.isSafeInteger(updateId) || updateId < 0 || !Number.isSafeInteger(updateId + 1)) {
+                            throw new Error("Telegram getUpdates returned an invalid update_id");
+                        }
+                        const nextOffset = updateId + 1;
                         const msg = parseTelegramUpdate(u);
-                        if (!msg)
+                        if (!msg) {
+                            offset = Math.max(offset, nextOffset);
                             continue;
+                        }
                         const fid = photoFileId(u); // a photo message → download it so the agent can SEE it
                         if (fid && shouldDownload?.(msg) === true) {
                             const budget = new InboundMediaBudget("telegram", signal);
@@ -113,12 +344,31 @@ export function telegramAdapter(token) {
                                 msg.transientFiles = [path];
                             }
                         }
-                        await onMessage(msg).catch(() => { });
+                        // Acknowledge only after the whole gateway callback succeeds. On failure the offset stays put,
+                        // so Telegram redelivers this update and later batch entries cannot overtake it.
+                        const cleanup = await onMessage(msg);
+                        offset = Math.max(offset, nextOffset);
+                        if (cleanup)
+                            postAck.push({ cleanup, failures: 0 });
+                        if (signal.aborted)
+                            break;
                     }
+                    if (outageAlerted)
+                        console.error("hara telegram: ✓ polling recovered");
+                    consecutiveFailures = 0;
+                    outageAlerted = false;
                 }
-                catch {
+                catch (error) {
                     if (signal.aborted)
                         break;
+                    consecutiveFailures++;
+                    if (consecutiveFailures === 1) {
+                        console.error(`hara telegram: update handling failed — ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    else if (consecutiveFailures === 3 || consecutiveFailures % 10 === 0) {
+                        outageAlerted = true;
+                        console.error(`hara telegram: ALERT polling/handling has failed ${consecutiveFailures} consecutive times`);
+                    }
                     await sleep(2000); // network blip → back off + retry
                 }
             }

package/dist/gateway/tts.js

@@ -11,8 +11,18 @@
 import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { writeFileSync } from "node:fs";
+import { chmodSync, lstatSync, rmSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
+import { terminateSubprocessTree } from "../security/subprocess-env.js";
+const DEFAULT_TTS_TIMEOUT_MS = 60_000;
+const MAX_TTS_TIMEOUT_MS = 120_000;
+/** TTS cannot opt out of a deadline. Small values remain available for deterministic health checks/tests. */
+export function ttsTimeoutMs(value = process.env.HARA_TTS_TIMEOUT_MS) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) && parsed > 0
+        ? Math.max(50, Math.min(Math.floor(parsed), MAX_TTS_TIMEOUT_MS))
+        : DEFAULT_TTS_TIMEOUT_MS;
+}
 /** Read TTS settings from the environment (fully configurable — nothing hardcoded). */
 export function ttsConfigFromEnv(env = process.env) {
     return {
@@ -22,6 +32,8 @@ export function ttsConfigFromEnv(env = process.env) {
         baseURL: (env.HARA_TTS_BASE_URL || "").trim(),
         apiKey: (env.HARA_TTS_API_KEY || "").trim(),
         cmd: (env.HARA_TTS_CMD || "").trim(),
+        // Passing an explicit fixture env must not accidentally fall back to the live process environment.
+        timeoutMs: ttsTimeoutMs(env.HARA_TTS_TIMEOUT_MS ?? Number.NaN),
     };
 }
 /** Normalize a reply for speech: collapse whitespace, drop code fences, cap length (long audio is unwanted). */
@@ -32,38 +44,113 @@ export function ttsCleanText(text, max = 1200) {
         .trim()
         .slice(0, max);
 }
-function run(cmd, args, stdin) {
-    return new Promise((resolve) => {
-        const c = spawn(cmd, args, { stdio: [stdin != null ? "pipe" : "ignore", "ignore", "ignore"] });
-        c.on("error", () => resolve(false));
-        c.on("close", (code) => resolve(code === 0));
-        if (stdin != null)
-            c.stdin?.end(stdin);
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("TTS cancelled");
+}
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw abortReason(signal);
+}
+/** Race even an API implementation that ignores AbortSignal, while still passing the signal to its fetch. */
+function withAbort(task, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            fn();
+        };
+        const onAbort = () => finish(() => reject(abortReason(signal)));
+        signal.addEventListener("abort", onAbort, { once: true });
+        task.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
+/** Run local TTS in its own process group. Cancellation escalates TERM→KILL for the whole descendant tree. */
+function run(cmd, args, signal, stdin) {
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const processGroup = process.platform !== "win32";
+        let child;
+        try {
+            child = spawn(cmd, args, {
+                stdio: [stdin != null ? "pipe" : "ignore", "ignore", "ignore"],
+                detached: processGroup,
+                windowsHide: true,
+            });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        let settled = false;
+        let stopping = false;
+        let cancelTermination;
+        const settle = (ok, error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", stop);
+            // Cancel only the API fallback. If TERM closed the direct child while a descendant survived, the helper's
+            // referenced force timer still kills the owned process group after the grace period.
+            cancelTermination?.();
+            child.stdin?.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(ok);
+        };
+        const stop = () => {
+            if (settled || stopping)
+                return;
+            stopping = true;
+            cancelTermination = terminateSubprocessTree(child, {
+                processGroup,
+                graceMs: 250,
+                fallbackMs: 250,
+                onFallback: () => settle(false, abortReason(signal)),
+            });
+        };
+        child.once("error", () => settle(false, stopping ? abortReason(signal) : undefined));
+        child.once("close", (code) => settle(code === 0, stopping ? abortReason(signal) : undefined));
+        child.stdin?.on("error", () => { });
+        signal.addEventListener("abort", stop, { once: true });
+        if (signal.aborted)
+            stop();
+        if (stdin != null && !stopping)
+            child.stdin?.end(stdin);
     });
 }
 // local: macOS `say` → m4a (AAC). Zero config; HARA_TTS_VOICE picks the voice (default Tingting / zh).
-async function sayTts(text, out, cfg) {
-    return run("say", ["-v", cfg.voice || "Tingting", "-o", out, "--file-format", "m4af", "--data-format", "aac", text]);
+async function sayTts(text, out, cfg, signal) {
+    return run("say", ["-v", cfg.voice || "Tingting", "-o", out, "--file-format", "m4af", "--data-format", "aac", text], signal);
 }
 // API: OpenAI-compatible /audio/speech. Works against OpenAI, Aliyun DashScope (compatible-mode), or a local
 // server exposing the same shape — set HARA_TTS_BASE_URL + HARA_TTS_API_KEY + HARA_TTS_MODEL + HARA_TTS_VOICE.
-async function openaiTts(text, out, cfg) {
+async function openaiTts(text, out, cfg, signal) {
     if (!cfg.apiKey && !cfg.baseURL)
         return false; // not configured → unavailable
-    const { default: OpenAI } = (await import("openai"));
-    const client = new OpenAI({ baseURL: cfg.baseURL || undefined, apiKey: cfg.apiKey || "x" });
-    const res = await client.audio.speech.create({ model: cfg.model || "tts-1", voice: cfg.voice || "alloy", input: text });
-    const buf = Buffer.from(await res.arrayBuffer());
-    if (!buf.length)
-        return false;
-    writeFileSync(out, buf);
-    return true;
+    return withAbort((async () => {
+        const { default: OpenAI } = (await import("openai"));
+        throwIfAborted(signal);
+        const client = new OpenAI({ baseURL: cfg.baseURL || undefined, apiKey: cfg.apiKey || "x" });
+        const res = await client.audio.speech.create({ model: cfg.model || "tts-1", voice: cfg.voice || "alloy", input: text }, { signal });
+        const buf = Buffer.from(await res.arrayBuffer());
+        throwIfAborted(signal);
+        if (!buf.length)
+            return false;
+        writeFileSync(out, buf, { flag: "wx", mode: 0o600 });
+        return true;
+    })(), signal);
 }
 // local: a configurable command (e.g. VoxCPM). `{out}` → output path; the text is piped on stdin.
-async function cmdTts(text, out, cfg) {
+async function cmdTts(text, out, cfg, signal) {
     if (!cfg.cmd)
         return false;
-    return run("sh", ["-c", cfg.cmd.replace(/\{out\}/g, out)], text);
+    return run("sh", ["-c", cfg.cmd.replace(/\{out\}/g, out)], signal, text);
 }
 const PROVIDERS = {
     say: sayTts,
@@ -71,30 +158,87 @@ const PROVIDERS = {
     cmd: cmdTts,
 };
 const EXT = { say: "m4a", openai: "mp3", cmd: "wav" };
-/** Synthesize `text` to a temp audio file; returns its path, or null on failure. Falls back to local `say`
- *  if a configured provider fails (so a misconfigured API never silently kills voice replies). */
-export async function synthesize(text, cfg = ttsConfigFromEnv()) {
+function isAbortSignal(value) {
+    return Boolean(value && typeof value.addEventListener === "function" && typeof value.aborted === "boolean");
+}
+function safeProviderError(error, cfg) {
+    let message = error instanceof Error ? error.message : String(error);
+    for (const [secret, replacement] of [[cfg.apiKey, "[redacted]"], [cfg.baseURL, "[redacted-url]"]]) {
+        if (secret)
+            message = message.split(secret).join(replacement);
+    }
+    return message;
+}
+function secureCompletedAudio(path) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size <= 0)
+            return false;
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Synthesize `text` to a temp audio file; returns its path, or null on provider/deadline failure. The legacy
+ * `synthesize(text, config)` form remains valid; gateway callers use `synthesize(text, signal, config?)`. */
+export async function synthesize(text, signalOrConfig, explicitConfig) {
+    const parentSignal = isAbortSignal(signalOrConfig) ? signalOrConfig : undefined;
+    if (parentSignal?.aborted)
+        throw abortReason(parentSignal);
     const clean = ttsCleanText(text);
     if (!clean)
         return null;
+    const cfg = isAbortSignal(signalOrConfig)
+        ? (explicitConfig ?? ttsConfigFromEnv())
+        : (explicitConfig ?? signalOrConfig ?? ttsConfigFromEnv());
+    const deadline = new AbortController();
+    const timeoutMs = ttsTimeoutMs(cfg.timeoutMs);
+    const timeoutError = new Error(`TTS timed out after ${timeoutMs}ms`);
+    const timeout = setTimeout(() => deadline.abort(timeoutError), timeoutMs);
+    const cancel = () => deadline.abort(parentSignal?.reason instanceof Error ? parentSignal.reason : new Error("TTS cancelled"));
+    parentSignal?.addEventListener("abort", cancel, { once: true });
     const provider = PROVIDERS[cfg.provider] ? cfg.provider : "say";
-    const out = join(tmpdir(), `hara-tts-${randomUUID().slice(0, 8)}.${EXT[provider] || "wav"}`);
+    const out = join(tmpdir(), `hara-tts-${randomUUID()}.${EXT[provider] || "wav"}`);
     try {
-        if (await PROVIDERS[provider](clean, out, cfg))
-            return out;
-    }
-    catch (e) {
-        console.error(`tts(${provider}): ${e?.message ?? e}`);
-    }
-    if (provider !== "say") {
         try {
-            const o2 = join(tmpdir(), `hara-tts-${randomUUID().slice(0, 8)}.m4a`);
-            if (await sayTts(clean, o2, cfg))
-                return o2; // graceful fallback to local
+            if (await PROVIDERS[provider](clean, out, cfg, deadline.signal) && secureCompletedAudio(out))
+                return out;
         }
-        catch {
-            /* give up */
+        catch (error) {
+            if (parentSignal?.aborted)
+                throw abortReason(parentSignal);
+            if (deadline.signal.aborted) {
+                console.error(`tts(${provider}): ${timeoutError.message}`);
+                return null;
+            }
+            console.error(`tts(${provider}): ${safeProviderError(error, cfg)}`);
         }
+        rmSync(out, { force: true });
+        if (provider !== "say" && !deadline.signal.aborted) {
+            const fallback = join(tmpdir(), `hara-tts-${randomUUID()}.m4a`);
+            try {
+                if (await sayTts(clean, fallback, cfg, deadline.signal) && secureCompletedAudio(fallback))
+                    return fallback; // graceful local fallback
+            }
+            catch (error) {
+                if (parentSignal?.aborted)
+                    throw abortReason(parentSignal);
+                if (deadline.signal.aborted)
+                    console.error(`tts(say): ${timeoutError.message}`);
+                else
+                    console.error(`tts(say): ${safeProviderError(error, cfg)}`);
+            }
+            rmSync(fallback, { force: true });
+        }
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+        parentSignal?.removeEventListener("abort", cancel);
+        // Returned paths are owned by the caller. Every other partial/late provider output is removed here.
+        if (deadline.signal.aborted)
+            rmSync(out, { force: true });
     }
-    return null;
 }