@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/usage.js

@@ -0,0 +1,243 @@
+/**
+ * Cumulative per-chat token usage — issue #152.
+ *
+ * `@herdctl/core`'s `extractSessionUsage` streams a transcript but keeps only the
+ * *last* assistant turn's `input + cache_read + cache_creation` — the current
+ * context-window fill level that drives the ContextRing / ContextMeter. It
+ * deliberately overwrites (`=`) each turn and never reads `output_tokens`, so it
+ * can't answer "how many tokens did this whole chat consume?".
+ *
+ * This module reads the same transcript in one pass and *accumulates* (`+=`)
+ * every assistant turn's input, output, cache-read and cache-creation tokens, so
+ * a chat's lifetime token cost (and a ballpark dollar figure at API rates) can be
+ * shown alongside the context-fill gauge. It lives in paddock — not upstream —
+ * because paddock already owns the `.chats/` layout and reads these transcripts
+ * directly (see {@link ./transcripts.ts} and {@link ./subagents.ts}); the core
+ * `SessionUsage` shape and its consumers are left untouched.
+ *
+ * Correctness notes:
+ *  - Dedupe by `message.id` exactly like core: streaming writes the same message
+ *    id more than once, and both the cumulative sums and the last-turn fill count
+ *    each assistant message at most once (keep-first, matching core).
+ *  - The last-turn `contextTokens` is tracked in the same pass so callers get the
+ *    context-fill number without a second core call.
+ */
+import { createReadStream } from "node:fs";
+import { promises as fs } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { projectChatsDir } from "./transcripts.js";
+/** sessionId is a path segment — keep it inside `.chats/`. */
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const EMPTY = {
+    hasData: false,
+    turnCount: 0,
+    contextTokens: 0,
+    inputTotal: 0,
+    outputTotal: 0,
+    cacheReadTotal: 0,
+    cacheCreationTotal: 0,
+    byModel: {},
+};
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+/**
+ * Stream a transcript file and accumulate cumulative token usage. Deduplicates
+ * assistant messages by `message.id` (keep-first) so repeated stream frames for
+ * one message are counted once. Returns {@link EMPTY} for a missing/unreadable
+ * file (parity with core, which returns a zeroed summary).
+ */
+export async function readSessionTokenUsageFile(file) {
+    const seenIds = new Set();
+    let hasData = false;
+    let contextTokens = 0;
+    let inputTotal = 0;
+    let outputTotal = 0;
+    let cacheReadTotal = 0;
+    let cacheCreationTotal = 0;
+    const byModel = {};
+    const stream = createReadStream(file, { encoding: "utf8" });
+    stream.on("error", () => undefined);
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.type !== "assistant")
+                continue;
+            const message = parsed.message;
+            if (!message)
+                continue;
+            // Deduplicate by message id (keep-first), exactly like core.
+            const id = typeof message.id === "string" ? message.id : undefined;
+            if (id) {
+                if (seenIds.has(id))
+                    continue;
+                seenIds.add(id);
+            }
+            const usage = message.usage;
+            if (!usage)
+                continue;
+            hasData = true;
+            const input = num(usage.input_tokens);
+            const output = num(usage.output_tokens);
+            const cacheCreation = num(usage.cache_creation_input_tokens);
+            const cacheRead = num(usage.cache_read_input_tokens);
+            inputTotal += input;
+            outputTotal += output;
+            cacheCreationTotal += cacheCreation;
+            cacheReadTotal += cacheRead;
+            // Bucket the same tokens under the model that produced them, so cost is
+            // priced per-model rather than at one blended rate. Turns with no recorded
+            // model land under "" and are treated as unpriced downstream.
+            const model = typeof message.model === "string" ? message.model : "";
+            const bucket = (byModel[model] ??= {
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheCreationTokens: 0,
+            });
+            bucket.inputTokens += input;
+            bucket.outputTokens += output;
+            bucket.cacheReadTokens += cacheRead;
+            bucket.cacheCreationTokens += cacheCreation;
+            // Context fill of this turn — the last one to run wins (matches core).
+            contextTokens = input + cacheCreation + cacheRead;
+        }
+    }
+    catch {
+        return EMPTY;
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return {
+        hasData,
+        turnCount: seenIds.size,
+        contextTokens,
+        inputTotal,
+        outputTotal,
+        cacheReadTotal,
+        cacheCreationTotal,
+        byModel,
+    };
+}
+/**
+ * mtime-keyed cache of cumulative usage, keyed by transcript path. A session's
+ * totals only change when its transcript grows (and its mtime bumps), so the
+ * chat-list build (which needs every session's usage for its rings) skips
+ * re-scanning unchanged transcripts. A `stat` is negligible next to a full-file
+ * walk, so we always derive the stamp here — one consistent mtime source across
+ * both the bulk and single-chat endpoints. One entry per file; a fresh mtime
+ * overwrites the stale one.
+ */
+const cache = new Map();
+/**
+ * Cumulative token usage for a chat, resolved from `<projectDir>/.chats/`.
+ * Memoized on the transcript's mtime. Returns {@link EMPTY} for an unsafe
+ * session id or a session with no transcript yet.
+ */
+export async function readSessionTokenUsage(projectDir, sessionId) {
+    if (!SAFE_SEGMENT.test(sessionId))
+        return EMPTY;
+    const file = path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`);
+    const mtime = await fs
+        .stat(file)
+        .then((s) => s.mtimeMs)
+        .catch(() => 0);
+    if (!mtime)
+        return EMPTY;
+    const hit = cache.get(file);
+    if (hit && hit.mtime === mtime)
+        return hit.usage;
+    const usage = await readSessionTokenUsageFile(file);
+    cache.set(file, { mtime, usage });
+    return usage;
+}
+/**
+ * Per-message context-window fill, keyed by the transcript record `uuid` that the
+ * messages DTO carries (issue #451). For every `type:"assistant"` record we store
+ * `input + cache_read + cache_creation` — the context-window fill at that turn.
+ *
+ * A single assistant message is written across several JSONL records (one per
+ * content block: text, tool_use, …), each with its own `uuid` but the SAME
+ * message-level `usage`, so keying by record `uuid` resolves any of a message's
+ * turn ids to the identical fill. Callers forward-fill the value across the
+ * non-assistant records between turns (user prompts, tool results) to answer
+ * "how full was the context as of this point" for every message.
+ *
+ * This is a SEPARATE pass from {@link readSessionTokenUsageFile} on purpose: it
+ * only runs on the open-chat messages path, never the chat-list rings, so the
+ * list DTO stays lean. It rides its own mtime cache below.
+ */
+export async function readContextSeriesFile(file) {
+    const series = new Map();
+    const stream = createReadStream(file, { encoding: "utf8" });
+    stream.on("error", () => undefined);
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.type !== "assistant")
+                continue;
+            const uuid = typeof parsed.uuid === "string" ? parsed.uuid : undefined;
+            const usage = parsed.message?.usage;
+            if (!uuid || !usage)
+                continue;
+            series.set(uuid, num(usage.input_tokens) +
+                num(usage.cache_creation_input_tokens) +
+                num(usage.cache_read_input_tokens));
+        }
+    }
+    catch {
+        return series;
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return series;
+}
+/** mtime-keyed cache of the per-message context series (see {@link readContextSeriesFile}). */
+const seriesCache = new Map();
+/**
+ * Per-message context series for a chat, resolved from `<projectDir>/.chats/`.
+ * Memoized on the transcript's mtime (parity with {@link readSessionTokenUsage}).
+ * Returns an empty map for an unsafe session id or a session with no transcript.
+ */
+export async function readContextSeries(projectDir, sessionId) {
+    if (!SAFE_SEGMENT.test(sessionId))
+        return new Map();
+    const file = path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`);
+    const mtime = await fs
+        .stat(file)
+        .then((s) => s.mtimeMs)
+        .catch(() => 0);
+    if (!mtime)
+        return new Map();
+    const hit = seriesCache.get(file);
+    if (hit && hit.mtime === mtime)
+        return hit.series;
+    const series = await readContextSeriesFile(file);
+    seriesCache.set(file, { mtime, series });
+    return series;
+}

package/packages/server/dist/wake-injection.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Wake-time injected-MCP resolution (edspencer/herdctl#390, wired in
+ * @herdctl/core 5.22.1).
+ *
+ * ── The bug ───────────────────────────────────────────────────────────────────
+ * Paddock injects in-process MCP servers — `mcp__paddock_manage__*` (self-
+ * management, #214) and `mcp__paddock__*` (send_file, #113) — into keeper turns via
+ * `injectedMcpServers`. These are per-turn runtime values Paddock supplies only when
+ * IT drives a turn (the human socket path and every server-initiated `startAgentTurn`
+ * fire). herdctl's session WAKE path — a `ScheduleWakeup` / `/loop` / `CronCreate`
+ * re-fire of an idle/reaped session — drives the turn INSIDE herdctl and, before
+ * 5.22.1, re-spawned the `claude` subprocess with the `mcp__paddock*__*` tools still
+ * "allowed" (they're on `agent.allowed_tools`) but with NO in-process server behind
+ * them. Result: the injected tools vanish from the catalog for the whole autonomous
+ * stretch (observed multi-hour episodes; permanent after a host restart, since the
+ * durable wake set re-fires MCP-less). See `/tmp/mcp-flap-investigation.md`.
+ *
+ * ── The fix ───────────────────────────────────────────────────────────────────
+ * 5.22.1 added `FleetManager.setResolveInjectedMcpServers(resolve)` — a SYNCHRONOUS
+ * resolver herdctl calls on each wake fire and threads into `openChatSession` before
+ * the subprocess spawns. This module is Paddock's policy for that resolver.
+ *
+ * Because Paddock's live-turn builder is ASYNC (it awaits provenance + project state
+ * for depth/trigger gating) but the herdctl resolver is SYNC, we resolve from an
+ * in-memory cache of the last server set Paddock built for each session
+ * ({@link WakeInjectionResolver.remember}, called on every live turn). A wake fire
+ * ({@link WakeInjectionResolver.resolve}) replays the cached set synchronously. This
+ * closes the LIVE flap fully — including the common case (a human/spawn turn sets up
+ * a self-wake, so the cache is warm when that same session wakes).
+ *
+ * The cold-cache case (a durable wake re-firing after a server RESTART, before any
+ * live turn re-populates the cache) can't be served synchronously — the source data
+ * is async. On a miss we kick a background {@link WakeInjectionResolver.warm} that
+ * rebuilds + caches the set, so the NEXT wake for that session is covered; the FIRST
+ * post-restart wake still degrades to no-injection (the next human/Trigger turn — or
+ * the next wake — restores it). This is the single documented residual.
+ */
+import type { InjectedMcpServerDef, SessionWakeEntry } from "@herdctl/core";
+import type { TurnOrigin } from "./run-provenance.js";
+/** The per-turn context that decides which injected servers a turn receives. */
+export interface InjectedMcpBuildArgs {
+    /** Workspace key this turn runs in (`""` is the root). */
+    projectSlug: string;
+    /** Keeper cwd — resolves the send_file tool's relative `file_path`. */
+    workingDir: string;
+    /**
+     * The session being resumed, or `null` for a new chat. On a resume, the CHAT's
+     * OWN recorded depth (not the caller's describe-the-run value) governs self-MCP
+     * gating — a depth-1 child reporting back to its depth-0 root must gate on 0.
+     */
+    resume: string | null;
+    /** Origin stamped on any child this turn's self-MCP write tools spawn. */
+    origin: TurnOrigin;
+    /** The depth to gate on when there's no recorded provenance for {@link resume}. */
+    depth: number;
+    /** Effective spawn bound for the chat this turn runs in (resolved by the caller). */
+    maxSpawnDepth: number;
+    /** Late-bound accessor for the resolved session id (self-MCP tools attribute by it). */
+    currentSessionId: () => string | null;
+}
+/** The (mostly injected) collaborators {@link buildInjectedMcpServers} needs. */
+export interface InjectedMcpBuildContext {
+    /** Instance self-MCP gates (resolved from `PaddockConfig`). */
+    cfg: {
+        selfMcpEnabled: boolean;
+        selfMcpWriteEnabled: boolean;
+        selfMcpProjectsEnabled: boolean;
+        hooksMcpEnabled: boolean;
+    };
+    /** Persist a file's bytes into the attachment store (send_file's snapshot). */
+    saveAttachment: (bytes: Buffer, filenameForExt: string) => Promise<string>;
+    /**
+     * Resolve a chat's recorded provenance for injection-depth on a resume. Optional
+     * (mirrors the optional `runProvenance` dep on the socket handler): absent ⇒ the
+     * caller's `depth` is used unchanged, exactly like the pre-extraction inline path.
+     */
+    getProvenance?: (sessionId: string) => Promise<{
+        depth: number;
+    } | undefined>;
+    /**
+     * Resolve a project's `hooksMcpEnabled` OVERRIDE (undefined when unset/unknown),
+     * for the T3 trigger-tool gate. Only consulted when write tools are on.
+     */
+    getProjectHooksMcp: (slug: string) => Promise<boolean | undefined>;
+    /**
+     * Build the self-management MCP server def. Provided by ws.ts because it closes
+     * over the hub / `startAgentTurn` spawn path; injected here so this module stays
+     * pure + unit-testable.
+     */
+    buildSelfMcp: (params: {
+        currentProjectSlug: string;
+        currentSessionId: () => string | null;
+        parentProvenance: {
+            origin: TurnOrigin;
+            depth: number;
+        };
+        includeWrite: boolean;
+        includeTriggers: boolean;
+        includeProjects: boolean;
+    }) => InjectedMcpServerDef;
+}
+/**
+ * Build the injected-MCP server set for one keeper turn — the SINGLE source of the
+ * per-turn injection policy, shared by the live `startAgentTurn` path and the wake
+ * rebuild so they can never drift. send_file is ALWAYS present (parity with the human
+ * path); the self-management MCP is appended iff the depth-gated
+ * {@link spawnedSelfMcpDecision} says so, and its T3 trigger tools iff writes are on
+ * AND the project's reused hooks-MCP gate is enabled. Semantics are identical to the
+ * previously-inline construction in `startAgentTurn`.
+ */
+export declare function buildInjectedMcpServers(args: InjectedMcpBuildArgs, ctx: InjectedMcpBuildContext): Promise<Record<string, InjectedMcpServerDef>>;
+/** Public surface of the wake-injection cache/resolver. */
+export interface WakeInjectionResolver {
+    /**
+     * Record the server set Paddock built for a live turn, keyed by its session id, so
+     * a later wake of that session can replay it. Idempotent; a null/blank id is a
+     * no-op; the newest entry is most-recently-used for eviction.
+     */
+    remember(sessionId: string | null | undefined, servers: Record<string, InjectedMcpServerDef>): void;
+    /**
+     * The SYNCHRONOUS resolver registered with herdctl. On a cache hit it replays the
+     * remembered set (refreshing recency); on a miss it kicks a background
+     * {@link warm} (so the NEXT wake is covered) and returns `undefined` — no injection
+     * for THIS fire. NEVER throws.
+     */
+    resolve(entry: SessionWakeEntry): Record<string, InjectedMcpServerDef> | undefined;
+    /**
+     * Rebuild + cache the server set for a woken session (cold-cache warm after a
+     * restart). Deduplicates concurrent warms and is non-throwing.
+     */
+    warm(entry: SessionWakeEntry): Promise<Record<string, InjectedMcpServerDef> | undefined>;
+    /** True if a session's set is currently cached (test/introspection). */
+    has(sessionId: string): boolean;
+    /** Number of cached sessions (test/introspection). */
+    size(): number;
+}
+export interface WakeInjectionDeps {
+    /**
+     * Rebuild the injected servers for a woken session — resolves the project + its
+     * config and delegates to {@link buildInjectedMcpServers}. Returns `undefined` when
+     * the session should receive no injection (a non-keeper agent / unknown project).
+     * Should not
+     * reject (the cache catches defensively regardless).
+     */
+    rebuild: (entry: SessionWakeEntry) => Promise<Record<string, InjectedMcpServerDef> | undefined>;
+    /** Soft cap on cached sessions; oldest (LRU) evicted past it. Default 1024. */
+    limit?: number;
+}
+/** Default cap — generous vs. any realistic live-session count, bounds memory. */
+export declare const DEFAULT_WAKE_INJECTION_LIMIT = 1024;
+/**
+ * Create the wake-injection cache/resolver. Holds an LRU-ish map of the last server
+ * set built per session; the sync {@link WakeInjectionResolver.resolve} replays it on
+ * a wake, and a background {@link WakeInjectionResolver.warm} rebuilds a cold entry.
+ */
+export declare function createWakeInjectionCache(deps: WakeInjectionDeps): WakeInjectionResolver;

package/packages/server/dist/wake-injection.js

@@ -0,0 +1,136 @@
+import { sendFileServerDef, SEND_FILE_SERVER_KEY } from "./send-file-mcp.js";
+import { SELF_MCP_SERVER_KEY } from "./self-mcp.js";
+import { spawnedSelfMcpDecision } from "./spawn-capability.js";
+import { resolveHooksMcpEnabled } from "./hook-config.js";
+/**
+ * Build the injected-MCP server set for one keeper turn — the SINGLE source of the
+ * per-turn injection policy, shared by the live `startAgentTurn` path and the wake
+ * rebuild so they can never drift. send_file is ALWAYS present (parity with the human
+ * path); the self-management MCP is appended iff the depth-gated
+ * {@link spawnedSelfMcpDecision} says so, and its T3 trigger tools iff writes are on
+ * AND the project's reused hooks-MCP gate is enabled. Semantics are identical to the
+ * previously-inline construction in `startAgentTurn`.
+ */
+export async function buildInjectedMcpServers(args, ctx) {
+    const { projectSlug, workingDir, resume, origin, depth, maxSpawnDepth, currentSessionId } = args;
+    // Always-on send_file (parity with the human path).
+    const servers = {
+        [SEND_FILE_SERVER_KEY]: sendFileServerDef({
+            workingDirectory: workingDir,
+            saveAttachment: ctx.saveAttachment,
+        }),
+    };
+    // A resume runs in an EXISTING chat whose own recorded depth governs it; fall back
+    // to the caller's `depth` when the chat has no marker (or provenance isn't wired).
+    let injectionDepth = depth;
+    if (resume !== null && ctx.getProvenance) {
+        const rec = await ctx.getProvenance(resume).catch(() => undefined);
+        if (rec)
+            injectionDepth = rec.depth;
+    }
+    const selfMcp = spawnedSelfMcpDecision({
+        selfMcpEnabled: ctx.cfg.selfMcpEnabled,
+        selfMcpWriteEnabled: ctx.cfg.selfMcpWriteEnabled,
+        depth: injectionDepth,
+        maxSpawnDepth,
+    });
+    if (selfMcp.inject) {
+        // Trigger-management tools (T3) follow the TARGET project's reused hooks-MCP
+        // opt-in (override else instance default) — only meaningful with write tools.
+        let includeTriggers = false;
+        if (selfMcp.includeWrite) {
+            const override = await ctx.getProjectHooksMcp(projectSlug).catch(() => undefined);
+            includeTriggers = resolveHooksMcpEnabled(override, ctx.cfg.hooksMcpEnabled);
+        }
+        servers[SELF_MCP_SERVER_KEY] = ctx.buildSelfMcp({
+            currentProjectSlug: projectSlug,
+            currentSessionId,
+            parentProvenance: { origin, depth: injectionDepth },
+            includeWrite: selfMcp.includeWrite,
+            includeTriggers,
+            // The project tool (#467) is a purely instance-level gate — no per-project
+            // override — but still rides on the write block, so writes must be on.
+            includeProjects: selfMcp.includeWrite && ctx.cfg.selfMcpProjectsEnabled,
+        });
+    }
+    return servers;
+}
+/** Default cap — generous vs. any realistic live-session count, bounds memory. */
+export const DEFAULT_WAKE_INJECTION_LIMIT = 1024;
+/**
+ * Create the wake-injection cache/resolver. Holds an LRU-ish map of the last server
+ * set built per session; the sync {@link WakeInjectionResolver.resolve} replays it on
+ * a wake, and a background {@link WakeInjectionResolver.warm} rebuilds a cold entry.
+ */
+export function createWakeInjectionCache(deps) {
+    const limit = deps.limit && deps.limit > 0 ? deps.limit : DEFAULT_WAKE_INJECTION_LIMIT;
+    const cache = new Map();
+    const inflight = new Map();
+    const remember = (sessionId, servers) => {
+        if (!sessionId)
+            return;
+        // delete-then-set moves the key to the newest position (Map preserves insertion
+        // order), so eviction below drops the genuinely least-recently-touched entry.
+        cache.delete(sessionId);
+        cache.set(sessionId, servers);
+        while (cache.size > limit) {
+            const oldest = cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            cache.delete(oldest);
+        }
+    };
+    const warm = (entry) => {
+        const id = entry?.sessionId;
+        if (!id)
+            return Promise.resolve(undefined);
+        const cached = cache.get(id);
+        if (cached)
+            return Promise.resolve(cached);
+        const existing = inflight.get(id);
+        if (existing)
+            return existing;
+        const p = (async () => {
+            try {
+                const servers = await deps.rebuild(entry);
+                if (servers)
+                    remember(id, servers);
+                return servers;
+            }
+            catch {
+                return undefined; // a rebuild failure degrades to no-injection, never throws
+            }
+            finally {
+                inflight.delete(id);
+            }
+        })();
+        inflight.set(id, p);
+        return p;
+    };
+    const resolve = (entry) => {
+        try {
+            const id = entry?.sessionId;
+            if (!id)
+                return undefined;
+            const hit = cache.get(id);
+            if (hit) {
+                cache.delete(id);
+                cache.set(id, hit); // refresh recency
+                return hit;
+            }
+            // Cold cache (e.g. post-restart): warm for the NEXT fire, no injection now.
+            void warm(entry);
+            return undefined;
+        }
+        catch {
+            return undefined; // resolve is called sync by herdctl — must never throw
+        }
+    };
+    return {
+        remember,
+        resolve,
+        warm,
+        has: (sessionId) => cache.has(sessionId),
+        size: () => cache.size,
+    };
+}

package/packages/server/dist/whisper-local.d.ts

@@ -0,0 +1,9 @@
+import type { TranscriptionConfig } from "./config.js";
+import type { TranscriptionInput } from "./transcribe.js";
+/**
+ * Transcribe an audio blob with whisper.cpp running on this box. Returns the raw
+ * transcript text (the caller trims it).
+ */
+export declare function transcribeLocal(input: TranscriptionInput, cfg: TranscriptionConfig): Promise<string>;
+/** Remove whisper.cpp's `[00:00:00.000 --> 00:00:02.000]` line prefixes. */
+export declare function stripTimestamps(raw: string): string;

package/packages/server/dist/whisper-local.js

@@ -0,0 +1,122 @@
+/**
+ * Local whisper.cpp transcription — the `local` backend for {@link makeTranscriber}.
+ *
+ * This module is imported LAZILY (see transcribe.ts) so its heavy, optional
+ * dependencies — `nodejs-whisper` (which builds/bundles whisper.cpp) and a
+ * system `ffmpeg` — are only required on instances that actually set
+ * `PADDOCK_WHISPER_MODE=local`. Remote-mode and dictation-off instances never
+ * touch it.
+ *
+ * Flow: the browser records WebM/Opus, which whisper.cpp can't read directly, so
+ * we first transcode to the 16 kHz mono PCM WAV whisper.cpp wants (via ffmpeg),
+ * then run whisper.cpp over it and return the cleaned transcript.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { TranscriptionError } from "./transcribe.js";
+/**
+ * Transcribe an audio blob with whisper.cpp running on this box. Returns the raw
+ * transcript text (the caller trims it).
+ */
+export async function transcribeLocal(input, cfg) {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "paddock-whisper-"));
+    const srcPath = path.join(dir, safeName(input.filename));
+    const wavPath = path.join(dir, "audio.wav");
+    try {
+        await writeFile(srcPath, input.audio);
+        await toWav(srcPath, wavPath);
+        return await runWhisper(wavPath, cfg);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/** Transcode any input ffmpeg understands to 16 kHz mono PCM WAV. */
+async function toWav(src, dest) {
+    await run("ffmpeg", ["-nostdin", "-y", "-i", src, "-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le", dest], "ffmpeg (audio transcode)");
+}
+/**
+ * Run whisper.cpp via nodejs-whisper and return the transcript. nodejs-whisper
+ * writes a sibling `<wav>.txt`; we read that and strip whisper's `[hh:mm:ss.mmm
+ * --> …]` line prefixes so the composer gets clean prose.
+ */
+async function runWhisper(wavPath, cfg) {
+    let nodewhisper;
+    try {
+        // Optional dependency — only present on instances configured for local
+        // whisper. Resolved dynamically so remote/off instances never need it.
+        // @ts-ignore — module may be absent at build time (declared optional).
+        ({ nodewhisper } = (await import("nodejs-whisper")));
+    }
+    catch {
+        throw new TranscriptionError("local whisper is not installed on this instance (missing nodejs-whisper). " +
+            "Install it, or set PADDOCK_WHISPER_MODE=remote.", 503);
+    }
+    const modelName = cfg.model || "base";
+    try {
+        await nodewhisper(wavPath, {
+            modelName,
+            autoDownloadModelName: modelName,
+            removeWavFileAfterTranscription: false,
+            // Only the plain-text output; we read the `.txt` and strip timestamps
+            // ourselves. (Avoid `splitOnWord`, which nodejs-whisper renders as a bare
+            // `-sow true`, making whisper-cli treat `true` as a stray input file.)
+            whisperOptions: {
+                outputInText: true,
+                outputInVtt: false,
+                outputInSrt: false,
+                outputInCsv: false,
+                translateToEnglish: false,
+            },
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new TranscriptionError(`whisper.cpp failed: ${truncate(reason, 300)}`, 502);
+    }
+    const txt = await readFile(`${wavPath}.txt`, "utf-8").catch(() => null);
+    if (txt === null) {
+        throw new TranscriptionError("whisper.cpp produced no transcript output", 502);
+    }
+    return stripTimestamps(txt);
+}
+/** Remove whisper.cpp's `[00:00:00.000 --> 00:00:02.000]` line prefixes. */
+export function stripTimestamps(raw) {
+    return raw
+        .split("\n")
+        .map((line) => line.replace(/^\s*\[[0-9:.]+\s*-->\s*[0-9:.]+\]\s*/, ""))
+        .join("\n")
+        .replace(/\n{2,}/g, "\n")
+        .trim();
+}
+/** Spawn a process, rejecting with a clear TranscriptionError on failure. */
+function run(cmd, args, label) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => {
+            stderr += String(d);
+        });
+        child.on("error", (err) => {
+            const hint = err.code === "ENOENT"
+                ? ` — is ${cmd} installed and on PATH?`
+                : "";
+            reject(new TranscriptionError(`${label} could not start: ${err.message}${hint}`, 503));
+        });
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new TranscriptionError(`${label} exited ${code}: ${truncate(stderr.trim(), 200)}`, 502));
+        });
+    });
+}
+function safeName(name) {
+    const base = path.basename(name || "audio").replace(/[^a-zA-Z0-9._-]/g, "_");
+    return base || "audio";
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}