@openparachute/vault 0.6.5-rc.2 → 0.6.5

package/src/transcription/providers/parakeet-mlx.ts

@@ -0,0 +1,242 @@
+/**
+ * `parakeet-mlx` — the local Apple-Silicon transcription provider
+ * (scribe-fold Phase 2b).
+ *
+ * Turns audio into text by subprocessing the `parakeet-mlx` CLI
+ * (github.com/senstella/parakeet-mlx — NVIDIA Parakeet on Apple's MLX,
+ * macOS/Apple-Silicon only). Ported from scribe's proven
+ * `src/transcribe/parakeet-mlx.ts`; structurally a sibling of the
+ * `transcribe-cpp` provider (same SpawnRunner seam, same terminal-vs-retriable
+ * error contract).
+ *
+ * ## The audio path
+ *
+ * `parakeet-mlx` decodes the input itself (shelling to ffmpeg internally for
+ * non-WAV audio), so unlike transcribe-cpp we do NOT pre-transcode — the raw
+ * capture bytes are written to a temp file and handed over directly:
+ *
+ *   parakeet-mlx <audio> --output-format txt --output-dir <tmpout> [--model <id>]
+ *
+ * The transcript comes back as a `.txt` file in the output dir — named after
+ * the input file's stem, though some versions use their own stem, so we fall
+ * back to "any .txt in the dir" (scribe's proven fallback).
+ *
+ * ## The ffmpeg-missing mask (scribe's classic silent failure)
+ *
+ * parakeet-mlx shells to ffmpeg internally and, when ffmpeg is missing,
+ * prints the error then **exits 0** with no output file — the exitCode gate
+ * never fires. The signature in the combined stdout+stderr is the only
+ * signal, so "no output + ffmpeg-missing signature" maps to a terminal
+ * `ffmpeg_missing` error the operator can actually fix (ported from scribe's
+ * `looksLikeFfmpegMissing`).
+ *
+ * ## Error mapping (mirrors transcribe-cpp)
+ *
+ *   - binary not installed → non-retriable `missing_provider` (never spawns).
+ *   - launch failure (127) → non-retriable `missing_provider`.
+ *   - non-zero exit → RETRIABLE `parakeet_mlx_error` (transient resource blip
+ *     backs off; a deterministic failure still terminates after maxAttempts).
+ *   - exit 0 + no output + ffmpeg signature → non-retriable `ffmpeg_missing`.
+ *   - exit 0 + no output otherwise / empty transcript → plain `Error`
+ *     (retriable via the worker).
+ *
+ * NOTE on first use: the model (~2.5GB for parakeet-tdt-0.6b-v3) downloads
+ * into the HuggingFace cache on the first transcription. A slow first run may
+ * hit the subprocess timeout; the download resumes on the worker's retry.
+ */
+
+import { randomUUID } from "crypto";
+import { existsSync, mkdirSync, readdirSync } from "fs";
+import { writeFile, readFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  TranscriptionError,
+  type TranscriptionProvider,
+  type TranscribeInput,
+  type TranscribeResult,
+  type ProviderAvailability,
+} from "../../../core/src/transcription/provider.ts";
+import { defaultSpawnRunner, type SpawnRunner } from "./transcribe-cpp.ts";
+
+/** Model download on first use + MLX inference can be slow; generous default. */
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+/**
+ * Detect an ffmpeg-missing signature in a tool's combined stdout+stderr.
+ * Ported verbatim from scribe's `transcribe/backend-error.ts`: tolerant by
+ * design — requires the co-occurrence of an `ffmpeg` mention with a "not
+ * installed / not found / no such file" phrasing anywhere in the output
+ * (e.g. `[Errno 2] No such file or directory: 'ffmpeg'`).
+ */
+const FFMPEG_TOKEN = /ffmpeg/i;
+const NOT_PRESENT = /not (?:installed|found)|no such file/i;
+
+export function looksLikeFfmpegMissing(combinedOutput: string): boolean {
+  if (!combinedOutput) return false;
+  return FFMPEG_TOKEN.test(combinedOutput) && NOT_PRESENT.test(combinedOutput);
+}
+
+export interface ParakeetMlxProviderOpts {
+  /** Path to the `parakeet-mlx` binary. Undefined ⇒ unavailable + terminal. */
+  binPath?: string;
+  /** HF model repo id passed as `--model`. Undefined ⇒ the CLI's own default. */
+  model?: string;
+  /** Per-transcription timeout (ms). Default 600s. */
+  timeoutMs?: number;
+  /** Subprocess runner (tests inject a mock). Default `defaultSpawnRunner`. */
+  spawn?: SpawnRunner;
+  /** Existence probe (tests inject). Default `fs.existsSync`. */
+  existsImpl?: (p: string) => boolean;
+  /** Scratch dir for the temp audio + output files. Default `os.tmpdir()`. */
+  tmpDir?: string;
+}
+
+/**
+ * Build the `parakeet-mlx` argv. Scribe's proven invocation:
+ *   `parakeet-mlx <audio> --output-format txt --output-dir <dir>`
+ * plus an optional `--model <hf-repo>` (the ratified default is
+ * mlx-community/parakeet-tdt-0.6b-v3). Exported so a test pins the shape.
+ */
+export function buildParakeetMlxArgs(
+  binPath: string,
+  audioPath: string,
+  outDir: string,
+  model?: string,
+): string[] {
+  const args = [binPath, audioPath, "--output-format", "txt", "--output-dir", outDir];
+  if (model) args.push("--model", model);
+  return args;
+}
+
+export class ParakeetMlxProvider implements TranscriptionProvider {
+  readonly name = "parakeet-mlx";
+
+  private readonly binPath: string | undefined;
+  private readonly model: string | undefined;
+  private readonly timeoutMs: number;
+  private readonly spawn: SpawnRunner;
+  private readonly existsImpl: (p: string) => boolean;
+  private readonly tmpDir: string;
+  /** Once available, stays available for this process — avoids re-statting. */
+  private cachedAvailable = false;
+
+  constructor(opts: ParakeetMlxProviderOpts = {}) {
+    this.binPath = opts.binPath;
+    this.model = opts.model;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.spawn = opts.spawn ?? defaultSpawnRunner;
+    this.existsImpl = opts.existsImpl ?? existsSync;
+    this.tmpDir = opts.tmpDir ?? tmpdir();
+  }
+
+  /**
+   * Cheap readiness probe — a runnable `parakeet-mlx` binary on disk. NEVER
+   * spawns (it gates the capability flag on every `/api/vault` GET). The
+   * MODEL is not checked: it lives in the HF cache and downloads on first
+   * use, so binary presence is the honest cheap signal. Memoizes the
+   * once-true result so repeated landing reads don't re-stat.
+   */
+  async available(): Promise<ProviderAvailability> {
+    if (this.cachedAvailable) return { ok: true };
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      return {
+        ok: false,
+        reason:
+          "parakeet-mlx is not installed (run `parachute-vault transcription install` on this Mac, or set PARAKEET_MLX_BIN)",
+      };
+    }
+    this.cachedAvailable = true;
+    return { ok: true };
+  }
+
+  async transcribe(input: TranscribeInput): Promise<TranscribeResult> {
+    if (!this.binPath || !this.existsImpl(this.binPath)) {
+      throw new TranscriptionError("parakeet-mlx not installed", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+
+    const id = randomUUID();
+    const inExt = extFor(input.filename, input.mimeType);
+    const stem = `parachute-pk-${id}`;
+    const inputPath = join(this.tmpDir, `${stem}.${inExt}`);
+    const outDir = join(this.tmpDir, `${stem}-out`);
+
+    try {
+      await writeFile(inputPath, input.audio);
+      mkdirSync(outDir, { recursive: true });
+
+      const res = await this.spawn(
+        buildParakeetMlxArgs(this.binPath, inputPath, outDir, this.model),
+        { timeoutMs: this.timeoutMs },
+      );
+      const combined = `${res.stdout}\n${res.stderr}`;
+
+      if (res.exitCode !== 0) {
+        if (res.exitCode === 127) {
+          throw new TranscriptionError(
+            `parakeet-mlx could not be launched: ${res.stderr.trim()}`,
+            { code: "missing_provider", retriable: false },
+          );
+        }
+        throw new TranscriptionError(
+          `parakeet-mlx exited ${res.exitCode}: ${res.stderr.trim().slice(0, 500)}`,
+          { code: "parakeet_mlx_error", retriable: true },
+        );
+      }
+
+      // Find the transcript: <stem>.txt, else any .txt the tool wrote (some
+      // versions name outputs after their own stem — scribe's proven fallback).
+      const expected = join(outDir, `${stem}.txt`);
+      let outFile: string | undefined = this.existsImpl(expected) ? expected : undefined;
+      if (!outFile) {
+        const txts = safeListTxt(outDir);
+        if (txts.length > 0) outFile = join(outDir, txts[0]!);
+      }
+
+      if (!outFile) {
+        // No output AND exit 0 — the classic ffmpeg-missing mask. Promote to a
+        // terminal, actionable error instead of an opaque retry loop.
+        if (looksLikeFfmpegMissing(combined)) {
+          throw new TranscriptionError(
+            "parakeet-mlx needs `ffmpeg` to decode this audio, but ffmpeg isn't installed or isn't on the daemon's PATH (brew install ffmpeg)",
+            { code: "ffmpeg_missing", retriable: false },
+          );
+        }
+        // Plain Error is treated as retriable by the worker.
+        throw new Error("parakeet-mlx produced no transcript output");
+      }
+
+      const text = (await readFile(outFile, "utf8")).trim();
+      if (!text) {
+        throw new Error("parakeet-mlx produced no transcript text");
+      }
+      return { text };
+    } finally {
+      await Promise.all([
+        rm(inputPath, { force: true }).catch(() => {}),
+        rm(outDir, { recursive: true, force: true }).catch(() => {}),
+      ]);
+    }
+  }
+}
+
+/** List `.txt` files in a dir, tolerating a dir the tool never created. */
+function safeListTxt(dir: string): string[] {
+  try {
+    return (readdirSync(dir) as string[]).filter((f) => f.endsWith(".txt"));
+  } catch {
+    return [];
+  }
+}
+
+/** Choose a temp-file extension from the filename or mime type. */
+function extFor(filename: string, mimeType: string): string {
+  const fromName = filename.split(".").pop();
+  if (fromName && fromName.length <= 5 && /^[a-z0-9]+$/i.test(fromName)) return fromName.toLowerCase();
+  const sub = mimeType.split("/")[1]?.split(";")[0]?.trim();
+  if (sub && /^[a-z0-9]+$/i.test(sub)) return sub.toLowerCase();
+  return "bin";
+}

package/src/transcription/providers/scribe-http.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect } from "bun:test";
+import { ScribeHttpProvider } from "./scribe-http.ts";
+import { TranscriptionError } from "../../../core/src/transcription/provider.ts";
+
+/**
+ * Conformance tests for the `scribe-http` provider (scribe-fold Phase 1).
+ *
+ * These pin that the provider reproduces the former `callScribe` behavior
+ * EXACTLY — endpoint shape, auth header, context part, and the terminal-vs-
+ * retriable error mapping the worker depends on. If these drift, existing
+ * scribe installs change behavior across the fold, which Phase 1 forbids.
+ */
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** Capture the last fetch call so we can assert endpoint/headers/body. */
+function recordingFetch(response: Response | (() => Response | Promise<Response>)): {
+  fetchImpl: typeof fetch;
+  calls: Array<{ url: string; init: RequestInit | undefined }>;
+} {
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+  const fetchImpl = (async (url: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({ url: String(url), init });
+    return typeof response === "function" ? await response() : response;
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const AUDIO = new Uint8Array([1, 2, 3, 4]);
+
+describe("ScribeHttpProvider.available", () => {
+  test("ok:true when a URL is configured", async () => {
+    const p = new ScribeHttpProvider({ url: "http://scribe.test" });
+    expect(await p.available()).toEqual({ ok: true });
+  });
+
+  test("ok:false with a reason when no URL is configured", async () => {
+    const p = new ScribeHttpProvider({ url: undefined });
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toBeTruthy();
+  });
+
+  test("ok:false for an empty/whitespace URL", async () => {
+    expect((await new ScribeHttpProvider({ url: "   " }).available()).ok).toBe(false);
+  });
+
+  test("name is stable 'scribe-http'", () => {
+    expect(new ScribeHttpProvider({ url: "http://scribe.test" }).name).toBe("scribe-http");
+  });
+});
+
+describe("ScribeHttpProvider.transcribe — happy path", () => {
+  test("POSTs multipart to /v1/audio/transcriptions and returns { text }", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ text: "hello world" }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test/", fetchImpl });
+
+    const result = await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+
+    expect(result.text).toBe("hello world");
+    // Trailing slash on the base URL is normalized away (no `//v1`).
+    expect(calls[0]!.url).toBe("http://scribe.test/v1/audio/transcriptions");
+    expect(calls[0]!.init?.method).toBe("POST");
+    expect(calls[0]!.init?.body).toBeInstanceOf(FormData);
+    const form = calls[0]!.init?.body as FormData;
+    expect(form.get("file")).toBeInstanceOf(File);
+  });
+
+  test("sends Authorization: Bearer when a token is set", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ text: "x" }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", token: "sekret", fetchImpl });
+    await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    expect((calls[0]!.init?.headers as Record<string, string>)["Authorization"]).toBe("Bearer sekret");
+  });
+
+  test("omits Authorization when no token (loopback-trust)", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ text: "x" }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+    await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    expect((calls[0]!.init?.headers as Record<string, string>)["Authorization"]).toBeUndefined();
+  });
+
+  test("attaches a context part when context has entries", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ text: "x" }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+    await p.transcribe({
+      audio: AUDIO,
+      filename: "a.webm",
+      mimeType: "audio/webm",
+      context: { entries: [{ name: "Aaron", summary: "founder" }] },
+    });
+    const form = calls[0]!.init?.body as FormData;
+    expect(form.get("context")).toBeInstanceOf(Blob);
+  });
+
+  test("no context part when entries is empty", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ text: "x" }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+    await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm", context: { entries: [] } });
+    expect((calls[0]!.init?.body as FormData).get("context")).toBeNull();
+  });
+});
+
+describe("ScribeHttpProvider.transcribe — error mapping", () => {
+  test("4xx with error_code → non-retriable TranscriptionError carrying code", async () => {
+    const { fetchImpl } = recordingFetch(
+      jsonResponse({ error: "no transcription provider configured", error_code: "missing_provider" }, 400),
+    );
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+
+    let thrown: unknown;
+    try {
+      await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(TranscriptionError);
+    const e = thrown as TranscriptionError;
+    expect(e.code).toBe("missing_provider");
+    expect(e.httpStatus).toBe(400);
+    expect(e.retriable).toBe(false);
+    // error message prefers the JSON `error` field verbatim.
+    expect(e.message).toBe("no transcription provider configured");
+  });
+
+  test("4xx without error_code → non-retriable with 'scribe returned 400: <body>' message", async () => {
+    const { fetchImpl } = recordingFetch(new Response("bad multipart", { status: 400 }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+
+    let thrown: unknown;
+    try {
+      await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    } catch (err) {
+      thrown = err;
+    }
+    const e = thrown as TranscriptionError;
+    expect(e).toBeInstanceOf(TranscriptionError);
+    expect(e.code).toBeUndefined();
+    expect(e.retriable).toBe(false);
+    expect(e.message).toBe("scribe returned 400: bad multipart");
+  });
+
+  test("5xx → retriable TranscriptionError", async () => {
+    const { fetchImpl } = recordingFetch(new Response("upstream boom", { status: 503 }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+
+    let thrown: unknown;
+    try {
+      await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    } catch (err) {
+      thrown = err;
+    }
+    const e = thrown as TranscriptionError;
+    expect(e).toBeInstanceOf(TranscriptionError);
+    expect(e.retriable).toBe(true);
+    expect(e.httpStatus).toBe(503);
+  });
+
+  test("200 with missing text field → plain Error (retriable via worker)", async () => {
+    const { fetchImpl } = recordingFetch(jsonResponse({ not_text: 1 }));
+    const p = new ScribeHttpProvider({ url: "http://scribe.test", fetchImpl });
+
+    let thrown: unknown;
+    try {
+      await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(Error);
+    expect(thrown).not.toBeInstanceOf(TranscriptionError);
+    expect((thrown as Error).message).toBe("scribe response missing text field");
+  });
+
+  test("no URL configured → non-retriable missing_provider (never fetches)", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ text: "should not run" }));
+    const p = new ScribeHttpProvider({ url: undefined, fetchImpl });
+
+    let thrown: unknown;
+    try {
+      await p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" });
+    } catch (err) {
+      thrown = err;
+    }
+    const e = thrown as TranscriptionError;
+    expect(e).toBeInstanceOf(TranscriptionError);
+    expect(e.code).toBe("missing_provider");
+    expect(e.retriable).toBe(false);
+    expect(calls.length).toBe(0);
+  });
+});

package/src/transcription/providers/scribe-http.ts

@@ -0,0 +1,144 @@
+/**
+ * `scribe-http` — the whisper-compatible remote transcription provider
+ * (scribe-fold Phase 1).
+ *
+ * This is a byte-for-byte port of the transcription worker's former
+ * `callScribe`: discover a scribe URL (via `SCRIBE_URL` / `services.json`,
+ * resolved by the caller and handed in), POST the audio as multipart
+ * `file` to `<url>/v1/audio/transcriptions` (the Whisper API shape) with an
+ * optional `context` part and an optional `Authorization: Bearer` header,
+ * and read `{ text }` back. It is BOTH the default provider for existing
+ * installs (so their behavior is unchanged across the fold) and the migration
+ * bridge to any remote/whisper-compatible endpoint.
+ *
+ * Error mapping (unchanged from the old `callScribe`, now expressed as the
+ * runtime-agnostic `TranscriptionError`):
+ *   - 4xx with a JSON `error_code` → non-retriable `TranscriptionError`
+ *     carrying that `code` (e.g. `missing_provider`). Re-POSTing the same
+ *     audio at the same broken scribe just fails again; the operator must act.
+ *   - 4xx without `error_code` (auth, malformed multipart) → non-retriable
+ *     `TranscriptionError` with the body text.
+ *   - 5xx → retriable `TranscriptionError` (upstream hiccup; worker backs off).
+ *   - network error / timeout → the raw `Error` propagates (worker treats a
+ *     plain Error as retriable).
+ *   - 200 with a missing/invalid `text` field → plain `Error` (retriable).
+ */
+
+import { appendContextPart } from "../../context.ts";
+import {
+  TranscriptionError,
+  type TranscriptionProvider,
+  type TranscribeInput,
+  type TranscribeResult,
+  type ProviderAvailability,
+} from "../../../core/src/transcription/provider.ts";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface ScribeHttpProviderOpts {
+  /**
+   * Resolved scribe base URL (no trailing slash required — trimmed here).
+   * `undefined`/empty means scribe isn't discoverable → `available()` is false
+   * and `transcribe()` throws a non-retriable `missing_provider`-style error.
+   */
+  url?: string;
+  /** Optional bearer token for scribe (the shared loopback secret / hub JWT). */
+  token?: string;
+  /** Per-request timeout (ms). Default 120s — matches the former worker default. */
+  timeoutMs?: number;
+  /** Injection seam for tests; production omits it and uses global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+export class ScribeHttpProvider implements TranscriptionProvider {
+  readonly name = "scribe-http";
+
+  private readonly url: string | undefined;
+  private readonly token: string | undefined;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: ScribeHttpProviderOpts = {}) {
+    this.url = opts.url?.trim() ? opts.url.trim().replace(/\/$/, "") : undefined;
+    this.token = opts.token;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  /**
+   * Availability is purely "can we resolve a scribe URL" — no network probe.
+   * The capability flag is read on config reads, so this must stay cheap.
+   */
+  async available(): Promise<ProviderAvailability> {
+    if (!this.url) {
+      return {
+        ok: false,
+        reason: "no scribe URL configured (set SCRIBE_URL or install scribe so it registers in services.json)",
+      };
+    }
+    return { ok: true };
+  }
+
+  async transcribe(input: TranscribeInput): Promise<TranscribeResult> {
+    if (!this.url) {
+      // Mirrors scribe's own `missing_provider` contract: terminal, operator
+      // must act. Reaching here means the worker was constructed without a
+      // resolvable scribe URL — a config problem, not a transient one.
+      throw new TranscriptionError("no scribe URL configured", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const file = new File([input.audio], input.filename, { type: input.mimeType });
+      const form = new FormData();
+      form.append("file", file);
+      if (input.context) appendContextPart(form, input.context);
+
+      const endpoint = `${this.url}/v1/audio/transcriptions`;
+      const headers: Record<string, string> = {};
+      if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
+
+      const resp = await this.fetchImpl(endpoint, {
+        method: "POST",
+        headers,
+        body: form,
+        signal: controller.signal,
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        // Try to extract a structured error_code from a JSON body (scribe#47).
+        let errorCode: string | undefined;
+        let errorMessage: string | undefined;
+        try {
+          const parsed = JSON.parse(body) as { error?: string; error_code?: string; message?: string };
+          if (typeof parsed.error_code === "string") errorCode = parsed.error_code;
+          if (typeof parsed.error === "string") errorMessage = parsed.error;
+          else if (typeof parsed.message === "string") errorMessage = parsed.message;
+        } catch {
+          // Not JSON — leave errorCode undefined; the raw body becomes the message.
+        }
+        // 4xx is terminal (re-POSTing the same audio at the same broken scribe
+        // will just fail again). 5xx is retriable — provider hiccup.
+        const retriable = resp.status >= 500;
+        const message = errorMessage
+          ?? (errorCode ? `scribe ${errorCode}` : `scribe returned ${resp.status}: ${body}`);
+        throw new TranscriptionError(message, {
+          code: errorCode,
+          httpStatus: resp.status,
+          retriable,
+        });
+      }
+      const result = await resp.json() as { text?: string };
+      if (typeof result.text !== "string") {
+        throw new Error("scribe response missing text field");
+      }
+      return { text: result.text };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}