@nanhara/hara 0.122.2 → 0.122.4

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

package/dist/hooks.js

@@ -2,12 +2,11 @@
 // PreToolUse runs BEFORE a tool: non-zero, timeout, signal, or launch failure BLOCKS the call.
 // PostToolUse runs AFTER: observe-only (format, log, notify). Configured in config.json `hooks` + contributed
 // by plugins. The command receives {tool, payload} as JSON on stdin + HARA_TOOL_NAME in the env.
-import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { loadConfig } from "./config.js";
 import { pluginHooks } from "./plugins/plugins.js";
-import { redactToolSubprocessOutput, toolSubprocessEnv } from "./security/subprocess-env.js";
-import { shellCommand } from "./sandbox.js";
+import { redactToolSubprocessOutput } from "./security/subprocess-env.js";
+import { runShell } from "./sandbox.js";
 const cache = new Map();
 export function resetHooksCache() {
     cache.clear();
@@ -42,41 +41,42 @@ export function hasHooks(cwd = process.cwd()) {
     return !!(h.PreToolUse?.length || h.PostToolUse?.length);
 }
 /** Run hooks for an event matching `toolName`. Any abnormal PreToolUse termination fails closed;
- *  PostToolUse remains observe-only. Sync (hooks are short, opt-in); 30s timeout each. */
-export function runHooks(event, toolName, payload, cwd, timeoutMs = 30_000) {
+ *  PostToolUse remains observe-only. Every child owns a cancellable process group; no hook may hold the
+ *  event loop past the parent run deadline, and an aborted batch never starts its next command. */
+export async function runHooks(event, toolName, payload, cwd, timeoutMs = 30_000, signal) {
     for (const h of merged(cwd)[event] ?? []) {
+        if (signal?.aborted) {
+            return event === "PreToolUse"
+                ? { block: true, message: "⛔ blocked because the agent run was cancelled before the PreToolUse hook completed" }
+                : { block: false, message: "" };
+        }
         if (!matches(h.matcher, toolName))
             continue;
-        let r;
         try {
             // Hooks are user/plugin-configured external code. Route them through the same command preflight and
             // macOS protected-read mask as Bash, even though hooks remain observe-only after a tool has run.
-            const shell = shellCommand(h.command, cwd, "off");
-            r = spawnSync(shell.cmd, shell.args, {
-                cwd,
-                input: JSON.stringify({ tool: toolName, payload }),
-                encoding: "utf8",
+            await runShell(h.command, cwd, "off", {
+                signal,
                 timeout: timeoutMs,
-                env: toolSubprocessEnv(process.env, { HARA_TOOL_NAME: toolName }),
+                maxBuffer: 256 * 1024,
+                input: JSON.stringify({ tool: toolName, payload }),
+                env: { HARA_TOOL_NAME: toolName },
             });
         }
         catch (error) {
             if (event === "PreToolUse") {
-                const detail = redactToolSubprocessOutput(error instanceof Error ? error.message : String(error));
-                return { block: true, message: `⛔ blocked because a PreToolUse hook could not start${detail ? `: ${detail}` : ""}` };
+                const failure = error;
+                const output = redactToolSubprocessOutput(`${failure.stdout ?? ""}${failure.stderr ?? ""}`.trim());
+                const detail = redactToolSubprocessOutput(failure.message || String(error));
+                return {
+                    block: true,
+                    message: `⛔ blocked by a PreToolUse hook${output ? `: ${output}` : detail ? ` (${detail})` : ""}`,
+                };
             }
             // PostToolUse is best-effort: a policy-blocked or broken observer must never rewrite the result of a
             // tool that already completed. In particular, do not retry it through an unsandboxed fallback shell.
             continue;
         }
-        // A hook is allowed to ignore stdin. On Linux, a command that exits successfully before Node finishes
-        // writing `input` can report EPIPE in r.error *alongside status=0*. The wait status is authoritative in
-        // that case; true launch/write failures still have status=null, while timeouts/signals remain blocked.
-        if (event === "PreToolUse" && (r.status !== 0 || !!r.signal)) {
-            const output = redactToolSubprocessOutput((String(r.stdout ?? "") + String(r.stderr ?? "")).trim());
-            const failure = redactToolSubprocessOutput(r.error?.message || (r.signal ? `terminated by ${r.signal}` : `exit ${r.status ?? "unknown"}`));
-            return { block: true, message: `⛔ blocked by a PreToolUse hook${output ? `: ${output}` : ` (${failure})`}` };
-        }
     }
     return { block: false, message: "" };
 }