@ar-ai/brink-cli 0.0.0-stage → 1.0.6

package/support/chat-bridge.js

@@ -0,0 +1,1093 @@
+"use strict";
+
+const { randomUUID, createHash } = require("crypto");
+const { failure, writeChunk, sseEvents, decodedStream } = require("./bridge-stream");
+const { cleanHeaders, requestWithRetries, upstreamFailure } = require("./transport");
+const { observeActivity } = require("./activity");
+
+const UPSTREAM = new URL("https://agentrouter.org/v1/chat/completions");
+
+
+function invalid(message) {
+  throw failure(message, 400, "invalid_request_error");
+}
+
+function identifier(prefix) {
+  return `${prefix}_${randomUUID().replace(/-/g, "")}`;
+}
+
+function convertContent(content, context) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content))
+    invalid(`${context} must contain text or a content array`);
+  const parts = content.map((part) => {
+    if (!part || typeof part !== "object")
+      invalid(`Invalid content in ${context}`);
+    if (["input_text", "output_text", "text"].includes(part.type)) {
+      if (typeof part.text !== "string")
+        invalid(`Non-string text in ${context}`);
+      return { type: "text", text: part.text };
+    }
+    if (part.type === "refusal" && typeof part.refusal === "string") {
+      return { type: "text", text: part.refusal };
+    }
+    if (part.type === "input_image" || part.type === "image_url") {
+      const source = part.image_url;
+      const url = typeof source === "string" ? source : source && source.url;
+      if (typeof url !== "string" || !url)
+        invalid(
+          `Images in ${context} require image_url; file IDs cannot be resolved by the Chat bridge`,
+        );
+      const image_url = { url };
+      const detail = part.detail || (source && source.detail);
+      if (detail) image_url.detail = detail;
+      return { type: "image_url", image_url };
+    }
+    invalid(`Unsupported ${context} content type: ${part.type || "unknown"}`);
+  });
+  return parts.every((part) => part.type === "text")
+    ? parts.map((part) => part.text).join("")
+    : parts;
+}
+
+function buildRequest(payload, tracker) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    invalid("Expected a Responses request object");
+  if (typeof payload.model !== "string" || !payload.model)
+    invalid("model is required");
+  if (payload.previous_response_id || payload.conversation)
+    invalid(
+      "The Chat bridge requires full input history; previous_response_id and conversation are not supported",
+    );
+  if (payload.background)
+    invalid("Background Responses are not supported by the Chat bridge");
+  const byKey = new Map();
+  const byWireName = new Map();
+  const tools = [];
+  const keyFor = (name, namespace) => `${namespace || ""}\0${name}`;
+
+  function register(name, namespace, kind, definition, namespaceDescription) {
+    if (typeof name !== "string" || !name)
+      invalid("Every tool requires a name");
+    if (namespace != null && (typeof namespace !== "string" || !namespace))
+      invalid("Invalid tool namespace");
+    const key = keyFor(name, namespace);
+    const existing = byKey.get(key);
+    if (existing) {
+      if (existing.kind !== kind) invalid(`Conflicting tool types for ${name}`);
+      if (definition && existing.definition)
+        invalid(`Duplicate tool definition: ${name}`);
+      return existing;
+    }
+    const qualified = namespace ? `${namespace}.${name}` : name;
+    let wireName = qualified;
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(wireName) || byWireName.has(wireName)) {
+      wireName = `${qualified.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40)}_${createHash("sha256").update(key).digest("hex").slice(0, 20)}`;
+    }
+    if (byWireName.has(wireName)) invalid(`Tool name collision: ${qualified}`);
+    const descriptor = { name, namespace, kind, wireName, definition };
+    byKey.set(key, descriptor);
+    byWireName.set(wireName, descriptor);
+    if (definition) {
+      const fn = { name: wireName };
+      const descriptions = [
+        namespaceDescription,
+        definition.description,
+      ].filter((value) => typeof value === "string" && value);
+      if (kind === "custom") {
+        descriptions.push(
+          "This is a freeform tool. Supply its entire raw input as the single string property input, without JSON-encoding that string a second time.",
+        );
+        if (definition.format && definition.format.type !== "text")
+          descriptions.push(
+            `Required freeform input format: ${JSON.stringify(definition.format)}`,
+          );
+        fn.parameters = {
+          type: "object",
+          properties: {
+            input: {
+              type: "string",
+              description: "The complete raw freeform tool input.",
+            },
+          },
+          required: ["input"],
+          additionalProperties: false,
+        };
+        fn.strict = true;
+      } else {
+        fn.parameters = definition.parameters || {
+          type: "object",
+          properties: {},
+        };
+        if (definition.strict != null) fn.strict = definition.strict;
+      }
+      if (descriptions.length) fn.description = descriptions.join("\n\n");
+      tools.push({ type: "function", function: fn });
+    }
+    return descriptor;
+  }
+
+  function addTool(tool, namespace, description) {
+    if (!tool || typeof tool !== "object") invalid("Invalid tool definition");
+    if (tool.type === "web_search" || tool.type === "web_search_preview") {
+      tracker?.note(
+        "warn",
+        "Claude Chat bridge omits the unsupported hosted web-search tool advertisement",
+      );
+      return;
+    }
+    if (tool.type === "namespace") {
+      if (namespace) invalid("Nested tool namespaces are not supported");
+      if (
+        typeof tool.name !== "string" ||
+        !tool.name ||
+        !Array.isArray(tool.tools)
+      )
+        invalid("Invalid namespace tool definition");
+      for (const child of tool.tools)
+        addTool(child, tool.name, tool.description);
+      return;
+    }
+    if (!["function", "custom", "freeform"].includes(tool.type))
+      invalid(
+        `Unsupported Chat bridge tool type: ${tool.type || "unknown"}. Use a function or custom tool instead of hosted Responses tools.`,
+      );
+    const definition =
+      tool.type === "function" && tool.function ? tool.function : tool;
+    register(
+      definition.name,
+      namespace || definition.namespace,
+      tool.type === "function" ? "function" : "custom",
+      definition,
+      description,
+    );
+  }
+  if (payload.tools != null && !Array.isArray(payload.tools))
+    invalid("tools must be an array");
+  for (const tool of payload.tools || []) addTool(tool);
+
+  function lookup(name, namespace, kind, replay = false) {
+    let found = byKey.get(keyFor(name, namespace));
+    if (!found && !namespace) {
+      const matches = [...byKey.values()].filter(
+        (entry) =>
+          entry.name === name ||
+          (entry.namespace && `${entry.namespace}.${entry.name}` === name),
+      );
+      if (matches.length === 1) found = matches[0];
+    }
+    if (found && kind && found.kind !== kind)
+      invalid(`Tool call type does not match definition: ${name}`);
+    if (found) return found;
+    if (replay) return register(name, namespace, kind);
+    invalid(
+      `Unknown tool in tool_choice: ${namespace ? `${namespace}.` : ""}${name}`,
+    );
+  }
+
+  const messages = [];
+  const seenCalls = new Set();
+  const answeredCalls = new Set();
+  let pendingImages = [];
+  function flushImages() {
+    if (pendingImages.length)
+      messages.push({ role: "user", content: pendingImages });
+    pendingImages = [];
+  }
+  function appendInput(input, instruction = false) {
+    if (typeof input === "string") {
+      flushImages();
+      messages.push({ role: instruction ? "system" : "user", content: input });
+      return;
+    }
+    const items = Array.isArray(input) ? input : [input];
+    for (const item of items) {
+      if (!item || typeof item !== "object")
+        invalid("Invalid Responses input item");
+      // Opaque backend reasoning is never converted into visible messages.
+      if (item.type === "reasoning") continue;
+      const output =
+        item.type === "function_call_output" ||
+        item.type === "custom_tool_call_output" ||
+        item.type === "freeform_call_output";
+      if (!output) flushImages();
+      if (item.type === "message" || (!item.type && item.role)) {
+        if (!["system", "developer", "user", "assistant"].includes(item.role))
+          invalid(`Unsupported message role: ${item.role}`);
+        const role = item.role === "developer" ? "system" : item.role;
+        if (instruction && role !== "system")
+          invalid(
+            "instructions must contain only system or developer messages",
+          );
+        messages.push({
+          role,
+          content: convertContent(item.content, `${item.role} message`),
+        });
+      } else if (
+        ["function_call", "custom_tool_call", "freeform_call"].includes(
+          item.type,
+        )
+      ) {
+        if (instruction) invalid("Tool calls are not valid instructions");
+        const kind = item.type === "function_call" ? "function" : "custom";
+        const descriptor = lookup(item.name, item.namespace, kind, true);
+        if (
+          typeof item.call_id !== "string" ||
+          !item.call_id ||
+          seenCalls.has(item.call_id)
+        )
+          invalid("Tool calls require unique call_id values");
+        seenCalls.add(item.call_id);
+        const argument = kind === "custom" ? item.input : item.arguments;
+        if (typeof argument !== "string")
+          invalid(
+            `Tool ${item.name} requires string ${kind === "custom" ? "input" : "arguments"}`,
+          );
+        const call = {
+          id: item.call_id,
+          type: "function",
+          function: {
+            name: descriptor.wireName,
+            arguments:
+              kind === "custom"
+                ? JSON.stringify({ input: argument })
+                : argument,
+          },
+        };
+        let assistant = messages[messages.length - 1];
+        if (!assistant || assistant.role !== "assistant") {
+          assistant = { role: "assistant", content: null };
+          messages.push(assistant);
+        }
+        (assistant.tool_calls ||= []).push(call);
+      } else if (output) {
+        if (instruction) invalid("Tool outputs are not valid instructions");
+        if (!seenCalls.has(item.call_id) || answeredCalls.has(item.call_id))
+          invalid(
+            `Tool output ${item.call_id || "(missing call_id)"} requires its preceding tool call in input history`,
+          );
+        answeredCalls.add(item.call_id);
+        const content = convertContent(item.output, "tool output");
+        if (typeof content === "string") {
+          messages.push({ role: "tool", tool_call_id: item.call_id, content });
+        } else {
+          // Chat tool messages permit text only. Lift images into a labelled
+          // user message after all adjacent tool replies, keeping call linkage.
+          const text = [];
+          for (const part of content) {
+            if (part.type === "text") text.push(part.text);
+            else {
+              const label = `[Image returned by tool call ${item.call_id}]`;
+              text.push(label);
+              pendingImages.push({ type: "text", text: label }, part);
+            }
+          }
+          messages.push({
+            role: "tool",
+            tool_call_id: item.call_id,
+            content: text.join(""),
+          });
+        }
+      } else {
+        invalid(`Unsupported Responses input item: ${item.type || "unknown"}`);
+      }
+    }
+  }
+  if (payload.instructions != null) appendInput(payload.instructions, true);
+  if (payload.input != null) appendInput(payload.input);
+  flushImages();
+  if (!messages.length) invalid("input or instructions must contain a message");
+  const request = {
+    model: payload.model,
+    messages,
+    stream: payload.stream === true,
+  };
+  if (request.stream) request.stream_options = { include_usage: true };
+  for (const key of [
+    "temperature",
+    "top_p",
+    "parallel_tool_calls",
+    "user",
+    "seed",
+    "frequency_penalty",
+    "presence_penalty",
+    "stop",
+  ]) {
+    if (payload[key] != null) request[key] = payload[key];
+  }
+  if (payload.max_output_tokens != null)
+    request.max_tokens = payload.max_output_tokens;
+  if (tools.length) request.tools = tools;
+  const choice = payload.tool_choice;
+  if (typeof choice === "string") {
+    if (!["auto", "none", "required"].includes(choice))
+      invalid(`Unsupported tool_choice: ${choice}`);
+    if (tools.length || choice !== "auto") request.tool_choice = choice;
+  } else if (choice != null) {
+    if (choice.type === "allowed_tools") {
+      if (
+        !Array.isArray(choice.tools) ||
+        !["auto", "required"].includes(choice.mode)
+      )
+        invalid("Invalid allowed_tools choice");
+      const allowed = new Set(
+        choice.tools.map(
+          (entry) =>
+            lookup(
+              entry.name,
+              entry.namespace,
+              entry.type === "custom" || entry.type === "freeform"
+                ? "custom"
+                : "function",
+            ).wireName,
+        ),
+      );
+      request.tools = tools.filter((tool) => allowed.has(tool.function.name));
+      if (!request.tools.length)
+        invalid("allowed_tools must select at least one available tool");
+      request.tool_choice = choice.mode;
+    } else if (["function", "custom", "freeform"].includes(choice.type)) {
+      const selected = lookup(
+        choice.name || (choice.function && choice.function.name),
+        choice.namespace,
+        choice.type === "function" ? "function" : "custom",
+      );
+      request.tool_choice = {
+        type: "function",
+        function: { name: selected.wireName },
+      };
+    } else invalid(`Unsupported tool_choice type: ${choice.type}`);
+  }
+  const format = payload.text && payload.text.format;
+  if (format && format.type !== "text") {
+    if (format.type === "json_object")
+      request.response_format = { type: "json_object" };
+    else if (format.type === "json_schema") {
+      const json_schema = { name: format.name, schema: format.schema };
+      if (format.description != null)
+        json_schema.description = format.description;
+      if (format.strict != null) json_schema.strict = format.strict;
+      request.response_format = { type: "json_schema", json_schema };
+    } else invalid(`Unsupported text format: ${format.type}`);
+  }
+  return { request, byWireName };
+}
+
+// Decode the one-property custom-tool envelope incrementally, including JSON
+// escapes split between arbitrary Chat argument fragments.
+class CustomInputDecoder {
+  constructor() {
+    this.prefix = "";
+    this.started = false;
+    this.closed = false;
+    this.escape = false;
+    this.unicode = null;
+    this.trailing = "";
+    this.pendingSurrogate = "";
+    this.value = "";
+  }
+
+  feed(fragment) {
+    let cursor = 0;
+    if (!this.started) {
+      this.prefix += fragment;
+      const match = /^\s*\{\s*"input"\s*:\s*"/.exec(this.prefix);
+      if (!match) return "";
+      fragment = this.prefix.slice(match[0].length);
+      this.prefix = "";
+      this.started = true;
+    }
+    let delta = this.pendingSurrogate;
+    this.pendingSurrogate = "";
+    for (; cursor < fragment.length; cursor++) {
+      const char = fragment[cursor];
+      if (this.closed) {
+        this.trailing += fragment.slice(cursor);
+        break;
+      }
+      if (this.unicode !== null) {
+        if (!/[0-9a-fA-F]/.test(char))
+          throw failure("Invalid Unicode escape in custom tool input");
+        this.unicode += char;
+        if (this.unicode.length === 4) {
+          delta += String.fromCharCode(parseInt(this.unicode, 16));
+          this.unicode = null;
+        }
+      } else if (this.escape) {
+        this.escape = false;
+        if (char === "u") this.unicode = "";
+        else {
+          const escapes = {
+            '"': '"',
+            "\\": "\\",
+            "/": "/",
+            b: "\b",
+            f: "\f",
+            n: "\n",
+            r: "\r",
+            t: "\t",
+          };
+          if (!(char in escapes))
+            throw failure("Invalid escape in custom tool input");
+          delta += escapes[char];
+        }
+      } else if (char === "\\") this.escape = true;
+      else if (char === '"') this.closed = true;
+      else {
+        if (char.charCodeAt(0) < 32)
+          throw failure("Unescaped control character in custom tool input");
+        delta += char;
+      }
+    }
+    if (delta.length && /[\uD800-\uDBFF]/.test(delta[delta.length - 1])) {
+      this.pendingSurrogate = delta.slice(-1);
+      delta = delta.slice(0, -1);
+    }
+    this.value += delta;
+    return delta;
+  }
+
+  finish(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw failure("Upstream custom tool arguments are not valid JSON");
+    }
+    if (
+      !parsed ||
+      typeof parsed.input !== "string" ||
+      Object.keys(parsed).length !== 1 ||
+      !this.closed ||
+      this.pendingSurrogate ||
+      parsed.input !== this.value
+    ) {
+      throw failure(
+        "Upstream custom tool arguments must contain exactly one string property: input",
+      );
+    }
+    return this.value;
+  }
+}
+
+function responseUsage(usage) {
+  if (!usage) return null;
+  const input = usage.prompt_tokens ?? usage.input_tokens ?? 0;
+  const output = usage.completion_tokens ?? usage.output_tokens ?? 0;
+  return {
+    input_tokens: input,
+    input_tokens_details: {
+      cached_tokens:
+        usage.prompt_tokens_details?.cached_tokens ??
+        usage.input_tokens_details?.cached_tokens ??
+        0,
+    },
+    output_tokens: output,
+    output_tokens_details: {
+      reasoning_tokens:
+        usage.completion_tokens_details?.reasoning_tokens ??
+        usage.output_tokens_details?.reasoning_tokens ??
+        0,
+    },
+    total_tokens: usage.total_tokens ?? input + output,
+  };
+}
+
+
+class ResponseWriter {
+  constructor(res, payload, catalog, streaming, tracker) {
+    this.res = res;
+    this.catalog = catalog;
+    this.streaming = streaming;
+    this.tracker = tracker;
+    this.sequence = 0;
+    this.states = [];
+    this.calls = new Map();
+    this.message = null;
+    this.reasoning = null;
+    this.finishReason = null;
+    this.sawChoice = false;
+    this.response = {
+      id: identifier("resp"),
+      object: "response",
+      created_at: Math.floor(Date.now() / 1000),
+      status: "in_progress",
+      error: null,
+      incomplete_details: null,
+      model: payload.model,
+      output: [],
+      usage: null,
+      parallel_tool_calls: payload.parallel_tool_calls ?? true,
+      tool_choice: payload.tool_choice ?? "auto",
+      tools: payload.tools || [],
+      instructions: payload.instructions ?? null,
+      max_output_tokens: payload.max_output_tokens ?? null,
+      temperature: payload.temperature ?? null,
+      top_p: payload.top_p ?? null,
+      text: payload.text || { format: { type: "text" } },
+      truncation: "disabled",
+      metadata: payload.metadata || {},
+      store: false,
+    };
+  }
+
+  async event(type, fields) {
+    // Chat reasoning_content is raw provider reasoning, not a public summary.
+    // Display only its presence; preserve the existing client protocol unchanged.
+    observeActivity({ type, ...fields }, this.tracker, { summaries: false });
+    if (!this.streaming) return;
+    await writeChunk(
+      this.res,
+      `event: ${type}\ndata: ${JSON.stringify({ type, sequence_number: this.sequence++, ...fields })}\n\n`,
+    );
+  }
+
+  async start() {
+    await this.event("response.created", { response: this.response });
+    await this.event("response.in_progress", { response: this.response });
+  }
+
+  async add(item) {
+    const state = { item, index: this.states.length };
+    this.states.push(state);
+    this.response.output.push(item);
+    await this.event("response.output_item.added", {
+      output_index: state.index,
+      item,
+    });
+    return state;
+  }
+
+  fields(state) {
+    return { item_id: state.item.id, output_index: state.index };
+  }
+
+  async textDelta(text, refusal = false) {
+    if (typeof text !== "string")
+      throw failure("Unsupported non-text upstream assistant content");
+    if (!text) return;
+    if (!this.message) {
+      this.message = await this.add({
+        id: identifier("msg"),
+        type: "message",
+        role: "assistant",
+        status: "in_progress",
+        content: [],
+      });
+    }
+    const state = this.message;
+    const kind = refusal ? "refusal" : "output_text";
+    let contentIndex = state.item.content.findIndex(
+      (part) => part.type === kind,
+    );
+    if (contentIndex < 0) {
+      contentIndex = state.item.content.length;
+      const part = refusal
+        ? { type: "refusal", refusal: "" }
+        : { type: "output_text", text: "", annotations: [], logprobs: [] };
+      state.item.content.push(part);
+      await this.event("response.content_part.added", {
+        ...this.fields(state),
+        content_index: contentIndex,
+        part,
+      });
+    }
+    state.item.content[contentIndex][refusal ? "refusal" : "text"] += text;
+    await this.event(`response.${kind}.delta`, {
+      ...this.fields(state),
+      content_index: contentIndex,
+      delta: text,
+      ...(refusal ? {} : { logprobs: [] }),
+    });
+  }
+
+  async reasoningDelta(text) {
+    if (typeof text !== "string")
+      throw failure("Unsupported non-text upstream reasoning_content");
+    if (!text) return;
+    if (!this.reasoning) {
+      this.reasoning = await this.add({
+        id: identifier("rs"),
+        type: "reasoning",
+        status: "in_progress",
+        summary: [],
+      });
+      const part = { type: "summary_text", text: "" };
+      this.reasoning.item.summary.push(part);
+      await this.event("response.reasoning_summary_part.added", {
+        ...this.fields(this.reasoning),
+        summary_index: 0,
+        part,
+      });
+    }
+    this.reasoning.item.summary[0].text += text;
+    await this.event("response.reasoning_summary_text.delta", {
+      ...this.fields(this.reasoning),
+      summary_index: 0,
+      delta: text,
+    });
+  }
+
+  async exposeCall(call, final = false) {
+    if (call.state) return;
+    const descriptor = this.catalog.get(call.name);
+    // Names can arrive in separate deltas. Never guess a custom/function kind
+    // from a partial name or expose a name that is still being accumulated.
+    if (!descriptor) {
+      if (final)
+        throw failure(
+          `Upstream returned an unknown tool: ${call.name || "(missing name)"}`,
+        );
+      return;
+    }
+    if (
+      !final &&
+      (!call.arguments ||
+        [...this.catalog.keys()].some(
+          (name) => name !== call.name && name.startsWith(call.name),
+        ))
+    )
+      return;
+    call.descriptor = descriptor;
+    const item = {
+      id: identifier(descriptor.kind === "custom" ? "ctc" : "fc"),
+      type: descriptor.kind === "custom" ? "custom_tool_call" : "function_call",
+      // A bridge-owned ID remains stable even if Chat fragments its ID.
+      // Follow-up requests replay this ID unchanged in calls and outputs.
+      call_id: identifier("call"),
+      name: descriptor.name,
+      status: "in_progress",
+      ...(descriptor.namespace ? { namespace: descriptor.namespace } : {}),
+      ...(descriptor.kind === "custom" ? { input: "" } : { arguments: "" }),
+    };
+    call.state = await this.add(item);
+    if (descriptor.kind === "custom") call.decoder = new CustomInputDecoder();
+    await this.argumentDelta(call, call.arguments);
+  }
+
+  async argumentDelta(call, fragment) {
+    if (!fragment) return;
+    const custom = call.descriptor.kind === "custom";
+    const delta = custom ? call.decoder.feed(fragment) : fragment;
+    if (!delta) return;
+    call.state.item[custom ? "input" : "arguments"] += delta;
+    await this.event(
+      custom
+        ? "response.custom_tool_call_input.delta"
+        : "response.function_call_arguments.delta",
+      { ...this.fields(call.state), delta },
+    );
+  }
+
+  async toolDelta(tool, fallbackIndex) {
+    const index = tool.index ?? fallbackIndex;
+    if (!Number.isInteger(index) || index < 0)
+      throw failure("Upstream tool call is missing a valid index");
+    if (tool.type && tool.type !== "function")
+      throw failure(`Unsupported upstream tool call type: ${tool.type}`);
+    let call = this.calls.get(index);
+    if (!call) {
+      call = { name: "", arguments: "", upstreamId: "", state: null };
+      this.calls.set(index, call);
+    }
+    if (tool.id != null) {
+      if (typeof tool.id !== "string")
+        throw failure("Invalid upstream tool call ID");
+      call.upstreamId += tool.id;
+    }
+    const fn = tool.function || {};
+    if (fn.name != null) {
+      if (typeof fn.name !== "string")
+        throw failure("Invalid upstream tool name");
+      if (call.state && fn.name)
+        throw failure(
+          "Upstream changed a tool name after streaming its arguments",
+        );
+      call.name += fn.name;
+    }
+    const fragment = fn.arguments ?? "";
+    if (typeof fragment !== "string")
+      throw failure("Invalid upstream tool arguments");
+    call.arguments += fragment;
+    if (call.state) await this.argumentDelta(call, fragment);
+    else await this.exposeCall(call);
+  }
+
+  async consume(chunk, complete = false) {
+    // AgentRouter emits JSON null for Anthropic block boundary events.
+    // They carry no Chat delta; finish_reason and [DONE] still remain required.
+    if (chunk === null && !complete) return;
+    if (!chunk || typeof chunk !== "object")
+      throw failure("Invalid Chat response payload");
+    if (chunk.error) {
+      const message =
+        typeof chunk.error === "string"
+          ? chunk.error
+          : chunk.error.message || "AgentRouter returned an error";
+      throw failure(message, 502, chunk.error.code || "upstream_error");
+    }
+    if (chunk.usage) {
+      this.response.usage = responseUsage(chunk.usage);
+      this.tracker?.usage(chunk.usage);
+    }
+    if (!Array.isArray(chunk.choices))
+      throw failure("Chat response has no choices array");
+    if (chunk.choices.length > 1)
+      throw failure(
+        "Multiple Chat choices cannot be represented as one Responses output",
+      );
+    for (const choice of chunk.choices) {
+      if (choice.index != null && choice.index !== 0)
+        throw failure("Unexpected Chat choice index");
+      if (this.finishReason)
+        throw failure("Upstream emitted a choice after its finish_reason");
+      this.sawChoice = true;
+      const delta = complete ? choice.message : choice.delta;
+      if (!delta || typeof delta !== "object")
+        throw failure("Chat choice is missing assistant content");
+      if (delta.role && delta.role !== "assistant")
+        throw failure(`Unexpected upstream role: ${delta.role}`);
+      if (delta.reasoning_content != null)
+        await this.reasoningDelta(delta.reasoning_content);
+      if (delta.content != null) {
+        if (typeof delta.content === "string")
+          await this.textDelta(delta.content);
+        else if (Array.isArray(delta.content)) {
+          for (const part of delta.content) {
+            if (part.type === "text" || part.type === "output_text")
+              await this.textDelta(part.text);
+            else if (part.type === "refusal")
+              await this.textDelta(part.refusal, true);
+            else
+              throw failure(
+                `Unsupported upstream assistant content: ${part.type}`,
+              );
+          }
+        } else throw failure("Unsupported upstream assistant content");
+      }
+      if (delta.refusal != null) await this.textDelta(delta.refusal, true);
+      if (delta.audio || delta.function_call)
+        throw failure(
+          "Unsupported upstream audio or legacy function_call output",
+        );
+      if (delta.tool_calls != null) {
+        if (!Array.isArray(delta.tool_calls))
+          throw failure("Invalid upstream tool_calls");
+        for (let i = 0; i < delta.tool_calls.length; i++)
+          await this.toolDelta(delta.tool_calls[i], complete ? i : undefined);
+      }
+      if (choice.finish_reason != null) {
+        if (
+          !["stop", "tool_calls", "length", "content_filter"].includes(
+            choice.finish_reason,
+          )
+        )
+          throw failure(
+            `Unsupported upstream finish_reason: ${choice.finish_reason}`,
+          );
+        this.finishReason = choice.finish_reason;
+      }
+    }
+  }
+
+  async finish() {
+    if (!this.sawChoice || !this.finishReason)
+      throw failure(
+        "Upstream stream ended without a finish_reason",
+        502,
+        "incomplete_stream",
+      );
+    const incomplete =
+      this.finishReason === "length" || this.finishReason === "content_filter";
+    if (this.finishReason === "tool_calls" && !this.calls.size)
+      throw failure("Upstream finished with tool_calls but returned no calls");
+    for (const call of this.calls.values()) {
+      await this.exposeCall(call, true);
+      if (!incomplete && call.descriptor.kind === "custom")
+        call.decoder.finish(call.arguments);
+      if (!incomplete && call.descriptor.kind === "function") {
+        try {
+          JSON.parse(call.arguments);
+        } catch {
+          throw failure(
+            `Invalid JSON arguments for tool ${call.descriptor.name}`,
+          );
+        }
+      }
+    }
+    // Validate every call before publishing any executable output_item.done.
+    for (const state of this.states) {
+      const item = state.item;
+      item.status = incomplete ? "incomplete" : "completed";
+      if (item.type === "message") {
+        for (
+          let content_index = 0;
+          content_index < item.content.length;
+          content_index++
+        ) {
+          const part = item.content[content_index];
+          const fields = { ...this.fields(state), content_index };
+          if (part.type === "output_text")
+            await this.event("response.output_text.done", {
+              ...fields,
+              text: part.text,
+              logprobs: [],
+            });
+          else
+            await this.event("response.refusal.done", {
+              ...fields,
+              refusal: part.refusal,
+            });
+          await this.event("response.content_part.done", { ...fields, part });
+        }
+      } else if (item.type === "reasoning") {
+        const fields = { ...this.fields(state), summary_index: 0 };
+        await this.event("response.reasoning_summary_text.done", {
+          ...fields,
+          text: item.summary[0].text,
+        });
+        await this.event("response.reasoning_summary_part.done", {
+          ...fields,
+          part: item.summary[0],
+        });
+      } else if (item.type === "custom_tool_call") {
+        await this.event("response.custom_tool_call_input.done", {
+          ...this.fields(state),
+          input: item.input,
+        });
+      } else {
+        await this.event("response.function_call_arguments.done", {
+          ...this.fields(state),
+          name: item.name,
+          arguments: item.arguments,
+        });
+      }
+      await this.event("response.output_item.done", {
+        output_index: state.index,
+        item,
+      });
+    }
+    this.response.status = incomplete ? "incomplete" : "completed";
+    this.response.completed_at = Math.floor(Date.now() / 1000);
+    this.response.end_turn = !this.calls.size;
+    this.response.output_text = this.response.output
+      .filter((item) => item.type === "message")
+      .flatMap((item) => item.content)
+      .filter((part) => part.type === "output_text")
+      .map((part) => part.text)
+      .join("");
+    if (incomplete)
+      this.response.incomplete_details = {
+        reason:
+          this.finishReason === "length"
+            ? "max_output_tokens"
+            : "content_filter",
+      };
+    await this.event(
+      incomplete ? "response.incomplete" : "response.completed",
+      { response: this.response },
+    );
+    if (incomplete)
+      this.tracker?.fail(
+        "AgentRouter reported an incomplete response (generation limit or content restriction)",
+      );
+    else this.tracker?.complete();
+    return this.response;
+  }
+
+  async fail(error) {
+    this.response.status = "failed";
+    this.response.error = {
+      code: error.code || "bridge_error",
+      message: error.message || "AgentRouter stream failed",
+    };
+    for (const item of this.response.output) item.status = "incomplete";
+    await this.event("error", { ...this.response.error, param: null });
+    await this.event("response.failed", { response: this.response });
+  }
+}
+
+
+
+async function readJSON(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(chunk);
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw failure("AgentRouter returned invalid Chat Completions JSON");
+  }
+}
+
+async function bridgeResponses(req, res, payload, { agent, tracker } = {}) {
+  let upstreamRequest;
+  let upstreamResponse;
+  let upstreamStream;
+  const controller = new AbortController();
+  let stream;
+  let writer;
+  let cancelled = false;
+  let passthrough = false;
+  const cancel = () => {
+    if (res.writableFinished) return;
+    cancelled = true;
+    controller.abort();
+    upstreamStream?.destroy();
+    upstreamRequest?.destroy();
+    upstreamResponse?.destroy();
+    if (stream && stream !== upstreamResponse) stream.destroy();
+  };
+  req.once("aborted", cancel);
+  res.once("close", cancel);
+  res.once("error", cancel);
+  try {
+    const { request, byWireName } = buildRequest(payload, tracker);
+    const body = JSON.stringify(request);
+    const headers = cleanHeaders(req.headers);
+    for (const key of [
+      "host",
+      "content-length",
+      "content-encoding",
+      "expect",
+      "accept-encoding",
+    ])
+      delete headers[key];
+    headers.host = UPSTREAM.host;
+    headers["content-type"] = "application/json";
+    headers["content-length"] = Buffer.byteLength(body);
+    headers["accept-encoding"] = "identity";
+    headers.accept ??= request.stream
+      ? "text/event-stream"
+      : "application/json";
+    if (cancelled || req.aborted || res.destroyed) return;
+    const result = await requestWithRetries(
+      UPSTREAM,
+      { method: "POST", headers, agent },
+      body,
+      {
+        signal: controller.signal,
+        tracker,
+        clientOwnsRetries: req.headers["x-agentrouter-retry-owner"] === "client",
+      },
+    );
+    upstreamRequest = result.request;
+    upstreamResponse = result.response;
+    upstreamStream = result.stream;
+    const status = upstreamResponse.statusCode || 502;
+    tracker?.upstream(status);
+    if (status < 200 || status >= 300 || result.retryReason) {
+      tracker?.fail(upstreamFailure(result.retryReason ? null : status, { code: result.retryReason }));
+      passthrough = true;
+      res.writeHead(status, cleanHeaders(upstreamResponse.headers));
+      for await (const chunk of upstreamStream) await writeChunk(res, chunk);
+      res.end();
+      return;
+    }
+    stream = decodedStream(upstreamResponse, upstreamStream);
+    writer = new ResponseWriter(
+      res,
+      payload,
+      byWireName,
+      request.stream,
+      tracker,
+    );
+    const responseHeaders = cleanHeaders(upstreamResponse.headers);
+    for (const key of ["content-length", "content-encoding", "etag"])
+      delete responseHeaders[key];
+    responseHeaders["cache-control"] = "no-cache";
+    responseHeaders["x-accel-buffering"] = "no";
+    responseHeaders["openai-model"] = payload.model;
+    if (request.stream) {
+      responseHeaders["content-type"] = "text/event-stream; charset=utf-8";
+      res.writeHead(200, responseHeaders);
+      res.flushHeaders?.();
+      await writer.start();
+      const contentType = String(
+        upstreamResponse.headers["content-type"] || "",
+      );
+      if (contentType.includes("application/json")) {
+        await writer.consume(await readJSON(stream), true);
+      } else {
+        let done = false;
+        for await (const event of sseEvents(stream)) {
+          if (done) continue;
+          if (event.data.trim() === "[DONE]") {
+            done = true;
+            // Consume through HTTP EOF so the shared agent can reuse this
+            // socket; breaking the async iterator would destroy it.
+            continue;
+          }
+          let chunk;
+          try {
+            chunk = JSON.parse(event.data);
+          } catch {
+            throw failure("AgentRouter returned malformed SSE JSON");
+          }
+          if (event.event === "error" && !chunk.error)
+            throw failure(
+              chunk.message || "AgentRouter returned a stream error",
+              502,
+              chunk.code || "upstream_error",
+            );
+          await writer.consume(chunk);
+        }
+        if (!done)
+          throw failure(
+            "Upstream SSE ended before [DONE]",
+            502,
+            "incomplete_stream",
+          );
+      }
+      await writer.finish();
+      res.end();
+    } else {
+      await writer.consume(await readJSON(stream), true);
+      const response = await writer.finish();
+      responseHeaders["content-type"] = "application/json";
+      res.writeHead(200, responseHeaders);
+      res.end(JSON.stringify(response));
+    }
+  } catch (error) {
+    if (!cancelled && !res.destroyed && !res.writableEnded)
+      tracker?.fail(upstreamFailure(null, error));
+    controller.abort();
+    upstreamStream?.destroy();
+    upstreamRequest?.destroy();
+    upstreamResponse?.destroy();
+    if (stream && stream !== upstreamResponse) stream.destroy();
+    if (cancelled || res.destroyed || res.writableEnded) return;
+    if (passthrough) {
+      res.destroy();
+      return;
+    }
+    if (res.headersSent) {
+      if (writer && writer.streaming) {
+        try {
+          await writer.fail(error);
+          res.end();
+        } catch {
+          res.destroy();
+        }
+      } else res.destroy();
+    } else {
+      res.writeHead(error.status || 502, {
+        "content-type": "application/json",
+      });
+      res.end(
+        JSON.stringify({
+          error: {
+            type: error.status === 400 ? "invalid_request_error" : "api_error",
+            code: error.code || "bridge_error",
+            message: error.message,
+          },
+        }),
+      );
+    }
+  } finally {
+    req.off("aborted", cancel);
+    res.off("close", cancel);
+    res.off("error", cancel);
+  }
+}
+
+module.exports = { bridgeResponses };