rovecode 0.3.2

package/src/providers/registry.ts

@@ -0,0 +1,333 @@
+/** Live provider registry — the ADAPTER half of the provider layer, over provider-config.ts (data).
+ *
+ *  One registry per runtime. stream() returns a DISPATCHING StreamFn: every call resolves
+ *  `model.provider` against the live snapshot (hot reload — provider-config.ts), so a provider added
+ *  from another terminal, by `rovecode provider add`, by `/provider add` in the TUI or by the agent's
+ *  provider_edit tool serves the very next model call. No restart, no runtime rebuild. Concrete
+ *  adapters (stream.ts) are cached per provider id and rebuilt when baseUrl, protocol, key or
+ *  headers change — a rotated key takes effect on the next call too.
+ *
+ *  Seam contract (ADR-003): the dispatcher never throws. An unknown provider or a missing key is ONE
+ *  error turn whose text starts with `config: ` — router.ts classifyStreamError treats that prefix
+ *  as non-retryable, so neither the same-model retry (port #23) nor a fallback chain (port #14)
+ *  spins on a configuration mistake; the text tells the human exactly how to fix it.
+ *
+ *  Because the dispatcher honours model.provider per call, cross-provider fallback chains
+ *  (ROVECODE_MODEL_<ROLE>=a/x,b/y) now really route each candidate to its own endpoint.
+ *
+ *  Secrets: this module reads keys to build adapters and to redact them from probe errors
+ *  (scrubSecret). Nothing here prints or returns a key; formatProviderList shows key SOURCES. */
+
+import type { AssistantTurn, Message, ModelRef, StreamEvent, StreamFn, StreamOptions } from "../core/types.ts";
+import { fetchModels, providerStream, providerStreaming, wantsStreaming, type ProviderConfig as WireProviderConfig } from "./stream.ts";
+import {
+  ProviderConfig, isConfigured, parseSelector, pickDefault, providersPathFor, readProvidersFile, validateSpec, writeProvidersFile,
+  type FileScope, type ProviderEntry, type ProviderSnapshot, type ProviderSpec, type ResolvedProvider,
+} from "./provider-config.ts";
+import { next } from "../core/voice.ts";
+
+export type AdapterFactory = (p: ResolvedProvider, opts: { sse: boolean }) => StreamFn;
+
+/** stream.ts ProviderConfig for a resolved provider (a keyless provider sends an empty bearer). */
+export function toWireConfig(p: ResolvedProvider): WireProviderConfig {
+  return {
+    id: p.id, baseUrl: p.baseUrl, apiKey: p.apiKey ?? "", protocol: p.protocol,
+    ...(p.defaultModel !== undefined ? { defaultModel: p.defaultModel } : {}),
+    ...(p.headers !== undefined ? { headers: p.headers } : {}),
+  };
+}
+
+export const defaultAdapterFactory: AdapterFactory = (p, { sse }) => {
+  const wire = toWireConfig(p);
+  // both protocols stream (openai SSE chunks, anthropic Messages events); `sse` is off only when
+  // ROVECODE_STREAM asked for the one-shot JSON adapters
+  return sse ? providerStreaming(wire) : providerStream(wire);
+};
+
+/** Error-text prefix the router/retry classifier treats as non-retryable (router.ts). */
+export const CONFIG_ERROR_PREFIX = "config: ";
+
+export function configErrorTurn(text: string): AssistantTurn {
+  return { parts: [], stopReason: "error", usage: { input: 0, output: 0 }, error: CONFIG_ERROR_PREFIX + text };
+}
+
+/** Replace a secret wherever it leaked into text (some proxies echo request headers in error bodies). */
+export function scrubSecret(text: string, secret: string | null | undefined): string {
+  return secret !== null && secret !== undefined && secret.length > 0 ? text.split(secret).join("…") : text;
+}
+
+export interface RegistryOptions {
+  env?: NodeJS.ProcessEnv;
+  /** test seam: build adapters without touching the network */
+  adapterFactory?: AdapterFactory;
+  /** provider-config.ts reload throttle (ms); tests pass 0 */
+  throttleMs?: number;
+}
+
+export class ProviderRegistry {
+  readonly cwd: string;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly cfg: ProviderConfig;
+  private readonly factory: AdapterFactory;
+  private readonly adapters = new Map<string, { sig: string; fn: StreamFn }>();
+
+  constructor(cwd: string, opts: RegistryOptions = {}) {
+    this.cwd = cwd;
+    this.env = opts.env ?? process.env;
+    this.factory = opts.adapterFactory ?? defaultAdapterFactory;
+    this.cfg = new ProviderConfig(cwd, this.env, opts.throttleMs);
+  }
+
+  snapshot(): ProviderSnapshot { return this.cfg.snapshot(); }
+  list(): ResolvedProvider[] { return this.snapshot().providers; }
+  ids(): string[] { return this.list().map((p) => p.id); }
+  get(id: string): ResolvedProvider | undefined { return this.list().find((p) => p.id === id); }
+  /** at least one provider has a key (or needs none) */
+  configured(): boolean { return this.list().some(isConfigured); }
+  warnings(): string[] { return this.snapshot().warnings; }
+  /** fires after every rebuild: external file edits (detected lazily) and in-process add/remove/setDefault */
+  onChange(cb: (snap: ProviderSnapshot) => void): () => void { return this.cfg.onChange(cb); }
+  /** re-read now (in-process writers call it right after writing) and notify listeners */
+  refresh(): ProviderSnapshot { this.cfg.invalidate(); return this.cfg.snapshot(); }
+
+  /** default provider + model with env ROVECODE_MODEL layered on top; null when nothing is configured */
+  defaultRef(): ModelRef | null {
+    const d = pickDefault(this.snapshot());
+    if (d === null) return null;
+    return { provider: d.provider.id, model: this.env["ROVECODE_MODEL"] ?? d.model ?? "" };
+  }
+
+  /** stream.ts-shaped config of the default provider (Runtime.provider compatibility) */
+  defaultConfig(): WireProviderConfig | null {
+    const d = pickDefault(this.snapshot());
+    if (d === null) return null;
+    return { ...toWireConfig(d.provider), ...(d.model !== undefined ? { defaultModel: d.model } : {}) };
+  }
+
+  defaultSelector(): string | undefined { return this.snapshot().defaultSelector; }
+
+  /** "provider/model" or a bare model on `currentProvider`. A leading segment counts as a provider
+   *  only when it names one, so "zai-org/glm-5.3" stays a model id on the current provider. The
+   *  current provider is not validated (it may be "mock" or an injected test stream): a bare model
+   *  always lands there, exactly as `/model <id>` always did. */
+  resolveSelector(selector: string, currentProvider: string): ModelRef | { error: string } {
+    const s = selector.trim();
+    if (s.length === 0) return { error: "empty model selector" };
+    const i = s.indexOf("/");
+    if (i > 0) {
+      const head = s.slice(0, i);
+      const tail = s.slice(i + 1).trim();
+      if (this.get(head) !== undefined) return tail.length > 0 ? { provider: head, model: tail } : { error: `"${s}" names no model — use ${head}/<model>` };
+    }
+    return { provider: currentProvider, model: s };
+  }
+
+  add(spec: ProviderSpec, scope: FileScope = "user"): ResolvedProvider | { error: string } {
+    const { id, ...raw } = spec;
+    const v = validateSpec(id, raw);
+    if ("error" in v) return v;
+    if (this.get(id)?.scope === "env") return { error: `"custom" is reserved for the ROVECODE_BASE_URL/ROVECODE_API_KEY pair — pick another id` };
+    const path = providersPathFor(scope, this.cwd);
+    const { data } = readProvidersFile(path);
+    const { id: _id, ...rest } = v.spec;
+    data.providers = { ...(data.providers ?? {}), [id]: rest };
+    writeProvidersFile(path, data);
+    this.refresh();
+    return this.get(id)!;
+  }
+
+  remove(id: string): { removed: FileScope[] } | { error: string } {
+    const p = this.get(id);
+    if (p === undefined) return { error: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (p.scope === "builtin") return { error: `"${id}" is built in; drop its key with \`rovecode auth remove ${id}\` instead` };
+    if (p.scope === "env") return { error: `"custom" comes from ROVECODE_BASE_URL/ROVECODE_API_KEY — unset those env vars` };
+    const removed: FileScope[] = [];
+    for (const scope of ["user", "project"] as const) {
+      const path = providersPathFor(scope, this.cwd);
+      const { data } = readProvidersFile(path);
+      if (data.providers !== undefined && id in data.providers) {
+        delete data.providers[id];
+        if (Object.keys(data.providers).length === 0) delete data.providers;
+        writeProvidersFile(path, data);
+        removed.push(scope);
+      }
+    }
+    this.refresh();
+    return { removed };
+  }
+
+  setDefault(selector: string, scope: FileScope = "user"): ModelRef | { error: string } {
+    const sel = parseSelector(selector);
+    const p = this.get(sel.provider);
+    if (p === undefined) return { error: `unknown provider "${sel.provider}" — known: ${this.ids().join(" ")}` };
+    const model = sel.model ?? p.defaultModel;
+    if (model === undefined) return { error: `"${selector}" names no model and ${p.id} has no default — use ${p.id}/<model>` };
+    const path = providersPathFor(scope, this.cwd);
+    const { data } = readProvidersFile(path);
+    data.default = `${p.id}/${model}`;
+    writeProvidersFile(path, data);
+    this.refresh();
+    return { provider: p.id, model };
+  }
+
+  /** pin a provider's ACTIVE model list (the connect wizard's model step): writes `models` on the
+   *  provider's row in the scope's file — creating the row for a builtin, which is how `add` works
+   *  too. An EMPTY list removes the field: the provider goes back to asking its /models endpoint
+   *  every time (the "use them all" answer — nothing frozen). Returns the written list. */
+  setModels(id: string, models: readonly string[], scope: FileScope = "user"): { models: string[] } | { error: string } {
+    const p = this.get(id);
+    if (p === undefined) return { error: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (p.scope === "env") return { error: `"custom" comes from ROVECODE_BASE_URL/ROVECODE_API_KEY — a model list cannot be pinned on it` };
+    for (const m of models) if (m.trim().length === 0) return { error: "model ids must be non-empty strings" };
+    const path = providersPathFor(scope, this.cwd);
+    const { data } = readProvidersFile(path);
+    const rows = data.providers ?? {};
+    const existing = rows[id];
+    // a builtin with no file row yet carries its baseUrl in the spec — the new row must too
+    const row: ProviderEntry = existing ?? { baseUrl: p.baseUrl };
+    const deduped = [...new Set(models.map((m) => m.trim()))];
+    if (deduped.length === 0) {
+      delete row.models;
+    } else {
+      row.models = deduped;
+      // a pinned list that does not contain the current default silently breaks the default —
+      // keep the field only when it still names a usable model
+      if (row.defaultModel !== undefined && !deduped.includes(row.defaultModel)) delete row.defaultModel;
+    }
+    rows[id] = row;
+    data.providers = rows;
+    writeProvidersFile(path, data);
+    this.refresh();
+    return { models: deduped };
+  }
+
+  keyHint(p: ResolvedProvider): string {
+    return `no API key for provider "${p.id}" — I can't call it without one. ${next(`rovecode auth set ${p.id}`)} (masked prompt) · or /provider key ${p.id} <key> in the TUI · or set ${p.keyEnv}`;
+  }
+
+  async models(id: string): Promise<{ ok: true; models: string[]; source: "file" | "endpoint" } | { ok: false; error: string }> {
+    const p = this.get(id);
+    if (p === undefined) return { ok: false, error: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (p.models !== undefined && p.models.length > 0) return { ok: true, models: p.models, source: "file" };
+    if (!isConfigured(p)) return { ok: false, error: this.keyHint(p) };
+    const list = await fetchModels(toWireConfig(p), true);
+    return { ok: true, models: list.map((m) => m.id), source: "endpoint" };
+  }
+
+  /** One tiny real call ("ping", ≤8 output tokens): proves url + key + model together. */
+  async probe(id: string, model?: string): Promise<{ ok: boolean; model: string; detail: string }> {
+    const p = this.get(id);
+    if (p === undefined) return { ok: false, model: model ?? "", detail: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (!isConfigured(p)) return { ok: false, model: model ?? "", detail: this.keyHint(p) };
+    const m = model ?? p.defaultModel;
+    if (m === undefined) return { ok: false, model: "", detail: `${p.id} has no default model — pass one: test ${p.id} <model>` };
+    const probeMsg: Message = { id: "probe", role: "user", parts: [{ kind: "text", text: "ping" }], parentId: null, createdAt: Date.now() };
+    const t0 = Date.now();
+    let turn: AssistantTurn | undefined;
+    try {
+      for await (const ev of this.adapterFor(p)({ provider: p.id, model: m, maxTokens: 8 }, [probeMsg], { tools: [] })) if (ev.type === "turn") turn = ev.turn;
+    } catch (e) {
+      return { ok: false, model: m, detail: scrubSecret(e instanceof Error ? e.message : String(e), p.apiKey) };
+    }
+    if (turn === undefined) return { ok: false, model: m, detail: "stream produced no turn" };
+    if (turn.stopReason === "error") return { ok: false, model: m, detail: scrubSecret(turn.error ?? "stream error", p.apiKey) };
+    return { ok: true, model: m, detail: `ok in ${Date.now() - t0} ms (${turn.usage.input} in / ${turn.usage.output} out tokens)` };
+  }
+
+  /** The dispatching StreamFn (see the header). */
+  stream(): StreamFn {
+    const self = this;
+    return async function* (model: ModelRef, messages: Message[], options?: StreamOptions): AsyncGenerator<StreamEvent> {
+      const p = self.get(model.provider);
+      if (p === undefined) {
+        yield { type: "turn", turn: configErrorTurn(`provider "${model.provider}" is not configured — I can't route to it. ${next(`rovecode provider add ${model.provider} <baseUrl> [--protocol openai|anthropic]`)} (or /provider add in the TUI); known: ${self.ids().join(" ")}`) };
+        return;
+      }
+      if (!isConfigured(p)) { yield { type: "turn", turn: configErrorTurn(self.keyHint(p)) }; return; }
+      yield* self.adapterFor(p)(model, messages, options);
+    };
+  }
+
+  private adapterFor(p: ResolvedProvider): StreamFn {
+    const sse = wantsStreaming({ ROVECODE_STREAM: this.env["ROVECODE_STREAM"] }); // default ON
+    const sig = [p.baseUrl, p.protocol, p.apiKey ?? "", JSON.stringify(p.headers ?? {}), sse ? "sse" : "json"].join("\u0000");
+    const hit = this.adapters.get(p.id);
+    if (hit !== undefined && hit.sig === sig) return hit.fn;
+    const fn = this.factory(p, { sse });
+    this.adapters.set(p.id, { sig, fn });
+    return fn;
+  }
+}
+
+// ---------- shared CLI / TUI helpers ----------
+
+export const ADD_USAGE = "add <id> <baseUrl> [--protocol openai|anthropic] [--key-env NAME] [--model <id>] [--no-key] [--project]";
+
+export interface AddArgs { spec: ProviderSpec; scope: FileScope; promptKey: boolean }
+
+/** Parse `add` words (CLI argv tail or TUI slash args) into a validated spec + scope. `--key` (CLI:
+ *  prompt for the secret afterwards) is recorded, never a value. Pure; never throws. */
+export function parseAddArgs(words: readonly string[]): AddArgs | { error: string } {
+  const pos: string[] = [];
+  const raw: Record<string, unknown> = {};
+  let scope: FileScope = "user";
+  let promptKey = false;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]!;
+    const value = (): string | { error: string } => {
+      const v = words[i + 1];
+      if (v === undefined || v.startsWith("-")) return { error: `${w} needs a value — ${ADD_USAGE}` };
+      i++;
+      return v;
+    };
+    switch (w) {
+      case "--protocol": { const v = value(); if (typeof v !== "string") return v; raw["protocol"] = v; break; }
+      case "--key-env": { const v = value(); if (typeof v !== "string") return v; raw["keyEnv"] = v; break; }
+      case "--model": { const v = value(); if (typeof v !== "string") return v; raw["defaultModel"] = v; break; }
+      case "--scope": {
+        const v = value(); if (typeof v !== "string") return v;
+        if (v !== "user" && v !== "project") return { error: "--scope must be user or project" };
+        scope = v; break;
+      }
+      case "--project": scope = "project"; break;
+      case "--user": scope = "user"; break;
+      case "--no-key": raw["noKey"] = true; break;
+      case "--key": promptKey = true; break;
+      default:
+        if (w.startsWith("-")) return { error: `unknown flag ${w} — ${ADD_USAGE}` };
+        pos.push(w);
+    }
+  }
+  const [id, baseUrl] = pos;
+  if (id === undefined || baseUrl === undefined) return { error: `usage: ${ADD_USAGE}` };
+  raw["baseUrl"] = baseUrl;
+  const v = validateSpec(id, raw);
+  if ("error" in v) return v;
+  return { spec: v.spec, scope, promptKey };
+}
+
+/** One row per provider — key SOURCE only, never the value. */
+export function formatProviderLine(p: ResolvedProvider): string {
+  const key = p.keySource === "stored" ? "key: stored"
+    : p.keySource === "env" ? `key: env ${p.keyEnv}`
+    : p.keySource === "inline" ? "key: ROVECODE_API_KEY"
+    : p.noKey === true ? "key: not needed"
+    : `key: NONE (rovecode auth set ${p.id} · or set ${p.keyEnv})`;
+  return `${p.id.padEnd(12)} ${p.protocol.padEnd(9)} ${p.baseUrl.padEnd(40)} ${key}${p.defaultModel !== undefined ? `  model: ${p.defaultModel}` : ""}  [${p.scope}]`;
+}
+
+/** Listing for `rovecode provider list`, `/provider list` and the provider_list tool. Built-in providers
+ *  without a key are folded into a count unless `all` — sixteen dead rows hide the live ones. */
+export function formatProviderList(reg: ProviderRegistry, opts: { all?: boolean } = {}): string {
+  const d = reg.defaultRef();
+  const all = reg.list();
+  const rows = all.filter((p) => opts.all === true || isConfigured(p) || p.scope !== "builtin");
+  const lines = [d !== null
+    ? `default → ${d.provider}/${d.model || "(no model — pass one with /model or ROVECODE_MODEL)"}${reg.defaultSelector() !== undefined ? `  (providers.json default: ${reg.defaultSelector()})` : ""}`
+    : `default → none yet. ${next("rovecode setup")} (or rovecode provider add <id> <baseUrl>, then rovecode auth set <id>)`];
+  lines.push(...rows.map(formatProviderLine));
+  const hidden = all.length - rows.length;
+  if (hidden > 0) lines.push(`(+${hidden} built-in providers without a key — \`list --all\` shows them)`);
+  lines.push(...reg.warnings().map((w) => `warning: ${w}`));
+  return lines.join("\n");
+}

package/src/providers/responses.ts

@@ -0,0 +1,209 @@
+/** OpenAI Responses API wire (aion port #75, brought over 2026-09-07) — the second OpenAI adapter beside stream.ts's
+ *  /chat/completions pair. ADR-003 seam: ONE StreamFn, errors cross as stopReason "error" / "aborted", never a throw.
+ *  Hand-rolled fetch + SSE exactly like stream.ts (no `openai` npm dependency). providers/wire-select.ts decides per
+ *  call which of the two wires a request takes; this module never imports stream.ts at runtime (it shares sse.ts,
+ *  stream-errors.ts, usage.ts, thinking.ts, catalog.ts and wire-responses.ts with it).
+ *
+ *  Request: POST <baseUrl>/responses `{ model, instructions?, input, tools?, stream: true, store: false,
+ *  max_output_tokens?, reasoning? }`. `max_output_tokens` is max(cap, 16) — cap = model.maxTokens, the stream.ts rule
+ *  — and is OMITTED on the ChatGPT Codex backend (a URL containing chatgpt.com/backend-api; pi's codex path never
+ *  sends it), which also gets the `OpenAI-Beta: responses=experimental` + `originator: rovecode` headers.
+ *  `reasoning: { effort, summary: "auto" }` is the Responses spelling of rovecode's ONE thinking dial
+ *  (providers/thinking.ts thinkingPlan — the same dialect table stream.ts spreads as `reasoning_effort`; auto sends
+ *  nothing, a model the catalog or the dialect marks without a reasoning mode sends nothing).
+ *  NOT brought over: `include: ["reasoning.encrypted_content"]` and the reasoning item as a message part — rovecode
+ *  has no reasoning MessagePart to replay it from (wire-responses.ts header), so asking the provider for encrypted
+ *  content we would then discard is cost without product. Reasoning TEXT still streams live as reasoning_delta.
+ *  Pattern sources, MIT — earendil-works/pi packages/ai/src/api: openai-responses.ts:290-302 (store:false,
+ *  stream:true, max_output_tokens), :32-33 (the 16-token floor the API enforces), :323-332 (reasoning effort +
+ *  summary "auto"); openai-codex-responses.ts:549-556 (`instructions`), :45 + :633-639 (chatgpt.com/backend-api →
+ *  codex/responses), :1607-1609 + :1622 (chatgpt-account-id, originator, `OpenAI-Beta: responses=experimental`,
+ *  accept text/event-stream); openai-responses-shared.ts:440,:463 (output slots keyed by output_index), :597-668
+ *  (the deltas), :680-739 (output_item.done finalises a slot: message text authoritative, function_call arguments
+ *  parsed), :757-759 (a stream without a terminal event is an error), :762-792 (stop mapping), :592-594 (a tool call
+ *  overrides a completed stop), :742-755 (`<code>: <message>` for response.failed / error events).
+ *  Pattern source, Apache-2.0 at pattern level (no code copied) — openai/codex: codex-rs/codex-api/src/sse/
+ *  responses.rs:357-518 (the event set a client consumes; :843-845 fixtures pair `event:` and `data:` lines),
+ *  codex-rs/model-provider-info/src/lib.rs:40 (CHATGPT_CODEX_BASE_URL), codex-rs/core/src/client.rs:688 (an
+ *  `originator` header on every request — the value is `rovecode` here; codex's own OpenAI-Beta value is
+ *  websocket-only, so `responses=experimental` is pi's). NOTICE entry: THIRD_PARTY_NOTICES.md, `## openai/codex`.
+ *  NOT ported: `previous_response_id`, `prompt_cache_key` / `prompt_cache_retention`, `text.verbosity`,
+ *  `service_tier`, `parallel_tool_calls`, `tool_choice`, strict / grammar / custom tools, developer-role items,
+ *  the websocket and zstd transports, pi's retry loop (rovecode's withRetry + router classify the error turn as
+ *  for chat completions) and codex's error taxonomy. Selection is static — no runtime 404 → chat re-issue.
+ *
+ *  Events (`data:` payloads through sse.ts; `event:` lines are ignored — `type` names the event):
+ *  `response.output_text.delta` / `response.refusal.delta` → text_delta (and the abort-salvage buffer);
+ *  `response.reasoning_summary_text.delta` / `response.reasoning_text.delta` → reasoning_delta — NEVER into the
+ *  text buffer, never a text part (`…summary_part.done` → one "\n\n" reasoning_delta);
+ *  `response.function_call_arguments.delta` accumulates per output_index (a tool_call_delta once the slot knows
+ *  its call id and name); `response.output_item.done` finalises the slot (a reasoning item finalises to nothing);
+ *  `response.completed` → tool_use when a tool_call part exists, else end_turn; `response.incomplete` → length for
+ *  max_output_tokens, else error naming the reason; `response.failed` / `error` → error "<code>: <message>"; no
+ *  terminal event → error. Usage: `response.usage` through core/usage.ts normalizeUsage (input_tokens −
+ *  input_tokens_details.cached_tokens, cacheRead; reasoning_tokens are not carried — TokenUsage has no field for
+ *  them and normalizeUsage does not expose them). Non-2xx → httpErrorTurn (status + Retry-After for withRetry / the
+ *  router); a thrown fetch or abort → failedTurn (an aborted turn keeps the streamed text, never a tool_call
+ *  fragment). No header, token or account id ever reaches an error text or an event (oauth/common.ts hygiene rule). */
+
+import type { AssistantTurn, Message, MessagePart, ModelRef, StopReason, StreamEvent, StreamFn, StreamOptions, TokenUsage } from "../core/types.ts";
+import { normalizeUsage } from "../core/usage.ts";
+import { supportsImages } from "./catalog.ts";
+import { sseLines } from "./sse.ts";
+import { failedTurn, fetchFirstByte, httpErrorTurn } from "./stream-errors.ts";
+import { thinkingPlan } from "./thinking.ts";
+import { toResponsesInput, toResponsesTools } from "./wire-responses.ts";
+
+/** the same opts as openaiCompatStreaming — oauth/seam.ts MakeStream is unchanged */
+export interface ResponsesAdapterOptions { baseUrl: string; apiKey: string; headers?: Record<string, string> }
+
+/** the API rejects max_output_tokens below 16 (pi openai-responses.ts:32-33) */
+export const RESPONSES_MIN_OUTPUT_TOKENS = 16;
+/** the ChatGPT Codex backend: no max_output_tokens, plus the two headers below (pi openai-codex-responses.ts) */
+export const CODEX_BACKEND = /chatgpt\.com\/backend-api/;
+export const CODEX_HEADERS: Readonly<Record<string, string>> = { "OpenAI-Beta": "responses=experimental", originator: "rovecode" };
+export const NO_TERMINAL_EVENT = "OpenAI Responses stream ended before a terminal response event";
+
+export interface ResponsesRequest { url: string; headers: Record<string, string>; body: Record<string, unknown> }
+
+/** the Responses spelling of the thinking dial: the word the OpenAI-compatible dialect would put in `reasoning_effort`
+ *  (or OpenRouter's `reasoning.effort`) becomes `reasoning: { effort, summary: "auto" }`; nothing when the dial sends
+ *  nothing (auto, a model without a reasoning mode, the catalog's `reasoning: false` stamp) */
+export function responsesReasoning(model: ModelRef): { reasoning?: { effort: string; summary: "auto" } } {
+  const fields = thinkingPlan(model, "openai").fields;
+  const nested = fields.reasoning as { effort?: unknown } | undefined;
+  const word = typeof fields.reasoning_effort === "string" ? fields.reasoning_effort : typeof nested?.effort === "string" ? nested.effort : undefined;
+  return word === undefined ? {} : { reasoning: { effort: word, summary: "auto" } };
+}
+
+/** URL, headers and body for one call (header rules); exported so the request shape is testable without fetch */
+export function responsesRequest(opts: ResponsesAdapterOptions, model: ModelRef, messages: Message[], options?: StreamOptions): ResponsesRequest {
+  const url = opts.baseUrl.replace(/\/$/, "") + "/responses";
+  const codex = CODEX_BACKEND.test(url);
+  const { instructions, input } = toResponsesInput(messages, { vision: supportsImages(model) !== false, model }); // port #34 vision gate (stream.ts wireOptions rule)
+  const cap = model.maxTokens;
+  const body: Record<string, unknown> = {
+    model: model.model,
+    ...(instructions !== undefined ? { instructions } : {}),
+    input,
+    ...(options?.tools?.length ? { tools: toResponsesTools(options.tools) } : {}),
+    stream: true,
+    store: false,
+    ...(cap && !codex ? { max_output_tokens: Math.max(cap, RESPONSES_MIN_OUTPUT_TOKENS) } : {}),
+    ...responsesReasoning(model),
+  };
+  const headers: Record<string, string> = { "content-type": "application/json", accept: "text/event-stream", ...(codex ? CODEX_HEADERS : {}), ...opts.headers, authorization: `Bearer ${opts.apiKey}` };
+  return { url, headers, body };
+}
+
+// ---------- SSE state ----------
+
+type Slot = { kind: "message"; text: string } | { kind: "function_call"; callId: string; name: string; args: string } | { kind: "reasoning" };
+interface Item { type?: string; id?: string; call_id?: string; name?: string; arguments?: string; content?: { type?: string; text?: string; refusal?: string }[]; summary?: { text?: string }[] }
+interface Event {
+  type?: string; output_index?: number; delta?: string; arguments?: string; item?: Item; code?: string; message?: string;
+  response?: { usage?: unknown; incomplete_details?: { reason?: string } | null; error?: { code?: string; message?: string } | null };
+}
+
+function newSlot(item: Item | undefined): Slot | undefined {
+  if (item?.type === "message") return { kind: "message", text: "" };
+  if (item?.type === "function_call") return { kind: "function_call", callId: item.call_id ?? "", name: item.name ?? "", args: item.arguments ?? "" };
+  if (item?.type === "reasoning") return { kind: "reasoning" };
+  return undefined;
+}
+
+/** the part an `output_item.done` item finalises to (pi shared.ts:680-739); undefined for an empty message and for a
+ *  reasoning item (no reasoning MessagePart here — header) */
+function finishedPart(item: Item, slot: Slot | undefined, index: number): MessagePart | undefined {
+  if (item.type === "message") {
+    const text = item.content ? item.content.map((c) => (c.type === "refusal" ? c.refusal ?? "" : c.text ?? "")).join("") : slot?.kind === "message" ? slot.text : "";
+    return text ? { kind: "text", text } : undefined;
+  }
+  if (item.type === "function_call") {
+    const fc = slot?.kind === "function_call" ? slot : undefined;
+    const raw = item.arguments ?? fc?.args ?? "";
+    let args: unknown = {};
+    try { args = JSON.parse(raw || "{}"); } catch { args = { _raw: raw }; }
+    return { kind: "tool_call", id: item.call_id || fc?.callId || item.id || `fc${index}`, tool: item.name || fc?.name || "unknown", args };
+  }
+  return undefined;
+}
+
+/** the same normalization the stream.ts adapters apply (cached share subtracted, zero fields dropped) */
+function turnUsage(raw: unknown): TokenUsage {
+  const u = normalizeUsage(raw);
+  return { input: u.input, output: u.output, cacheRead: u.cacheRead || undefined, cacheWrite: u.cacheWrite || undefined };
+}
+
+// ---------- the adapter ----------
+
+export function openaiResponsesStream(opts: ResponsesAdapterOptions): StreamFn {
+  return async function* (model: ModelRef, messages: Message[], options?: StreamOptions): AsyncGenerator<StreamEvent> {
+    let turn: AssistantTurn;
+    let buffer = ""; // text deltas only — the abort salvage (failedTurn); reasoning deltas never land here
+    try {
+      const req = responsesRequest(opts, model, messages, options);
+      const res = await fetchFirstByte(req.url, { method: "POST", headers: req.headers, body: JSON.stringify(req.body), signal: options?.signal });
+      if (!res.ok || !res.body) {
+        yield { type: "turn", turn: await httpErrorTurn(res) }; // status + Retry-After recorded for withRetry (stream-errors.ts)
+        return;
+      }
+      const slots = new Map<number, Slot>();
+      const parts = new Map<number, MessagePart>();
+      let usage: TokenUsage = { input: 0, output: 0 };
+      let terminal: { stop: StopReason; error?: string } | undefined;
+      for await (const line of sseLines(res.body)) {
+        const ev = JSON.parse(line) as Event;
+        const idx = ev.output_index ?? 0;
+        switch (ev.type) {
+          case "response.output_item.added": { const s = newSlot(ev.item); if (s) slots.set(idx, s); break; }
+          case "response.output_text.delta":
+          case "response.refusal.delta": {
+            if (!ev.delta) break;
+            const s: Slot = slots.get(idx) ?? { kind: "message", text: "" };
+            if (s.kind === "message") { s.text += ev.delta; slots.set(idx, s); }
+            buffer += ev.delta;
+            yield { type: "text_delta", text: ev.delta };
+            break;
+          }
+          case "response.reasoning_summary_text.delta":
+          case "response.reasoning_text.delta": if (ev.delta) yield { type: "reasoning_delta", text: ev.delta }; break;
+          case "response.reasoning_summary_part.done": yield { type: "reasoning_delta", text: "\n\n" }; break;
+          case "response.function_call_arguments.delta": {
+            if (!ev.delta) break;
+            const s: Slot = slots.get(idx) ?? { kind: "function_call", callId: "", name: "", args: "" };
+            if (s.kind !== "function_call") break;
+            s.args += ev.delta;
+            slots.set(idx, s);
+            if (s.callId && s.name) yield { type: "tool_call_delta", id: s.callId, tool: s.name, argsDelta: ev.delta };
+            break;
+          }
+          case "response.function_call_arguments.done": { const s = slots.get(idx); if (s?.kind === "function_call" && typeof ev.arguments === "string") s.args = ev.arguments; break; }
+          case "response.output_item.done": {
+            if (ev.item) { const p = finishedPart(ev.item, slots.get(idx), idx); if (p) parts.set(idx, p); }
+            slots.delete(idx);
+            break;
+          }
+          case "response.completed":
+          case "response.incomplete": {
+            if (ev.response?.usage) usage = turnUsage(ev.response.usage);
+            const reason = ev.response?.incomplete_details?.reason;
+            terminal = ev.type === "response.completed" ? { stop: "end_turn" } : reason === "max_output_tokens" ? { stop: "length" } : { stop: "error", error: `Response incomplete: ${reason ?? "no reason given"}` };
+            break;
+          }
+          case "response.failed": { const e = ev.response?.error; terminal = { stop: "error", error: `${e?.code || "unknown"}: ${e?.message || "no message"}` }; break; }
+          case "error": terminal = { stop: "error", error: `${ev.code || "unknown"}: ${ev.message || "no message"}` }; break;
+          default: break; // response.created / in_progress / content_part.* / *_part.added / *.done text echoes: nothing to do
+        }
+      }
+      if (!terminal) terminal = { stop: "error", error: NO_TERMINAL_EVENT }; // pi shared.ts:757-759 — never end_turn
+      const ordered = [...parts].sort((a, b) => a[0] - b[0]).map(([, p]) => p);
+      turn = terminal.stop === "error"
+        ? { parts: [], stopReason: "error", usage, error: terminal.error }
+        : { parts: ordered, stopReason: terminal.stop === "end_turn" && ordered.some((p) => p.kind === "tool_call") ? "tool_use" : terminal.stop, usage };
+    } catch (e) {
+      turn = failedTurn(e, options?.signal, buffer); // mid-stream abort: the text already streamed survives, tool fragments do not
+    }
+    yield { type: "turn", turn };
+  };
+}