@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/wire/openai-chat.mjs

@@ -0,0 +1,332 @@
+/**
+ * lib/engine/wire/openai-chat.mjs — the OpenAI Chat Completions wire.
+ *
+ * cohort-llm's `/v1/chat/completions` is a zero-translation passthrough to the
+ * open-model supplier (design §4.2), so this is the engine's default wire.
+ *
+ * Three layers, only the last one does I/O:
+ *   · `buildOpenAIRequest`   canonical history → request body (pure)
+ *   · `createOpenAIAccumulator` SSE frames → one assistant turn (pure state)
+ *   · `callOpenAIChat`       the edge, over `postStream`
+ *
+ * Prompt caching. The open-model supplier caches by PREFIX automatically; what
+ * the engine controls is that the prefix is byte-stable across turns: the
+ * system message is first and alone, tools are sent in registry order, and the
+ * history only ever grows at the tail. For suppliers that honour explicit
+ * breakpoints on this wire (the OpenRouter dialect), `cacheBreakpoints:true`
+ * sends the system prompt as a content part carrying `cache_control` — the end
+ * of the stable prefix. It is off by default because a strict OpenAI server
+ * rejects a content-part array on a system message.
+ *
+ * `promptCacheKey` is sent as `prompt_cache_key` when the caller has one (the
+ * gateway advertised support or config enabled it; see wire/prompt-cache.mjs).
+ * With `cacheBreakpoints:true` the final user message is marked too.
+ *
+ * Images. OpenAI tool messages carry text only, so images from tool results
+ * (`images:true`) follow the tool messages as ONE user message of `image_url`
+ * data-URL parts. With `images:false` (the default: open text models reject
+ * image parts) the tool text says the images were not sent.
+ *
+ * Reasoning (CF-72): `reasoning_content` and `reasoning_signature` deltas are
+ * kept as one canonical thinking block, and an assistant turn sent back echoes
+ * both fields (`reasoningFields`), so a leg that needs its signed reasoning on
+ * replay gets it — including after a resume, since the block is in the transcript.
+ *
+ * Usage (design §4.5): arrives on the finish chunk or a trailing chunk
+ * (`stream_options.include_usage`); the LAST usage object wins, normalised by
+ * `normaliseOpenAIUsage` (prompt_tokens INCLUDES cached tokens).
+ *
+ * @module lib/engine/wire/openai-chat
+ */
+
+import { classifyStreamError, protocolError } from "./errors.mjs";
+import { postStream, joinUrl } from "./http.mjs";
+import { normaliseOpenAIUsage, emptyUsage } from "./usage.mjs";
+import { normaliseHistory } from "../messages.mjs";
+
+export const OPENAI_CHAT_ROUTE = "/v1/chat/completions";
+
+/**
+ * @param {object} p
+ * @param {string} p.model
+ * @param {string} p.system
+ * @param {Array<{role:string, content:any[]}>} p.messages
+ * @param {Array<{name:string, description:string, input_schema:object}>} [p.tools]
+ * @param {number} p.maxTokens
+ * @param {boolean} [p.cacheBreakpoints]
+ * @param {'low'|'medium'|'high'|null} [p.reasoningEffort]
+ * @param {string|null} [p.promptCacheKey]
+ * @param {boolean} [p.images]
+ */
+export function buildOpenAIRequest({ model, system, messages, tools = [], maxTokens, cacheBreakpoints = false, reasoningEffort = null, promptCacheKey = null, images = false }) {
+  /** @type {any[]} */
+  const out = [];
+  if (system) {
+    out.push(
+      cacheBreakpoints
+        ? { role: "system", content: [{ type: "text", text: system, cache_control: { type: "ephemeral" } }] }
+        : { role: "system", content: system },
+    );
+  }
+  for (const m of normaliseHistory(messages)) {
+    if (m.role === "assistant") {
+      const text = m.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+      const calls = m.content
+        .filter((b) => b.type === "tool_use")
+        .map((b) => ({
+          id: b.id,
+          type: "function",
+          function: {
+            name: b.name,
+            // A call whose JSON never parsed is echoed as the model sent it, so
+            // the model sees its own mistake next to the error result.
+            arguments: b.inputError && typeof b.rawInput === "string" ? b.rawInput : JSON.stringify(b.input ?? {}),
+          },
+        }));
+      /** @type {any} */
+      const msg = { role: "assistant", content: text === "" ? null : text };
+      if (calls.length > 0) msg.tool_calls = calls;
+      if (msg.content === null && calls.length === 0) continue;
+      Object.assign(msg, reasoningFields(m.content));
+      out.push(msg);
+    } else {
+      /** @type {Array<{mediaType:string, data:string}>} */
+      const attached = [];
+      for (const b of m.content) {
+        if (b.type === "tool_result") {
+          let content = b.is_error ? `Error: ${b.content}` : b.content;
+          const imgs = Array.isArray(b.images) ? b.images : [];
+          if (imgs.length > 0 && images) attached.push(...imgs);
+          else if (imgs.length > 0) content = `${content}${imageFallbackNote(imgs.length)}`;
+          out.push({ role: "tool", tool_call_id: b.tool_use_id, content });
+        }
+      }
+      const text = m.content.filter((b) => b.type === "text").map((b) => b.text).join("\n\n");
+      if (attached.length > 0) {
+        out.push({
+          role: "user",
+          content: [
+            { type: "text", text: text !== "" ? text : "Images returned by the tool calls above:" },
+            ...attached.map((i) => ({ type: "image_url", image_url: { url: `data:${i.mediaType};base64,${i.data}` } })),
+          ],
+        });
+      } else if (text !== "") out.push({ role: "user", content: text });
+    }
+  }
+  if (cacheBreakpoints) {
+    const last = out[out.length - 1];
+    if (last && last.role === "user" && typeof last.content === "string") {
+      out[out.length - 1] = { role: "user", content: [{ type: "text", text: last.content, cache_control: { type: "ephemeral" } }] };
+    }
+  }
+  /** @type {any} */
+  const body = {
+    model,
+    messages: out,
+    max_tokens: maxTokens,
+    stream: true,
+    stream_options: { include_usage: true },
+  };
+  if (reasoningEffort) body.reasoning_effort = reasoningEffort; // wire/effort.mjs decides when
+  if (tools.length > 0) {
+    body.tools = tools.map((t) => ({
+      type: "function",
+      function: { name: t.name, description: t.description, parameters: t.input_schema },
+    }));
+    body.tool_choice = "auto";
+  }
+  if (promptCacheKey) body.prompt_cache_key = promptCacheKey;
+  return body;
+}
+
+/**
+ * CF-72: an assistant turn's thinking blocks as the OpenAI wire's reasoning
+ * fields. `reasoning_content` is the thinking text; `reasoning_signature` (the
+ * gateway's carrier for an Anthropic-wire leg's thinking signature) is echoed
+ * beside it, or that leg's reasoning is dropped on replay. The wire has one
+ * field of each per message: texts are joined and the last signature wins.
+ * Neither field is sent when the turn has no thinking. Pure.
+ * @param {any[]} content
+ * @returns {{reasoning_content?:string, reasoning_signature?:string}}
+ */
+export function reasoningFields(content) {
+  const blocks = content.filter((b) => b && b.type === "thinking");
+  if (blocks.length === 0) return {};
+  const reasoning = blocks.map((b) => (typeof b.thinking === "string" ? b.thinking : "")).join("");
+  const signature = blocks.reduce((s, b) => (typeof b.signature === "string" && b.signature !== "" ? b.signature : s), "");
+  if (reasoning === "" && signature === "") return {};
+  return signature === "" ? { reasoning_content: reasoning } : { reasoning_content: reasoning, reasoning_signature: signature };
+}
+
+/** The text a tool result carries when its images cannot be sent on this connection. @param {number} n */
+export function imageFallbackNote(n) {
+  return `\n[${n === 1 ? "1 image was" : `${n} images were`} not shown: this model connection does not accept images]`;
+}
+
+const FINISH_TO_STOP = {
+  stop: "end_turn",
+  tool_calls: "tool_use",
+  function_call: "tool_use",
+  length: "max_tokens",
+  content_filter: "refusal",
+};
+
+/**
+ * Accumulate one streamed completion into a canonical assistant turn.
+ * @param {{ now?: () => number }} [opts]
+ */
+export function createOpenAIAccumulator(opts = {}) {
+  const now = opts.now || Date.now;
+  let text = "";
+  // CF-72: reasoning text and its signature, each accumulated across deltas.
+  let reasoning = "";
+  let signature = "";
+  /** @type {Map<number, {id:string, name:string, args:string}>} */
+  const calls = new Map();
+  let finish = null;
+  let usage = null;
+  let model = null;
+  let sawChunk = false;
+  let sawDone = false;
+
+  return {
+    /** @param {import('./sse.mjs').SseFrame} frame */
+    onFrame(frame) {
+      if (frame.data === "[DONE]") {
+        sawDone = true;
+        return { ok: true, done: true };
+      }
+      let chunk;
+      try {
+        chunk = JSON.parse(frame.data);
+      } catch {
+        return { ok: false, error: protocolError(`unparseable stream chunk: ${frame.data.slice(0, 120)}`) };
+      }
+      if (chunk && chunk.error) return { ok: false, error: classifyStreamError(chunk, null, now()) };
+      sawChunk = true;
+      if (typeof chunk.model === "string") model = chunk.model;
+      if (chunk.usage && typeof chunk.usage === "object") usage = chunk.usage;
+      for (const choice of Array.isArray(chunk.choices) ? chunk.choices : []) {
+        // A non-stream-shaped choice carries `message` instead of `delta`; its fields read the same.
+        const d = choice.delta || choice.message || {};
+        if (typeof d.content === "string") text += d.content;
+        if (typeof d.reasoning_content === "string") reasoning += d.reasoning_content;
+        if (typeof d.reasoning_signature === "string") signature += d.reasoning_signature;
+        for (const tc of Array.isArray(d.tool_calls) ? d.tool_calls : []) {
+          const idx = Number.isInteger(tc.index) ? tc.index : calls.size;
+          const cur = calls.get(idx) || { id: "", name: "", args: "" };
+          if (typeof tc.id === "string" && tc.id) cur.id = tc.id;
+          if (tc.function) {
+            if (typeof tc.function.name === "string") cur.name += tc.function.name;
+            if (typeof tc.function.arguments === "string") cur.args += tc.function.arguments;
+          }
+          calls.set(idx, cur);
+        }
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) finish = choice.finish_reason;
+      }
+      return { ok: true };
+    },
+
+    finish() {
+      if (!sawChunk || (finish === null && !sawDone)) {
+        return { ok: false, error: protocolError("stream ended before the completion finished") };
+      }
+      /** @type {any[]} */
+      const content = [];
+      // Thinking comes first, as on the Anthropic wire; the signature is kept only when one arrived.
+      if (reasoning !== "" || signature !== "") content.push(signature === "" ? { type: "thinking", thinking: reasoning } : { type: "thinking", thinking: reasoning, signature });
+      if (text !== "") content.push({ type: "text", text });
+      const ordered = [...calls.entries()].sort((a, b) => a[0] - b[0]);
+      ordered.forEach(([idx, c]) => {
+        const block = parseToolArguments(c.args);
+        content.push({ type: "tool_use", id: c.id || `call_${idx}`, name: c.name, ...block });
+      });
+      // A length stop is kept even when tool calls exist: their arguments may be
+      // cut off, and the loop must not run them (it refuses the whole turn).
+      const stopReason = finish === "length" ? "max_tokens" : calls.size > 0 ? "tool_use" : (FINISH_TO_STOP[finish] ?? "end_turn");
+      return {
+        ok: true,
+        value: {
+          message: { role: "assistant", content },
+          stopReason,
+          usage: usage ? normaliseOpenAIUsage(usage) : emptyUsage("estimated"),
+          model,
+        },
+      };
+    },
+  };
+}
+
+/**
+ * @param {string} raw
+ * @returns {{input: object, inputError?: string, rawInput?: string}}
+ */
+export function parseToolArguments(raw) {
+  const s = (raw ?? "").trim();
+  if (s === "") return { input: {} };
+  try {
+    const v = JSON.parse(s);
+    if (v && typeof v === "object" && !Array.isArray(v)) return { input: v };
+    return { input: {}, inputError: "tool arguments must be a JSON object", rawInput: raw };
+  } catch (e) {
+    return { input: {}, inputError: e instanceof Error ? e.message : String(e), rawInput: raw };
+  }
+}
+
+/**
+ * One model turn over the OpenAI wire.
+ *
+ * @param {object} p
+ * @param {string} p.baseUrl
+ * @param {string|((o:{refresh:boolean})=>string|Promise<string>)} p.token
+ * @param {string} p.model
+ * @param {string} p.system
+ * @param {any[]} p.messages
+ * @param {any[]} [p.tools]
+ * @param {number} [p.maxTokens]
+ * @param {boolean} [p.cacheBreakpoints]
+ * @param {string|null} [p.promptCacheKey]
+ * @param {boolean} [p.images]
+ * @param {Record<string,string>} [p.headers]   attribution headers (x-cohort-*)
+ * @param {'low'|'medium'|'high'|null} [p.reasoningEffort]  sent as reasoning_effort
+ * @param {(frame:any)=>void} [p.onFrame]        observer of each stream frame (stream-json partials)
+ * @param {AbortSignal} [p.signal]
+ * @param {typeof fetch} [p.fetchImpl]
+ * @param {number} [p.maxRetries]
+ * @param {() => number} [p.now]
+ * @param {(ms:number, s?:AbortSignal)=>Promise<void>} [p.sleep]
+ * @param {number} [p.idleTimeoutMs]  silence budget between SSE events (CF-156); 0 disables
+ * @param {number} [p.slowStreamMs]   a completed stream slower than this is recorded
+ * @param {(d: import('./stall.mjs').StreamDiagnostic) => void} [p.onStreamDiagnostic]
+ */
+export async function callOpenAIChat(p) {
+  const body = buildOpenAIRequest({
+    model: p.model,
+    system: p.system,
+    messages: p.messages,
+    tools: p.tools,
+    maxTokens: p.maxTokens ?? 16000,
+    cacheBreakpoints: p.cacheBreakpoints,
+    reasoningEffort: p.reasoningEffort ?? null,
+    promptCacheKey: p.promptCacheKey ?? null,
+    images: p.images ?? false,
+  });
+  return postStream({
+    url: joinUrl(p.baseUrl, OPENAI_CHAT_ROUTE),
+    headers: { ...(p.headers || {}) },
+    body,
+    token: p.token,
+    createAccumulator: () => createOpenAIAccumulator({ now: p.now }),
+    onFrame: p.onFrame,
+    signal: p.signal,
+    fetchImpl: p.fetchImpl,
+    maxRetries: p.maxRetries,
+    now: p.now,
+    sleep: p.sleep,
+    idleTimeoutMs: p.idleTimeoutMs,
+    slowStreamMs: p.slowStreamMs,
+    onStreamDiagnostic: p.onStreamDiagnostic,
+    wire: "openai",
+    tier: p.model,
+  });
+}

package/lib/engine/wire/prompt-cache.mjs

@@ -0,0 +1,79 @@
+/**
+ * lib/engine/wire/prompt-cache.mjs — when to send `prompt_cache_key`.
+ *
+ * `prompt_cache_key` routes requests that share a prefix to the same cache on
+ * the OpenAI wire. A gateway or supplier that does not know the field may
+ * reject it, so the engine sends it only when:
+ *
+ *   · mode `on`   — configuration says the gateway supports it
+ *                   (COHORT_LLM_PROMPT_CACHE_KEY=1, or settings
+ *                   `cohort.promptCacheKey: true`);
+ *   · mode `auto` — the default: from the first response that carries
+ *                   `x-cohort-prompt-cache-key-supported: 1` (or `true`) on;
+ *   · mode `off`  — never (COHORT_LLM_PROMPT_CACHE_KEY=0, or `false`).
+ *
+ * The key itself never changes within a run, so turning it on changes no
+ * prompt bytes; only routing.
+ *
+ * @module lib/engine/wire/prompt-cache
+ */
+
+import { header } from "./errors.mjs";
+
+export const PROMPT_CACHE_KEY_HEADER = "x-cohort-prompt-cache-key-supported";
+
+/**
+ * @param {unknown} envValue  COHORT_LLM_PROMPT_CACHE_KEY
+ * @param {unknown} settingValue  settings cohort.promptCacheKey
+ * @returns {'on'|'off'|'auto'}
+ */
+export function promptCacheKeyMode(envValue, settingValue) {
+  const e = String(envValue ?? "").trim().toLowerCase();
+  if (["1", "true", "on", "yes"].includes(e)) return "on";
+  if (["0", "false", "off", "no"].includes(e)) return "off";
+  if (settingValue === true) return "on";
+  if (settingValue === false) return "off";
+  return "auto";
+}
+
+/** @param {string|null} v */
+function truthy(v) {
+  return v != null && ["1", "true", "yes"].includes(String(v).trim().toLowerCase());
+}
+
+/**
+ * @param {{key:string, mode:'on'|'off'|'auto'}} p
+ */
+export function createPromptCacheKeyState({ key, mode }) {
+  let supported = mode === "on";
+  return {
+    key,
+    mode,
+    /** The key to send on the next request, or null. */
+    current: () => (mode !== "off" && supported ? key : null),
+    /** @param {any} headers */
+    observe(headers) {
+      if (mode === "auto" && !supported && truthy(header(headers, PROMPT_CACHE_KEY_HEADER))) supported = true;
+    },
+    get supported() {
+      return supported;
+    },
+  };
+}
+
+/**
+ * A fetch that reports every response's headers to the state.
+ * @param {typeof fetch|undefined} fetchImpl
+ * @param {{observe:(h:any)=>void}} state
+ * @returns {typeof fetch}
+ */
+export function observingFetch(fetchImpl, state) {
+  const f = fetchImpl ?? globalThis.fetch;
+  return /** @type {typeof fetch} */ (
+    async (url, init) => {
+      const res = await f(url, init);
+      state.observe(res.headers);
+      return res;
+    }
+  );
+}

package/lib/engine/wire/search.mjs

@@ -0,0 +1,140 @@
+/**
+ * lib/engine/wire/search.mjs — the gateway's web search endpoint (client).
+ *
+ * Contract (cohort-llm, owned with the gateway; WebSearch is its only caller):
+ *
+ *   POST <base>/cohort/v1/search
+ *     Authorization: Bearer <seat token>
+ *     body  {"query":"…","maxResults":8,"allowedDomains":["…"],"blockedDomains":["…"]}
+ *     200   {"results":[{"title":"…","url":"…","snippet":"…"}],"costMicros":"1200"}
+ *           (costMicros: decimal integer string of micro-USD, or a safe integer;
+ *            `x-cohort-request-id` and `x-cohort-cost-micros` headers as on every route)
+ *     404   the gateway has no search → the tool reports search as unavailable
+ *     4xx/5xx refusals use the §4.6/§4.8 error bodies
+ *
+ * Expected failures are returned values. A 401 is retried once with a
+ * refreshed token when the token is a function; nothing else is retried
+ * (a search is cheap to ask for again, and a refusal must not be hammered).
+ *
+ * @module lib/engine/wire/search
+ */
+
+import { classifyHttpError, classifyTransportError, tokenFailureError, header } from "./errors.mjs";
+
+export const SEARCH_ROUTE = "/cohort/v1/search";
+export const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
+export const MAX_SEARCH_RESULTS = 20;
+
+/** @param {string} baseUrl */
+export function searchUrl(baseUrl) {
+  let base = String(baseUrl || "").trim().replace(/\/+$/, "");
+  if (base.endsWith("/v1")) base = base.slice(0, -3);
+  return `${base}${SEARCH_ROUTE}`;
+}
+
+/** @param {unknown} v @returns {string|null} */
+function micros(v) {
+  if (typeof v === "number") return Number.isSafeInteger(v) && v >= 0 ? String(v) : null;
+  return typeof v === "string" && /^\d+$/.test(v.trim()) ? v.trim() : null;
+}
+
+/**
+ * Validate the 200 body (pure).
+ * @param {unknown} body
+ * @returns {{ok:true, results:Array<{title:string, url:string, snippet:string}>, costMicros:string|null}|{ok:false, message:string}}
+ */
+export function parseSearchBody(body) {
+  if (!body || typeof body !== "object" || !Array.isArray(/** @type any */ (body).results)) return { ok: false, message: "the search response has no results array" };
+  const b = /** @type any */ (body);
+  const results = b.results
+    .filter((r) => r && typeof r === "object" && typeof r.url === "string" && r.url !== "")
+    .map((r) => ({ title: typeof r.title === "string" ? r.title : r.url, url: r.url, snippet: typeof r.snippet === "string" ? r.snippet : "" }));
+  return { ok: true, results, costMicros: micros(b.costMicros) };
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.baseUrl
+ * @param {string|((o:{refresh:boolean})=>string|Promise<string>)} p.token
+ * @param {string} p.query
+ * @param {number} [p.maxResults]
+ * @param {string[]} [p.allowedDomains]
+ * @param {string[]} [p.blockedDomains]
+ * @param {Record<string,string>} [p.headers]
+ * @param {typeof fetch} [p.fetchImpl]
+ * @param {AbortSignal} [p.signal]
+ * @param {number} [p.timeoutMs]
+ * @param {() => number} [p.now]
+ * @returns {Promise<{ok:true, results:Array<{title:string,url:string,snippet:string}>, cohort:{requestId:string|null, costMicros:string|null}}
+ *   | {ok:false, error:{kind:string, code:string, status:number|null, message:string}, cohort:{requestId:string|null, costMicros:string|null}|null, accepted:boolean}>}
+ */
+export async function searchWeb(p) {
+  const fetchImpl = p.fetchImpl ?? globalThis.fetch;
+  const now = p.now ?? Date.now;
+  const body = {
+    query: p.query,
+    maxResults: Math.min(MAX_SEARCH_RESULTS, Math.max(1, p.maxResults ?? 8)),
+    allowedDomains: p.allowedDomains ?? [],
+    blockedDomains: p.blockedDomains ?? [],
+  };
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  if (p.signal?.aborted) controller.abort();
+  else p.signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => controller.abort(), p.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS);
+  try {
+    let refresh = false;
+    /** @type {string|undefined} */
+    let rejected;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      let token;
+      try {
+        token = typeof p.token === "function" ? await p.token(refresh ? { refresh, rejected } : { refresh }) : p.token;
+      } catch (e) {
+        // token_unavailable, or a retryable cohort_unavailable when the token endpoint was down (CF-143).
+        return { ok: false, error: tokenFailureError(e), cohort: null, accepted: false };
+      }
+      let res;
+      try {
+        res = await fetchImpl(searchUrl(p.baseUrl), {
+          method: "POST",
+          headers: { "content-type": "application/json", accept: "application/json", authorization: `Bearer ${token}`, ...(p.headers ?? {}) },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+      } catch (e) {
+        const err = classifyTransportError(e, controller.signal);
+        return { ok: false, error: { kind: err.kind, code: err.code, status: null, message: err.message }, cohort: null, accepted: false };
+      }
+      const cohort = { requestId: header(res.headers, "x-cohort-request-id"), costMicros: micros(header(res.headers, "x-cohort-cost-micros")) };
+      if (res.status === 401 && typeof p.token === "function" && !refresh) {
+        await res.body?.cancel().catch(() => {});
+        refresh = true;
+        rejected = token;
+        continue;
+      }
+      if (res.status === 404) {
+        await res.body?.cancel().catch(() => {});
+        return { ok: false, error: { kind: "unavailable", code: "search_unavailable", status: 404, message: "the gateway does not offer web search" }, cohort, accepted: false };
+      }
+      const text = await res.text().catch(() => "");
+      if (!res.ok) {
+        const err = classifyHttpError(res.status, res.headers, text, now());
+        return { ok: false, error: { kind: err.kind, code: err.code, status: res.status, message: err.message }, cohort, accepted: false };
+      }
+      let json;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        return { ok: false, error: { kind: "protocol", code: "search_protocol_error", status: res.status, message: "the search response was not JSON" }, cohort, accepted: true };
+      }
+      const parsed = parseSearchBody(json);
+      if (!parsed.ok) return { ok: false, error: { kind: "protocol", code: "search_protocol_error", status: res.status, message: parsed.message }, cohort, accepted: true };
+      return { ok: true, results: parsed.results.slice(0, body.maxResults), cohort: { requestId: cohort.requestId, costMicros: parsed.costMicros ?? cohort.costMicros } };
+    }
+    return { ok: false, error: { kind: "auth", code: "http_401", status: 401, message: "the gateway refused the refreshed token" }, cohort: null, accepted: false };
+  } finally {
+    clearTimeout(timer);
+    p.signal?.removeEventListener("abort", onAbort);
+  }
+}

package/lib/engine/wire/sse.mjs

@@ -0,0 +1,114 @@
+/**
+ * lib/engine/wire/sse.mjs — a small, strict Server-Sent Events reader.
+ *
+ * Both gateway wires stream as SSE: OpenAI Chat sends bare `data:` frames and a
+ * terminal `data: [DONE]`; Anthropic Messages sends named `event:` frames. One
+ * parser serves both. It follows the WHATWG event-stream grammar closely enough
+ * for an LLM gateway: LF / CRLF / CR line endings, multi-line `data:` joined
+ * with "\n", `:` comment lines (the gateway's 15 s keep-alive pings) ignored,
+ * and a frame dispatched on a blank line. `id:` / `retry:` are read and
+ * surfaced but never acted on — reconnecting a half-streamed completion would
+ * double-bill, so the engine does not.
+ *
+ * The chunk → frame split is a pure function (`createSseDecoder`) so it can be
+ * tested with adversarial chunk boundaries without a socket; `readSse` is the
+ * thin async-iterator edge over a fetch body.
+ *
+ * @module lib/engine/wire/sse
+ */
+
+/**
+ * @typedef {{ event: string, data: string, id?: string }} SseFrame
+ */
+
+/**
+ * Create an incremental decoder. Feed it text chunks; it returns the frames
+ * completed by each chunk. Holds at most one partial line and one partial frame.
+ *
+ * @returns {{ push: (text: string) => SseFrame[], end: () => SseFrame[] }}
+ */
+export function createSseDecoder() {
+  let buffer = "";
+  let dataLines = [];
+  let eventName = "";
+  let lastId;
+  let sawField = false;
+
+  function dispatch(out) {
+    if (!sawField) return;
+    if (dataLines.length > 0) {
+      const frame = { event: eventName || "message", data: dataLines.join("\n") };
+      if (lastId !== undefined) frame.id = lastId;
+      out.push(frame);
+    }
+    dataLines = [];
+    eventName = "";
+    sawField = false;
+  }
+
+  function line(raw, out) {
+    if (raw === "") return dispatch(out);
+    if (raw.startsWith(":")) return; // comment / keep-alive ping
+    const colon = raw.indexOf(":");
+    const field = colon === -1 ? raw : raw.slice(0, colon);
+    let value = colon === -1 ? "" : raw.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    sawField = true;
+    if (field === "data") dataLines.push(value);
+    else if (field === "event") eventName = value;
+    else if (field === "id") lastId = value;
+    // `retry` and unknown fields are ignored by design (see header).
+  }
+
+  return {
+    push(text) {
+      const out = [];
+      buffer += text;
+      // Split on any of CRLF / LF / CR. A trailing lone CR might be the first
+      // half of a CRLF split across chunks, so keep it buffered.
+      let start = 0;
+      for (let i = 0; i < buffer.length; i++) {
+        const ch = buffer[i];
+        if (ch === "\n") {
+          line(buffer.slice(start, i), out);
+          start = i + 1;
+        } else if (ch === "\r") {
+          if (i === buffer.length - 1) break; // wait for the next chunk
+          line(buffer.slice(start, i), out);
+          if (buffer[i + 1] === "\n") i++;
+          start = i + 1;
+        }
+      }
+      buffer = buffer.slice(start);
+      return out;
+    },
+    end() {
+      const out = [];
+      if (buffer !== "") {
+        line(buffer.replace(/\r$/, ""), out);
+        buffer = "";
+      }
+      dispatch(out);
+      return out;
+    },
+  };
+}
+
+/**
+ * Iterate the SSE frames of a response body (a WHATWG ReadableStream, or any
+ * async iterable of Uint8Array / string chunks).
+ *
+ * @param {AsyncIterable<Uint8Array|string>} body
+ * @returns {AsyncGenerator<SseFrame>}
+ */
+export async function* readSse(body) {
+  const decoder = createSseDecoder();
+  const text = new TextDecoder();
+  for await (const chunk of body) {
+    const str = typeof chunk === "string" ? chunk : text.decode(chunk, { stream: true });
+    for (const frame of decoder.push(str)) yield frame;
+  }
+  const tail = text.decode();
+  if (tail) for (const frame of decoder.push(tail)) yield frame;
+  for (const frame of decoder.end()) yield frame;
+}