codex-grok-bridge 1.0.0

package/src/bridge.mjs

@@ -0,0 +1,237 @@
+import http from "node:http";
+import { timingSafeEqual, randomUUID } from "node:crypto";
+import { GrokAuthError, readGrokBearerToken } from "./auth.mjs";
+import { sanitizeImages, toImageBlocks } from "./images.mjs";
+import {
+  buildGrokInvocation,
+  decodeOutput,
+  parseGrokResult,
+  runGrok,
+} from "./cli-inference.mjs";
+import { openProxyStreamWithRetry, pipeProxySse } from "./proxy.mjs";
+import { toProxyRequest } from "./tools.mjs";
+import { classifyBridgeError, errorSignature, bridgeErrorMessage } from "./errors.mjs";
+import { createDiagnostics } from "./diagnostics.mjs";
+import { createSlots } from "./slots.mjs";
+
+export const MODEL_INFO = {
+  slug: "grok-4.6",
+  display_name: "Grok 4.6 / xAI",
+  description: "Grok 4.6 via grok login; Codex executes tools",
+  default_reasoning_level: "high",
+  supported_reasoning_levels: ["low", "medium", "high", "xhigh"].map(
+    (effort) => ({ effort, description: effort }),
+  ),
+  shell_type: "unified_exec",
+  visibility: "list",
+  supported_in_api: true,
+  priority: 50,
+  availability_nux: null,
+  upgrade: null,
+  support_verbosity: false,
+  default_verbosity: null,
+  apply_patch_tool_type: "freeform",
+  truncation_policy: { mode: "tokens", limit: 10000 },
+  experimental_supported_tools: [],
+  context_window: 500000,
+  input_modalities: ["text", "image"],
+  tool_mode: "direct",
+  node_repl_disabled: true,
+  model_messages: {
+    instructions_template:
+      "You are Grok 4.6 by xAI, running as the Codex model. Use the tools provided by Codex and respect its permissions. Complete the user request accurately.",
+  },
+};
+
+export function publicBridgeError(error, context = {}) {
+  if (error instanceof GrokAuthError) return error.message;
+  const message = String(error?.message ?? "");
+  // Upstream status errors and CLI exit codes already carry an accurate,
+  // redacted message; passing them through keeps their status code visible.
+  if (/^Grok Build CLI exited with code \d+$/.test(message)) return message;
+  if (/^Grok (login|Responses proxy)/.test(message)) return message;
+  const kind = classifyBridgeError(error, context);
+  return bridgeErrorMessage(kind, context.detail);
+}
+
+export function createBridgeServer(options = {}) {
+  if (!options.token) throw new Error("A bridge token is required");
+  const diagnostics = options.diagnostics ?? createDiagnostics(options.diagnosticsOptions);
+  const token = Buffer.from(`Bearer ${options.token}`);
+  const slots = createSlots({
+    limit: options.maxConcurrentInference,
+    queueLimit: options.maxQueuedInference,
+  });
+  return http.createServer(async (req, res) => {
+    const json = (status, data) => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(data));
+    };
+    const route = new URL(req.url, "http://127.0.0.1").pathname;
+    if (req.method === "GET" && route === "/v1/models")
+      return json(200, { models: [MODEL_INFO] });
+    if (req.method !== "POST" || route !== "/v1/responses")
+      return json(404, { error: "Not found" });
+    const auth = Buffer.from(req.headers.authorization ?? "");
+    if (auth.length !== token.length || !timingSafeEqual(auth, token))
+      return json(401, { error: "Unauthorized" });
+    if (req.headers.origin)
+      return json(403, { error: "Browser requests are not accepted" });
+    let body;
+    let requestBytes = 0;
+    try {
+      // Collect buffers and decode once. Concatenating into a string as chunks
+      // arrive doubles the payload in memory as UTF-16 and reallocates on every
+      // chunk, which matters now that a request can carry 20 MiB of images.
+      const chunks = [];
+      let size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > (options.maxBodyBytes ?? 40 * 1024 * 1024)) {
+          json(413, { error: "Request too large" });
+          return;
+        }
+        chunks.push(chunk);
+      }
+      requestBytes = size;
+      body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      if (body?.model !== "grok-4.6" || !Array.isArray(body.input))
+        throw new Error();
+    } catch {
+      return json(400, { error: "Invalid request" });
+    }
+    // Refuse only when even the queue is full; anything else waits for a slot.
+    // The check must sit after the body read, not before it: an `await` between
+    // the check and the claim lets concurrent requests all past it.
+    if (slots.isFull())
+      return json(429, { error: "Grok is busy; retry after this turn" });
+    const controller = new AbortController();
+    res.on("close", () => controller.abort());
+    res.writeHead(200, {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+    });
+    // writeHead() alone leaves the status line buffered until the first body
+    // write, so a slow upstream leaves the client on a wholly silent socket.
+    res.flushHeaders();
+    const event = (type, data) =>
+      res.write(
+        `event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`,
+      );
+    const id = "resp_" + randomUUID();
+    const startedAt = Date.now();
+    const keepalive = setInterval(() => {
+      if (!res.destroyed && !res.writableEnded) res.write(": keepalive\n\n");
+    }, 10000);
+    const useCli =
+      Boolean(options.runGrok) ||
+      options.inferenceMode === "cli" ||
+      process.env.GROK_BRIDGE_INFERENCE === "cli";
+    // Shape of the turn, for the diagnostic record. Structural counts only:
+    // never prompt text, tool output, or anything that could carry a secret.
+    const shape = {
+      mode: useCli ? "cli" : "proxy",
+      requestBytes,
+      items: Array.isArray(body.input) ? body.input.length : 0,
+      tools: Array.isArray(body.tools) ? body.tools.length : 0,
+    };
+    const queuedAt = Date.now();
+    let acquired = false;
+    let queuedMs = 0;
+    try {
+      await slots.acquire(controller.signal);
+      acquired = true;
+      queuedMs = Date.now() - queuedAt;
+      if (useCli) {
+        event("response.created", { response: { id } });
+        const invocation = buildGrokInvocation(body, options);
+        invocation.threadId = req.headers["thread-id"];
+        const result = await (options.runGrok ?? runGrok)(
+          invocation,
+          controller.signal,
+        );
+        if (result.exitCode !== 0)
+          throw new Error(
+            `Grok Build CLI exited with code ${Number(result.exitCode) || 1}`,
+          );
+        const parsed = parseGrokResult(result.stdout);
+        const items = decodeOutput(parsed, body.tools, body.tool_choice);
+        for (const item of items) event("response.output_item.done", { item });
+        const inputTokens =
+            parsed.usage?.input_tokens ?? parsed.usage?.inputTokens ?? 0,
+          outputTokens =
+            parsed.usage?.output_tokens ?? parsed.usage?.outputTokens ?? 0;
+        event("response.completed", {
+          response: {
+            id,
+            usage: {
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+              total_tokens: inputTokens + outputTokens,
+            },
+          },
+        });
+      } else {
+        const session = readGrokBearerToken(options.grokHome);
+        // Grok takes input_image blocks natively; only unusable attachments
+        // are swapped for an explanation, so one bad image cannot make the
+        // upstream reject the whole conversation.
+        const { request, map } = toProxyRequest(sanitizeImages(body));
+        const proxy = await openProxyStreamWithRetry({
+          token: session.token,
+          userId: session.userId,
+          body: request,
+          signal: controller.signal,
+          fetchImpl: options.proxyFetch,
+          baseUrl: options.proxyBaseUrl,
+          convId: body.prompt_cache_key,
+          sessionId: req.headers["thread-id"],
+          onRetry: ({ attempt, kind }) =>
+            diagnostics.record({
+              event: "turn_retried",
+              kind,
+              attempt,
+              elapsedMs: Date.now() - startedAt,
+            }),
+        });
+        await pipeProxySse(proxy.body, res, map);
+      }
+      diagnostics.record({
+        event: "turn_ok",
+        ...shape,
+        queuedMs,
+        elapsedMs: Date.now() - startedAt,
+      });
+    } catch (error) {
+      const kind = classifyBridgeError(error);
+      diagnostics.record({
+        event: "turn_failed",
+        kind,
+        signature: errorSignature(error),
+        ...shape,
+        queuedMs,
+        elapsedMs: Date.now() - startedAt,
+        detail: error?.message,
+      });
+      if (!res.writableEnded && !res.destroyed) {
+        try {
+          event("response.failed", {
+            response: {
+              id,
+              error: {
+                code: `bridge_${kind}`,
+                message: publicBridgeError(error),
+              },
+            },
+          });
+        } catch {
+          // SSE already closed; Codex will see the disconnect without this event.
+        }
+      }
+    } finally {
+      clearInterval(keepalive);
+      if (acquired) slots.release();
+      res.end();
+    }
+  });
+}

package/src/cli-inference.mjs

@@ -0,0 +1,265 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir, homedir } from "node:os";
+import path from "node:path";
+import { toImageBlocks } from "./images.mjs";
+
+// The GROK_BRIDGE_INFERENCE=cli fallback. It drives the Grok CLI once per turn
+// with the whole Codex request as a prompt and parses a JSON envelope back out.
+// The default path is streaming Responses over HTTP (proxy.mjs); this exists so
+// a transport problem can be worked around without losing the harness.
+
+const textOf = (item) =>
+  typeof item.content === "string"
+    ? item.content
+    : (item.content ?? [])
+        .filter((p) => p.type === "input_text" || p.type === "output_text")
+        .map((p) => p.text)
+        .join("\n\n");
+export function extractLatestUserPrompt(input) {
+  return textOf(
+    [...(input ?? [])].reverse().find((i) => i.role === "user") ?? {},
+  );
+}
+const isDirectory = (p) => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+export function extractCodexCwd(input, fallback, check = isDirectory) {
+  const isAllowed = check ?? isDirectory;
+  for (const item of [...(input ?? [])].reverse()) {
+    if (item.role !== "developer") continue;
+    const match = textOf(item).match(
+      /<environment_context>[\s\S]*?<cwd>([^<]+)<\/cwd>[\s\S]*?<\/environment_context>/,
+    );
+    if (match && path.isAbsolute(match[1]) && isAllowed(match[1]))
+      return match[1];
+  }
+  return fallback;
+}
+
+export function buildGrokInvocation(body, options = {}) {
+  const effort =
+    {
+      ultra: "xhigh",
+      max: "xhigh",
+      xhigh: "xhigh",
+      high: "high",
+      medium: "medium",
+      low: "low",
+      minimal: "low",
+      none: "low",
+    }[body.reasoning?.effort] ?? "high";
+  const args = [
+    "--single",
+    extractLatestUserPrompt(body.input),
+    "--model",
+    "grok-4.6",
+    "--output-format",
+    "json",
+    "--json-schema",
+    JSON.stringify({
+      type: "object",
+      properties: {
+        text: { type: "string" },
+        calls: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              namespace: { type: ["string", "null"] },
+              arguments: { type: "string" },
+            },
+            required: ["name", "namespace", "arguments"],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["text", "calls"],
+      additionalProperties: false,
+    }),
+    "--reasoning-effort",
+    effort,
+    "--permission-mode",
+    options.permissionMode ?? "dontAsk",
+    "--tools",
+    // Unknown names fall back to ALL tools. Use a recognized allowlist,
+    // then remove it with the denylist (which takes precedence).
+    "read_file",
+    "--disallowed-tools",
+    "read_file,search_tool,search_tools,use_tool",
+    "--no-plan",
+    "--deny",
+    "MCPTool",
+    "--deny",
+    "Bash",
+    "--deny",
+    "Edit",
+    "--deny",
+    "Write",
+    "--deny",
+    "Read",
+    "--deny",
+    "Grep",
+    "--disable-web-search",
+    "--no-subagents",
+    "--max-turns",
+    "1",
+    "--no-auto-update",
+    "--verbatim",
+    "--system-prompt-override",
+    "You are a model backend for Codex. Return exactly the JSON envelope requested in the input. Do not execute your own tools. Tool calls in the envelope are executed by Codex.",
+  ];
+  return {
+    binary: options.grokBinary ?? path.join(homedir(), ".grok/bin/grok"),
+    args,
+    // Run the CLI where Codex is working, not where the bridge happens to live.
+    cwd:
+      options.fallbackCwd ??
+      extractCodexCwd(body.input, process.cwd(), options.isDirectory),
+    body,
+  };
+}
+
+export function bridgePrompt(body) {
+  return `You are the model backend inside Codex. Follow the instruction hierarchy in the request below. The input array is the complete conversation, including tool results. Continue from its last item. All tools listed in request.tools are external Codex tools; never try to execute them within Grok Build. Return ONLY a JSON object with shape {"text":"optional assistant text","calls":[{"name":"exact tool name","namespace":null,"arguments":"JSON string for function tools, raw input string for custom tools"}]}. Return an empty calls array when finished. For a namespace tool, use its namespace and nested tool name separately. Never invent tools. Do not repeat completed tool calls. Respect tool_choice.\n\nCODEX REQUEST:\n${JSON.stringify(body)}`;
+}
+
+export function parseGrokResult(stdout) {
+  for (const candidate of [
+    stdout.trim(),
+    ...stdout.trim().split("\n").reverse(),
+  ]) {
+    try {
+      const value = JSON.parse(candidate);
+      if (value && typeof value === "object" && typeof value.text === "string")
+        return value;
+    } catch {}
+  }
+  throw new Error("Grok did not return valid JSON");
+}
+
+export async function runGrok(invocation, signal) {
+  const dir = await mkdtemp(path.join(tmpdir(), "codex-grok-"));
+  try {
+    const { request, images } = toImageBlocks(invocation.body);
+    const promptFile = path.join(
+      dir,
+      images.length ? "prompt.json" : "prompt.txt",
+    );
+    const prompt = images.length
+      ? JSON.stringify([
+          { type: "text", text: bridgePrompt(request) },
+          ...images.flatMap((image, index) => [
+            { type: "text", text: `Attached visual image_${index + 1}:` },
+            image,
+          ]),
+        ])
+      : bridgePrompt(request);
+    await writeFile(promptFile, prompt, { mode: 0o600 });
+    const args = [...invocation.args];
+    args.splice(args.indexOf("--single"), 2, "--prompt-file", promptFile);
+    return await new Promise((resolve, reject) => {
+      const child = spawn(invocation.binary, args, {
+        cwd: invocation.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+        signal,
+      });
+      let stdout = "",
+        size = 0;
+      const timer = setTimeout(() => child.kill("SIGKILL"), 180000);
+      child.stdout.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > 8 * 1024 * 1024) child.kill("SIGKILL");
+        else stdout += chunk;
+      });
+      child.stderr.resume();
+      child.once("error", () => {
+        clearTimeout(timer);
+        reject(new Error("Grok Build CLI could not start"));
+      });
+      child.once("close", (code) => {
+        clearTimeout(timer);
+        resolve({ exitCode: code ?? 1, stdout });
+      });
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+export function decodeOutput(result, tools = [], toolChoice = "auto") {
+  let envelope;
+  try {
+    envelope =
+      result.structured_output ??
+      JSON.parse(result.text.replace(/^```json\s*|\s*```$/g, ""));
+  } catch {
+    throw new Error("Invalid tool envelope");
+  }
+  if (
+    !envelope ||
+    typeof envelope.text !== "string" ||
+    !Array.isArray(envelope.calls) ||
+    envelope.calls.length > 32
+  )
+    throw new Error("Invalid tool envelope");
+  if (toolChoice === "none" && envelope.calls.length)
+    throw new Error("Tool calls forbidden");
+  if (toolChoice === "required" && !envelope.calls.length)
+    throw new Error("Tool call required");
+  if (
+    toolChoice &&
+    typeof toolChoice === "object" &&
+    toolChoice.name &&
+    (!envelope.calls.length ||
+      envelope.calls.some((c) => c.name !== toolChoice.name))
+  )
+    throw new Error("Required tool not selected");
+  const items = [];
+  if (envelope.text)
+    items.push({
+      type: "message",
+      id: "msg_" + randomUUID(),
+      role: "assistant",
+      content: [{ type: "output_text", text: envelope.text }],
+    });
+  for (const call of envelope.calls) {
+    const namespace = call.namespace ?? null;
+    const candidates = namespace
+      ? (tools.find((t) => t.type === "namespace" && t.name === namespace)
+          ?.tools ?? [])
+      : tools;
+    const tool = candidates.find(
+      (t) =>
+        t.name === call.name && (t.type === "function" || t.type === "custom"),
+    );
+    if (!tool || typeof call.arguments !== "string")
+      throw new Error("Unknown tool call");
+    if (tool.type === "function") {
+      try {
+        JSON.parse(call.arguments);
+      } catch {
+        throw new Error("Invalid tool arguments");
+      }
+    }
+    items.push({
+      type: tool.type === "custom" ? "custom_tool_call" : "function_call",
+      call_id: "call_" + randomUUID(),
+      name: call.name,
+      ...(namespace ? { namespace } : {}),
+      ...(tool.type === "custom"
+        ? { input: call.arguments }
+        : { arguments: call.arguments }),
+    });
+  }
+  if (!items.length) throw new Error("Empty model output");
+  return items;
+}

package/src/diagnostics.mjs

@@ -0,0 +1,67 @@
+// Prototype of src/diagnostics.mjs — a local, redacted, size-capped record of
+// every bridge turn, so a failure is diagnosable after the fact instead of
+// vanishing into an Electron process's inherited stderr.
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const DEFAULT_LOG_DIR = path.join(homedir(), ".local/share/codex-grok-bridge/logs");
+export const MAX_LOG_BYTES = 4 * 1024 * 1024;
+
+// Values that must never reach disk, matched structurally rather than by name,
+// because the field a token arrives in is not stable.
+const SECRET_PATTERNS = [
+  [/Bearer\s+[A-Za-z0-9._~+/-]+=*/g, "Bearer [redacted]"],
+  [/eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/g, "[jwt]"],
+  [/sk-[A-Za-z0-9_-]{16,}/g, "[key]"],
+  [/xai-[A-Za-z0-9_-]{16,}/g, "[key]"],
+];
+
+export function redact(value, home = homedir()) {
+  let text = String(value ?? "");
+  for (const [pattern, replacement] of SECRET_PATTERNS) text = text.replace(pattern, replacement);
+  // Home paths identify the operator and can carry project names; keep the shape.
+  return text.split(home).join("~").slice(0, 400);
+}
+
+function rotate(file) {
+  try {
+    if (statSync(file).size > MAX_LOG_BYTES) renameSync(file, `${file}.1`);
+  } catch {
+    // Nothing to rotate.
+  }
+}
+
+export function createDiagnostics(options = {}) {
+  // Opt-in: only the runtime enables this. A directly constructed server
+  // (every test does that) must never touch the operator's real log.
+  if (!options.enabled) return { record: () => {}, file: null };
+  const dir = options.dir ?? DEFAULT_LOG_DIR;
+  const file = path.join(dir, "bridge.jsonl");
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    return { record: () => {}, file: null };
+  }
+  return {
+    file,
+    // Only structural facts: sizes, counts, durations, codes. Never prompt text,
+    // never tool output, never a token, never a raw upstream body.
+    record(entry) {
+      try {
+        rotate(file);
+        appendFileSync(
+          file,
+          JSON.stringify({
+            at: new Date().toISOString(),
+            ...entry,
+            ...(entry.detail === undefined ? {} : { detail: redact(entry.detail) }),
+          }) + "\n",
+          { mode: 0o600 },
+        );
+      } catch {
+        // Diagnostics must never break a turn.
+      }
+    },
+  };
+}

package/src/errors.mjs

@@ -0,0 +1,93 @@
+// Prototype of src/errors.mjs — the error taxonomy the bridge is missing today.
+// Node's fetch reports every network fault as `TypeError: fetch failed` or
+// `TypeError: terminated` with the real code hidden on `.cause`, so classification
+// MUST walk the cause chain instead of matching a fixed set of top-level codes.
+
+export const BRIDGE_ERROR = Object.freeze({
+  ABORTED: "aborted",
+  AUTH: "auth",
+  DNS: "dns",
+  CONNECT: "connect",
+  UPSTREAM_TIMEOUT: "upstream_timeout",
+  UPSTREAM_CLOSED: "upstream_closed",
+  UPSTREAM_STATUS: "upstream_status",
+  UPSTREAM_PROTOCOL: "upstream_protocol",
+  PAYLOAD: "payload",
+  INTERNAL: "internal",
+});
+
+const MESSAGES = Object.freeze({
+  [BRIDGE_ERROR.ABORTED]: "Grok request was aborted",
+  [BRIDGE_ERROR.AUTH]: "Grok login expired. Run grok login.",
+  [BRIDGE_ERROR.DNS]:
+    "Grok is unreachable: DNS lookup for the Grok proxy failed. Check network or DNS, then retry.",
+  [BRIDGE_ERROR.CONNECT]:
+    "Grok is unreachable: could not connect to the Grok proxy. Check network, then retry.",
+  [BRIDGE_ERROR.UPSTREAM_TIMEOUT]:
+    "Grok did not respond in time. Retry, or shorten the turn.",
+  [BRIDGE_ERROR.UPSTREAM_CLOSED]:
+    "Grok closed the connection before finishing. Retry.",
+  [BRIDGE_ERROR.UPSTREAM_PROTOCOL]:
+    "Grok sent a malformed response. Retry.",
+  [BRIDGE_ERROR.PAYLOAD]: "Grok rejected the request payload",
+  [BRIDGE_ERROR.INTERNAL]: "Grok bridge failed to process the turn",
+});
+
+const DNS_CODES = new Set(["EAI_AGAIN", "ENOTFOUND", "EAI_NODATA", "EAI_NONAME", "ETIMEOUT"]);
+const CONNECT_CODES = new Set([
+  "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN", "EACCES",
+  "UND_ERR_CONNECT_TIMEOUT", "CERT_HAS_EXPIRED", "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "DEPTH_ZERO_SELF_SIGNED_CERT", "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+const TIMEOUT_CODES = new Set(["UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT", "ETIMEDOUT"]);
+const CLOSED_CODES = new Set(["UND_ERR_SOCKET", "ECONNRESET", "EPIPE"]);
+const ABORT_CODES = new Set([
+  "ABORT_ERR", "ERR_STREAM_DESTROYED", "ERR_STREAM_WRITE_AFTER_END", "ERR_STREAM_PREMATURE_CLOSE",
+]);
+
+// Walk the whole cause chain once, newest first, and yield every (name, code, message).
+function* chain(error, depth = 0) {
+  if (!error || typeof error !== "object" || depth > 8) return;
+  yield error;
+  yield* chain(error.cause, depth + 1);
+}
+
+export function classifyBridgeError(error, context = {}) {
+  for (const link of chain(error)) {
+    const code = typeof link.code === "string" ? link.code : "";
+    if (link.name === "AbortError" || ABORT_CODES.has(code)) {
+      // The bridge aborts the upstream only when the client hangs up, so an
+      // abort-shaped error means the client left. If the bridge ever aborts for
+      // its own reason it must pass that reason to controller.abort() and set
+      // context.reason here, instead of having classification guess from
+      // socket state (which races with the failing write).
+      return context.reason ?? BRIDGE_ERROR.ABORTED;
+    }
+    if (DNS_CODES.has(code)) return BRIDGE_ERROR.DNS;
+    if (CONNECT_CODES.has(code)) return BRIDGE_ERROR.CONNECT;
+    if (TIMEOUT_CODES.has(code)) return BRIDGE_ERROR.UPSTREAM_TIMEOUT;
+    if (CLOSED_CODES.has(code)) return BRIDGE_ERROR.UPSTREAM_CLOSED;
+    if (code.startsWith("HPE_") || link.name === "HTTPParserError")
+      return BRIDGE_ERROR.UPSTREAM_PROTOCOL;
+  }
+  if (/this operation was aborted/i.test(String(error?.message ?? "")))
+    return BRIDGE_ERROR.ABORTED;
+  return BRIDGE_ERROR.INTERNAL;
+}
+
+// A short, stable, secret-free trace of the cause chain: names and codes only,
+// never messages (a message can carry a host, a path, or a token fragment).
+export function errorSignature(error) {
+  const parts = [];
+  for (const link of chain(error)) {
+    const name = typeof link.name === "string" ? link.name : "Error";
+    const code = typeof link.code === "string" ? link.code : "";
+    parts.push(code ? `${name}[${code}]` : name);
+  }
+  return parts.join(" <- ").slice(0, 200);
+}
+
+export function bridgeErrorMessage(kind, detail) {
+  const base = MESSAGES[kind] ?? MESSAGES[BRIDGE_ERROR.INTERNAL];
+  return detail ? `${base} (${detail})` : base;
+}