comisai 1.0.42 → 1.0.44

package/node_modules/@comis/skills/dist/tools/integrations/local-stt-adapter.js

@@ -0,0 +1,331 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * In-process keyless whisper STT adapter (LOCAL-01 / LOCAL-02 / LOCAL-04).
+ *
+ * The zero-config default rung of STT `auto`: it transcribes with NO key by
+ * running whisper in-process via `@huggingface/transformers` (Transformers.js),
+ * auto-downloading a small ONNX model on first use to a scoped cache under
+ * `~/.comis/models/whisper/`, then reusing it on every later call (a
+ * module-level singleton — the model loads once per process and is NOT evicted
+ * by a per-call transcribe failure, only by a load failure; modulo a concurrent
+ * cold start where two simultaneous first calls can each build it before the
+ * promise is memoized — IN-01, a self-healing cold-start-only inefficiency).
+ *
+ * Design constraints (all enforced by local-stt-adapter.test.ts):
+ *  - **Honest-degrade (LOCAL-02):** the engine is lazy-imported INSIDE a guarded
+ *    `await import("@huggingface/transformers")` — NEVER a top-level static
+ *    import — so a missing/broken install (or its native ORT addon) yields
+ *    `Result.err` rather than crashing the whole `@comis/skills` import graph.
+ *    Every failure branch returns `ok(...)` / `err(...)`; this module NEVER
+ *    `throw`s (the raw-throw architecture gate).
+ *  - **Audio decode:** the inbound Buffer is decoded to a 16 kHz mono
+ *    `Float32Array` by shelling the existing ffmpeg binary (`-f f32le -ar 16000
+ *    -ac 1`) — no new audio library (mirrors `audio-converter.ts`).
+ *  - **Scoped cache (LOCAL-04):** `env.cacheDir` is set to
+ *    `safePath(dataDir, "models", "whisper")` (NEVER raw `path.join`) before the
+ *    first `pipeline()` call; that path is already inside the daemon's
+ *    `--allow-fs-write=${COMIS_DATA_DIR}` scope, so no new permission flag.
+ *  - **Fail-closed + integrity (SEC-03):** the LIVE, prod-running integrity
+ *    mechanism is the pinned `MODEL_IDS` anchor (only a hardcoded id is loaded;
+ *    an unknown key → the pinned default) + the TLS HF-Hub source + the
+ *    fail-closed load: a short/corrupt `pipeline()` load → `err` (kind
+ *    `model_load_failed`) and the singleton is RESET so a transient failure can
+ *    retry — never a silent partial-model success. The post-load `statModelCache`
+ *    size-floor (a sub-`MODEL_SIZE_FLOOR_BYTES` cached model → fail-closed) is an
+ *    OPTIONAL, **TEST-ONLY** seam: its default (`defaultStatModelCache`) returns
+ *    `undefined`, so it enforces NOTHING off a real daemon (the transformers.js
+ *    etag cache layout is not a documented contract — guessing a path to stat is
+ *    the §2.10 bug class). Do NOT read the size-floor as live corrupt-download
+ *    protection; the fail-closed LOAD is what catches a truncated download in
+ *    prod. HONEST limit: transformers.js exposes NO caller-visible content-hash,
+ *    so SEC-03 is pinned-id + TLS + fail-closed load (NOT a content-hash, and NOT
+ *    a size-floor in prod). The TTS twin (`local-tts-adapter.ts`) deliberately
+ *    carries NO size-floor seam at all — its SEC-03 scope is the same pinned-id +
+ *    TLS + fail-closed-load triad, MINUS the inert STT size seam.
+ *  - **Redaction (SEC-01 light floor):** every surfaced error string is passed
+ *    through `sanitizeApiError`, which strips URLs (`[URL]`) and long tokens
+ *    (`[REDACTED]`), so no credential-bearing `baseUrl`/token leaks.
+ *
+ * The engine loader and the ffmpeg decode are injectable config seams
+ * (`loadEngine` / `decodeToPcm16kF32`) so unit tests never touch the network
+ * or ffmpeg; they default to the real lazy-import + ffmpeg path.
+ *
+ * @module
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as fs from "node:fs/promises";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
+import { safePath } from "@comis/core";
+import { ok, err } from "@comis/shared";
+import { sanitizeApiError } from "./media-adapter-shared.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_MODEL = "base";
+const DEFAULT_MAX_FILE_SIZE_MB = 25;
+const DECODE_TIMEOUT_MS = 30_000;
+/**
+ * Exact ONNX whisper repo ids per size (the `onnx-community/*` Transformers.js-
+ * compatible repos). This is the SEC-03 "pinned model id" anchor: only these
+ * hardcoded ids are ever loaded — an unknown/blank model key resolves to the
+ * pinned default ({@link DEFAULT_MODEL}) below, so no caller-supplied/arbitrary
+ * remote id can be fetched. Fetched over TLS from the HF Hub (`allowRemoteModels`).
+ *
+ * SEC-03 HONEST scope: this is pinned-id + TLS + the fail-closed
+ * `model_load_failed` seam + an OPTIONAL post-load size-floor — NOT a pinned
+ * content-hash. Transformers.js etag-caches the download but exposes no
+ * caller-visible content-hash API, so no cryptographic-integrity claim is made
+ * (documented in voice.mdx by Plan 04).
+ */
+const MODEL_IDS = {
+    tiny: "onnx-community/whisper-tiny",
+    base: "onnx-community/whisper-base",
+    small: "onnx-community/whisper-small",
+};
+/**
+ * SEC-03 size-floor: a cached whisper model below this many bytes is treated as
+ * a truncated/partial download (corruption), never a valid model. The smallest
+ * pinned model (whisper-tiny, q8) is multiple MB on disk; 1 MB is a conservative
+ * floor that no real model undershoots but a near-zero/partial file trips. Only
+ * enforced when the `statModelCache` seam returns a concrete size (the default
+ * returns `undefined` → no enforcement; see the seam doc-comment).
+ */
+const MODEL_SIZE_FLOOR_BYTES = 1024 * 1024; // 1 MB
+/**
+ * Module-level singleton: memoizes the `pipeline(...)` promise so the model
+ * loads once per process (LOCAL-01 "2nd call no re-download"). It is reset to
+ * `undefined` ONLY on a LOAD error (fail-closed retry — never a memoized partial
+ * model). A per-call TRANSCRIBE failure does NOT reset it (WR-01) — a bad audio
+ * input must not thrash the good, already-loaded model.
+ */
+let pipelinePromise;
+/**
+ * TEST-ONLY: reset the module singleton between tests. Not exported on the
+ * package barrel — only imported by `local-stt-adapter.test.ts`.
+ */
+export function __resetLocalWhisperPipelineForTests() {
+    pipelinePromise = undefined;
+}
+/**
+ * Attach a domain `SttErrorKind` onto an Error and brand it as a
+ * `SttDegradeError` (WR-02). Used for the clean-message guard branches
+ * (empty buffer / oversize) where the message needs no third-party
+ * sanitization — only the kind. Writable assign; public shape is readonly.
+ */
+function withKind(error, kind) {
+    // Assign through an index-signature view (overlaps with Error, so no
+    // through-`unknown` cast); the public SttDegradeError shape is readonly.
+    error["kind"] = kind;
+    return error;
+}
+/**
+ * Build a redacted, hint-bearing, kind-carrying Error for a surfaced failure
+ * branch that wraps a third-party `cause` (WR-02). The `kind` is attached so the
+ * Phase-196 obs path can read it without re-deriving; the free-text `detail` is
+ * run through `sanitizeApiError` (strips URLs → `[URL]`, long tokens →
+ * `[REDACTED]`) so no credential-bearing `baseUrl`/token leaks.
+ */
+function degraded(hint, cause, kind) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return withKind(new Error(`${hint} — ${sanitizeApiError(0, detail, "Local Whisper")}`), kind);
+}
+/**
+ * Convert a raw f32le PCM buffer (as ffmpeg writes it) into a copied
+ * `Float32Array`, validating the decode at the boundary (WR-04).
+ *
+ * A zero-byte buffer means ffmpeg "succeeded" (exit 0) but produced no PCM —
+ * a valid container with no decodable audio stream, or a 0-duration clip. A
+ * non-multiple-of-4 length means stray bytes that are NOT a whole f32 sample.
+ * Both are decode anomalies: surface a `degraded` `err` (kind `dependency`)
+ * instead of feeding an empty / truncated sample array into the engine (which
+ * would either throw — mishandled — or yield a phantom-empty transcript). The
+ * result is copied out of the file-backed buffer so it survives temp cleanup.
+ */
+function pcmBufferToSamples(pcmBuffer) {
+    if (pcmBuffer.byteLength === 0 || pcmBuffer.byteLength % 4 !== 0) {
+        return err(degraded("ffmpeg produced no decodable PCM for local whisper (no audio stream or zero-length clip)", new Error(`pcm bytes=${pcmBuffer.byteLength}`), "dependency"));
+    }
+    const samples = new Float32Array(pcmBuffer.buffer, pcmBuffer.byteOffset, pcmBuffer.byteLength / 4);
+    // Copy out of the file-backed buffer so the typed array survives cleanup.
+    return ok(Float32Array.from(samples));
+}
+/**
+ * TEST-ONLY: exercise the WR-04 PCM-boundary guard without shelling real ffmpeg.
+ * Not exported on the package barrel — only imported by
+ * `local-stt-adapter.test.ts` (same invariant as
+ * `__resetLocalWhisperPipelineForTests`).
+ */
+export function __pcmBufferToSamplesForTests(pcmBuffer) {
+    return pcmBufferToSamples(pcmBuffer);
+}
+/**
+ * Default ffmpeg decode: shells ffmpeg to raw 16 kHz mono f32 PCM, then reads it
+ * into a Float32Array. Mirrors `audio-converter.ts:extractWaveform` (s16le/8000
+ * → f32le/16000). Returns a `degraded(...)` `err` carrying kind `dependency`
+ * (IN-02: the kind is now ATTACHED to the surfaced error, not discarded — see
+ * `degraded`) on any ffmpeg failure OR an empty / non-4-byte-multiple decode
+ * (WR-04). Never throws. The temp file is always cleaned up.
+ */
+async function defaultDecodeToPcm16kF32(audio, _mime) {
+    const tempDir = os.tmpdir();
+    const inputPath = safePath(tempDir, `stt-in-${crypto.randomUUID()}.bin`);
+    const tempPcm = safePath(tempDir, `stt-pcm-${crypto.randomUUID()}.raw`);
+    try {
+        await fs.writeFile(inputPath, audio);
+        await execFileAsync("ffmpeg", ["-y", "-i", inputPath, "-f", "f32le", "-ac", "1", "-ar", "16000", tempPcm], { timeout: DECODE_TIMEOUT_MS });
+        const pcmBuffer = await fs.readFile(tempPcm);
+        // WR-04: validate the decode (empty / non-4-byte-multiple) at the boundary.
+        return pcmBufferToSamples(pcmBuffer);
+    }
+    catch (e) {
+        return err(degraded("ffmpeg failed to decode audio for local whisper — ensure ffmpeg is installed and the input is valid audio", e, "dependency"));
+    }
+    finally {
+        await fs.rm(inputPath, { force: true }).catch(() => undefined);
+        await fs.rm(tempPcm, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Default SEC-03 size-floor seam: ALWAYS returns `undefined` (size unknown), so
+ * the size-floor enforces NOTHING in production — it is inert by default and the
+ * floor branch only ever fires when a test injects a concrete size. The
+ * transformers.js etag cache layout is NOT a documented contract, so production
+ * does NOT guess a model-file path to `fs.stat` (the §2.10 bug class — a
+ * hand-built path that may not exist). The LIVE prod integrity floor is the
+ * pinned id + the fail-closed LOAD (`model_load_failed`) + the TLS HF-Hub source,
+ * NOT this seam. `safePath` would be used (never raw `path.join`) by any future
+ * real inspection that adopts a documented layout.
+ */
+async function defaultStatModelCache(_cacheDir, _modelId) {
+    return undefined;
+}
+/** Default engine loader: a guarded lazy import (never a top-level static import). */
+async function defaultLoadEngine() {
+    // The literal module name appears ONLY here, inside the guarded loader, so a
+    // missing/broken install degrades to Result.err in transcribe() rather than
+    // crashing the @comis/skills import graph.
+    const mod = (await import("@huggingface/transformers"));
+    return mod;
+}
+/**
+ * Create the in-process keyless whisper STT adapter.
+ *
+ * No API key. The first `transcribe()` lazy-loads the engine, decodes the audio
+ * via ffmpeg, and downloads + caches the model once; later calls reuse the
+ * cached pipeline. Every failure branch returns `Result.err` — never throws.
+ */
+export function createLocalWhisperAdapter(cfg) {
+    const modelKey = cfg.model ?? DEFAULT_MODEL;
+    const maxFileSizeMb = cfg.maxFileSizeMb ?? DEFAULT_MAX_FILE_SIZE_MB;
+    const cacheDir = safePath(cfg.dataDir, "models", "whisper");
+    const loadEngine = cfg.loadEngine ?? defaultLoadEngine;
+    const decode = cfg.decodeToPcm16kF32 ?? defaultDecodeToPcm16kF32;
+    const statModelCache = cfg.statModelCache ?? defaultStatModelCache;
+    // SEC-03 pinned-id anchor: only a hardcoded MODEL_IDS value is ever loaded; an
+    // unknown/blank key resolves to the pinned default — never the raw caller key.
+    const modelId = MODEL_IDS[modelKey] ?? MODEL_IDS[DEFAULT_MODEL];
+    return {
+        async transcribe(audio, options) {
+            // 1. Empty-buffer guard — runs before any engine load or decode.
+            if (audio.byteLength === 0) {
+                // Carry the kind like every other branch (clean message, no third-party
+                // cause to sanitize → withKind, not degraded). IN-02: this is really a
+                // VALIDATION failure (bad input), but the closed SttErrorKind vocabulary
+                // (voice-error.ts) has no `validation` member, so `dependency` is the
+                // deliberate vocabulary mapping here — NOT a real missing-dependency.
+                return err(withKind(new Error("Audio buffer is empty"), "dependency"));
+            }
+            // 2. Size cap. IN-02: also a validation failure; `dependency` is the
+            //    deliberate mapping (the SttErrorKind union has no `validation` member).
+            const fileSizeMb = audio.byteLength / (1024 * 1024);
+            if (fileSizeMb > maxFileSizeMb) {
+                return err(withKind(new Error(`Audio file size ${fileSizeMb.toFixed(1)}MB exceeds limit of ${maxFileSizeMb}MB`), "dependency"));
+            }
+            // 3. Decode to 16 kHz mono f32 PCM FIRST — a cheap ffmpeg check that
+            //    short-circuits before paying the (heavy) engine-import cost on a
+            //    decode failure (no engine load attempted after a decode fail).
+            const pcm = await decode(audio, options.mimeType);
+            if (!pcm.ok) {
+                return pcm;
+            }
+            // 4. Lazy engine load — honest-degrade (LOCAL-02), never a module-load crash.
+            let mod;
+            try {
+                mod = await loadEngine();
+            }
+            catch (e) {
+                return err(degraded("Local whisper engine unavailable — install @huggingface/transformers or set transcription.local.baseUrl to a local whisper server", e, "dependency"));
+            }
+            // 5. Singleton pipeline build — fail-closed ONLY on a bad load (SEC-03
+            //    seam). IN-01: memoize the pipeline() PROMISE synchronously the moment
+            //    the engine module is in hand — there is NO `await` between the
+            //    `undefined` check and the assignment, so two near-simultaneous first
+            //    calls that reach here serialize on the one shared promise rather than
+            //    each building the model (modulo a concurrent cold start where both
+            //    are still awaiting loadEngine — see the doc-comment caveat).
+            let transcriber;
+            try {
+                if (pipelinePromise === undefined) {
+                    mod.env["cacheDir"] = cacheDir; // scoped, inside --allow-fs-write (LOCAL-04)
+                    mod.env["allowRemoteModels"] = true; // first-run HF-Hub download over TLS
+                    pipelinePromise = mod.pipeline("automatic-speech-recognition", modelId, {
+                        dtype: "q8", // quantized → minimal first-run download
+                    });
+                }
+                transcriber = await pipelinePromise;
+            }
+            catch (e) {
+                // Fail-closed: a failed/partial LOAD is NOT memoized — reset so a
+                // transient load failure can retry on the next call. This reset is
+                // correct ONLY for the load branch (WR-01).
+                pipelinePromise = undefined;
+                return err(degraded("Local whisper model failed to load — the download may be incomplete or the model id is unavailable", e, "model_load_failed"));
+            }
+            // SEC-03 size-floor (OPTIONAL, TEST-ONLY seam — inert in prod): a
+            // pipeline() that "loaded" but whose on-disk model is implausibly small is
+            // a truncated/partial download masquerading as a working model (the
+            // v2.24/188 silent-corrupt-download lesson). When the injected size seam
+            // reports a concrete sub-floor size, FAIL CLOSED and reset the singleton
+            // (same fail-closed discipline as the load catch) so the bad model is never
+            // memoized and a re-download is retried. The DEFAULT seam returns
+            // `undefined` (cache layout is not a documented contract → no path guess),
+            // so this branch enforces NOTHING off a real daemon — the live SEC-03
+            // protection for a corrupt download is the fail-closed LOAD above, not this.
+            let modelBytes;
+            try {
+                modelBytes = await statModelCache(cacheDir, modelId);
+            }
+            catch {
+                // A stat failure is NOT corruption — keep the load and rely on the
+                // pinned-id + fail-closed triad (an unreadable stat must not block a
+                // working model).
+                modelBytes = undefined;
+            }
+            if (modelBytes !== undefined && modelBytes < MODEL_SIZE_FLOOR_BYTES) {
+                pipelinePromise = undefined;
+                return err(degraded("Local whisper model failed integrity check — the cached model is implausibly small (incomplete/truncated download)", new Error(`model bytes=${modelBytes} below floor=${MODEL_SIZE_FLOOR_BYTES}`), "model_load_failed"));
+            }
+            // 6. Transcribe — a per-call inference failure does NOT evict the good,
+            //    already-loaded model (WR-01). The singleton stays memoized; a bad
+            //    audio input is not a reason to thrash the load-once pipeline. The
+            //    kind is `dependency` (a runtime inference failure), NOT
+            //    `model_load_failed` (the model loaded fine).
+            try {
+                const out = await transcriber(pcm.value);
+                // WR-03: out.text is the result of an injected/dynamically-imported
+                // third-party fn; the `text: string` type is an assertion, not a
+                // runtime guarantee. Validate at the boundary so an unexpected shape
+                // ({ text: undefined }, a chunked array, {}) surfaces as an honest err
+                // rather than a phantom ok({ text: undefined }).
+                const text = typeof out?.text === "string" ? out.text : undefined;
+                if (text === undefined) {
+                    return err(degraded("Local whisper returned no transcript text — unexpected engine output shape", new Error(`unexpected result: ${typeof out?.text}`), "dependency"));
+                }
+                return ok({ text, language: options.language, durationMs: undefined });
+            }
+            catch (e) {
+                return err(degraded("Local whisper failed to transcribe this audio", e, "dependency"));
+            }
+        },
+    };
+}

package/node_modules/@comis/skills/dist/tools/integrations/local-stt-probe.d.ts

@@ -0,0 +1,65 @@
+/**
+ * One-shot boot probe for the keyless local STT engine (LOCAL-02).
+ *
+ * `detectLocalSttEngine` answers, ONCE at daemon boot, the question the
+ * Phase-193 resolver predicate `localEngineAvailable()` needs: can the `local`
+ * STT rung actually transcribe? It NEVER throws and it NEVER downloads a model
+ * — it only checks cheap signals (a short-timeout reachability fetch to a
+ * configured server, OR engine-importability + ffmpeg presence). The boolean
+ * result is captured by the daemon wiring and closed over as a synchronous
+ * `() => boolean` (Plan 03), so the resolver does no per-call I/O.
+ *
+ * Availability rule (CONTEXT decision I6):
+ *   1. `baseUrl` set + reachable  → available, mode "baseUrl" (the in-process
+ *      engine is NOT consulted — a reachable local OpenAI-compatible whisper
+ *      server is sufficient).
+ *   2. else, in-process path: ffmpeg present AND `@huggingface/transformers`
+ *      importable → available, mode "in-process".
+ *   3. otherwise → not available, mode "none".
+ *
+ * Security (SEC-02): the configured `baseUrl` is validated by
+ * `validateLocalServerUrl` (the inverse SSRF guard — ALLOW loopback + an
+ * explicit allowlist, DENY public/private egress, keep the cloud-metadata deny)
+ * BEFORE the reachability fetch fires. A non-loopback/unconfigured baseUrl is
+ * treated as not-reachable (the guard rejects it and the probe falls through to
+ * the in-process path) so a mis/maliciously-configured URL can never drive an
+ * SSRF fetch from the boot probe. The reachability check itself is a
+ * short-timeout fetch wrapped in a try (any error → not-reachable), and (CR-01)
+ * is PINNED to the IP the guard resolved (undici dispatcher) so a hostname that
+ * passed as loopback cannot be rebound to a different IP at connect time
+ * (DNS-rebinding/TOCTOU). No credential-bearing URL is logged.
+ *
+ * @module
+ */
+/** Result of the one-shot local STT boot probe. */
+export interface LocalSttProbeResult {
+    /** Whether the `local` STT rung can transcribe. */
+    readonly available: boolean;
+    /** Which mechanism made it available (or "none"). */
+    readonly mode: "baseUrl" | "in-process" | "none";
+}
+/** Dependencies for the one-shot local STT boot probe. */
+export interface LocalSttProbeDeps {
+    /** Optional local OpenAI-compatible whisper server URL (LOCAL-03). */
+    readonly baseUrl?: string;
+    /** Whether ffmpeg is available (the in-process path needs it to decode). */
+    readonly ffmpegAvailable: boolean;
+    /**
+     * Reachability seam: resolves `true` if the baseUrl server is reachable.
+     * Defaults to a short-timeout fetch. Injected in tests to avoid real I/O.
+     */
+    readonly fetchProbe?: (url: string) => Promise<boolean>;
+    /**
+     * Engine-importability seam: resolves `true` if `@huggingface/transformers`
+     * imports. Defaults to a guarded lazy import (never throws, never downloads).
+     * Injected in tests.
+     */
+    readonly canImportEngine?: () => Promise<boolean>;
+    /** Reachability-probe timeout in ms (default 1500). */
+    readonly timeoutMs?: number;
+}
+/**
+ * Detect whether the keyless local STT engine is usable. One-shot, never throws,
+ * never downloads a model.
+ */
+export declare function detectLocalSttEngine(deps: LocalSttProbeDeps): Promise<LocalSttProbeResult>;

package/node_modules/@comis/skills/dist/tools/integrations/local-stt-probe.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * One-shot boot probe for the keyless local STT engine (LOCAL-02).
+ *
+ * `detectLocalSttEngine` answers, ONCE at daemon boot, the question the
+ * Phase-193 resolver predicate `localEngineAvailable()` needs: can the `local`
+ * STT rung actually transcribe? It NEVER throws and it NEVER downloads a model
+ * — it only checks cheap signals (a short-timeout reachability fetch to a
+ * configured server, OR engine-importability + ffmpeg presence). The boolean
+ * result is captured by the daemon wiring and closed over as a synchronous
+ * `() => boolean` (Plan 03), so the resolver does no per-call I/O.
+ *
+ * Availability rule (CONTEXT decision I6):
+ *   1. `baseUrl` set + reachable  → available, mode "baseUrl" (the in-process
+ *      engine is NOT consulted — a reachable local OpenAI-compatible whisper
+ *      server is sufficient).
+ *   2. else, in-process path: ffmpeg present AND `@huggingface/transformers`
+ *      importable → available, mode "in-process".
+ *   3. otherwise → not available, mode "none".
+ *
+ * Security (SEC-02): the configured `baseUrl` is validated by
+ * `validateLocalServerUrl` (the inverse SSRF guard — ALLOW loopback + an
+ * explicit allowlist, DENY public/private egress, keep the cloud-metadata deny)
+ * BEFORE the reachability fetch fires. A non-loopback/unconfigured baseUrl is
+ * treated as not-reachable (the guard rejects it and the probe falls through to
+ * the in-process path) so a mis/maliciously-configured URL can never drive an
+ * SSRF fetch from the boot probe. The reachability check itself is a
+ * short-timeout fetch wrapped in a try (any error → not-reachable), and (CR-01)
+ * is PINNED to the IP the guard resolved (undici dispatcher) so a hostname that
+ * passed as loopback cannot be rebound to a different IP at connect time
+ * (DNS-rebinding/TOCTOU). No credential-bearing URL is logged.
+ *
+ * @module
+ */
+import { systemSetTimeout, systemClearTimeout, validateLocalServerUrl } from "@comis/core";
+import { fetchPinned } from "./pinned-fetch.js";
+/** Default reachability-probe timeout (ms). */
+const DEFAULT_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Default reachability check: a short-timeout GET to the server root. Any error
+ * (refused, DNS, timeout, non-2xx is still "reachable") resolves `false`. The
+ * SSRF guard (`validateLocalServerUrl`) has already run in `detectLocalSttEngine`
+ * BEFORE this fetch — so this only ever fetches a loopback/explicitly-allowed
+ * host (SEC-02).
+ *
+ * CR-01: the fetch is PINNED to `pinnedIp` (the IP the guard already resolved)
+ * via an undici dispatcher, so a hostname that resolved to loopback at
+ * validation cannot be rebound to a different IP at connect time (the
+ * DNS-rebinding/TOCTOU gap a plain re-resolving fetch left open). TLS SNI is
+ * preserved because the original hostname stays in `url`.
+ */
+async function defaultReachable(url, pinnedIp, timeoutMs) {
+    const controller = new AbortController();
+    const timer = systemSetTimeout(() => controller.abort(), timeoutMs);
+    try {
+        // A response of ANY status proves the server is up; only a network/abort
+        // error means unreachable. We do not log the URL (it may carry creds).
+        await fetchPinned(url, pinnedIp, { method: "GET", signal: controller.signal });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        systemClearTimeout(timer);
+    }
+}
+/**
+ * Default engine-importability check: a guarded lazy `import()` that resolves
+ * `true`/`false` and NEVER throws. Importability only — it does NOT build a
+ * pipeline or download any model (same lazy discipline as the adapter).
+ */
+async function defaultCanImportEngine() {
+    try {
+        await import("@huggingface/transformers");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run an async boolean check, resolving `false` if it rejects. Keeps
+ * `detectLocalSttEngine` total (never throws) without a dead initial
+ * assignment.
+ */
+async function safeBoolean(check) {
+    try {
+        return await check();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect whether the keyless local STT engine is usable. One-shot, never throws,
+ * never downloads a model.
+ */
+export async function detectLocalSttEngine(deps) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    // 1. A reachable configured server is sufficient (I6) — do NOT consult the
+    //    in-process engine. SEC-02: the baseUrl is SSRF-guarded BEFORE the
+    //    reachability check fires (guard-before-fetch). validateLocalServerUrl
+    //    ALLOWS loopback + an explicit allowlist and DENIES public/private egress
+    //    (keeping the cloud-metadata deny); a rejected URL is treated as
+    //    not-reachable so a mis/maliciously-configured baseUrl can never drive an
+    //    SSRF fetch — the probe falls through to the in-process path. The guard
+    //    also gates the injected `fetchProbe` test seam (it sits before the seam).
+    const baseUrl = deps.baseUrl;
+    if (baseUrl) {
+        const guard = await validateLocalServerUrl(baseUrl);
+        if (guard.ok) {
+            // CR-01: the default reachability fetch pins the connection to the IP the
+            // guard just resolved (guard.value.ip). An injected `fetchProbe` test seam
+            // bypasses the real fetch entirely (the guard still gates it above).
+            const validatedIp = guard.value.ip;
+            const reachableFn = deps.fetchProbe ?? ((url) => defaultReachable(url, validatedIp, timeoutMs));
+            const reachable = await safeBoolean(() => reachableFn(baseUrl));
+            if (reachable) {
+                return { available: true, mode: "baseUrl" };
+            }
+        }
+    }
+    // 2. In-process path: ffmpeg is required to decode the audio.
+    if (!deps.ffmpegAvailable) {
+        return { available: false, mode: "none" };
+    }
+    const importFn = deps.canImportEngine ?? defaultCanImportEngine;
+    const importable = await safeBoolean(importFn);
+    return importable
+        ? { available: true, mode: "in-process" }
+        : { available: false, mode: "none" };
+}

package/node_modules/@comis/skills/dist/tools/integrations/local-tts-adapter.d.ts

@@ -0,0 +1,124 @@
+/**
+ * In-process keyless local/Piper TTS adapter (TTS-02).
+ *
+ * The offline keyless rung of TTS `auto` (`edge → local/piper →
+ * honest-unavailable`): it synthesizes speech with NO key and NO network at
+ * synth time by running a single-speaker `text-to-audio` model in-process via
+ * `@huggingface/transformers` (Transformers.js), auto-downloading a small ONNX
+ * voice model on first use to a scoped cache under `~/.comis/models/tts/`, then
+ * reusing it on every later call (a module-level singleton — the model loads
+ * once per process and is NOT evicted by a per-call synth failure, only by a
+ * load failure; modulo a concurrent cold start where two simultaneous first
+ * calls can each build it before the promise is memoized — a self-healing
+ * cold-start-only inefficiency).
+ *
+ * This is the near-verbatim TTS twin of `local-stt-adapter.ts` — same lazy
+ * guarded import, same fail-closed module-singleton, same scoped `safePath`
+ * cache, same redaction + kind-carrying honest-degrade discipline — with the
+ * data flow INVERTED: STT decodes inbound audio → text; TTS synthesizes text →
+ * a raw f32 waveform, then ENCODES that waveform to an audio buffer (the inverse
+ * of STT's ffmpeg decode).
+ *
+ * Design constraints (all enforced by local-tts-adapter.test.ts):
+ *  - **Honest-degrade:** the engine is lazy-imported INSIDE a guarded
+ *    `await import("@huggingface/transformers")` — NEVER a top-level static
+ *    import — so a missing/broken install (or its native ORT addon) yields
+ *    `Result.err` rather than crashing the whole `@comis/skills` import graph.
+ *    Every failure branch returns `ok(...)` / `err(...)`; this module NEVER
+ *    `throw`s (the raw-throw architecture gate).
+ *  - **Waveform encode:** the model's raw f32 waveform is encoded to MP3 by
+ *    shelling the existing ffmpeg binary (`-f f32le -ar <sr> -ac 1 -i - out.mp3`)
+ *    — the INVERSE of STT's PCM decode; no new audio library (mirrors
+ *    `audio-converter.ts` / `local-stt-adapter.ts`).
+ *  - **Scoped cache:** `env.cacheDir` is set to `safePath(dataDir, "models",
+ *    "tts")` (NEVER raw `path.join`) — a SEPARATE subdir from `models/whisper/`
+ *    — before the first `pipeline()` call; that path is already inside the
+ *    daemon's `--allow-fs-write=${COMIS_DATA_DIR}` scope, so no new permission flag.
+ *  - **Fail-closed + integrity:** a short/corrupt model load → `err` (kind
+ *    `model_load_failed`) and the singleton is RESET so a transient failure can
+ *    retry — never a silent partial-model success. The pinned `MODEL_ID` anchor
+ *    (only a hardcoded single-speaker MMS-TTS id is loaded) + the TLS HF-Hub
+ *    source are the integrity floor (transformers.js exposes NO caller-visible
+ *    content-hash — same honest limit as STT SEC-03).
+ *  - **Redaction (SEC-01 light floor):** every surfaced error string is passed
+ *    through `sanitizeApiError`, which strips URLs (`[URL]`) and long tokens
+ *    (`[REDACTED]`), so no credential-bearing `baseUrl`/token leaks.
+ *
+ * The engine loader and the ffmpeg waveform encode are injectable config seams
+ * (`loadEngine` / `encodeWaveform`) so unit tests never touch the network or
+ * ffmpeg; they default to the real lazy-import + ffmpeg path.
+ *
+ * @module
+ */
+import type { TTSPort } from "@comis/core";
+import type { SttErrorKind } from "@comis/core";
+import type { Result } from "@comis/shared";
+/**
+ * The result shape of the transformers.js `text-to-audio` pipeline: a raw f32
+ * waveform plus its sample rate (the VITS/MMS-TTS native rate).
+ */
+interface TtaOutput {
+    audio: Float32Array;
+    sampling_rate: number;
+}
+/** Text-to-audio pipeline: takes text → `{ audio: Float32Array, sampling_rate }`. */
+type TtaPipeline = (text: string) => Promise<TtaOutput>;
+/**
+ * The subset of `@huggingface/transformers` the adapter consumes. `env` is the
+ * library's mutable global config (we set `cacheDir` / `allowRemoteModels` on
+ * it); `pipeline` builds the text-to-audio synthesiser.
+ */
+export interface TtsTransformersModule {
+    env: Record<string, unknown>;
+    pipeline: (task: string, model: string, options?: Record<string, unknown>) => Promise<TtaPipeline>;
+}
+/** Configuration for the in-process local/Piper TTS adapter. */
+export interface LocalTtsConfig {
+    /** Reserved for future multi-voice support; the current pin is single-speaker. */
+    readonly model?: string;
+    /** Data directory; the model cache is `<dataDir>/models/tts/`. */
+    readonly dataDir: string;
+    /** Default voice (carried opaquely; the current MMS-TTS pin is single-speaker). */
+    readonly voice?: string;
+    /** Output audio format hint (carried opaquely; ffmpeg encodes to MP3). */
+    readonly format?: string;
+    /** Maximum text length in characters (default: 5000). */
+    readonly maxTextLength?: number;
+    /**
+     * Engine loader seam. Defaults to a guarded lazy `import("@huggingface/transformers")`.
+     * Injected in tests to avoid a real model download.
+     */
+    readonly loadEngine?: () => Promise<TtsTransformersModule>;
+    /**
+     * Waveform encode seam: raw f32 waveform + sample rate → an audio Buffer.
+     * Defaults to the ffmpeg shell (`-f f32le -ar <sr> -ac 1 -i - out.mp3`).
+     * Injected in tests to avoid shelling ffmpeg.
+     */
+    readonly encodeWaveform?: (waveform: Float32Array, samplingRate: number) => Promise<Result<Buffer, Error>>;
+}
+/**
+ * TEST-ONLY: reset the module singleton between tests. Not exported on the
+ * package barrel — only imported by `local-tts-adapter.test.ts` (same invariant
+ * as `__resetLocalWhisperPipelineForTests`).
+ */
+export declare function __resetLocalTtsPipelineForTests(): void;
+/**
+ * A surfaced TTS failure that CARRIES its domain `SttErrorKind`. The same error
+ * vocabulary serves STT and TTS (design §17 / Assumption A3 — the resolver and
+ * the obs bridge read `error.kind` directly instead of re-deriving it). Kept
+ * adapter-local; the helper RETURNS the error to `Result.err` (no raw throw).
+ */
+export interface TtsDegradeError extends Error {
+    readonly kind: SttErrorKind;
+}
+/**
+ * Create the in-process keyless local/Piper TTS adapter.
+ *
+ * No API key, no network at synth time after the first load. The first
+ * `synthesize()` lazy-loads the engine, downloads + caches the model once, then
+ * synthesizes a raw f32 waveform and encodes it to MP3 via ffmpeg; later calls
+ * reuse the cached pipeline. Every failure branch returns `Result.err` — never
+ * throws.
+ */
+export declare function createLocalTtsAdapter(cfg: LocalTtsConfig): TTSPort;
+export {};