@openparachute/vault 0.6.5-rc.2 → 0.6.5-rc.9

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

package/src/transcription/providers/transcribe-cpp.test.ts

@@ -0,0 +1,314 @@
+import { describe, test, expect } from "bun:test";
+import {
+  TranscribeCppProvider,
+  buildTranscribeArgs,
+  buildFfmpegArgs,
+  parseTranscribeCliOutput,
+  type SpawnRunner,
+  type SubprocessResult,
+} from "./transcribe-cpp.ts";
+import { TranscriptionError } from "../../../core/src/transcription/provider.ts";
+
+/**
+ * Conformance tests for the `transcribe-cpp` local provider (scribe-fold
+ * Phase 2a). The subprocess (`Bun.spawn`) is mocked so no real binary runs and
+ * no bytes are downloaded — we pin the argv shape, the WAV/transcode decision,
+ * the stdout parse, and the terminal-vs-retriable error mapping the worker
+ * depends on.
+ */
+
+const AUDIO = new Uint8Array([1, 2, 3, 4]);
+
+/** A spawn mock that records every argv and returns canned results per call. */
+function recordingSpawn(results: SubprocessResult[] | ((cmd: string[]) => SubprocessResult)): {
+  spawn: SpawnRunner;
+  calls: string[][];
+} {
+  const calls: string[][] = [];
+  let i = 0;
+  const spawn: SpawnRunner = async (cmd) => {
+    calls.push(cmd);
+    if (typeof results === "function") return results(cmd);
+    return results[Math.min(i++, results.length - 1)]!;
+  };
+  return { spawn, calls };
+}
+
+const ok = (stdout: string): SubprocessResult => ({ exitCode: 0, stdout, stderr: "" });
+
+/**
+ * A real `transcribe-cli` v0.1.1 stdout report (macOS arm64, whisper-tiny.en).
+ * The transcript is the single `text:` line; library `[info]`/`[debug]` logs go
+ * to STDERR (not shown here). Build one with a given `text:` value.
+ */
+function cliReport(text: string): string {
+  return [
+    "audio: test.wav",
+    "  samples:    48422",
+    "  duration:   3.026 s",
+    "  sample rate 16000 Hz mono float32",
+    "model: /models/whisper-tiny.en-Q5_K_M.gguf -> ok",
+    "  backend:    MTL0",
+    "  name:       Whisper Tiny (English)",
+    "  license:    apache-2.0",
+    "  max audio:  unbounded (long audio chunked internally)",
+    "run: ok",
+    `text: ${text}`,
+    "segments: 1",
+    `  [   0.00 ->    3.00] ${text}`,
+    "  realtime:   9x (332.1 ms for 3.0 s)",
+    "",
+  ].join("\n");
+}
+
+/** A provider whose binary + model both "exist", with an injected spawn. */
+function provider(spawn: SpawnRunner, opts: Partial<{ existsImpl: (p: string) => boolean }> = {}) {
+  return new TranscribeCppProvider({
+    binPath: "/tc/bin/transcribe-cli",
+    modelPath: "/tc/models/whisper-tiny.en-Q5_K_M.gguf",
+    ffmpegPath: "ffmpeg",
+    spawn,
+    existsImpl: opts.existsImpl ?? (() => true),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+describe("buildTranscribeArgs", () => {
+  test("matches upstream usage: transcribe-cli -m <model> <wav>", () => {
+    expect(buildTranscribeArgs("/bin/transcribe-cli", "/m.gguf", "/a.wav")).toEqual([
+      "/bin/transcribe-cli",
+      "-m",
+      "/m.gguf",
+      "/a.wav",
+    ]);
+  });
+});
+
+describe("buildFfmpegArgs", () => {
+  test("transcodes to 16kHz mono WAV", () => {
+    const args = buildFfmpegArgs("ffmpeg", "/in.webm", "/out.wav");
+    expect(args).toContain("-ar");
+    expect(args[args.indexOf("-ar") + 1]).toBe("16000");
+    expect(args).toContain("-ac");
+    expect(args[args.indexOf("-ac") + 1]).toBe("1");
+    expect(args[args.length - 1]).toBe("/out.wav");
+  });
+});
+
+describe("parseTranscribeCliOutput", () => {
+  test("extracts exactly the `text:` line from the real v0.1.1 report", () => {
+    const report = cliReport("Hello parachute. Testing transcribe CPP.");
+    expect(parseTranscribeCliOutput(report)).toBe("Hello parachute. Testing transcribe CPP.");
+  });
+  test("ignores the indented per-segment line (starts with a bracket, not `text:`)", () => {
+    // The segment line repeats the transcript but is indented + bracketed; only
+    // the column-0 `text:` line is the transcript, and we return it once.
+    const report = cliReport("just once");
+    expect(parseTranscribeCliOutput(report)).toBe("just once");
+  });
+  test("the `(empty)` no-result sentinel maps to \"\"", () => {
+    expect(parseTranscribeCliOutput(cliReport("(empty)"))).toBe("");
+  });
+  test("no `text:` line at all → empty string", () => {
+    expect(parseTranscribeCliOutput("audio: test.wav\nrun: ok\nsegments: 0\n")).toBe("");
+  });
+  test("empty / whitespace stdout → empty string", () => {
+    expect(parseTranscribeCliOutput("   \n  ")).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// available() — cheap, no spawn
+// ---------------------------------------------------------------------------
+
+describe("TranscribeCppProvider.available", () => {
+  test("name is stable 'transcribe-cpp'", () => {
+    expect(provider(recordingSpawn([]).spawn).name).toBe("transcribe-cpp");
+  });
+
+  test("ok:true when binary + model exist — and NEVER spawns", async () => {
+    const { spawn, calls } = recordingSpawn([]);
+    const p = provider(spawn);
+    expect(await p.available()).toEqual({ ok: true });
+    expect(calls.length).toBe(0); // no subprocess on the hot path
+  });
+
+  test("ok:false with reason when the binary is missing", async () => {
+    const { spawn, calls } = recordingSpawn([]);
+    const p = provider(spawn, { existsImpl: (path) => !path.includes("transcribe-cli") });
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toContain("transcribe-cli");
+    expect(calls.length).toBe(0);
+  });
+
+  test("ok:false when the model is missing", async () => {
+    const { spawn } = recordingSpawn([]);
+    const p = provider(spawn, { existsImpl: (path) => !path.endsWith(".gguf") });
+    expect((await p.available()).ok).toBe(false);
+  });
+
+  test("dylib-only install (model exists, no runnable CLI) → ok:false (honesty)", async () => {
+    // v0.1.1 ships a library, not a CLI: libs + model land on disk but no
+    // transcribe-cli. available() must gate on the binary so the capability
+    // flag reports enabled:false rather than a capability we can't deliver.
+    const { spawn } = recordingSpawn([]);
+    const p = provider(spawn, { existsImpl: (path) => path.endsWith(".gguf") }); // only the model exists
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toContain("transcribe-cli");
+  });
+
+  test("unconfigured (no binPath) → ok:false, no throw", async () => {
+    const p = new TranscribeCppProvider({});
+    expect((await p.available()).ok).toBe(false);
+  });
+
+  test("caches the once-true result (no repeated existsSync after ok)", async () => {
+    let calls = 0;
+    const p = provider(recordingSpawn([]).spawn, {
+      existsImpl: () => {
+        calls++;
+        return true;
+      },
+    });
+    await p.available();
+    const afterFirst = calls;
+    await p.available();
+    expect(calls).toBe(afterFirst); // second call short-circuits the cache
+  });
+});
+
+// ---------------------------------------------------------------------------
+// transcribe() — happy paths
+// ---------------------------------------------------------------------------
+
+describe("TranscribeCppProvider.transcribe — happy path", () => {
+  test("non-WAV input transcodes via ffmpeg THEN runs transcribe-cli", async () => {
+    const { spawn, calls } = recordingSpawn([ok(""), ok(cliReport("the transcript"))]);
+    const p = provider(spawn);
+    const res = await p.transcribe({ audio: AUDIO, filename: "memo.webm", mimeType: "audio/webm" });
+
+    expect(res.text).toBe("the transcript");
+    expect(calls.length).toBe(2);
+    // First call: ffmpeg transcode to 16kHz mono WAV.
+    expect(calls[0]![0]).toBe("ffmpeg");
+    expect(calls[0]).toContain("16000");
+    // Second call: transcribe-cli -m <model> <wav>.
+    expect(calls[1]![0]).toBe("/tc/bin/transcribe-cli");
+    expect(calls[1]![1]).toBe("-m");
+    expect(calls[1]![2]).toBe("/tc/models/whisper-tiny.en-Q5_K_M.gguf");
+    expect(calls[1]![3]).toMatch(/\.16k\.wav$/);
+  });
+
+  test("WAV input ALSO transcodes (strict 16kHz — we can't trust its rate)", async () => {
+    // Regression for the live-verified bug: a 44.1kHz .wav made transcribe-cli
+    // exit 1. We now ALWAYS run ffmpeg first, even for a .wav → two spawns, and
+    // the CLI reads the 16k .wav ffmpeg produced (not the raw input).
+    const { spawn, calls } = recordingSpawn([ok(""), ok(cliReport("wav text"))]);
+    const p = provider(spawn);
+    const res = await p.transcribe({ audio: AUDIO, filename: "clip.wav", mimeType: "audio/wav" });
+
+    expect(res.text).toBe("wav text");
+    expect(calls.length).toBe(2);
+    expect(calls[0]![0]).toBe("ffmpeg");
+    expect(calls[0]).toContain("16000");
+    expect(calls[0]).toContain("1"); // -ac 1 mono
+    expect(calls[1]![0]).toBe("/tc/bin/transcribe-cli");
+    expect(calls[1]![3]).toMatch(/\.16k\.wav$/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// transcribe() — error mapping
+// ---------------------------------------------------------------------------
+
+describe("TranscribeCppProvider.transcribe — error mapping", () => {
+  async function catchErr(fn: () => Promise<unknown>): Promise<unknown> {
+    try {
+      await fn();
+    } catch (err) {
+      return err;
+    }
+    throw new Error("expected transcribe() to throw");
+  }
+
+  test("binary missing → non-retriable missing_provider, NEVER spawns", async () => {
+    const { spawn, calls } = recordingSpawn([ok("nope")]);
+    const p = provider(spawn, { existsImpl: (path) => !path.includes("transcribe-cli") });
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+    expect(calls.length).toBe(0);
+  });
+
+  test("model missing → non-retriable missing_provider", async () => {
+    const { spawn } = recordingSpawn([ok("nope")]);
+    const p = provider(spawn, { existsImpl: (path) => !path.endsWith(".gguf") });
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("ffmpeg not found (exit 127) → non-retriable ffmpeg_missing", async () => {
+    const { spawn } = recordingSpawn([{ exitCode: 127, stdout: "", stderr: "not found" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("ffmpeg_missing");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("ffmpeg transcode failure (non-127) → non-retriable transcode_failed", async () => {
+    const { spawn } = recordingSpawn([{ exitCode: 1, stdout: "", stderr: "bad input" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.webm", mimeType: "audio/webm" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("transcode_failed");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("transcribe-cli non-zero exit → RETRIABLE transcribe_cli_error", async () => {
+    // ffmpeg succeeds; transcribe-cli then fails with a generic exit code.
+    const { spawn } = recordingSpawn([ok(""), { exitCode: 2, stdout: "", stderr: "decode error" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as TranscriptionError;
+    expect(err).toBeInstanceOf(TranscriptionError);
+    expect(err.code).toBe("transcribe_cli_error");
+    expect(err.retriable).toBe(true);
+  });
+
+  test("transcribe-cli launch failure (127) → non-retriable missing_provider", async () => {
+    const { spawn } = recordingSpawn([ok(""), { exitCode: 127, stdout: "", stderr: "gone" }]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as TranscriptionError;
+    expect(err.code).toBe("missing_provider");
+    expect(err.retriable).toBe(false);
+  });
+
+  test("`text: (empty)` no-result → plain Error (retriable via worker), not TranscriptionError", async () => {
+    // ffmpeg ok; transcribe-cli returns its (empty) sentinel → parses to "".
+    const { spawn } = recordingSpawn([ok(""), ok(cliReport("(empty)"))]);
+    const p = provider(spawn);
+    const err = (await catchErr(() =>
+      p.transcribe({ audio: AUDIO, filename: "a.wav", mimeType: "audio/wav" }),
+    )) as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(TranscriptionError);
+    expect(err.message).toContain("no transcript text");
+  });
+});