@opengeni/codex 0.2.0

package/src/fetch.ts

@@ -0,0 +1,337 @@
+// codexSubscriptionFetch — the transport installed on the OpenAI client for the
+// "codex-subscription" provider. Mirrors the runtime's computerCallNormalizingFetch
+// pattern: wraps a base fetch and returns a (input, init) => Promise<Response>.
+//
+// It reads the per-request Codex context from AsyncLocalStorage at CALL time, so a
+// single process-cached client serves every workspace with the correct token. It:
+//   - rewrites /responses -> /codex/responses
+//   - injects the subscription auth headers (omits OpenAI-Beta on SSE; spec §1.2)
+//   - normalizes the request body (spec §0 verdict)
+//   - retries once on 401 after a forced token refresh (spec §1.9)
+// Stream parsing is delegated to the SDK (SSE passthrough; spec §0(d)).
+
+import { CODEX_ORIGINATOR } from "./constants";
+import { normalizeCodexRequestBody } from "./normalize";
+import { codexRequestStorage, type CodexTokenSnapshot, type CodexUsageHeaderSnapshot } from "./request-context";
+
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+/** Parse an integer header value; null when absent or not a finite integer. */
+function parseIntHeader(value: string | null): number | null {
+  if (value === null) {
+    return null;
+  }
+  const n = Number.parseInt(value.trim(), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Resolve a window reset instant from the response headers: prefer the absolute
+ * `*-reset-at` (epoch SECONDS → ms, mirroring codex-token-resolver's usage parse),
+ * else the relative `*-reset-after-seconds` from now, else now (a missing reset
+ * reads as "already cleared" — availableAt treats an elapsed reset as a bounded
+ * default cooldown, so the ranker never strands on it).
+ */
+function resolveResetAt(headers: Headers, atKey: string, afterKey: string, nowMs: number): Date {
+  const at = parseIntHeader(headers.get(atKey));
+  if (at !== null) {
+    return new Date(at * 1000);
+  }
+  const after = parseIntHeader(headers.get(afterKey));
+  if (after !== null) {
+    return new Date(nowMs + after * 1000);
+  }
+  return new Date(nowMs);
+}
+
+/**
+ * Multi-account P4 (Part A): scrape the full usage snapshot the codex backend
+ * stamps on every `/codex/responses` response in `x-codex-primary-*` /
+ * `x-codex-secondary-*` headers (integer-identical to GET /wham/usage, for free).
+ *
+ * CRITICAL clobber-fix: return null unless BOTH windows expose a valid used-percent
+ * integer. recordCodexAccountUsage writes all five columns unconditionally, so a
+ * primary-only snapshot would null the weekly column. Both windows are always
+ * emitted together on `/codex/responses`; gating on both makes every write a full
+ * 5-column snapshot byte-identical to the poll path, and a malformed/absent header
+ * set simply no-ops (the /wham/usage poll fallback still covers it).
+ */
+export function parseCodexUsageHeaders(headers: Headers): CodexUsageHeaderSnapshot | null {
+  const primaryUsedPercent = parseIntHeader(headers.get("x-codex-primary-used-percent"));
+  const secondaryUsedPercent = parseIntHeader(headers.get("x-codex-secondary-used-percent"));
+  if (primaryUsedPercent === null || secondaryUsedPercent === null) {
+    return null; // not a full both-windows snapshot — no-op (never a partial clobber)
+  }
+  const nowMs = Date.now();
+  return {
+    primaryUsedPercent,
+    primaryResetAt: resolveResetAt(headers, "x-codex-primary-reset-at", "x-codex-primary-reset-after-seconds", nowMs),
+    secondaryUsedPercent,
+    secondaryResetAt: resolveResetAt(headers, "x-codex-secondary-reset-at", "x-codex-secondary-reset-after-seconds", nowMs),
+    checkedAt: new Date(nowMs),
+  };
+}
+
+export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): FetchLike {
+  return async (input, init) => {
+    const ctx = codexRequestStorage.getStore();
+    if (!ctx) {
+      return base(input, init); // not a codex turn — passthrough, untouched
+    }
+
+    const rawUrl =
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    // /responses -> /codex/responses, idempotent: the negative lookbehind skips
+    // URLs whose base already includes /codex (avoids /codex/codex/responses).
+    const rewritten = rawUrl.replace(/(?<!\/codex)\/responses(\b|$)/, "/codex/responses$1");
+
+    const attempt = async (auth: CodexTokenSnapshot): Promise<Response> => {
+      const headers = new Headers(init?.headers);
+      headers.set("Authorization", `Bearer ${auth.accessToken}`);
+      if (auth.chatgptAccountId) {
+        headers.set("ChatGPT-Account-ID", auth.chatgptAccountId);
+      }
+      headers.set("originator", CODEX_ORIGINATOR);
+      headers.set("User-Agent", `${CODEX_ORIGINATOR}/${ctx.clientVersion}`);
+      headers.set("version", ctx.clientVersion);
+      headers.set("accept", "text/event-stream");
+      headers.set("content-type", "application/json");
+      if (auth.isFedramp) {
+        headers.set("X-OpenAI-Fedramp", "true");
+      }
+      headers.delete("OpenAI-Beta"); // omit on SSE (spec §1.2); fallback: "responses=experimental" if backend 400s
+      headers.delete("x-api-key");
+
+      // The backend is streaming-only; force stream=true on the wire but remember
+      // the caller's intent so a non-streaming caller (e.g. the compaction
+      // summarizer) still gets a single JSON Response back.
+      let callerWantsStream = true;
+      const nextInit: RequestInit = { ...init, headers };
+      if (typeof init?.body === "string") {
+        try {
+          const parsed = JSON.parse(init.body) as Record<string, unknown>;
+          callerWantsStream = parsed.stream === true;
+          nextInit.body = JSON.stringify(normalizeCodexRequestBody(parsed, ctx.resolveModel));
+        } catch {
+          /* leave unparseable bodies untouched (already copied from init) */
+        }
+      }
+      if (process.env.CODEX_DEBUG) {
+        const keys = typeof nextInit.body === "string" ? Object.keys(JSON.parse(nextInit.body) as Record<string, unknown>) : [];
+        console.error(`[codex-debug] POST ${rewritten} stream=${callerWantsStream} bodyKeys=[${keys.join(",")}]`);
+      }
+      const res = await base(rewritten, nextInit);
+      // Multi-account P4 (Part A): scrape the usage headers ONCE, before the
+      // OK/!res.ok branch, so the same fire-and-forget read also covers the 429
+      // hard-cap path (an exhausted serving account stamps its own fresh
+      // used_percent with no extra fetch). Sync + non-throwing + never awaited;
+      // `if (usage)` makes an absent/malformed header set a safe no-op. We read
+      // res.headers only — the SSE body is never touched here.
+      const usage = parseCodexUsageHeaders(res.headers);
+      if (usage) {
+        ctx.onUsageHeaders?.(usage);
+      }
+      if (process.env.CODEX_DEBUG && !res.ok) {
+        console.error(`[codex-debug] <- ${res.status} ${await res.clone().text()}`);
+      }
+      // The codex backend leaves the terminal event's response.output empty and
+      // delivers the assistant items via output_item.done events instead. The
+      // @openai/agents parser (streaming AND non-streaming) reads response.output,
+      // so we must reconstruct it: collapse to one JSON Response for a non-streaming
+      // caller, or repair the live stream's terminal event for a streaming caller.
+      if (!res.ok) {
+        // Buffer the error body once and re-emit it as a concrete JSON Response.
+        // A streaming responses request whose error body is left as the raw
+        // (possibly SSE / already-streamed) Response makes the SDK throw
+        // "<status> status code (no body)" — the JSON error (type/message/
+        // resets_in_seconds) is lost, so a 429 usage cap surfaces as a generic,
+        // wrongly-retryable rate-limit. Re-emitting a clean application/json
+        // Response lets the SDK reconstruct error.error for EVERY codex error
+        // (401/400/5xx too). For a hard usage cap we also pin x-should-retry:false
+        // so the SDK does not burn its retry budget on a limit that won't lift.
+        return await bufferCodexErrorResponse(res);
+      }
+      return callerWantsStream ? repairCodexStream(res) : await sseToJsonResponse(res);
+    };
+
+    let res = await attempt(await ctx.getToken());
+    if (res.status === 401) {
+      res = await attempt(await ctx.refresh()); // single refresh-on-401 retry (spec §1.9)
+    }
+    return res;
+  };
+}
+
+/** The codex backend's hard-cap error type (ChatGPT/Codex usage limit reached). */
+export const CODEX_USAGE_LIMIT_ERROR_TYPE = "usage_limit_reached";
+
+export type CodexUsageLimitInfo = {
+  /** Seconds until the usage cap resets, when the backend reported it. */
+  resetsInSeconds: number | null;
+};
+
+/**
+ * Classify a thrown error as a ChatGPT/Codex usage-cap (429 usage_limit_reached)
+ * and extract the reset window. The SDK surfaces the codex backend's 429 as an
+ * OpenAI APIError whose `.type` (and `.error.type`) is `usage_limit_reached` and
+ * whose `.error.resets_in_seconds` carries the cap reset. Walks the cause chain
+ * and tolerates the message-only shape so it survives any SDK re-wrapping.
+ * Returns null for anything that is not a usage cap.
+ */
+export function classifyCodexUsageLimitError(error: unknown): CodexUsageLimitInfo | null {
+  let cur: unknown = error;
+  for (let depth = 0; depth < 6 && cur && typeof cur === "object"; depth++) {
+    const e = cur as Record<string, unknown>;
+    const body = (e.error && typeof e.error === "object" ? e.error : undefined) as Record<string, unknown> | undefined;
+    const type = (typeof e.type === "string" ? e.type : undefined) ?? (typeof body?.type === "string" ? body.type : undefined);
+    const message = typeof e.message === "string" ? e.message : "";
+    const status = Number(e.status);
+    if (
+      type === CODEX_USAGE_LIMIT_ERROR_TYPE ||
+      message.includes(CODEX_USAGE_LIMIT_ERROR_TYPE) ||
+      (status === 429 && /usage limit/i.test(message))
+    ) {
+      const resets =
+        (typeof body?.resets_in_seconds === "number" ? body.resets_in_seconds : undefined) ??
+        (typeof e.resets_in_seconds === "number" ? (e.resets_in_seconds as number) : undefined) ??
+        null;
+      return { resetsInSeconds: resets };
+    }
+    cur = e.cause;
+  }
+  return null;
+}
+
+/**
+ * Buffer a non-OK codex Response and re-emit it as a clean `application/json`
+ * Response so the SDK can reconstruct `error.error` from the body. A 429 usage
+ * cap (`error.type === "usage_limit_reached"`) is a HARD limit, not transient
+ * backpressure, so we pin `x-should-retry: false` to stop the SDK retrying it.
+ * Reading the body here also drains the socket of a discarded 401 (no leak).
+ */
+async function bufferCodexErrorResponse(res: Response): Promise<Response> {
+  const bodyText = await res.text().catch(() => "");
+  const headers = new Headers(res.headers);
+  headers.set("content-type", "application/json");
+  headers.delete("content-length"); // body re-serialized
+  headers.delete("content-encoding"); // text() already decoded any gzip
+  let errorType: string | undefined;
+  try {
+    const parsed = JSON.parse(bodyText) as { error?: { type?: unknown } };
+    errorType = typeof parsed.error?.type === "string" ? parsed.error.type : undefined;
+  } catch {
+    /* non-JSON error body — leave as-is, no retry-header override */
+  }
+  if (errorType === CODEX_USAGE_LIMIT_ERROR_TYPE) {
+    headers.set("x-should-retry", "false");
+  }
+  return new Response(bodyText, { status: res.status, statusText: res.statusText, headers });
+}
+
+/**
+ * Collapse a Responses SSE stream into the single JSON Response object a
+ * non-streaming `responses.create` caller expects: the terminal response.*
+ * event carries the full `response` payload.
+ */
+async function sseToJsonResponse(res: Response): Promise<Response> {
+  const text = await res.text();
+  let final: Record<string, unknown> | null = null;
+  const items: unknown[] = []; // assembled from output_item.done (the codex backend
+  // leaves response.completed.response.output empty and emits the items separately).
+  for (const block of text.split("\n\n")) {
+    const data = block
+      .split("\n")
+      .filter((l) => l.startsWith("data:"))
+      .map((l) => l.slice(5).trim())
+      .join("\n");
+    if (!data || data === "[DONE]") {
+      continue;
+    }
+    try {
+      const ev = JSON.parse(data) as { type?: string; response?: Record<string, unknown>; item?: unknown };
+      if (ev.type === "response.output_item.done" && ev.item !== undefined) {
+        items.push(ev.item);
+      } else if (ev.type === "response.completed" || ev.type === "response.done" || ev.type === "response.incomplete") {
+        final = ev.response ?? null;
+      }
+    } catch {
+      /* ignore non-JSON keepalive lines */
+    }
+  }
+  if (final && items.length > 0) {
+    final = { ...final, output: items }; // prefer the assembled items over an empty output array
+  }
+  if (process.env.CODEX_DEBUG) {
+    console.error(`[codex-debug] sse->json items=${items.length} outputLen=${Array.isArray(final?.output) ? (final.output as unknown[]).length : "?"}`);
+  }
+  const headers = new Headers(res.headers);
+  headers.set("content-type", "application/json");
+  headers.delete("content-length");
+  return new Response(JSON.stringify(final ?? {}), { status: 200, headers });
+}
+
+/**
+ * Repair a live Responses SSE stream for the @openai/agents streaming parser: pass
+ * every event through unchanged, collect the output_item.done items, and inject
+ * them into the terminal event's empty `output` so the parser sees the message.
+ */
+function repairCodexStream(res: Response): Response {
+  if (!res.body) {
+    return res;
+  }
+  const items: unknown[] = [];
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = "";
+  const transform = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      buffer += decoder.decode(chunk, { stream: true });
+      let idx = buffer.indexOf("\n\n");
+      while (idx !== -1) {
+        const block = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        controller.enqueue(encoder.encode(`${patchSseBlock(block, items)}\n\n`));
+        idx = buffer.indexOf("\n\n");
+      }
+    },
+    flush(controller) {
+      if (buffer.length > 0) {
+        controller.enqueue(encoder.encode(patchSseBlock(buffer, items)));
+      }
+    },
+  });
+  const headers = new Headers(res.headers);
+  headers.delete("content-length");
+  return new Response(res.body.pipeThrough(transform), { status: res.status, headers });
+}
+
+/** Collect output_item.done items (mutating `items`); rewrite the terminal event's empty output. */
+function patchSseBlock(block: string, items: unknown[]): string {
+  const lines = block.split("\n");
+  const dataStr = lines.filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).join("\n");
+  if (!dataStr || dataStr === "[DONE]") {
+    return block;
+  }
+  let ev: { type?: string; item?: unknown; response?: Record<string, unknown> };
+  try {
+    ev = JSON.parse(dataStr);
+  } catch {
+    return block;
+  }
+  if (ev.type === "response.output_item.done" && ev.item !== undefined) {
+    items.push(ev.item);
+    return block;
+  }
+  if (
+    (ev.type === "response.completed" || ev.type === "response.done" || ev.type === "response.incomplete") &&
+    ev.response
+  ) {
+    const out = ev.response.output;
+    if ((!Array.isArray(out) || out.length === 0) && items.length > 0) {
+      ev.response = { ...ev.response, output: items };
+      const nonData = lines.filter((l) => !l.startsWith("data:"));
+      return [...nonData, `data: ${JSON.stringify(ev)}`].join("\n");
+    }
+  }
+  return block;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./constants";
+export * from "./billing";
+export * from "./device-code";
+export * from "./refresh";
+export * from "./normalize";
+export * from "./usage-normalize";
+export * from "./api-client";
+export * from "./request-context";
+export * from "./fetch";
+export * from "./mcp-sanitize";

package/src/mcp-sanitize.ts

@@ -0,0 +1,290 @@
+// The codex_apps connector MCP is incompatible with the Responses API tool
+// contract in two ways that each fail the whole turn:
+//
+//  1. NAMES. Connector tools are named like "vercel.deploy_to_vercel" (dots).
+//     The Responses API requires every function-tool name to match
+//     ^[A-Za-z0-9_-]+$, so the request 400s ("Invalid 'tools[0].name': string
+//     does not match pattern"). We cannot just rename them in tools/list — the
+//     model would then call a name the MCP server does not know. So we remap
+//     BIDIRECTIONALLY at the transport: sanitize the name (and remember the
+//     mapping) on the tools/list RESPONSE, and reverse it back to the original on
+//     the tools/call REQUEST.
+//
+//  2. OUTPUT SCHEMAS. 122 of 217 tools return an empty `outputSchema: {}` (no
+//     `type`). @modelcontextprotocol/sdk validates every tool's outputSchema as a
+//     strict `{ type: "object", ... }` and ZodErrors the WHOLE tools/list. Since
+//     codex_apps runs with cacheToolsList:false it re-lists per turn, so that
+//     error (thrown during tool enumeration, outside the best-effort connect
+//     wrapper) fails the turn. We drop any non-object outputSchema before the
+//     validator sees it — safe, as outputSchema is an advisory hint only.
+
+import { CODEX_APPS_MCP_SERVER_ID } from "./constants";
+import type { FetchLike } from "./fetch";
+
+const VALID_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;
+
+// The Responses API rejects a function-tool name longer than 64 chars (it 400s
+// the WHOLE turn). Some namespaced connector tool names exceed this, and the
+// collision-disambiguation suffix only lengthens names, so the mapper must cap
+// length too — not just charset.
+const MAX_TOOL_NAME_LEN = 64;
+
+// CRITICAL: this sanitizer runs on the codex_apps tools/list wire BEFORE OpenGeni's
+// PrefixedMcpServer (packages/runtime) prepends `<serverId>__` to every tool name
+// (prefixedMcpToolName). The 64-char limit applies to that FINAL prefixed name the
+// model sees, so a name we cap at 64 here becomes 64 + 12 = 76 after prefixing and
+// 400s the whole turn. Reserve the runtime prefix so `codex_apps__<sanitized>` is
+// always <= 64. The sanitizer owns the server id, so the reservation is exact and
+// stays self-contained (no runtime import). The reverse mapping is unaffected: the
+// mapper is keyed on the pre-prefix sanitized name, which is what tools/call carries
+// back after PrefixedMcpServer strips its prefix.
+const RUNTIME_TOOL_NAME_PREFIX_LEN = CODEX_APPS_MCP_SERVER_ID.length + "__".length; // `codex_apps__` = 12
+const EFFECTIVE_MAX_TOOL_NAME_LEN = MAX_TOOL_NAME_LEN - RUNTIME_TOOL_NAME_PREFIX_LEN; // 52
+
+/** Short, stable, charset-legal hash of a string (djb2 → base36). Deterministic. */
+function shortHash(input: string): string {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = ((h << 5) + h + input.charCodeAt(i)) >>> 0; // h * 33 + c, kept unsigned
+  }
+  return h.toString(36);
+}
+
+/** Truncate to <= EFFECTIVE_MAX_TOOL_NAME_LEN (reserving the runtime prefix), appending `_<hash(original)>` so the result stays unique + deterministic. */
+function capLength(candidate: string, original: string): string {
+  if (candidate.length <= EFFECTIVE_MAX_TOOL_NAME_LEN) {
+    return candidate;
+  }
+  const suffix = `_${shortHash(original)}`;
+  return candidate.slice(0, Math.max(0, EFFECTIVE_MAX_TOOL_NAME_LEN - suffix.length)) + suffix;
+}
+
+/**
+ * Maps connector tool names to a Responses-API-legal charset and back. One
+ * instance per codex_apps transport (i.e. per turn): tools/list populates it,
+ * tools/call reads it. Idempotent across repeat listings.
+ */
+export class ToolNameMapper {
+  private readonly sanitizedToOriginal = new Map<string, string>();
+  private readonly used = new Set<string>();
+
+  /** Return a legal, unique name (<= EFFECTIVE_MAX_TOOL_NAME_LEN, so `<prefix>__name` <= 64) for `original`, recording the reverse mapping. */
+  sanitize(original: string): string {
+    let candidate = VALID_TOOL_NAME.test(original)
+      ? original
+      : original.replace(/[^a-zA-Z0-9_-]/g, "_") || "tool";
+    // Enforce the Responses-API 64-char cap (stable hash suffix keyed on the
+    // ORIGINAL → deterministic across repeat listings, distinct originals don't
+    // collide after truncation).
+    candidate = capLength(candidate, original);
+    // Disambiguate a genuine collision with a DIFFERENT original (never with
+    // the same original — that keeps repeat listings stable/idempotent). Re-cap
+    // after each suffix so disambiguation never re-breaches the effective limit.
+    if (this.used.has(candidate) && this.sanitizedToOriginal.get(candidate) !== original) {
+      const base = candidate;
+      let n = 2;
+      do {
+        const suffix = `_${n++}`;
+        candidate = (base.length + suffix.length > EFFECTIVE_MAX_TOOL_NAME_LEN
+          ? base.slice(0, EFFECTIVE_MAX_TOOL_NAME_LEN - suffix.length)
+          : base) + suffix;
+      } while (this.used.has(candidate));
+    }
+    this.used.add(candidate);
+    this.sanitizedToOriginal.set(candidate, original);
+    return candidate;
+  }
+
+  /** Reverse a sanitized name back to the MCP server's original, if known. */
+  toOriginal(sanitized: string): string | undefined {
+    return this.sanitizedToOriginal.get(sanitized);
+  }
+}
+
+/**
+ * Drop bad outputSchemas + sanitize tool names on a JSON-RPC tools/list result, in place.
+ *
+ * P4 (Part B.1): when `namespaceSink` is provided, accumulate each tool's ORIGINAL
+ * connector namespace (the segment BEFORE the first dot, e.g. `github` from
+ * `github.create_issue`) into it — captured HERE because this pass sees the original
+ * dotted name BEFORE mapper.sanitize rewrites the dot away. Only dotted names carry a
+ * connector namespace; un-dotted (already-legal) names are not connectors and are skipped.
+ */
+function sanitizeToolsInRpcMessage(message: unknown, mapper: ToolNameMapper, namespaceSink?: Set<string>): void {
+  if (!message || typeof message !== "object") {
+    return;
+  }
+  const tools = (message as { result?: { tools?: unknown } }).result?.tools;
+  if (!Array.isArray(tools)) {
+    return;
+  }
+  for (const tool of tools) {
+    if (!tool || typeof tool !== "object") {
+      continue;
+    }
+    const record = tool as Record<string, unknown>;
+    if ("outputSchema" in record) {
+      // Drop EVERY outputSchema, not just malformed/empty ones. The MCP SDK client
+      // caches a validator for any tool that declares an outputSchema and validates
+      // each tool CALL's `structuredContent` against it — and the codex_apps
+      // connectors return results that do NOT match their own declared schemas
+      // (e.g. the schema requires a `result` property the response omits), so the
+      // SDK throws `McpError -32602: Structured content does not match the tool's
+      // output schema` and EVERY such connector tool call fails (observed live:
+      // gmail_search_emails / gmail_get_profile / gmail_list_labels all -32602ed).
+      // outputSchema is advisory — the agent reads the text `content` regardless —
+      // so dropping it makes the connector tools usable. This also subsumes the
+      // empty-`{}` case the strict Tool schema rejected at tools/list time.
+      delete record.outputSchema;
+    }
+    if (typeof record.name === "string") {
+      if (namespaceSink && record.name.includes(".")) {
+        const namespace = record.name.slice(0, record.name.indexOf("."));
+        if (namespace) {
+          namespaceSink.add(namespace);
+        }
+      }
+      record.name = mapper.sanitize(record.name);
+    }
+  }
+}
+
+/**
+ * Surface a tool CALL's `structuredContent` to the model by inlining it as a text
+ * `content` block, in place.
+ *
+ * WHY. The @openai/agents MCP bridge forwards ONLY `result.content` to the model
+ * (agents-core shims/mcp-server: `const result = parsed.content`) and DISCARDS
+ * `result.structuredContent`. The codex_apps connectors return the real payload in
+ * `structuredContent` and a bare `"Action completed."` placeholder in `content`
+ * (verified live: `gmail.get_profile` → content=[{text:"Action completed."}],
+ * structuredContent={id,name,email,…}). Without this the agent's tool call
+ * "succeeds" but carries NO data — the model sees only the placeholder. Appending
+ * the structured payload as a text block makes the data reach the model while
+ * leaving the original content untouched.
+ *
+ * No-op when there is no `structuredContent` — so a tools/list response (or any
+ * result without it) passes through unchanged. Runs alongside (after) the empty
+ * outputSchema drop, which is what stops the MCP SDK -32602ing this same result.
+ */
+function inlineStructuredContentInRpcMessage(message: unknown): void {
+  if (!message || typeof message !== "object") {
+    return;
+  }
+  const result = (message as { result?: unknown }).result;
+  if (!result || typeof result !== "object") {
+    return;
+  }
+  const record = result as Record<string, unknown>;
+  if (!("structuredContent" in record)) {
+    return;
+  }
+  const structured = record.structuredContent;
+  if (structured === undefined || structured === null) {
+    return;
+  }
+  const text = typeof structured === "string" ? structured : JSON.stringify(structured);
+  const content = Array.isArray(record.content) ? [...record.content] : [];
+  content.push({ type: "text", text });
+  record.content = content;
+}
+
+/** Sanitize a single JSON body (application/json MCP response). */
+export function sanitizeMcpJsonBody(text: string, mapper: ToolNameMapper = new ToolNameMapper(), namespaceSink?: Set<string>): string {
+  try {
+    const parsed = JSON.parse(text);
+    sanitizeToolsInRpcMessage(parsed, mapper, namespaceSink);
+    inlineStructuredContentInRpcMessage(parsed);
+    return JSON.stringify(parsed);
+  } catch {
+    return text; // not JSON we understand — leave untouched
+  }
+}
+
+/** Sanitize an SSE body: each JSON-RPC message rides on a `data:` line. */
+export function sanitizeMcpSseBody(text: string, mapper: ToolNameMapper = new ToolNameMapper(), namespaceSink?: Set<string>): string {
+  return text
+    .split("\n")
+    .map((line) => {
+      if (!line.startsWith("data:")) {
+        return line;
+      }
+      const payload = line.slice("data:".length).trimStart();
+      try {
+        const parsed = JSON.parse(payload);
+        sanitizeToolsInRpcMessage(parsed, mapper, namespaceSink);
+        inlineStructuredContentInRpcMessage(parsed);
+        return `data: ${JSON.stringify(parsed)}`;
+      } catch {
+        return line;
+      }
+    })
+    .join("\n");
+}
+
+/** Reverse a sanitized tools/call name back to the original; returns null if no rewrite is needed. */
+export function remapToolCallRequestBody(body: string, mapper: ToolNameMapper): string | null {
+  try {
+    const message = JSON.parse(body) as { method?: unknown; params?: { name?: unknown } };
+    if (message.method !== "tools/call") {
+      return null;
+    }
+    const name = message.params?.name;
+    if (typeof name !== "string") {
+      return null;
+    }
+    const original = mapper.toOriginal(name);
+    if (original === undefined || original === name) {
+      return null;
+    }
+    message.params!.name = original;
+    return JSON.stringify(message);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wrap a base fetch so the codex_apps MCP transport is Responses-API-compatible:
+ * tools/list responses get their names sanitized + bad outputSchemas dropped (and
+ * the name mapping recorded), and tools/call requests get their name reversed back
+ * to the MCP server's original. Only the POST request/response is buffered; the
+ * long-lived GET notification SSE stream is passed through untouched.
+ *
+ * P4 (Part B.1): an optional `namespaceSink` Set accumulates the ORIGINAL-dotted
+ * connector namespaces seen across every tools/list this turn (captured before the
+ * dot is sanitized away). The worker reads the (live, by-reference) Set after the
+ * turn to cache the serving account's connector set — packages/codex stays db-free.
+ */
+export function codexAppsSanitizingFetch(base: FetchLike = globalThis.fetch, namespaceSink?: Set<string>): FetchLike {
+  const mapper = new ToolNameMapper();
+  return async (input, init) => {
+    // Outgoing: reverse a sanitized tools/call name to the server's original.
+    let nextInit = init;
+    if (init && typeof init.body === "string" && (init.method ?? "GET").toUpperCase() === "POST") {
+      const remapped = remapToolCallRequestBody(init.body, mapper);
+      if (remapped !== null) {
+        nextInit = { ...init, body: remapped };
+      }
+    }
+    const res = await base(input, nextInit);
+    const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+    if (method !== "POST" || !res.ok || !res.body) {
+      return res;
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    const isJson = contentType.includes("application/json");
+    const isSse = contentType.includes("text/event-stream");
+    if (!isJson && !isSse) {
+      return res;
+    }
+    const originalBody = await res.text();
+    const sanitized = isJson
+      ? sanitizeMcpJsonBody(originalBody, mapper, namespaceSink)
+      : sanitizeMcpSseBody(originalBody, mapper, namespaceSink);
+    const headers = new Headers(res.headers);
+    headers.delete("content-length"); // body length changed
+    headers.delete("content-encoding");
+    return new Response(sanitized, { status: res.status, statusText: res.statusText, headers });
+  };
+}