@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/tooldetails.d.ts

@@ -0,0 +1,33 @@
+import { type EnrichedMessage, type EditDiff, type ReadInfo, type BashDetails, type SearchInfo, type TaskUpdateInfo, type TaskCreateInfo } from "./subagents.js";
+/** The structured fields we derive for one paired tool_use, keyed for the join. */
+interface ToolDetail {
+    toolName: string;
+    editDiff?: EditDiff;
+    readInfo?: ReadInfo;
+    bashDetails?: BashDetails;
+    searchInfo?: SearchInfo;
+    taskUpdate?: TaskUpdateInfo;
+    taskCreate?: TaskCreateInfo;
+}
+/** Recover per-tool details (file-ordered, paired-only) from a session transcript. */
+export declare function readToolDetails(projectDir: string, sessionId: string): Promise<ToolDetail[]>;
+/**
+ * Attach recovered per-tool detail to each detail-bearing tool message. The
+ * recovered details and the parsed messages are joined **per tool name, in file
+ * order** — the same paired-only/file-ordered invariant `enrichWithEdits`/
+ * `attachSubagentFields` rely on (which filter both sides to their tool set),
+ * bucketed by name so the defensive `toolName` match is intrinsic AND a tool herdctl
+ * happens to drop from its parsed stream (e.g. an interrupted, empty-output Bash)
+ * only misaligns its own family, never the whole tail. Sub-agent fields already
+ * attached by `enrichWithSubagents` are preserved (Task/Agent aren't in
+ * `DETAIL_TOOL_NAMES`). Detail-free sessions pass through unchanged.
+ */
+export declare function attachToolDetails(projectDir: string, sessionId: string, messages: EnrichedMessage[]): Promise<EnrichedMessage[]>;
+/**
+ * The single history-enrichment orchestrator (issue #237). Composes the three
+ * server-side passes so the routes call one function: sub-agent recovery (#37) →
+ * generalized per-tool detail (#237, subsuming #232's edit diff) → background /
+ * task-notification folding (#230) → local-command stdout recovery (#158).
+ */
+export declare function enrichWithToolDetails(projectDir: string, sessionId: string, messages: EnrichedMessage[]): Promise<EnrichedMessage[]>;
+export {};

package/packages/server/dist/tooldetails.js

@@ -0,0 +1,466 @@
+/**
+ * Unified tool-call detail enrichment — issue #237.
+ *
+ * herdctl's parsed `ChatToolCall` surfaces only `{toolName, inputSummary, output,
+ * isError, durationMs}` and discards two rich sources present on ~100% of tool
+ * calls in the raw Claude Code transcript:
+ *
+ *   1. the tool's full `input` (raw args), and
+ *   2. a structured `toolUseResult` sidecar written as a **top-level field** on the
+ *      `tool_result` line (Edit `structuredPatch`, Read `file`, Bash stdout/stderr,
+ *      Grep/Glob counts, Task* transitions, …).
+ *
+ * We'd recovered raw transcript data three times in one-off modules — `subagents.ts`
+ * (#37: Task input), `background.ts` (#230: task-notification correlation),
+ * `editdiff.ts` (#232: Edit diff). This module **generalizes that recovery into one
+ * shared pass**: a single mtime-cached raw-JSONL stream recovers `{input,
+ * toolUseResult}` for every paired tool_use and **positionally joins** it onto
+ * herdctl's parsed tool messages (same paired-only, file-ordered invariant
+ * `attachSubagentFields`/`enrichWithEdits` rely on; defensive `toolName` check).
+ *
+ * Recovery is generic; per-tool structured fields are derived here and rendered by
+ * a small set of gated branches in `ToolBlock`. No herdctl change. History-hydrated
+ * only (the live WS frame carries none of this) — enrichment applies on reload,
+ * consistent with #230/#232, and any tool without the sidecar degrades to the
+ * generic block.
+ *
+ * `enrichWithToolDetails` is the single orchestrator the history routes call: it
+ * composes `enrichWithSubagents` (sub-agent sidecars — a separate concern) → this
+ * pass → `enrichWithBackground` (task-notification folding).
+ */
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { projectChatsDir } from "./transcripts.js";
+import { fileKind } from "./projects.js";
+import { enrichWithSubagents } from "./subagents.js";
+import { enrichWithBackground } from "./background.js";
+import { enrichWithLocalCommands } from "./localcommand.js";
+import { SAFE_SEGMENT, statMtimeMs, mtimeCacheGet, mtimeCacheSet, } from "./subagents.js";
+/** Tool names we derive structured detail for. Others still consume a join slot
+ *  (so positional alignment holds) but carry no extra fields. */
+const EDIT_TOOL_NAMES = new Set(["Edit", "MultiEdit", "Write"]);
+const DETAIL_TOOL_NAMES = new Set([
+    ...EDIT_TOOL_NAMES,
+    "Read",
+    "Bash",
+    "Grep",
+    "Glob",
+    "TaskUpdate",
+    "TaskCreate",
+]);
+/** Cap rendered diff lines per edit tool call (stats stay exact; `truncated` flags it). */
+const MAX_DIFF_LINES = 400;
+const detailsCache = new Map();
+// --- small coercers -------------------------------------------------------
+/** Coerce to a trimmed non-empty string, else undefined. */
+function str(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const t = v;
+    return t.length ? t : undefined;
+}
+/** Coerce a string|number id to a string, else undefined. */
+function id(v) {
+    if (typeof v === "string" && v.length)
+        return v;
+    if (typeof v === "number")
+        return String(v);
+    return undefined;
+}
+/** Coerce to a finite number, else undefined. */
+function numOpt(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/** Coerce to a finite number, else 0. */
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+const asRec = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+// --- per-tool derivation --------------------------------------------------
+/**
+ * Build the structured diff from `toolUseResult.structuredPatch` — the git-style
+ * hunks Claude Code already computed, with real file line numbers. Deletions carry
+ * an `oldLine`, additions a `newLine`, context both. Stats count all lines; a
+ * global render budget caps line count (`truncated`).
+ */
+function editDiffFromResult(toolName, input, result) {
+    const patch = result?.structuredPatch;
+    if (!Array.isArray(patch))
+        return undefined;
+    const filePath = str(input.file_path) ?? str(result?.filePath);
+    const kind = toolName === "Write" ? "write" : toolName === "MultiEdit" ? "multiedit" : "edit";
+    let additions = 0;
+    let deletions = 0;
+    let budget = MAX_DIFF_LINES;
+    let truncated = false;
+    const hunks = [];
+    for (const rawHunk of patch) {
+        const h = asRec(rawHunk);
+        if (!h)
+            continue;
+        const oldStart = num(h.oldStart);
+        const newStart = num(h.newStart);
+        let oldNo = oldStart;
+        let newNo = newStart;
+        const lines = [];
+        const rawLines = Array.isArray(h.lines) ? h.lines : [];
+        for (const ln of rawLines) {
+            if (typeof ln !== "string")
+                continue;
+            const marker = ln[0];
+            const text = ln.slice(1);
+            if (marker === "+") {
+                additions++;
+                if (budget > 0) {
+                    lines.push({ t: "+", text, newLine: newNo });
+                    budget--;
+                }
+                else
+                    truncated = true;
+                newNo++;
+            }
+            else if (marker === "-") {
+                deletions++;
+                if (budget > 0) {
+                    lines.push({ t: "-", text, oldLine: oldNo });
+                    budget--;
+                }
+                else
+                    truncated = true;
+                oldNo++;
+            }
+            else if (marker === "\\") {
+                // "" — a jsdiff meta line, not real content.
+                continue;
+            }
+            else {
+                if (budget > 0) {
+                    lines.push({ t: " ", text, oldLine: oldNo, newLine: newNo });
+                    budget--;
+                }
+                else
+                    truncated = true;
+                oldNo++;
+                newNo++;
+            }
+        }
+        hunks.push({
+            oldStart,
+            oldLines: num(h.oldLines),
+            newStart,
+            newLines: num(h.newLines),
+            lines,
+        });
+    }
+    return {
+        filePath,
+        kind,
+        additions,
+        deletions,
+        hunks,
+        truncated: truncated || undefined,
+        userModified: result?.userModified === true || undefined,
+    };
+}
+/** File + line-range for a Read. Derivable from `input.file_path` alone (basename),
+ *  enriched with the range when the `toolUseResult.file` sidecar is present. */
+function readInfoFromResult(input, result) {
+    const file = asRec(result?.file);
+    const filePath = str(input.file_path) ?? str(file?.filePath);
+    if (!filePath && !file)
+        return undefined;
+    return {
+        filePath,
+        basename: filePath ? (filePath.split("/").pop() ?? filePath) : undefined,
+        startLine: numOpt(file?.startLine),
+        numLines: numOpt(file?.numLines),
+        totalLines: numOpt(file?.totalLines),
+        // Image detection is extension-based, so it's transcript-only (cache-safe).
+        // The servable `projectRelPath` depends on the project dir and is filled in at
+        // join time (see `attachToolDetails`).
+        isImage: filePath && fileKind(filePath) === "image" ? true : undefined,
+    };
+}
+/**
+ * The read target's path relative to `baseDir` (the project dir), or undefined if
+ * it isn't an absolute path inside it. Used to point the web's inline `<img>` at
+ * the raw file endpoint, which resolves names against the same project dir — with
+ * its own traversal guard as a second line of defence (issue #239).
+ */
+function servableRelPath(baseDir, absPath) {
+    if (!absPath || !path.isAbsolute(absPath))
+        return undefined;
+    const rel = path.relative(baseDir, absPath);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return undefined;
+    return rel;
+}
+/** Turn `gitOperation` (e.g. `{push:{branch:"main"}}`) into a short hint "push → main". */
+function gitOperationHint(op) {
+    const rec = asRec(op);
+    if (!rec)
+        return undefined;
+    const entry = Object.entries(rec)[0];
+    if (!entry)
+        return undefined;
+    const [name, detail] = entry;
+    const branch = str(asRec(detail)?.branch);
+    return branch ? `${name} → ${branch}` : name;
+}
+/** Split stdout/stderr + status affordances for a Bash. Only produced when there's
+ *  something beyond a clean stdout to show (else the generic output renders). */
+function bashDetailsFromResult(result) {
+    if (!result)
+        return undefined;
+    const stderr = str(result.stderr);
+    const interrupted = result.interrupted === true;
+    const returnCodeInterpretation = str(result.returnCodeInterpretation);
+    const gitHint = gitOperationHint(result.gitOperation);
+    if (!stderr && !interrupted && !returnCodeInterpretation && !gitHint)
+        return undefined;
+    return {
+        // Carry stdout only when we're splitting off a stderr, so the render can show
+        // both distinctly without doubling every clean Bash call's payload.
+        stdout: stderr ? str(result.stdout) : undefined,
+        stderr,
+        interrupted: interrupted || undefined,
+        returnCodeInterpretation,
+        gitHint,
+    };
+}
+/** Match/file counts for a Grep/Glob. */
+function searchInfoFromResult(toolName, result) {
+    if (!result)
+        return undefined;
+    if (toolName === "Grep") {
+        const mode = str(result.mode);
+        const info = {
+            kind: "grep",
+            numFiles: numOpt(result.numFiles),
+            numLines: mode === "content" ? numOpt(result.numLines) : undefined,
+            truncated: result.appliedLimit ? true : undefined,
+        };
+        return info.numFiles !== undefined || info.numLines !== undefined ? info : undefined;
+    }
+    // Glob
+    const info = {
+        kind: "glob",
+        numFiles: numOpt(result.numFiles),
+        totalMatches: numOpt(result.totalMatches),
+        truncated: result.truncated === true || undefined,
+    };
+    return info.numFiles !== undefined || info.totalMatches !== undefined ? info : undefined;
+}
+/** Status transition for a TaskUpdate. */
+function taskUpdateFromResult(result) {
+    if (!result)
+        return undefined;
+    const sc = asRec(result.statusChange);
+    const updatedFields = Array.isArray(result.updatedFields)
+        ? result.updatedFields.filter((x) => typeof x === "string")
+        : undefined;
+    const info = {
+        taskId: id(result.taskId),
+        updatedFields: updatedFields?.length ? updatedFields : undefined,
+        from: str(sc?.from),
+        to: str(sc?.to),
+    };
+    if (!info.taskId && !info.from && !info.to && !info.updatedFields)
+        return undefined;
+    return info;
+}
+/** Subject/description for a TaskCreate. */
+function taskCreateFromResult(input, result) {
+    const task = asRec(result?.task);
+    const subject = str(task?.subject) ?? str(input.subject);
+    const description = str(input.description) ?? str(input.prompt);
+    const taskId = id(task?.id);
+    if (!subject && !description && !taskId)
+        return undefined;
+    return { taskId, subject, description };
+}
+/** Derive the per-tool structured fields for one recovered tool_use. */
+function deriveDetail(toolName, input, result) {
+    const detail = { toolName };
+    if (EDIT_TOOL_NAMES.has(toolName))
+        detail.editDiff = editDiffFromResult(toolName, input, result);
+    else if (toolName === "Read")
+        detail.readInfo = readInfoFromResult(input, result);
+    else if (toolName === "Bash")
+        detail.bashDetails = bashDetailsFromResult(result);
+    else if (toolName === "Grep" || toolName === "Glob")
+        detail.searchInfo = searchInfoFromResult(toolName, result);
+    else if (toolName === "TaskUpdate")
+        detail.taskUpdate = taskUpdateFromResult(result);
+    else if (toolName === "TaskCreate")
+        detail.taskCreate = taskCreateFromResult(input, result);
+    return detail;
+}
+/** The additive fields to spread onto the tool call, or null if none were derived. */
+function extraFields(detail) {
+    const extra = {};
+    if (detail.editDiff)
+        extra.editDiff = detail.editDiff;
+    if (detail.readInfo)
+        extra.readInfo = detail.readInfo;
+    if (detail.bashDetails)
+        extra.bashDetails = detail.bashDetails;
+    if (detail.searchInfo)
+        extra.searchInfo = detail.searchInfo;
+    if (detail.taskUpdate)
+        extra.taskUpdate = detail.taskUpdate;
+    if (detail.taskCreate)
+        extra.taskCreate = detail.taskCreate;
+    return Object.keys(extra).length ? extra : null;
+}
+// --- recovery + join ------------------------------------------------------
+/** Recover per-tool details (file-ordered, paired-only) from a session transcript. */
+export async function readToolDetails(projectDir, sessionId) {
+    if (!SAFE_SEGMENT.test(sessionId))
+        return [];
+    return readToolDetailsFromFile(path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`));
+}
+async function readToolDetailsFromFile(file) {
+    const mtimeMs = await statMtimeMs(file);
+    if (mtimeMs !== undefined) {
+        const cached = mtimeCacheGet(detailsCache, file, mtimeMs);
+        if (cached.hit)
+            return cached.value;
+    }
+    const value = await readToolDetailsFromFileUncached(file);
+    if (mtimeMs !== undefined)
+        mtimeCacheSet(detailsCache, file, mtimeMs, value);
+    return value;
+}
+async function readToolDetailsFromFileUncached(file) {
+    const byId = new Map();
+    const order = [];
+    const resultIds = new Set();
+    // `toolUseResult` is a top-level field on the tool_result line, correlated to
+    // the tool_use via the (single) tool_result block's `tool_use_id`.
+    const resultById = 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;
+            }
+            const content = parsed.message?.content;
+            if (!Array.isArray(content))
+                continue;
+            // Collect this line's tool_result ids first — a single one lets us pin the
+            // line-level `toolUseResult` unambiguously (parallel results are rare and
+            // simply skip the sidecar rather than mis-attribute it).
+            const lineResultIds = [];
+            for (const block of content) {
+                const b = block;
+                if (b?.type === "tool_use" && b.name && DETAIL_TOOL_NAMES.has(b.name) && b.id) {
+                    if (!byId.has(b.id)) {
+                        order.push(b.id);
+                        byId.set(b.id, { toolName: b.name, input: b.input ?? {} });
+                    }
+                }
+                else if (b?.type === "tool_result" && typeof b.tool_use_id === "string") {
+                    resultIds.add(b.tool_use_id);
+                    lineResultIds.push(b.tool_use_id);
+                }
+            }
+            const tur = asRec(parsed.toolUseResult);
+            if (tur && lineResultIds.length === 1)
+                resultById.set(lineResultIds[0], tur);
+        }
+    }
+    catch {
+        return [];
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return order
+        .filter((tid) => resultIds.has(tid))
+        .map((tid) => {
+        const use = byId.get(tid);
+        return deriveDetail(use.toolName, use.input, resultById.get(tid));
+    });
+}
+/** True when any parsed message is a tool call we derive detail for. */
+function hasDetailTool(messages) {
+    return messages.some((m) => m.toolCall && DETAIL_TOOL_NAMES.has(m.toolCall.toolName));
+}
+/**
+ * Attach recovered per-tool detail to each detail-bearing tool message. The
+ * recovered details and the parsed messages are joined **per tool name, in file
+ * order** — the same paired-only/file-ordered invariant `enrichWithEdits`/
+ * `attachSubagentFields` rely on (which filter both sides to their tool set),
+ * bucketed by name so the defensive `toolName` match is intrinsic AND a tool herdctl
+ * happens to drop from its parsed stream (e.g. an interrupted, empty-output Bash)
+ * only misaligns its own family, never the whole tail. Sub-agent fields already
+ * attached by `enrichWithSubagents` are preserved (Task/Agent aren't in
+ * `DETAIL_TOOL_NAMES`). Detail-free sessions pass through unchanged.
+ */
+export async function attachToolDetails(projectDir, sessionId, messages) {
+    if (!hasDetailTool(messages))
+        return messages;
+    const details = await readToolDetails(projectDir, sessionId);
+    // Bucket the recovered details by tool name, preserving file order within each.
+    const byName = new Map();
+    for (const d of details) {
+        const arr = byName.get(d.toolName);
+        if (arr)
+            arr.push(d);
+        else
+            byName.set(d.toolName, [d]);
+    }
+    const cursor = new Map();
+    return messages.map((m) => {
+        const tc = m.toolCall;
+        if (!tc || !DETAIL_TOOL_NAMES.has(tc.toolName))
+            return m;
+        // An in-flight (`pending`) tool_use is unpaired, so `readToolDetails`
+        // (paired-only, positionally joined) has no slot for it — core@5.24.0 injects
+        // it into the stream for rehydration (herdctl#399). Skip it before advancing
+        // the per-name cursor so it doesn't steal the next completed call's detail.
+        if (tc.pending)
+            return m;
+        const i = cursor.get(tc.toolName) ?? 0;
+        cursor.set(tc.toolName, i + 1);
+        const detail = byName.get(tc.toolName)?.[i];
+        if (!detail)
+            return m;
+        let extra = extraFields(detail);
+        if (!extra)
+            return m;
+        // For an image Read inside the project dir, add the servable relative path so
+        // the web can render it inline (issue #239). Clone rather than mutate the
+        // cached `detail.readInfo`.
+        if (extra.readInfo?.isImage) {
+            const rel = servableRelPath(projectDir, extra.readInfo.filePath);
+            if (rel)
+                extra = { ...extra, readInfo: { ...extra.readInfo, projectRelPath: rel } };
+        }
+        return { ...m, toolCall: { ...tc, ...extra } };
+    });
+}
+/**
+ * The single history-enrichment orchestrator (issue #237). Composes the three
+ * server-side passes so the routes call one function: sub-agent recovery (#37) →
+ * generalized per-tool detail (#237, subsuming #232's edit diff) → background /
+ * task-notification folding (#230) → local-command stdout recovery (#158).
+ */
+export async function enrichWithToolDetails(projectDir, sessionId, messages) {
+    const withSubagents = await enrichWithSubagents(projectDir, sessionId, messages);
+    const withDetails = await attachToolDetails(projectDir, sessionId, withSubagents);
+    const withBackground = enrichWithBackground(withDetails);
+    return enrichWithLocalCommands(projectDir, sessionId, withBackground);
+}

package/packages/server/dist/transcribe.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Voice-dictation transcription — turns a recorded audio blob into text.
+ *
+ * Two backends, selected by {@link TranscriptionConfig.mode} (see config.ts):
+ *
+ *   - `remote` — POST the audio to an OpenAI-compatible `/audio/transcriptions`
+ *     endpoint (the same contract HushPod's remote whisper uses, so both can
+ *     point at one shared server, e.g. a laptop with a GPU). Uses global
+ *     `fetch` + `FormData`, so it is trivially stubbable in tests.
+ *   - `local` — run whisper.cpp on this box via nodejs-whisper. The heavy,
+ *     optional dependency (`./whisper-local.js`) is imported lazily so the
+ *     server boots — and remote mode works — even when whisper.cpp / ffmpeg
+ *     aren't installed.
+ *
+ * The composer's mic button is gated on {@link Transcriber.available}; a
+ * misconfigured or `off` instance simply advertises no dictation.
+ */
+import type { TranscriptionConfig, WhisperMode } from "./config.js";
+/** A recorded audio blob to transcribe (as uploaded by the browser). */
+export interface TranscriptionInput {
+    audio: Buffer;
+    /** Original filename incl. extension, e.g. `dictation.webm`. */
+    filename: string;
+    /** MIME type, e.g. `audio/webm`. */
+    mimeType: string;
+}
+export interface TranscriptionResult {
+    /** The transcribed text (trimmed). */
+    text: string;
+    /** Which backend produced it. */
+    mode: Exclude<WhisperMode, "off">;
+    /** The whisper model used. */
+    model: string;
+    /** Wall-clock transcription time. */
+    durationMs: number;
+}
+/** Thrown on any transcription failure; carries an HTTP-ish status hint. */
+export declare class TranscriptionError extends Error {
+    /** Suggested HTTP status for the route to surface (default 502). */
+    readonly status: number;
+    constructor(message: string, 
+    /** Suggested HTTP status for the route to surface (default 502). */
+    status?: number);
+}
+export interface Transcriber {
+    /** Whether dictation is usable (mode !== off and required config present). */
+    readonly available: boolean;
+    readonly mode: WhisperMode;
+    readonly model: string;
+    transcribe(input: TranscriptionInput): Promise<TranscriptionResult>;
+}
+/** Runs whisper.cpp locally. Injected so the local path is testable/mockable. */
+export type LocalRunner = (input: TranscriptionInput, cfg: TranscriptionConfig) => Promise<string>;
+export interface TranscriberDeps {
+    /** Override `globalThis.fetch` (tests). */
+    fetchImpl?: typeof fetch;
+    /** Override the local whisper.cpp runner (tests). Defaults to a lazy import. */
+    localRunner?: LocalRunner;
+}
+/**
+ * Build a {@link Transcriber} from resolved config. Pure — constructs no I/O
+ * until `transcribe()` is called, so it's safe to make one at startup regardless
+ * of mode.
+ */
+export declare function makeTranscriber(cfg: TranscriptionConfig, deps?: TranscriberDeps): Transcriber;
+/** Pull the transcript out of an OpenAI-ish response body (JSON `{text}` or raw). */
+export declare function extractText(raw: string): string | null;
+/** Join a base URL and path with exactly one slash between them. */
+export declare function joinUrl(base: string, path: string): string;

package/packages/server/dist/transcribe.js

@@ -0,0 +1,119 @@
+/** Thrown on any transcription failure; carries an HTTP-ish status hint. */
+export class TranscriptionError extends Error {
+    status;
+    constructor(message, 
+    /** Suggested HTTP status for the route to surface (default 502). */
+    status = 502) {
+        super(message);
+        this.status = status;
+        this.name = "TranscriptionError";
+    }
+}
+/**
+ * Build a {@link Transcriber} from resolved config. Pure — constructs no I/O
+ * until `transcribe()` is called, so it's safe to make one at startup regardless
+ * of mode.
+ */
+export function makeTranscriber(cfg, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    // `remote` requires an endpoint; without one it degrades to unavailable rather
+    // than 500-ing at request time.
+    const available = cfg.mode === "local" || (cfg.mode === "remote" && !!cfg.endpoint);
+    async function transcribe(input) {
+        if (!available) {
+            throw new TranscriptionError("transcription is not configured on this instance", 503);
+        }
+        if (input.audio.length === 0) {
+            throw new TranscriptionError("empty audio upload", 400);
+        }
+        const started = hrNow();
+        const text = cfg.mode === "remote"
+            ? await transcribeRemote(input, cfg, fetchImpl)
+            : await runLocal(input, cfg, deps.localRunner);
+        return {
+            text: text.trim(),
+            mode: cfg.mode,
+            model: cfg.model,
+            durationMs: Math.round(hrNow() - started),
+        };
+    }
+    return { available, mode: cfg.mode, model: cfg.model, transcribe };
+}
+/** Lazy-import the local runner so nodejs-whisper stays an optional dependency. */
+async function runLocal(input, cfg, injected) {
+    const runner = injected ?? (await import("./whisper-local.js")).transcribeLocal;
+    return runner(input, cfg);
+}
+/**
+ * OpenAI-compatible transcription: `POST {endpoint}/audio/transcriptions` with a
+ * multipart `file` + `model`. This is the same wire format as OpenAI's Whisper
+ * API and whisper-server / faster-whisper-server / speaches, so any of them (or
+ * HushPod's remote whisper) works unchanged.
+ */
+async function transcribeRemote(input, cfg, fetchImpl) {
+    const url = joinUrl(cfg.endpoint, "audio/transcriptions");
+    const form = new FormData();
+    form.append("file", new Blob([input.audio], { type: input.mimeType }), input.filename);
+    form.append("model", cfg.model);
+    form.append("response_format", "json");
+    if (cfg.language)
+        form.append("language", cfg.language);
+    const headers = {};
+    if (cfg.apiKey)
+        headers.authorization = `Bearer ${cfg.apiKey}`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers,
+            body: form,
+            signal: AbortSignal.timeout(120_000),
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new TranscriptionError(`whisper server unreachable at ${url}: ${reason}`, 502);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new TranscriptionError(`whisper server returned ${res.status}${body ? `: ${truncate(body, 200)}` : ""}`, 502);
+    }
+    // OpenAI's default `json` response is `{ text }`; `verbose_json` adds more.
+    // Be defensive: accept a raw string body too (some servers return text/plain).
+    const raw = await res.text();
+    const text = extractText(raw);
+    if (text === null) {
+        throw new TranscriptionError("whisper server returned no transcript text", 502);
+    }
+    return text;
+}
+/** Pull the transcript out of an OpenAI-ish response body (JSON `{text}` or raw). */
+export function extractText(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            const data = JSON.parse(trimmed);
+            if (typeof data.text === "string")
+                return data.text;
+            return null;
+        }
+        catch {
+            // Not JSON after all — fall through and treat as raw text.
+        }
+    }
+    return trimmed;
+}
+/** Join a base URL and path with exactly one slash between them. */
+export function joinUrl(base, path) {
+    return `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+// `Date.now()` is fine in the server runtime; kept behind a helper so the
+// duration math reads clearly and can be stubbed if ever needed.
+function hrNow() {
+    return Date.now();
+}