@visual-z/xeno 0.1.0

package/src/runtime/openai-responses.ts

@@ -0,0 +1,286 @@
+/**
+ * OpenAI Responses API -- the second place, beside openai.ts, that knows an
+ * OpenAI wire format.
+ *
+ * It exists for one reason: reasoning that survives a turn. Chat Completions
+ * returns no reasoning for OpenAI's models, so every request starts the
+ * model's thinking from nothing; OpenAI measured the difference at 73.9% to
+ * 78.2% on Tau-Bench Retail (GPT-5 prompting guide). Responses returns each
+ * reasoning item with `encrypted_content` when `store` is false, and accepts
+ * it back unchanged.
+ *
+ * Stateless on purpose. `previous_response_id` would keep the conversation on
+ * OpenAI's servers -- a second truth beside the log that no projection could
+ * recompute. Instead the whole reasoning item goes into the thinking block's
+ * opaque raw, and the projection replays it like any other block.
+ *
+ * Event handling follows pi-mono `packages/ai/src/api/openai-responses-shared.ts`
+ * (MIT, 6f75515); the transport and SSE framing are this project's own.
+ */
+import type { AssistantBlock } from "../core/events.ts";
+import type { ContentBlock, FrozenPrefix, Message } from "../core/project.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import type { OnDelta, Provider, ProviderConfig, ToolSchema, Turn } from "./provider.ts";
+import { pushSse, HttpError, StreamError } from "./openai.ts";
+import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
+
+/** What this adapter parks in a thinking block's raw: the reasoning item, whole. */
+interface ResponsesRaw { responses_item: Record<string, unknown> }
+
+function responsesItemOf(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const item = (raw as Partial<ResponsesRaw>).responses_item;
+  return typeof item === "object" && item !== null ? item : null;
+}
+
+type InputItem = Record<string, unknown>;
+
+function inputItems(messages: readonly Message[]): InputItem[] {
+  const out: InputItem[] = [];
+  for (const message of messages) {
+    if (message.role === "assistant") {
+      const text: string[] = [];
+      const flushText = () => {
+        if (text.length === 0) return;
+        out.push({ type: "message", role: "assistant", content: [{ type: "output_text", text: text.join("") }] });
+        text.length = 0;
+      };
+      for (const block of message.content) {
+        switch (block.type) {
+          case "thinking": {
+            // Another adapter's raw (a Completions reasoning string) is not a
+            // Responses item and cannot be sent as one; a model switch cuts,
+            // so this is the rare replay of a mixed log, not the common path.
+            const item = responsesItemOf(block.raw);
+            if (item !== null) { flushText(); out.push(item); }
+            break;
+          }
+          case "text":
+            text.push(block.text);
+            break;
+          case "tool_use": {
+            flushText();
+            const wire = typeof block.wire === "object" && block.wire !== null ? block.wire as Record<string, unknown> : {};
+            out.push({
+              type: "function_call",
+              ...(typeof wire["item_id"] === "string" ? { id: wire["item_id"] } : {}),
+              call_id: block.id, name: block.name, arguments: JSON.stringify(block.input),
+            });
+            break;
+          }
+          case "tool_result":
+            break;
+          default:
+            return assertNever(block, "responses assistant input");
+        }
+      }
+      flushText();
+    } else {
+      const text: string[] = [];
+      for (const block of message.content as readonly ContentBlock[]) {
+        if (block.type === "text") text.push(block.text);
+        else if (block.type === "tool_result") {
+          out.push({ type: "function_call_output", call_id: block.tool_use_id,
+            output: block.is_error ? `[error] ${block.content}` : block.content });
+        }
+      }
+      if (text.length > 0) out.push({ type: "message", role: "user", content: [{ type: "input_text", text: text.join("\n") }] });
+    }
+  }
+  return out;
+}
+
+function responsesTools(tools: readonly unknown[]): unknown[] {
+  return (tools as ToolSchema[]).map((tool) => ({
+    type: "function", name: tool.name, description: tool.description, parameters: tool.input_schema,
+  }));
+}
+
+export function buildResponsesRequest(config: ProviderConfig, frozen: FrozenPrefix, messages: readonly Message[]): Record<string, unknown> {
+  const spec = config.spec;
+  const request: Record<string, unknown> = {
+    model: spec.id,
+    instructions: frozen.system,
+    input: inputItems(messages),
+    store: false,
+    max_output_tokens: config.maxTokens,
+  };
+  if (frozen.tools.length > 0) request["tools"] = responsesTools(frozen.tools);
+  if (spec.reasoning) {
+    // Accepted but no longer required by current models; older ones need it.
+    request["include"] = ["reasoning.encrypted_content"];
+    const mapped = spec.thinkingLevelMap?.[config.effort];
+    if (mapped !== null) request["reasoning"] = { effort: mapped ?? config.effort, summary: "auto" };
+  }
+  return request;
+}
+
+interface Slot { kind: "thinking" | "text" | "call"; text: string; item?: Record<string, unknown> }
+
+interface ResponseEnvelope {
+  status?: string;
+  incomplete_details?: { reason?: string } | null;
+  error?: { code?: string; message?: string } | null;
+  usage?: {
+    input_tokens?: number; output_tokens?: number;
+    input_tokens_details?: { cached_tokens?: number };
+  };
+}
+
+function stopReasonOf(response: ResponseEnvelope, hasCalls: boolean): string | null {
+  switch (response.status) {
+    case "completed": return hasCalls ? "tool_use" : "end_turn";
+    // The loop's recovery keys on max_tokens; any other reason is not a
+    // completion and must not execute tools from the partial response.
+    case "incomplete": return response.incomplete_details?.reason === "max_output_tokens" ? "max_tokens" : `incomplete:${response.incomplete_details?.reason ?? "unknown"}`;
+    default: return response.status ?? null;
+  }
+}
+
+function decodeArguments(raw: string): unknown {
+  if (raw.length === 0) return {};
+  try { return JSON.parse(raw); } catch { return { __unparsed_arguments: raw }; }
+}
+
+async function readResponsesSse(body: ReadableStream<Uint8Array>, node: number, started: number, onDelta?: OnDelta): Promise<Turn> {
+  const slots = new Map<number, Slot>();
+  let final: ResponseEnvelope | undefined;
+  const handle = (event: Record<string, unknown>) => {
+    const index = typeof event["output_index"] === "number" ? event["output_index"] : -1;
+    const item = event["item"] as Record<string, unknown> | undefined;
+    switch (event["type"]) {
+      case "response.output_item.added": {
+        const kind = item?.["type"] === "reasoning" ? "thinking" : item?.["type"] === "function_call" ? "call" : item?.["type"] === "message" ? "text" : null;
+        if (kind !== null) slots.set(index, { kind, text: "", ...(item ? { item } : {}) });
+        return;
+      }
+      case "response.reasoning_summary_text.delta":
+      case "response.reasoning_text.delta":
+      case "response.output_text.delta":
+      case "response.refusal.delta":
+      case "response.function_call_arguments.delta": {
+        const slot = slots.get(index);
+        const delta = typeof event["delta"] === "string" ? event["delta"] : "";
+        if (slot === undefined || delta.length === 0) return;
+        slot.text += delta;
+        if (slot.kind === "thinking") onDelta?.({ kind: "thinking", text: delta });
+        else if (slot.kind === "text") onDelta?.({ kind: "text", text: delta });
+        return;
+      }
+      case "response.output_item.done": {
+        if (item === undefined) return;
+        const slot = slots.get(index) ?? { kind: item["type"] === "reasoning" ? "thinking" : item["type"] === "function_call" ? "call" : "text", text: "" } as Slot;
+        slot.item = item;
+        if (item["type"] === "function_call" && typeof item["arguments"] === "string") slot.text = item["arguments"];
+        if (item["type"] === "message" && Array.isArray(item["content"])) {
+          const parts = (item["content"] as Record<string, unknown>[]).map((c) => typeof c["text"] === "string" ? c["text"] : typeof c["refusal"] === "string" ? c["refusal"] : "");
+          if (parts.join("").length > 0) slot.text = parts.join("");
+        }
+        slots.set(index, slot);
+        return;
+      }
+      case "response.completed":
+      case "response.incomplete":
+        final = event["response"] as ResponseEnvelope;
+        return;
+      case "response.failed": {
+        const response = event["response"] as ResponseEnvelope | undefined;
+        const error = response?.error;
+        throw new StreamError(error ? `${error.code ?? "error"}: ${error.message ?? "no message"}` : "response failed without details", error?.code);
+      }
+      case "error":
+        throw new StreamError(`stream error: ${String(event["message"] ?? event["code"] ?? "unknown")}`,
+          typeof event["code"] === "string" ? event["code"] : undefined);
+      default:
+        return;
+    }
+  };
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      const pushed = pushSse(buffer, decoder.decode(value ?? new Uint8Array(), { stream: !done }));
+      buffer = pushed.buffer;
+      for (const payload of pushed.payloads) if (payload.length > 0 && payload !== "[DONE]") handle(JSON.parse(payload));
+      if (done) break;
+    }
+    for (const payload of pushSse(buffer, "\n").payloads) if (payload.length > 0 && payload !== "[DONE]") handle(JSON.parse(payload));
+  } finally { reader.releaseLock(); }
+  if (final === undefined) throw new Error("responses stream ended before a terminal response event");
+
+  const blocks: AssistantBlock[] = [];
+  for (const [, slot] of [...slots.entries()].sort(([a], [b]) => a - b)) {
+    if (slot.kind === "thinking" && slot.item !== undefined) {
+      const summary = Array.isArray(slot.item["summary"])
+        ? (slot.item["summary"] as Record<string, unknown>[]).map((s) => String(s["text"] ?? "")).join("\n\n") : "";
+      blocks.push({ type: "thinking", text: summary || slot.text, raw: { responses_item: slot.item } satisfies ResponsesRaw });
+    } else if (slot.kind === "text" && slot.text.length > 0) {
+      blocks.push({ type: "text", text: slot.text });
+    } else if (slot.kind === "call" && slot.item !== undefined) {
+      const callId = typeof slot.item["call_id"] === "string" ? slot.item["call_id"] : `call_${blocks.length}`;
+      blocks.push({ type: "tool_use", call_id: callId, name: String(slot.item["name"] ?? ""), input: decodeArguments(slot.text),
+        ...(typeof slot.item["id"] === "string" ? { wire: { item_id: slot.item["id"] } } : {}) });
+    }
+  }
+  const usage = final.usage;
+  const cached = usage?.input_tokens_details?.cached_tokens ?? 0;
+  return {
+    blocks,
+    stopReason: stopReasonOf(final, blocks.some((block) => block.type === "tool_use")),
+    usage: {
+      // input_tokens includes the cached part; the uncached remainder is the difference.
+      input_tokens: Math.max(0, (usage?.input_tokens ?? 0) - cached),
+      output_tokens: usage?.output_tokens ?? 0,
+      cache_creation_input_tokens: 0,
+      cache_read_input_tokens: cached,
+      node, ms: Date.now() - started,
+    },
+  };
+}
+
+export class OpenAIResponsesProvider implements Provider {
+  readonly config: ProviderConfig;
+  private readonly apiKey: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly retry: RetryPolicy;
+  private readonly onRetry: ((attempt: number, delayMs: number, error: unknown) => void) | undefined;
+
+  constructor(config: ProviderConfig, apiKey: string, options: {
+    fetchImpl?: typeof fetch; retry?: RetryPolicy; onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
+  } = {}) {
+    this.config = config;
+    this.apiKey = apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.retry = options.retry ?? DEFAULT_RETRY;
+    this.onRetry = options.onRetry;
+  }
+
+  send(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta): Promise<Turn> {
+    return withRetry(() => this.attempt(frozen, messages, node, signal, onDelta), this.retry, undefined,
+      (attempt, delayMs, error) => { onDelta?.({ kind: "discard" }); this.onRetry?.(attempt, delayMs, error); }, signal);
+  }
+
+  private async attempt(frozen: FrozenPrefix, messages: readonly Message[], node: number, signal?: AbortSignal, onDelta?: OnDelta): Promise<Turn> {
+    const started = Date.now();
+    const baseUrl = this.config.spec.baseUrl;
+    if (baseUrl === undefined) throw new Error(`model ${this.config.spec.id} has no baseUrl to send to`);
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${this.apiKey}` },
+      body: JSON.stringify({ ...buildResponsesRequest(this.config, frozen, messages), stream: true }),
+    };
+    if (signal !== undefined) init.signal = signal;
+    const response = await this.fetchImpl(`${baseUrl.replace(/\/$/, "")}/responses`, init);
+    if (!response.ok) {
+      const text = await response.text();
+      let detail = text.slice(0, 200);
+      try { const parsed = JSON.parse(text) as { error?: { message?: string } }; if (parsed.error?.message) detail = parsed.error.message; } catch { /* raw body */ }
+      throw new HttpError(response.status, response.headers, `HTTP ${response.status}: ${detail}`);
+    }
+    if (response.body === null) throw new Error(`${baseUrl} returned a streaming 200 with no body`);
+    return readResponsesSse(response.body, node, started, onDelta);
+  }
+}