@cohortapp/agent-sdk 2.3.0

package/lib/voice/session-rotation.mjs

@@ -0,0 +1,257 @@
+/**
+ * Maestro — Voice session rotation
+ *
+ * OpenAI Realtime has a documented latency-drift bug on long sessions:
+ * median turn latency climbs from ~800 ms to >2 s after ~20 turns. The
+ * supported mitigation is to **rotate the session** every N turns or M
+ * minutes — summarise the conversation, close the WebSocket, open a new
+ * one, and re-seed the new session with a system message containing the
+ * running summary.
+ *
+ * This module provides:
+ *   shouldRotate(state, opts) → boolean
+ *   rotateSessionIfStale(provider, state, opts) → { rotated, newProvider }
+ *   makeSummary(transcript)   → short text summary for re-seeding
+ *
+ * The voice worker calls rotateSessionIfStale() after each TURN_DONE.
+ * If rotation is needed it spins up a fresh provider with the same
+ * sessionConfig, plays the summary into it via sendText(), and the
+ * worker swaps providers transparently. The transcript + audit log
+ * persist across the rotation in state/voice/sessions/.
+ */
+
+import { VOICE_EVENTS } from "./provider.mjs";
+
+export const SESSION_ROTATION_DEFAULTS = Object.freeze({
+  max_turns: 12,                       // rotate after this many user→agent turn-pairs
+  max_duration_ms: 4 * 60 * 1000,      // rotate after this much wall-clock
+  max_p95_latency_ms: 2000,            // rotate if last 5 turns averaged > this
+});
+
+/**
+ * Decide whether the session is stale enough to rotate.
+ *
+ * @param {object} state  Tracking state from the voice worker:
+ *   {
+ *     turns: number,
+ *     started_at: number (ms epoch),
+ *     recent_latencies_ms: number[],   // last N turn latencies
+ *   }
+ * @param {object} opts  Optional overrides for the defaults.
+ * @returns {{ rotate: boolean, reason?: string }}
+ */
+export function shouldRotate(state, opts = {}) {
+  const cfg = { ...SESSION_ROTATION_DEFAULTS, ...opts };
+  if (!state) return { rotate: false };
+
+  if ((state.turns || 0) >= cfg.max_turns) {
+    return { rotate: true, reason: "max_turns" };
+  }
+  const ageMs = Date.now() - (state.started_at || Date.now());
+  if (ageMs >= cfg.max_duration_ms) {
+    return { rotate: true, reason: "max_duration" };
+  }
+  const recent = state.recent_latencies_ms || [];
+  if (recent.length >= 5) {
+    const sorted = [...recent].sort((a, b) => a - b);
+    const p95 = sorted[Math.max(0, Math.floor(sorted.length * 0.95) - 1)];
+    if (p95 >= cfg.max_p95_latency_ms) {
+      return { rotate: true, reason: "latency_drift" };
+    }
+  }
+  return { rotate: false };
+}
+
+/**
+ * Build a compact summary of a transcript for re-seeding into a fresh
+ * session. We keep this dumb-on-purpose: deterministic, no LLM round-trip,
+ * preserves the most recent N exchanges and the most recent tool calls.
+ *
+ * @param {Array<{role: string, text?: string, tool?: object}>} transcript
+ * @param {object} [opts]
+ * @returns {string}
+ */
+export function makeSummary(transcript, opts = {}) {
+  const keepExchanges = opts.keepExchanges ?? 4;
+  const keepTools = opts.keepTools ?? 3;
+
+  if (!Array.isArray(transcript) || !transcript.length) {
+    return "Conversation continues. No prior context available.";
+  }
+
+  const exchanges = transcript.filter((t) => t.role === "user" || t.role === "assistant");
+  const recentExchanges = exchanges.slice(-keepExchanges * 2);
+  const recentTools = transcript
+    .filter((t) => t.tool)
+    .slice(-keepTools)
+    .map((t) => ({
+      name: t.tool.name,
+      ok: t.tool.error ? false : true,
+      summary: summariseToolCall(t.tool),
+    }));
+
+  const lines = [
+    "[Session rotated for latency reasons — running summary follows.]",
+    "",
+    "Recent dialogue:",
+    ...recentExchanges.map((t) => `- ${t.role}: ${truncate(t.text || "", 240)}`),
+  ];
+  if (recentTools.length) {
+    lines.push("", "Recent tool activity:");
+    for (const r of recentTools) {
+      lines.push(`- ${r.name} → ${r.ok ? "ok" : "error"}${r.summary ? ` (${r.summary})` : ""}`);
+    }
+  }
+  lines.push("", "Continue the conversation from this state. Do not re-introduce yourself.");
+  return lines.join("\n");
+}
+
+function summariseToolCall(tool) {
+  if (!tool) return "";
+  if (tool.error) return `error: ${truncate(String(tool.error), 80)}`;
+  if (tool.args?.channel) return `to ${tool.args.channel}`;
+  if (tool.args?.to) return `to ${tool.args.to}`;
+  if (tool.args?.query) return `query="${truncate(tool.args.query, 60)}"`;
+  return "";
+}
+
+function truncate(s, n) {
+  if (!s || s.length <= n) return s;
+  return s.slice(0, n - 1) + "…";
+}
+
+/**
+ * Default time (ms) to wait for a freshly-spun provider to confirm it is
+ * live before we treat the rotation as failed and keep the old session.
+ */
+export const ROTATION_CONFIRM_TIMEOUT_MS = 5000;
+
+/**
+ * Wait until a freshly-connected provider is observably live, or fail.
+ *
+ * "Live" means either:
+ *   - its connect() promise resolved (already awaited by the caller), AND
+ *   - it has reached a non-idle/non-closed state, OR emitted CONNECTED /
+ *     SESSION_CREATED within `timeoutMs`.
+ *
+ * connect() resolving is necessary but not sufficient: a provider can
+ * resolve connect() and then immediately drop the upstream socket. We
+ * therefore confirm against the observable signals the provider exposes.
+ *
+ * @param {VoiceProvider} provider  The newly-connected provider.
+ * @param {number} timeoutMs
+ * @returns {Promise<void>}  Resolves when live; rejects on timeout/error.
+ */
+function confirmProviderLive(provider, timeoutMs) {
+  const healthy = (s) => s && s !== "idle" && s !== "closed";
+
+  return new Promise((resolve, reject) => {
+    // Fast path: if the provider already reports a healthy state (e.g.
+    // connect() resolved and set state="connected"), trust it. Evaluated
+    // inside the executor so it reflects state AFTER connect() resolved,
+    // not the state captured when this promise was constructed.
+    if (healthy(provider?.state)) { resolve(); return; }
+
+    // No event surface to observe and not already healthy → cannot confirm.
+    if (typeof provider?.once !== "function") {
+      reject(new Error("rotation: new provider is not observable and not in a live state"));
+      return;
+    }
+    let settled = false;
+    const finish = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { provider.removeListener?.(VOICE_EVENTS.CONNECTED, onUp); } catch { /* */ }
+      try { provider.removeListener?.(VOICE_EVENTS.SESSION_CREATED, onUp); } catch { /* */ }
+      try { provider.removeListener?.(VOICE_EVENTS.CLOSED, onDown); } catch { /* */ }
+      try { provider.removeListener?.(VOICE_EVENTS.ERROR, onErr); } catch { /* */ }
+      fn(arg);
+    };
+    const onUp = () => finish(resolve);
+    const onDown = (info) => finish(reject, new Error(`rotation: new provider closed before confirmed live${info?.reason ? ` (${info.reason})` : ""}`));
+    const onErr = (err) => finish(reject, err instanceof Error ? err : new Error(String(err?.message || err)));
+    const timer = setTimeout(
+      () => finish(reject, new Error(`rotation: new provider did not confirm live within ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    if (typeof timer.unref === "function") timer.unref();
+
+    provider.once(VOICE_EVENTS.CONNECTED, onUp);
+    provider.once(VOICE_EVENTS.SESSION_CREATED, onUp);
+    provider.once(VOICE_EVENTS.CLOSED, onDown);
+    provider.once(VOICE_EVENTS.ERROR, onErr);
+
+    // Re-check state after wiring listeners to avoid a race where the
+    // provider became healthy between the fast-path check and now.
+    if (healthy(provider.state)) finish(resolve);
+  });
+}
+
+/**
+ * Rotate the session if stale. Returns the (possibly-new) provider plus
+ * a flag indicating whether rotation actually happened.
+ *
+ * The new session is brought up and CONFIRMED LIVE before we touch the
+ * old one. If the bring-up rejects (or never confirms live), we keep the
+ * old provider running, best-effort close the half-open new provider, and
+ * return { rotated: false, provider: <old> } so the caller keeps serving
+ * the call instead of cutting over to a dead session. The old provider is
+ * only closed AFTER the new one is confirmed live (M10).
+ *
+ * Caller must:
+ *   - Provide `createNewProvider`: a factory the worker uses to spin up
+ *     a fresh provider with identical session config.
+ *   - Provide `state.transcript` so the summary can be built.
+ *
+ * @param {VoiceProvider} provider  Current live provider
+ * @param {object} state
+ * @param {object} opts
+ *   @param {number} [opts.confirmTimeoutMs]  Override the liveness timeout.
+ */
+export async function rotateSessionIfStale(provider, state, opts = {}) {
+  const decision = shouldRotate(state, opts.thresholds);
+  if (!decision.rotate) return { rotated: false, provider };
+
+  if (typeof opts.createNewProvider !== "function") {
+    throw new Error("rotateSessionIfStale requires opts.createNewProvider");
+  }
+
+  const summary = makeSummary(state.transcript || [], opts.summary);
+  const oldProvider = provider;
+  const sessionConfig = state.sessionConfig || provider.sessionConfig;
+  const confirmTimeoutMs = opts.confirmTimeoutMs ?? ROTATION_CONFIRM_TIMEOUT_MS;
+
+  let next;
+  try {
+    next = opts.createNewProvider({ reason: decision.reason });
+    // Bring up the new session, then confirm it is actually live before we
+    // touch the old one. confirmProviderLive checks the post-connect state
+    // (a well-behaved provider sets state="connected"/emits CONNECTED from
+    // connect()) and, if not yet healthy, waits for CONNECTED/SESSION_CREATED
+    // with a timeout — rejecting on CLOSED/ERROR. A provider that resolves
+    // connect() but drops (or never reaches a live state) fails confirmation
+    // and we keep the old session running rather than cutting over.
+    await Promise.resolve(next.connect(sessionConfig));
+    await confirmProviderLive(next, confirmTimeoutMs);
+    // New session is live — seed it with the running summary.
+    next.sendText(`(System) ${summary}`);
+  } catch (err) {
+    // Bring-up failed: do NOT cut over. Tear down the half-open new
+    // provider so it can't leak, keep the old provider serving the call.
+    if (next) { try { next.close?.(`rotation_failed: ${decision.reason}`); } catch { /* */ } }
+    return {
+      rotated: false,
+      provider: oldProvider,
+      reason: decision.reason,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  // Only now that the new session is confirmed live do we close the old.
+  try { oldProvider.close(`rotated: ${decision.reason}`); } catch { /* */ }
+
+  return { rotated: true, provider: next, reason: decision.reason };
+}
+
+export default { shouldRotate, rotateSessionIfStale, makeSummary, SESSION_ROTATION_DEFAULTS };

package/lib/voice/stt.mjs

@@ -0,0 +1,161 @@
+/**
+ * Maestro — Speech-to-text helper for inbound audio files.
+ *
+ * Wraps OpenAI's (and any OpenAI-compatible) `/v1/audio/transcriptions`
+ * endpoint. Used by the voice channel adapter's receive() path to turn an
+ * inbound voice note (WhatsApp PTT, Slack audio clip, a recorded Twilio
+ * call leg, an uploaded recording) into text the agent can reason over.
+ *
+ * Counterpart to lib/voice/tts.mjs (which goes text → audio). This goes
+ * audio file → text and mirrors its conventions: module-level defaults,
+ * apiKey from arg or OPENAI_API_KEY, clear HTTP errors, a default export.
+ *
+ * Why a separate helper from the Realtime API:
+ *   - Asynchronous transcription of a *file* is much cheaper than a live
+ *     Realtime session and is the right primitive for store-and-forward
+ *     channels (WhatsApp / Slack / SMS) that hand you a file, not a stream.
+ *   - whisper-1 / gpt-4o-transcribe accept multipart/form-data uploads;
+ *     no streaming session required.
+ *
+ * Ported and adapted from OpenClaw
+ * (src/media-understanding/openai-compatible-audio.ts —
+ * transcribeOpenAiCompatibleAudio) for the maestro autonomy model. The
+ * OpenClaw-specific provider-config / DNS-pinning / dispatcher plumbing is
+ * dropped in favour of plain global fetch + FormData/Blob (Node 18+) with
+ * an AbortController timeout.
+ *
+ * Public API:
+ *   transcribeAudioFile({ filePath | buffer, apiKey, model, baseUrl,
+ *                         language, prompt, fileName, mime, timeoutMs })
+ *     → Promise<{ text, raw }>
+ *
+ * Node builtins only (node:fs/promises, node:path); global fetch / FormData
+ * / Blob / AbortController are Node 18+ globals.
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_MODEL = "whisper-1";
+const DEFAULT_TIMEOUT_MS = 120000; // 2 min — large files / cold models
+const DEFAULT_FILE_NAME = "audio";
+
+/**
+ * Strip a single trailing slash so `${baseUrl}/audio/transcriptions` never
+ * doubles up. Mirrors OpenClaw's resolveProviderHttpRequestConfig behaviour
+ * of treating baseUrl as a root without a trailing slash.
+ * @param {string} url
+ * @returns {string}
+ */
+function normalizeBaseUrl(url) {
+  return String(url || "").replace(/\/+$/, "");
+}
+
+/**
+ * @typedef {Object} TranscribeAudioFileOptions
+ * @property {string}  [filePath]  Path to the audio file to transcribe. Mutually
+ *                                 sufficient with `buffer`; one of the two is required.
+ * @property {Buffer|Uint8Array|ArrayBuffer} [buffer] Raw audio bytes. Used instead of
+ *                                 reading from disk when supplied.
+ * @property {string}  [apiKey]    Override OPENAI_API_KEY.
+ * @property {string}  [model]     Transcription model id (default: whisper-1).
+ * @property {string}  [baseUrl]   OpenAI-compatible API root (default:
+ *                                 https://api.openai.com/v1). No trailing "/audio/...".
+ * @property {string}  [language]  ISO-639-1 language hint (e.g. "en"); improves accuracy.
+ * @property {string}  [prompt]    Optional prompt to steer style / spelling.
+ * @property {string}  [fileName]  Filename to send in the multipart part. Defaults to the
+ *                                 basename of `filePath`, else "audio".
+ * @property {string}  [mime]      Content-Type for the audio part (e.g. "audio/mpeg").
+ * @property {number}  [timeoutMs] Request timeout in ms (default: 120000).
+ */
+
+/**
+ * Transcribe a single audio file via an OpenAI-compatible
+ * `/audio/transcriptions` endpoint.
+ *
+ * @param {TranscribeAudioFileOptions} [opts]
+ * @returns {Promise<{ text: string, raw: any }>} The transcript text plus the
+ *          raw parsed JSON payload from the provider.
+ */
+export async function transcribeAudioFile(opts = {}) {
+  const apiKey = opts.apiKey || process.env.OPENAI_API_KEY;
+  if (!apiKey) throw new Error("OPENAI_API_KEY not set");
+
+  // Resolve the audio bytes: explicit buffer wins, else read from disk.
+  let bytes;
+  let fileName = opts.fileName;
+  if (opts.buffer != null) {
+    bytes =
+      opts.buffer instanceof ArrayBuffer ? Buffer.from(opts.buffer) : Buffer.from(opts.buffer);
+  } else if (opts.filePath) {
+    bytes = await readFile(opts.filePath);
+    if (!fileName) fileName = basename(opts.filePath);
+  } else {
+    throw new Error("transcribeAudioFile: provide either filePath or buffer");
+  }
+  if (!fileName) fileName = DEFAULT_FILE_NAME;
+
+  const model = (opts.model && String(opts.model).trim()) || DEFAULT_MODEL;
+  const baseUrl = normalizeBaseUrl(opts.baseUrl || DEFAULT_BASE_URL);
+  const url = `${baseUrl}/audio/transcriptions`;
+  const timeoutMs =
+    typeof opts.timeoutMs === "number" && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  // Build multipart/form-data. fetch sets the Content-Type (with boundary)
+  // automatically when the body is a FormData instance — do NOT set it by hand.
+  const form = new FormData();
+  const blob = opts.mime ? new Blob([bytes], { type: opts.mime }) : new Blob([bytes]);
+  form.append("file", blob, fileName);
+  form.append("model", model);
+  if (opts.language) form.append("language", String(opts.language));
+  if (opts.prompt) form.append("prompt", String(opts.prompt));
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let r;
+  try {
+    r = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: form,
+      signal: controller.signal,
+    });
+  } catch (err) {
+    if (err && err.name === "AbortError") {
+      throw new Error(`stt failed: request timed out after ${timeoutMs}ms`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!r.ok) {
+    let errText = "";
+    try {
+      errText = await r.text();
+    } catch {
+      errText = "";
+    }
+    throw new Error(`stt failed: HTTP ${r.status} ${errText.slice(0, 300)}`);
+  }
+
+  let payload;
+  try {
+    payload = await r.json();
+  } catch (err) {
+    throw new Error(`stt failed: invalid JSON response (${err && err.message})`);
+  }
+
+  const text = payload && typeof payload.text === "string" ? payload.text : undefined;
+  if (typeof text !== "string") {
+    throw new Error("stt failed: response missing text");
+  }
+
+  return { text, raw: payload };
+}
+
+export default { transcribeAudioFile };

package/lib/voice/stt.test.mjs

@@ -0,0 +1,226 @@
+/**
+ * Tests for lib/voice/stt.mjs — speech-to-text over an OpenAI-compatible
+ * /audio/transcriptions endpoint.
+ *
+ * Network is fully stubbed: global.fetch is replaced per-test so no real
+ * HTTP call is ever made. We assert the request URL, the Authorization
+ * header, the multipart field names/values (model, language, file), the
+ * parsed result shape, default model/baseUrl, the filePath read path, and
+ * error handling on a 401 stub.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { transcribeAudioFile } from "./stt.mjs";
+
+const realFetch = global.fetch;
+
+function jsonResponse(obj, { ok = true, status = 200 } = {}) {
+  return {
+    ok,
+    status,
+    async json() {
+      return obj;
+    },
+    async text() {
+      return JSON.stringify(obj);
+    },
+  };
+}
+
+function installFetchStub(handler) {
+  const calls = [];
+  global.fetch = async (url, init) => {
+    calls.push({ url, init });
+    return handler(url, init, calls);
+  };
+  return calls;
+}
+
+function restoreFetch() {
+  global.fetch = realFetch;
+}
+
+// Read multipart fields from a FormData body without making a network call.
+async function readForm(init) {
+  assert.ok(init && init.body instanceof FormData, "body must be a FormData instance");
+  const form = init.body;
+  return {
+    model: form.get("model"),
+    language: form.get("language"),
+    prompt: form.get("prompt"),
+    file: form.get("file"),
+  };
+}
+
+test("buffer path: posts multipart to default URL with auth + field names, parses result", async () => {
+  const calls = installFetchStub(() => jsonResponse({ text: "hello world", language: "en" }));
+  try {
+    const out = await transcribeAudioFile({
+      buffer: Buffer.from("FAKEAUDIOBYTES"),
+      apiKey: "sk-test-123",
+      language: "en",
+      fileName: "note.mp3",
+      mime: "audio/mpeg",
+    });
+
+    assert.equal(calls.length, 1, "exactly one fetch call");
+    const { url, init } = calls[0];
+
+    // URL + method
+    assert.equal(url, "https://api.openai.com/v1/audio/transcriptions");
+    assert.equal(init.method, "POST");
+
+    // Auth header
+    assert.equal(init.headers.Authorization, "Bearer sk-test-123");
+    // Caller must NOT hand-set Content-Type for FormData (fetch adds boundary).
+    assert.ok(
+      !init.headers["Content-Type"] && !init.headers["content-type"],
+      "Content-Type must not be set manually for multipart",
+    );
+
+    // Multipart fields
+    const fields = await readForm(init);
+    assert.equal(fields.model, "whisper-1", "default model");
+    assert.equal(fields.language, "en");
+    assert.equal(fields.prompt, null, "no prompt field when not provided");
+    assert.ok(fields.file instanceof Blob, "file part is a Blob");
+    assert.equal(fields.file.type, "audio/mpeg", "blob carries supplied mime");
+
+    // Parsed result
+    assert.equal(out.text, "hello world");
+    assert.deepEqual(out.raw, { text: "hello world", language: "en" });
+  } finally {
+    restoreFetch();
+  }
+});
+
+test("filePath path: reads file, derives fileName, honours baseUrl + model overrides", async () => {
+  const calls = installFetchStub(() => jsonResponse({ text: "from disk" }));
+  const dir = await mkdtemp(join(tmpdir(), "stt-test-"));
+  const fp = join(dir, "voicemail.wav");
+  await writeFile(fp, Buffer.from("RIFFfakewav"));
+  try {
+    const out = await transcribeAudioFile({
+      filePath: fp,
+      apiKey: "sk-abc",
+      model: "gpt-4o-transcribe",
+      baseUrl: "https://compat.example.com/v1/", // trailing slash should be normalized
+      prompt: "Northwind",
+    });
+
+    const { url, init } = calls[0];
+    assert.equal(url, "https://compat.example.com/v1/audio/transcriptions", "trailing slash trimmed");
+
+    const fields = await readForm(init);
+    assert.equal(fields.model, "gpt-4o-transcribe");
+    assert.equal(fields.prompt, "Northwind");
+    assert.ok(fields.file instanceof Blob);
+    // fileName defaults to the basename of filePath; assert via the part name.
+    assert.equal(fields.file.name, "voicemail.wav", "fileName derived from filePath basename");
+
+    assert.equal(out.text, "from disk");
+  } finally {
+    restoreFetch();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("apiKey falls back to process.env.OPENAI_API_KEY", async () => {
+  const calls = installFetchStub(() => jsonResponse({ text: "env key works" }));
+  const prev = process.env.OPENAI_API_KEY;
+  process.env.OPENAI_API_KEY = "sk-from-env";
+  try {
+    const out = await transcribeAudioFile({ buffer: Buffer.from("x") });
+    assert.equal(calls[0].init.headers.Authorization, "Bearer sk-from-env");
+    assert.equal(out.text, "env key works");
+  } finally {
+    restoreFetch();
+    if (prev === undefined) delete process.env.OPENAI_API_KEY;
+    else process.env.OPENAI_API_KEY = prev;
+  }
+});
+
+test("throws clear error when no apiKey available", async () => {
+  const prev = process.env.OPENAI_API_KEY;
+  delete process.env.OPENAI_API_KEY;
+  // fetch must never be called.
+  const calls = installFetchStub(() => {
+    throw new Error("fetch should not be called");
+  });
+  try {
+    await assert.rejects(
+      () => transcribeAudioFile({ buffer: Buffer.from("x") }),
+      /OPENAI_API_KEY not set/,
+    );
+    assert.equal(calls.length, 0, "no network call without a key");
+  } finally {
+    restoreFetch();
+    if (prev !== undefined) process.env.OPENAI_API_KEY = prev;
+  }
+});
+
+test("throws when neither filePath nor buffer is provided", async () => {
+  const calls = installFetchStub(() => jsonResponse({ text: "nope" }));
+  try {
+    await assert.rejects(
+      () => transcribeAudioFile({ apiKey: "sk-x" }),
+      /provide either filePath or buffer/,
+    );
+    assert.equal(calls.length, 0);
+  } finally {
+    restoreFetch();
+  }
+});
+
+test("error handling: non-2xx (401) surfaces status + body", async () => {
+  installFetchStub(() =>
+    jsonResponse({ error: { message: "Invalid API key" } }, { ok: false, status: 401 }),
+  );
+  try {
+    await assert.rejects(
+      () => transcribeAudioFile({ buffer: Buffer.from("x"), apiKey: "sk-bad" }),
+      (err) => {
+        assert.match(err.message, /stt failed: HTTP 401/);
+        assert.match(err.message, /Invalid API key/);
+        return true;
+      },
+    );
+  } finally {
+    restoreFetch();
+  }
+});
+
+test("error handling: 2xx but missing text field", async () => {
+  installFetchStub(() => jsonResponse({ language: "en" }));
+  try {
+    await assert.rejects(
+      () => transcribeAudioFile({ buffer: Buffer.from("x"), apiKey: "sk-x" }),
+      /response missing text/,
+    );
+  } finally {
+    restoreFetch();
+  }
+});
+
+test("timeout: AbortError is reported as a timeout", async () => {
+  global.fetch = async (_url, init) => {
+    // Simulate the runtime aborting the request.
+    const err = new Error("aborted");
+    err.name = "AbortError";
+    void init;
+    throw err;
+  };
+  try {
+    await assert.rejects(
+      () => transcribeAudioFile({ buffer: Buffer.from("x"), apiKey: "sk-x", timeoutMs: 5 }),
+      /request timed out after 5ms/,
+    );
+  } finally {
+    restoreFetch();
+  }
+});