@minhspark/codex-mcp-bridge 1.21.6 → 1.22.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.21.6",
+  "version": "1.22.1",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,37 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.1] - 2026-10-13
+
+### Fixed
+
+- Align the README badges in two centered rows. Render the three custom analytics badges at an intrinsic height of 20 pixels to match the standard flat badges even when GitHub overrides HTML height attributes. Scale both SVG dimensions together to preserve the artwork proportions.
+
+### Verification
+
+- Regression coverage checks the intrinsic height and aspect ratio of all three generated analytics badges. The existing analytics tests retain coverage for source dates, stale values, missing data, and aggregate privacy.
+- `npm test` passes from a clean archived checkout: 1,267 passed, 23 platform skips, and no failures. The Repository analytics workflow publishes the updated SVGs from the existing source data.
+
+### Upgrade notes
+
+- This release updates README presentation and the bundled analytics publisher. MCP behavior is unchanged; it does not add or validate a Desktop handoff feature. GitHub may cache badge images until its image proxy refreshes them.
+
+## [1.22.0] - 2026-10-12
+
+### Added
+
+- Optional response preferences for Desktop reads and reply observation, with tool payload filtering and bounded, replayable cursor pages. Snapshots remain bound to the caller, accounts, workspace, selected task, and delivery receipt (#125).
+
+### Fixed
+
+- Accept completed Desktop replies whose memory citation is represented separately in the completion event, but appended to the authoritative response item. Require an exact reconstruction from validated citation metadata and preserve reply IDs, hashes, lifecycle checks, and conflict rejection (#123).
+- Preserve bounded default history reads while allowing explicit tool output selection. Return structured oversize errors across native transport and serialized MCP responses.
+
+### Upgrade notes
+
+- Update both bridge and native relay companion. Calls without response preferences retain existing response formats and the 2,000-character default item budget. Preferred history reads use a 16,000-character item budget; exact-turn reads retain authoritative assistant text.
+- Cursor pages default to 64 KiB and support 8–96 KiB budgets. Native responses above 8 MiB and authoritative replies above 1 MiB remain explicit limits.
+
 ## [1.21.6] - 2026-10-12
 
 ### Fixed

package/README.md

@@ -6,13 +6,16 @@
 
 Local Desktop handoff guides: [daily workflow and directory verification](docs/daily-handoffs.md), [Windows setup](docs/new-windows-setup.md), [macOS setup](docs/new-macos-setup.md), and [project onboarding](docs/project-onboarding.md).
 
-[![npm](https://img.shields.io/npm/v/@minhspark/codex-mcp-bridge?logo=npm&color=CB3837)](https://www.npmjs.com/package/@minhspark/codex-mcp-bridge)
-[![npm downloads](https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads.svg)](https://www.npmjs.com/package/@minhspark/codex-mcp-bridge)
-[![npm downloads / month](https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads-month.svg)](https://www.npmcharts.com/compare/%40minhspark%2Fcodex-mcp-bridge?minimal=true)
-[![Used by repositories (Libraries.io)](https://img.shields.io/librariesio/dependent-repos/npm/@minhspark/codex-mcp-bridge?label=Used%20by&logo=github&color=0969da)](https://github.com/buidangminh23/codex-mcp-bridge/network/dependents)
-[![skills.sh installs](https://skills.sh/b/buidangminh23/codex-mcp-bridge?label=skills.sh)](https://skills.sh/buidangminh23/codex-mcp-bridge/codex-bridge)
-[![GitHub views / source window](https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-github-views.svg)](https://buidangminh23.github.io/codex-mcp-bridge/)
-[![license](https://img.shields.io/npm/l/@minhspark/codex-mcp-bridge)](LICENSE)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@minhspark/codex-mcp-bridge"><img src="https://img.shields.io/npm/v/@minhspark/codex-mcp-bridge?logo=npm&amp;color=CB3837" height="20" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/@minhspark/codex-mcp-bridge"><img src="https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads.svg" height="20" alt="npm downloads" /></a>
+  <a href="https://www.npmcharts.com/compare/%40minhspark%2Fcodex-mcp-bridge?minimal=true"><img src="https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads-month.svg" height="20" alt="npm downloads / month" /></a>
+  <br />
+  <a href="https://github.com/buidangminh23/codex-mcp-bridge/network/dependents"><img src="https://img.shields.io/librariesio/dependent-repos/npm/@minhspark/codex-mcp-bridge?label=Used%20by&amp;logo=github&amp;color=0969da" height="20" alt="Used by repositories (Libraries.io)" /></a>
+  <a href="https://skills.sh/buidangminh23/codex-mcp-bridge/codex-bridge"><img src="https://skills.sh/b/buidangminh23/codex-mcp-bridge?label=skills.sh" height="20" alt="skills.sh installs" /></a>
+  <a href="https://buidangminh23.github.io/codex-mcp-bridge/"><img src="https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-github-views.svg" height="20" alt="GitHub views / source window" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@minhspark/codex-mcp-bridge" height="20" alt="license" /></a>
+</p>
 
 Send prompts and replies between **Claude and Codex**, keeping each conversation in its own app. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.21.6",
+  "version": "1.22.1",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.21.6",
+  "version": "1.22.1",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -23,7 +23,7 @@ import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-acce
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.6";
+const VERSION = "1.22.1";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/scripts/publish-repo-analytics.mjs

@@ -129,7 +129,7 @@ function renderBadge(label, message, color, detail) {
   const messageWidth = Math.ceil([...message].length * 7.2 + 16);
   const width = labelWidth + messageWidth;
   const accessible = `${label}: ${message}`;
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="24" viewBox="0 0 ${width} 24" role="img" aria-label="${escapeXml(accessible)}"><title>${escapeXml(`${accessible}. ${detail}`)}</title><rect width="${width}" height="24" rx="4" fill="#555"/><path d="M${labelWidth} 0H${width - 4}Q${width} 0 ${width} 4V20Q${width} 24 ${width - 4} 24H${labelWidth}Z" fill="${color}"/><g fill="#fff" font-family="DejaVu Sans Mono,monospace" font-size="12" text-anchor="middle"><text x="${labelWidth / 2}" y="16">${escapeXml(label)}</text><text x="${labelWidth + messageWidth / 2}" y="16">${escapeXml(message)}</text></g></svg>
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width * 20 / 24}" height="20" viewBox="0 0 ${width} 24" role="img" aria-label="${escapeXml(accessible)}"><title>${escapeXml(`${accessible}. ${detail}`)}</title><rect width="${width}" height="24" rx="4" fill="#555"/><path d="M${labelWidth} 0H${width - 4}Q${width} 0 ${width} 4V20Q${width} 24 ${width - 4} 24H${labelWidth}Z" fill="${color}"/><g fill="#fff" font-family="DejaVu Sans Mono,monospace" font-size="12" text-anchor="middle"><text x="${labelWidth / 2}" y="16">${escapeXml(label)}</text><text x="${labelWidth + messageWidth / 2}" y="16">${escapeXml(message)}</text></g></svg>
 `;
 }
 

package/src/claude-bridge.mjs

@@ -29,7 +29,7 @@ import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.6";
+const VERSION = "1.22.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/codex-native-response.mjs

@@ -201,6 +201,17 @@ function completedEventText(entry) {
   return item.content.map((part) => part.text).join("");
 }
 
+function completedMemoryCitation(item) {
+  const citation = item.memory_citation;
+  if (!object(citation) || !Array.isArray(citation.entries) || !Array.isArray(citation.rolloutIds)) return null;
+  const singleLine = (value) => typeof value === "string" && !/[\r\n<>]/.test(value);
+  if (citation.entries.some((entry) => !object(entry) || !singleLine(entry.path) || !entry.path || !singleLine(entry.note) ||
+      !Number.isSafeInteger(entry.lineStart) || entry.lineStart < 1 || !Number.isSafeInteger(entry.lineEnd) || entry.lineEnd < entry.lineStart) ||
+      citation.rolloutIds.some((id) => typeof id !== "string" || !UUID.test(id))) return null;
+  const entries = citation.entries.map((entry) => `${entry.path}:${entry.lineStart}-${entry.lineEnd}|note=[${entry.note}]`).join("\n");
+  return `<oai-mem-citation>\n<citation_entries>\n${entries}\n</citation_entries>\n<rollout_ids>\n${citation.rolloutIds.join("\n")}\n</rollout_ids>\n</oai-mem-citation>`;
+}
+
 function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch } = {}) {
   const turns = records.filter((entry) => recordBelongsToTurn(entry, threadId, turnId));
   const starts = turns.filter(({ record }) => record.type === "event_msg" && STARTED.has(record.payload.type));
@@ -276,10 +287,11 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch }
         contextByte: contexts[0].start, completionByte: completions[0].start,
       });
     }
-    eventItems.set(id, { text, start });
+    eventItems.set(id, { text, start, memoryCitation: completedMemoryCitation(eventItem) });
   }
   for (const item of assistantItems) {
-    if (eventItems.has(item.id) && eventItems.get(item.id).text !== item.text) throw validationError("The native assistant item representations conflict", "assistant_representation_text", {
+    const event = eventItems.get(item.id);
+    if (event && event.text !== item.text && (!event.memoryCitation || event.text + event.memoryCitation !== item.text)) throw validationError("The native assistant item representations conflict", "assistant_representation_text", {
       responseItemByte: ids.get(item.id).start, completedEventByte: eventItems.get(item.id).start,
     });
   }

package/src/desktop-read-tools.mjs

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.mjs";
+import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
+import { ResponseSnapshots, responsePreferencesSchema, normalizeResponsePreferences, projectHistory, projectReply, assertResponseResultSize } from "./response-preferences.mjs";
+
+export function registerDesktopReadTools(registerTool, {
+  desktopTasksEnabled, desktopTasks, replyReceipts, security, client,
+  context: operationContext, assertOperation,
+  assertThreadAccess, normalizeThreadCwd, textResult, replyResult, failure,
+}) {
+  const snapshots = new ResponseSnapshots();
+  const invalid = (message) => Object.assign(new Error(message), { code: "INVALID_RESPONSE_PREFERENCES" });
+  const receiptHash = (delivered) => createHash("sha256").update(JSON.stringify(delivered)).digest("hex");
+  const binding = (operation) => {
+    const { accounts, caller } = operationContext();
+    return { operation, accounts, caller: { sessionId: caller.sessionId, taskId: caller.taskId, cwd: caller.cwd } };
+  };
+  const selector = (values) => Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+
+  async function authorize(auth, deliveryId) {
+    const context = operationContext();
+    await assertOperation(context);
+    if (deliveryId && receiptHash(replyReceipts.read(deliveryId, context)) !== auth.receiptHash) {
+      throw new Error("Reply observation binding changed; cached content was withheld");
+    }
+    if (auth.projectScope) recheckProjectScope(auth.projectScope);
+    if (auth.scopeBinding) security.hardenedRoots.recheck(auth.scopeBinding);
+    if (auth.threadId) {
+      const current = await desktopTasks.inspect(auth.threadId, auth.cwd, { deadline: context.deadline });
+      if (auth.projectScope) recheckProjectScope(auth.projectScope, current.projectScope);
+      if (auth.scopeBinding) security.hardenedRoots.recheck(auth.scopeBinding);
+    }
+    await assertOperation(context);
+  }
+
+  async function authorization(threadId, cwd, deliveryId, originalReceipt) {
+    const inspected = threadId ? await desktopTasks.inspect(threadId, cwd, { deadline: operationContext().deadline }) : null;
+    return { threadId, cwd: inspected?.thread.cwd ?? cwd, projectScope: inspected?.projectScope ?? captureProjectScope(operationContext().caller.cwd, cwd),
+      scopeBinding: inspected?.scopeBinding ?? (security.hardenedRoots?.mode === "project-policy" ? security.hardenedRoots.capture(cwd) : undefined), ...(deliveryId ? { receiptHash: receiptHash(originalReceipt) } : {}) };
+  }
+
+  async function continuation(preferences, owner, selection, deliveryId) {
+    const cached = snapshots.inspect(preferences, owner, selection);
+    await authorize(cached.authorization, deliveryId);
+    const result = snapshots.continue({ preferences, binding: owner, selection });
+    await authorize(cached.authorization, deliveryId);
+    return result;
+  }
+
+  async function respond({ preferences, owner, selection, metadata, items, auth, deliveryId }) {
+    await authorize(auth, deliveryId);
+    const result = snapshots.respond({ preferences, binding: owner, selection, metadata, items, authorization: auth });
+    await authorize(auth, deliveryId);
+    return result;
+  }
+
+  async function preferredRead({ threadId, turnId, limit, responsePreferences }) {
+    const owner = binding("read_codex_thread");
+    const selection = selector({ threadId, turnId, limit });
+    if (responsePreferences.delivery?.options?.cursor) return continuation(responsePreferences, owner, selection);
+    const preferences = normalizeResponsePreferences(responsePreferences);
+    const auth = await authorization(threadId);
+    const deadline = operationContext().deadline;
+    if (turnId) {
+      const response = await desktopTasks.inspectNativeTurn(threadId, turnId, auth.cwd, { deadline });
+      const { assistantItems, text, ...metadata } = response;
+      return respond({ preferences, owner, selection: { ...selection, limit: limit ?? 10 }, auth,
+        metadata: { ...metadata, threadId, turnId, turnStatus: response.turnStatus ?? (["completed", "completed_no_reply"].includes(response.status) ? "completed" : null) },
+        items: projectReply(assistantItems ?? [], turnId) });
+    }
+    const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10), includeOutputs: preferences.filter.includeToolPayloads, maxOutputCharsPerItem: 16000 }, { deadline });
+    const projected = projectHistory(response.turns ?? [], preferences.filter);
+    return respond({ preferences, owner, selection: { ...selection, limit: limit ?? 10 }, auth,
+      metadata: { threadId, turnId: response.turns?.[0]?.id ?? null, turnStatus: response.turns?.[0]?.status ?? null,
+        turns: projected.turns, sourceHasMore: response.page?.hasMore ?? Boolean(response.page?.nextCursor), omissions: projected.omissions },
+      items: projected.items });
+  }
+
+  async function preferredWait({ deliveryId, timeoutSec, responsePreferences }) {
+    const owner = binding("wait_codex_reply");
+    const selection = { deliveryId };
+    if (responsePreferences.delivery?.options?.cursor) {
+      if (timeoutSec !== undefined) throw invalid("A cursor reads a snapshot; omit timeoutSec on continuation");
+      return continuation(responsePreferences, owner, selection, deliveryId);
+    }
+    const preferences = normalizeResponsePreferences(responsePreferences);
+    const context = operationContext();
+    const originalReceipt = replyReceipts.read(deliveryId, context);
+    let delivered = originalReceipt;
+    // Leave time for the live authorization checks after observation.
+    const remaining = Math.max(0, context.deadline - Date.now());
+    const observationDeadline = context.deadline - Math.min(1000, Math.floor(remaining / 4));
+    const timeout = () => ({ threadId: delivered.threadId, status: "timeout", responseStatus: "unavailable", text: "" });
+    if (delivered.creationObservation) {
+      delivered = await desktopTasks.resolveCreation(delivered, { deadline: observationDeadline }) ?? delivered;
+    }
+    const auth = await authorization(delivered.threadId, delivered.cwd, deliveryId, originalReceipt);
+    const finish = async (result) => {
+      const { text, assistantItems, activity, ...metadata } = result;
+      return respond({ preferences, owner, selection, auth, deliveryId,
+        metadata: { ...metadata, threadId: delivered.threadId, turnId: result.turnId ?? null,
+          turnStatus: ["completed", "interrupted", "failed"].includes(result.status) ? result.status : null, deliveryId,
+          deliveryStatus: ["completed", "completed_no_reply"].includes(result.responseStatus) ? "accepted" : delivered.deliveryStatus ?? "accepted",
+          nextAction: result.status === "timeout" ? "wait_codex_reply" : "none" },
+        items: projectReply(assistantItems ?? [], result.turnId) });
+    };
+    if (!delivered.threadId || Date.now() >= observationDeadline) return finish(timeout());
+    const result = await desktopTasks.withThread(delivered.threadId, () => desktopTasks.wait(delivered.threadId, {
+      timeoutMs: Math.max(0, observationDeadline - Date.now()), previousTurnId: delivered.previousTurnId,
+      responseObservation: delivered.responseObservation,
+    }), { deadline: observationDeadline, onDeadline: timeout });
+    return finish(result);
+  }
+registerTool(
+  "wait_codex_reply",
+  {
+    title: "Continue waiting for a Codex reply",
+    description: "Continue a Desktop creation or send using its deliveryId; an unconfirmed acknowledgement does not prove delivery, including after MCP reconnect. Never sends a message or creates a task. On timeout, call again with the same deliveryId; do not ask the user to fetch the answer or resend. Stops for approval, user input or a verification error. Only the original verified Claude session and accounts can use the receipt.",
+    inputSchema: {
+      responsePreferences: responsePreferencesSchema.optional().describe("Opt in to versioned filtered responses and cursor delivery; omitted preserves existing behavior. Inspect the returned envelope and follow nextCursor with the same tool and selector."),
+      deliveryId: z.string().uuid().describe("Exact deliveryId returned by send_to_codex_thread, delegate_to_codex or start_codex_thread"),
+      timeoutSec: z.number().int().min(1).max(40).optional().describe("Bounded observation time, default 40 seconds; repeat with the same receipt if still running"),
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  async ({ deliveryId, timeoutSec, responsePreferences }) => {
+    if (responsePreferences !== undefined) {
+      try {
+        if (!desktopTasksEnabled) throw invalid("responsePreferences requires Desktop native delivery");
+        return await preferredWait({ deliveryId, timeoutSec, responsePreferences });
+      } catch (error) { return failure(error); }
+    }
+    if (!desktopTasksEnabled) return failure(new Error("Reply continuations require Desktop native delivery"));
+    const context = operationContext();
+    let delivered = replyReceipts.read(deliveryId, context);
+    if (delivered.creationObservation) {
+      const resolved = await desktopTasks.resolveCreation(delivered, { deadline: context.deadline });
+      if (!resolved) return replyResult(delivered, deliveryId, { threadId: null, status: "timeout", responseStatus: "unavailable", text: "" });
+      delivered = resolved;
+    }
+    const { threadId } = delivered;
+    const expired = () => replyResult(delivered, deliveryId, { threadId, status: "timeout", responseStatus: "unavailable", text: "" });
+    return desktopTasks.withThread(threadId, async () => {
+      await desktopTasks.inspect(threadId, delivered.cwd, { deadline: context.deadline });
+      const result = await desktopTasks.wait(threadId, { timeoutMs: Math.max(0, context.deadline - Date.now()), previousTurnId: delivered.previousTurnId, responseObservation: delivered.responseObservation });
+      return replyResult(delivered, deliveryId, result);
+    }, { deadline: context.deadline, onDeadline: expired });
+  },
+);
+
+registerTool(
+  "read_codex_thread",
+  {
+    title: "Read a Codex thread",
+    description: "Read a Codex thread without sending anything. In Desktop mode, pass the exact turnId returned by send_to_codex_thread for authoritative assistant item IDs, text, and reply hash; without turnId the native recent-history view may omit items.",
+    inputSchema: {
+      responsePreferences: responsePreferencesSchema.optional().describe("Opt in to versioned filtered responses and cursor delivery; omitted preserves existing behavior. Inspect the returned envelope and follow nextCursor with the same tool and selector."),
+      threadId: z.string().describe("Codex thread id"),
+      turnId: z.string().optional().describe("Exact turn id to inspect authoritatively in Codex Desktop mode"),
+      limit: z.number().int().min(1).max(50).optional().describe("How many recent messages to show (default 10)"),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ threadId, turnId, limit, responsePreferences }) => {
+    try {
+      if (responsePreferences !== undefined) {
+        if (!desktopTasksEnabled) throw invalid("responsePreferences requires Desktop native delivery");
+        return await preferredRead({ threadId, turnId, limit, responsePreferences });
+      }
+      if (desktopTasksEnabled) {
+        const deadline = operationContext()?.deadline ?? Date.now() + DESKTOP_TOOL_BUDGET_MS;
+        if (turnId) {
+          const response = await desktopTasks.inspectNativeTurn(threadId, turnId, undefined, { deadline });
+          return assertResponseResultSize(textResult(JSON.stringify(response, null, 2), response.status === "unavailable"));
+        }
+        await desktopTasks.inspect(threadId, undefined, { deadline });
+        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10), includeOutputs: false, maxOutputCharsPerItem: 2000 }, { deadline });
+        return assertResponseResultSize(textResult(JSON.stringify(response, null, 2)));
+      }
+      await assertThreadAccess(threadId);
+      const res = await client.call("thread/read", { threadId, includeTurns: true });
+      const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
+      security.assertCwd(thread.cwd);
+      const items = (thread.turns ?? []).flatMap((t) => t.items ?? []);
+      const msgs = items
+        .filter((i) => i?.type === "agentMessage" || i?.type === "userMessage")
+        .slice(-(limit ?? 10))
+        .map((i) => {
+          const body =
+            i.type === "userMessage"
+              ? (i.content ?? [])
+                  .map((c) => (c.type === "text" ? c.text : `<${c.type}>`))
+                  .join(" ")
+              : (i.text ?? "");
+          return `[${i.type === "userMessage" ? "user" : "codex"}] ${body.trim()}`;
+        });
+      const header = `thread ${threadId}\n  title: ${thread.name ?? "(unnamed)"}\n  cwd: ${thread.cwd ?? "?"}\n  status: ${thread.status?.type ?? "?"}`;
+      return textResult(msgs.length ? `${header}\n\n${msgs.join("\n\n")}` : `${header}\n\n(no messages found)`);
+    } catch (err) {
+      return failure(err);
+    }
+  },
+);
+}

package/src/index.mjs

@@ -35,11 +35,12 @@ import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs"
 import { bridgeReadiness } from "./bridge-readiness.mjs";
 import { captureProjectScope } from "./project-scope.mjs";
 import { DesktopReplyReceipts } from "./desktop-reply-receipts.mjs";
+import { registerDesktopReadTools } from "./desktop-read-tools.mjs";
 import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.6";
+const VERSION = "1.22.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -109,7 +110,7 @@ function withheldDesktopResult(error, context) {
   const reason = (error?.message ?? "The calling session or accounts could not be reverified.").replace(/\s*No message was sent\./g, "");
   return {
     ...textResult(`${reason} ${context.dispatched ? "A Desktop operation may already have been dispatched. Its original destination and any creation receipt were preserved." : "No Desktop mutation was dispatched."} Reply content was withheld. Inspect the original task and do not resend automatically.`, true),
-    structuredContent: { accountContext: context.accounts, operation: { state: context.dispatched ? "dispatched_outcome_unverified" : "blocked", threadId: context.threadId ?? null } },
+    structuredContent: { ...failure(error).structuredContent, accountContext: context.accounts, operation: { state: context.dispatched ? "dispatched_outcome_unverified" : "blocked", threadId: context.threadId ?? null } },
   };
 }
 
@@ -137,7 +138,16 @@ const textResult = (text, isError = false) => ({
   ...(isError ? { isError: true } : {}),
 });
 
-const failure = (err) => textResult(`Codex bridge error: ${err?.message ?? String(err)}`, true);
+const failure = (err) => {
+  const result = textResult(`Codex bridge error: ${err?.message ?? String(err)}`, true);
+  for (let cause = err; cause; cause = cause.cause) {
+    if (["RESPONSE_TOO_LARGE", "INVALID_RESPONSE_PREFERENCES", "INVALID_CURSOR", "CURSOR_EXPIRED"].includes(cause.code)) {
+      result.structuredContent = { error: Object.fromEntries(["code", "boundary", "bytes", "limit"].filter((key) => cause[key] !== undefined).map((key) => [key, cause[key]])) };
+      break;
+    }
+  }
+  return result;
+};
 
 function replyResult(delivered, deliveryId, result, notes = []) {
   result = { activity: [], errors: [], ...result };
@@ -430,7 +440,7 @@ function registerTool(name, definition, handler) {
             await assertDesktopOperation(context);
             const result = await handler(...args);
             await assertDesktopOperation(context);
-            if (result.isError && !context.dispatched) {
+            if (result.isError && !context.dispatched && result.structuredContent?.responseVersion !== 1) {
               result.structuredContent = { ...result.structuredContent, accountContext: context.accounts, operation: { state: "blocked", threadId: context.threadId ?? null } };
             }
             return result;
@@ -447,6 +457,12 @@ function registerTool(name, definition, handler) {
   });
 }
 
+registerDesktopReadTools(registerTool, {
+  desktopTasksEnabled, desktopTasks, replyReceipts, security, client,
+  context: () => desktopOperation.getStore(), assertOperation: assertDesktopOperation,
+  assertThreadAccess, normalizeThreadCwd, textResult, replyResult, failure,
+});
+
 registerProjectOnboardingTools(registerTool, { beforePrepare: async () => {
   if (!desktopTasksEnabled || !desktopOperation.getStore()?.caller) throw new Error("Project onboarding requires a verified Desktop caller");
   await assertDesktopOperation(desktopOperation.getStore(), { verifyProcess: true });
@@ -691,35 +707,6 @@ registerTool(
   },
 );
 
-registerTool(
-  "wait_codex_reply",
-  {
-    title: "Continue waiting for a Codex reply",
-    description: "Continue a Desktop creation or send using its deliveryId; an unconfirmed acknowledgement does not prove delivery, including after MCP reconnect. Never sends a message or creates a task. On timeout, call again with the same deliveryId; do not ask the user to fetch the answer or resend. Stops for approval, user input or a verification error. Only the original verified Claude session and accounts can use the receipt.",
-    inputSchema: {
-      deliveryId: z.string().uuid().describe("Exact deliveryId returned by send_to_codex_thread, delegate_to_codex or start_codex_thread"),
-      timeoutSec: z.number().int().min(1).max(40).optional().describe("Bounded observation time, default 40 seconds; repeat with the same receipt if still running"),
-    },
-    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-  },
-  async ({ deliveryId }) => {
-    if (!desktopTasksEnabled) return failure(new Error("Reply continuations require Desktop native delivery"));
-    const context = desktopOperation.getStore();
-    let delivered = replyReceipts.read(deliveryId, context);
-    if (delivered.creationObservation) {
-      const resolved = await desktopTasks.resolveCreation(delivered, { deadline: context.deadline });
-      if (!resolved) return replyResult(delivered, deliveryId, { threadId: null, status: "timeout", responseStatus: "unavailable", text: "" });
-      delivered = resolved;
-    }
-    const { threadId } = delivered;
-    const expired = () => replyResult(delivered, deliveryId, { threadId, status: "timeout", responseStatus: "unavailable", text: "" });
-    return desktopTasks.withThread(threadId, async () => {
-      await desktopTasks.inspect(threadId, delivered.cwd, { deadline: context.deadline });
-      const result = await desktopTasks.wait(threadId, { timeoutMs: Math.max(0, context.deadline - Date.now()), previousTurnId: delivered.previousTurnId, responseObservation: delivered.responseObservation });
-      return replyResult(delivered, deliveryId, result);
-    }, { deadline: context.deadline, onDeadline: expired });
-  },
-);
 
 registerTool(
   "list_codex_threads",
@@ -851,61 +838,6 @@ registerTool(
   },
 );
 
-registerTool(
-  "read_codex_thread",
-  {
-    title: "Read a Codex thread",
-    description: "Read a Codex thread without sending anything. In Desktop mode, pass the exact turnId returned by send_to_codex_thread for authoritative assistant item IDs, text, and reply hash; without turnId the native recent-history view may omit items.",
-    inputSchema: {
-      threadId: z.string().describe("Codex thread id"),
-      turnId: z.string().optional().describe("Exact turn id to inspect authoritatively in Codex Desktop mode"),
-      limit: z.number().int().min(1).max(50).optional().describe("How many recent messages to show (default 10)"),
-    },
-    annotations: {
-      readOnlyHint: true,
-      openWorldHint: true,
-    },
-  },
-  async ({ threadId, turnId, limit }) => {
-    try {
-      if (desktopTasksEnabled) {
-        const deadline = desktopOperation.getStore()?.deadline ?? Date.now() + DESKTOP_TOOL_BUDGET_MS;
-        if (turnId) {
-          const response = await desktopTasks.inspectNativeTurn(threadId, turnId, undefined, { deadline });
-          return textResult(JSON.stringify(response, null, 2), response.status === "unavailable");
-        }
-        await desktopTasks.inspect(threadId, undefined, { deadline });
-        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10), includeOutputs: false, maxOutputCharsPerItem: 2000 }, { deadline });
-        const result = textResult(JSON.stringify(response, null, 2));
-        if (Buffer.byteLength(JSON.stringify(result), "utf8") > 8 * 1024 * 1024) {
-          return textResult("DESKTOP_READ_RESPONSE_TOO_LARGE: The formatted Desktop read exceeds 8 MiB. Read fewer turns with limit: 1 or select a specific turnId.", true);
-        }
-        return result;
-      }
-      await assertThreadAccess(threadId);
-      const res = await client.call("thread/read", { threadId, includeTurns: true });
-      const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
-      security.assertCwd(thread.cwd);
-      const items = (thread.turns ?? []).flatMap((t) => t.items ?? []);
-      const msgs = items
-        .filter((i) => i?.type === "agentMessage" || i?.type === "userMessage")
-        .slice(-(limit ?? 10))
-        .map((i) => {
-          const body =
-            i.type === "userMessage"
-              ? (i.content ?? [])
-                  .map((c) => (c.type === "text" ? c.text : `<${c.type}>`))
-                  .join(" ")
-              : (i.text ?? "");
-          return `[${i.type === "userMessage" ? "user" : "codex"}] ${body.trim()}`;
-        });
-      const header = `thread ${threadId}\n  title: ${thread.name ?? "(unnamed)"}\n  cwd: ${thread.cwd ?? "?"}\n  status: ${thread.status?.type ?? "?"}`;
-      return textResult(msgs.length ? `${header}\n\n${msgs.join("\n\n")}` : `${header}\n\n(no messages found)`);
-    } catch (err) {
-      return failure(err);
-    }
-  },
-);
 
 registerTool(
   "interrupt_codex_turn",

package/src/native-relay-companion.mjs

@@ -8,8 +8,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 import {
-  MAX_FRAME_BYTES,
+  MAX_REQUEST_FRAME_BYTES,
   MAX_RESPONSE_FRAME_BYTES,
+  responseTooLargeError,
   NATIVE_DISPATCH_METHOD,
   NativeToolsClient,
   NativeRelayError,
@@ -37,11 +38,12 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.6";
+const VERSION = "1.22.1";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
-function errorResponse(code, message, sent) {
-  return { ok: false, v: RELAY_PROTOCOL_VERSION, error: { code, message, ...(sent === false ? { sent: false } : {}) } };
+function errorResponse(code, message, sent, details) {
+  const size = code === "RESPONSE_TOO_LARGE" && details ? { boundary: details.boundary, bytes: details.bytes, limit: details.limit } : {};
+  return { ok: false, v: RELAY_PROTOCOL_VERSION, error: { code, message, ...size, ...(sent === false ? { sent: false } : {}) } };
 }
 
 function boundRequest(payload) {
@@ -266,7 +268,7 @@ export async function handleRelayRequest(
     var authorization;
     if (strict) authorization = await authorize({ executorThreadId, targetThreadId, operation: "send_message_to_thread", accountContext });
   } catch (err) {
-    return errorResponse(errorCode(err), err.message, false);
+    return errorResponse(errorCode(err), err.message, false, err);
   }
 
   /**
@@ -294,7 +296,7 @@ export async function handleRelayRequest(
     }
     return { ok: true, v: boundRequest(payload) ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, targetThreadId, executorThreadId, result: result ?? null };
   } catch (err) {
-    return errorResponse(errorCode(err), err?.message ?? String(err), err?.sent === false && err?.reachedCompanion !== true ? false : undefined);
+    return errorResponse(errorCode(err), err?.message ?? String(err), err?.sent === false && err?.reachedCompanion !== true ? false : undefined, err);
   }
 }
 
@@ -311,7 +313,7 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
     try {
       accountContext = await checkAccountContext(payload, assertAccount);
     } catch (error) {
-      return errorResponse(errorCode(error), error.message, false);
+      return errorResponse(errorCode(error), error.message, false, error);
     }
     if (typeof dispatchDesktop !== "function") {
       return errorResponse("NATIVE_OPERATION_UNAVAILABLE", "This companion does not support Desktop operations; reload the native relay");
@@ -365,7 +367,7 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
       throw error;
     }
   } catch (err) {
-    return errorResponse(errorCode(err), err?.message ?? String(err), err?.sent === false && err?.reachedCompanion !== true ? false : undefined);
+    return errorResponse(errorCode(err), err?.message ?? String(err), err?.sent === false && err?.reachedCompanion !== true ? false : undefined, err);
   }
 }
 
@@ -568,9 +570,9 @@ export class RelaySocketServer {
     socket.on("data", (chunk) => {
       if (handled) return;
       buffer = Buffer.concat([buffer, chunk]);
-      if (buffer.length > MAX_FRAME_BYTES) {
+      if (buffer.length > MAX_REQUEST_FRAME_BYTES) {
         handled = true;
-        this.#reply(socket, errorResponse("RELAY_MESSAGE_TOO_LARGE", `a relay frame may not exceed ${MAX_FRAME_BYTES} bytes`));
+        this.#reply(socket, errorResponse("RELAY_MESSAGE_TOO_LARGE", `a relay frame may not exceed ${MAX_REQUEST_FRAME_BYTES} bytes`));
         return;
       }
       const index = buffer.indexOf(10);
@@ -614,12 +616,13 @@ export class RelaySocketServer {
 
   #reply(socket, response) {
     if (socket.destroyed) return;
-    const frame = `${JSON.stringify(response)}\n`;
-    if (Buffer.byteLength(frame, "utf8") > MAX_RESPONSE_FRAME_BYTES) {
-      socket.end(`${JSON.stringify(errorResponse("RELAY_RESPONSE_TOO_LARGE", `The native relay response exceeds ${MAX_RESPONSE_FRAME_BYTES} bytes; reduce the requested turns or outputs`))}\n`);
-      return;
+    let line = `${JSON.stringify(response)}\n`;
+    const bytes = Buffer.byteLength(line, "utf8");
+    if (bytes > MAX_RESPONSE_FRAME_BYTES) {
+      const error = responseTooLargeError("companion-to-bridge", bytes);
+      line = `${JSON.stringify({ ...errorResponse(error.code, error.message, undefined, error), v: response.v })}\n`;
     }
-    socket.end(frame);
+    socket.end(line);
   }
 
   stop() {

package/src/native-relay.mjs

@@ -39,8 +39,10 @@ export const NATIVE_DISPATCH_METHOD = "tools/call";
 export const RELAY_PROTOCOL_VERSION = 1;
 export const ACCOUNT_RELAY_PROTOCOL_VERSION = 2;
 
-export const MAX_FRAME_BYTES = 128 * 1024;
+// Requests carry commands; responses may contain a long Desktop history.
+export const MAX_REQUEST_FRAME_BYTES = 128 * 1024;
 export const MAX_RESPONSE_FRAME_BYTES = 8 * 1024 * 1024;
+export const MAX_FRAME_BYTES = MAX_REQUEST_FRAME_BYTES;
 
 const DEFAULT_TIMEOUT_MS = 30000;
 const RELAY_SOCKET_NAME = "native-relay.sock";
@@ -48,14 +50,21 @@ const WINDOWS_RELAY_SOCKET = "\\\\.\\pipe\\LOCAL\\codex-native-relay";
 const RELAY_CONFIG_NAME = "native-relay.json";
 
 export class NativeRelayError extends Error {
-  constructor(message, code, { reachedCompanion = false } = {}) {
+  constructor(message, code, { reachedCompanion = false, boundary, bytes, limit } = {}) {
     super(message);
     this.name = "NativeRelayError";
     this.code = code;
     this.reachedCompanion = reachedCompanion;
+    if (boundary !== undefined) this.boundary = boundary;
+    if (bytes !== undefined) this.bytes = bytes;
+    if (limit !== undefined) this.limit = limit;
   }
 }
 
+export function responseTooLargeError(boundary, bytes, limit = MAX_RESPONSE_FRAME_BYTES) {
+  return new NativeRelayError(`Response at ${boundary} exceeds ${limit} bytes (${bytes} bytes received or required); reduce the requested turns or outputs`, "RESPONSE_TOO_LARGE", { boundary, bytes, limit, reachedCompanion: true });
+}
+
 export function codexHome(env = process.env) {
   return env.CODEX_HOME ?? path.join(homeDir(), ".codex");
 }
@@ -81,7 +90,7 @@ export function relayAccountContext(value) {
 }
 
 function beforeWriteError(error) {
-  const failure = new NativeRelayError(error?.message ?? "Relay preflight failed before dispatch", typeof error?.code === "string" ? error.code : "RELAY_PREFLIGHT_FAILED", { reachedCompanion: false });
+  const failure = new NativeRelayError(error?.message ?? "Relay preflight failed before dispatch", typeof error?.code === "string" ? error.code : "RELAY_PREFLIGHT_FAILED", { ...error, reachedCompanion: false });
   failure.sent = false;
   return failure;
 }
@@ -613,7 +622,7 @@ export class NativeToolsClient {
         while (buffer.length >= 4) {
           const length = buffer.readUInt32LE(0);
           if (length > MAX_RESPONSE_FRAME_BYTES) {
-            fail(new NativeRelayError(`Codex Desktop native response exceeds ${MAX_RESPONSE_FRAME_BYTES} bytes; reduce the requested turns or outputs`, "NATIVE_RESPONSE_TOO_LARGE"));
+            fail(responseTooLargeError("native-pipe", length));
             return;
           }
           if (!length) {
@@ -674,7 +683,7 @@ export class NativeToolsClient {
       method: this.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
       params,
     }));
-    if (payload.length > MAX_FRAME_BYTES) {
+    if (payload.length > MAX_REQUEST_FRAME_BYTES) {
       throw new NativeRelayError("Native dispatch exceeds the frame limit", "RELAY_MESSAGE_TOO_LARGE");
     }
     try {
@@ -819,9 +828,9 @@ export class NativeDesktopRelay {
   async #request(request, timeoutMs, beforeSend) {
     validateBeforeSend(beforeSend);
     const line = `${JSON.stringify(request)}\n`;
-    if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
+    if (Buffer.byteLength(line, "utf8") > MAX_REQUEST_FRAME_BYTES) {
       throw new NativeRelayError(
-        `Relay message is larger than ${MAX_FRAME_BYTES} bytes; shorten it before relaying.`,
+        `Relay message is larger than ${MAX_REQUEST_FRAME_BYTES} bytes; shorten it before relaying.`,
         "RELAY_MESSAGE_TOO_LARGE",
       );
     }
@@ -834,7 +843,7 @@ export class NativeDesktopRelay {
     const error = new NativeRelayError(
       response?.error?.message ?? "the Codex Desktop relay refused the message",
       response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
-      { reachedCompanion: response?.error?.sent !== false },
+      { boundary: response?.error?.boundary, bytes: response?.error?.bytes, limit: response?.error?.limit, reachedCompanion: response?.error?.sent !== false },
     );
     if (response?.error?.sent === false) error.sent = false;
     throw error;
@@ -888,12 +897,7 @@ export class NativeDesktopRelay {
         const newline = chunk.indexOf(10);
         const frameChunk = newline < 0 ? chunk : chunk.subarray(0, newline + 1);
         if (buffer.length + frameChunk.length > MAX_RESPONSE_FRAME_BYTES) {
-          finish(
-            reject,
-            new NativeRelayError(`The Codex Desktop relay response exceeds ${MAX_RESPONSE_FRAME_BYTES} bytes; reduce the requested turns or outputs`, "RELAY_RESPONSE_TOO_LARGE", {
-              reachedCompanion: true,
-            }),
-          );
+          finish(reject, responseTooLargeError("companion-to-bridge", buffer.length + frameChunk.length));
           return;
         }
         buffer = Buffer.concat([buffer, frameChunk]);

package/src/response-preferences.mjs

@@ -0,0 +1,233 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+
+export const DEFAULT_PAGE_BYTES = 64 * 1024;
+export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export const responsePreferencesSchema = z.object({
+  delivery: z.object({
+    type: z.literal('cursorPagination'),
+    options: z.object({
+      maxBytes: z.number().int().min(8 * 1024).max(96 * 1024).optional(),
+      cursor: z.string().min(1).max(512).optional(),
+    }).strict().optional(),
+  }).strict().optional(),
+  filter: z.object({
+    includeReasoning: z.boolean().optional(),
+    includeToolPayloads: z.boolean().optional(),
+  }).strict().optional(),
+}).strict();
+
+function failure(code, message, details = {}) {
+  return Object.assign(new Error(message), { code, ...details });
+}
+function parsePreferences(input) {
+  const result = responsePreferencesSchema.safeParse(input);
+  if (!result.success) throw failure('INVALID_RESPONSE_PREFERENCES', result.error.message);
+  return result.data;
+}
+export function normalizeResponsePreferences(input) {
+  if (input === undefined) return undefined;
+  const value = parsePreferences(input);
+  return {
+    ...(value.delivery ? { delivery: { type: 'cursorPagination', options: { maxBytes: value.delivery.options?.maxBytes ?? DEFAULT_PAGE_BYTES } } } : {}),
+    filter: { includeReasoning: value.filter?.includeReasoning ?? true, includeToolPayloads: value.filter?.includeToolPayloads ?? false },
+  };
+}
+const scalar = value => value === null || ['string', 'number', 'boolean'].includes(typeof value);
+function pick(value, keys) {
+  return Object.fromEntries(keys.filter(key => value?.[key] !== undefined && scalar(value[key])).map(key => [key, value[key]]));
+}
+const IDENTITY = ['id', 'type', 'name', 'status', 'startedAt', 'completedAt', 'createdAt', 'updatedAt', 'timestamp', 'durationMs', 'exitCode'];
+const TOOL_TYPES = new Set(['commandExecution', 'mcpToolCall', 'dynamicToolCall', 'fileChange', 'collabAgentToolCall', 'webSearch', 'imageView', 'imageGeneration', 'function_call', 'function_call_output', 'tool_call', 'tool_result', 'functionCall', 'functionCallOutput', 'subAgentActivity', 'contextCompaction', 'sleep']);
+const MESSAGE_TYPES = new Set(['agentMessage', 'userMessage', 'assistantMessage', 'message', 'commentary']);
+
+export function projectHistory(turns, filter = { includeReasoning: true, includeToolPayloads: false }) {
+  const omissions = { reasoningRecords: 0, toolPayloadRecords: 0, unknownRecords: 0 };
+  const headers = [], items = [];
+  for (const turn of turns) {
+    const turnId = typeof turn.id === 'string' ? turn.id : typeof turn.turnId === 'string' ? turn.turnId : null;
+    headers.push({ ...pick(turn, ['id', 'turnId', 'status', 'startedAt', 'completedAt', 'createdAt', 'updatedAt', 'timestamp']), turnId });
+    const source = Array.isArray(turn.items) ? turn.items : [];
+    for (let index = source.length - 1; index >= 0; index--) {
+      const raw = source[index];
+      if (!raw || typeof raw !== 'object') { omissions.unknownRecords++; continue; }
+      let item;
+      if (raw.type === 'reasoning') {
+        if (!filter.includeReasoning) { omissions.reasoningRecords++; continue; }
+        item = raw;
+      } else if (MESSAGE_TYPES.has(raw.type)) item = raw;
+      else if (TOOL_TYPES.has(raw.type)) {
+        if (filter.includeToolPayloads) item = raw;
+        else {
+          omissions.toolPayloadRecords++;
+          item = pick(raw, [...IDENTITY, 'tool', 'server', 'callId', 'processId', 'cwd', 'path', 'kind', 'agentId', 'agentThreadId', 'agentPath', 'namespace', 'receiverThreadId', 'senderThreadId']);
+          if (Array.isArray(raw.changes)) item.changes = raw.changes.map(change => ({
+            ...pick(change, ['path', 'kind']),
+            ...(change?.kind && typeof change.kind === 'object' ? { kind: pick(change.kind, ['type', 'movePath']) } : {}),
+          }));
+        }
+      } else { omissions.unknownRecords++; item = pick(raw, IDENTITY); }
+      items.push({ turnId, itemId: typeof raw.id === 'string' ? raw.id : `${turnId}:${index}`, sourceIndex: index, item });
+    }
+  }
+  return { turns: headers, items, omissions };
+}
+export function projectReply(assistantItems, turnId) {
+  return assistantItems.map((item, sourceIndex) => ({ turnId, itemId: item.id ?? `${turnId}:${sourceIndex}`, sourceIndex, item: { type: 'agentMessage', text: item.text } }));
+}
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => [key, stable(value[key])]));
+  return value;
+}
+const encode = value => JSON.stringify(stable(value));
+export function responseResult(envelope) {
+  return { content: [{ type: 'text', text: JSON.stringify(envelope) }], structuredContent: envelope, ...(['unavailable', 'failed', 'systemError'].includes(envelope.status) ? { isError: true } : {}) };
+}
+const size = value => Buffer.byteLength(JSON.stringify(value));
+function oversize(bytes, limit) {
+  return failure('RESPONSE_TOO_LARGE', `Response requires ${bytes} bytes; limit is ${limit}`, { boundary: 'mcp_tool_result', bytes, limit });
+}
+export function assertResponseResultSize(result) {
+  const bytes = size(result);
+  if (bytes > MAX_RESPONSE_BYTES) throw oversize(bytes, MAX_RESPONSE_BYTES);
+  return result;
+}
+
+// The caller checks live scope and receipt ownership before and after each store operation.
+export class ResponseSnapshots {
+  constructor({ now = Date.now, maxCacheBytes = 32 * 1024 * 1024, ttlMs = 30 * 60 * 1000 } = {}) {
+    this.now = now;
+    this.maxCacheBytes = maxCacheBytes;
+    this.ttlMs = ttlMs;
+    this.snapshots = new Map();
+    this.cacheBytes = 0;
+  }
+  clear() { this.snapshots.clear(); this.cacheBytes = 0; }
+  remove(id) {
+    const entry = this.snapshots.get(id);
+    if (entry) { this.cacheBytes -= entry.bytes; this.snapshots.delete(id); }
+  }
+  prune() {
+    for (const [id, entry] of this.snapshots) if (entry.expires <= this.now()) this.remove(id);
+  }
+  token(entry, index, offset) {
+    const value = `${entry.id}.${index}.${offset}`;
+    return `${value}.${createHmac('sha256', entry.secret).update(value).digest('base64url')}`;
+  }
+  lookup(preferences, binding, selection) {
+    const requested = parsePreferences(preferences);
+    const cursor = requested.delivery?.options?.cursor;
+    const match = typeof cursor === 'string' && /^([A-Za-z0-9_-]{32})\.(\d+)\.(\d+)\.([A-Za-z0-9_-]{43})$/.exec(cursor);
+    if (!match) throw failure('INVALID_CURSOR', 'Invalid response cursor');
+    this.prune();
+    const entry = this.snapshots.get(match[1]);
+    if (!entry) throw failure('CURSOR_EXPIRED', 'Response snapshot expired or is no longer available');
+    if (entry.binding !== encode(binding)) throw failure('INVALID_CURSOR', 'Cursor does not belong to this caller');
+    const index = Number(match[2]), offset = Number(match[3]);
+    const expected = this.token(entry, index, offset);
+    if (cursor.length !== expected.length || !timingSafeEqual(Buffer.from(cursor), Buffer.from(expected))) throw failure('INVALID_CURSOR', 'Invalid response cursor');
+    const originalSelection = JSON.parse(entry.selection);
+    for (const [key, value] of Object.entries(selection ?? {})) {
+      if (value !== undefined && encode(value) !== encode(originalSelection[key])) throw failure('INVALID_CURSOR', `Cursor conflicts with selector ${key}`);
+    }
+    const original = JSON.parse(entry.preferences);
+    if (requested.delivery.options?.maxBytes !== undefined && requested.delivery.options.maxBytes !== original.delivery.options.maxBytes) throw failure('INVALID_CURSOR', 'Cursor conflicts with page budget');
+    for (const [key, value] of Object.entries(requested.filter ?? {})) {
+      if (value !== original.filter[key]) throw failure('INVALID_CURSOR', `Cursor conflicts with filter ${key}`);
+    }
+    return { entry, index, offset };
+  }
+  inspect(preferences, binding, selection) {
+    const { entry } = this.lookup(preferences, binding, selection);
+    return { selection: JSON.parse(entry.selection), metadata: JSON.parse(entry.metadata), authorization: JSON.parse(entry.authorization) };
+  }
+  continue({ preferences, binding, selection }) {
+    const { entry, index, offset } = this.lookup(preferences, binding, selection);
+    const result = this.render(entry, index, offset);
+    this.snapshots.delete(entry.id);
+    this.snapshots.set(entry.id, entry);
+    return result;
+  }
+  respond({ preferences, binding, selection, metadata = {}, items, authorization = null }) {
+    const supplied = parsePreferences(preferences);
+    if (supplied.delivery?.options?.cursor) throw failure('INVALID_CURSOR', 'Use continuation for a response cursor');
+    const applied = normalizeResponsePreferences(supplied);
+    const now = this.now();
+    const entry = {
+      id: randomBytes(24).toString('base64url'), secret: randomBytes(32),
+      binding: encode(binding), selection: encode(selection ?? {}), authorization: encode(authorization),
+      metadata: JSON.stringify({ ...metadata, responseVersion: 1, snapshotAt: new Date(now).toISOString(), appliedResponsePreferences: applied }),
+      preferences: JSON.stringify(applied), expires: now + this.ttlMs,
+      records: items.map(({ item, ...header }) => ({ header: JSON.stringify(header), body: Buffer.from(JSON.stringify(item), 'utf8') })),
+    };
+    entry.bytes = Buffer.byteLength(entry.binding + entry.selection + entry.authorization + entry.metadata + entry.preferences + entry.id) + entry.secret.length + entry.records.reduce((total, record) => total + Buffer.byteLength(record.header) + record.body.length + 32, 0);
+    if (!applied.delivery) {
+      const result = responseResult({ ...JSON.parse(entry.metadata), items: entry.records.map(record => ({ ...JSON.parse(record.header), item: JSON.parse(record.body.toString('utf8')) })), page: { complete: true, nextCursor: null, remainingItems: 0, expiresAt: null } });
+      return assertResponseResultSize(result);
+    }
+    const result = this.render(entry, 0, 0);
+    if (result.structuredContent.page.complete) return result;
+    const limit = applied.delivery.options.maxBytes;
+    const maximumOffset = entry.records.reduce((maximum, record) => Math.max(maximum, record.body.length), 0);
+    const page = { ...result.structuredContent.page, nextCursor: this.token(entry, entry.records.length, maximumOffset), remainingItems: entry.records.length };
+    for (const record of entry.records) {
+      const header = JSON.parse(record.header);
+      const measured = item => size(responseResult({ ...result.structuredContent, items: [item], page }));
+      if (record.body.length * 2 <= limit && measured({ ...header, item: JSON.parse(record.body.toString('utf8')) }) <= limit) continue;
+      // Reserve maximum offset/token widths and one four-byte code point before issuing any cursor.
+      const required = measured({ ...header, fragment: { encoding: 'json', offsetBytes: record.body.length, totalBytes: record.body.length, text: '🧑' } });
+      if (required > limit) throw oversize(required, limit);
+    }
+    if (entry.bytes > this.maxCacheBytes) throw oversize(entry.bytes, this.maxCacheBytes);
+    this.prune();
+    while (this.cacheBytes + entry.bytes > this.maxCacheBytes) this.remove(this.snapshots.keys().next().value);
+    this.snapshots.set(entry.id, entry);
+    this.cacheBytes += entry.bytes;
+    return result;
+  }
+  render(entry, startIndex, startOffset) {
+    const metadata = JSON.parse(entry.metadata);
+    const limit = metadata.appliedResponsePreferences.delivery.options.maxBytes;
+    const envelope = (items, index, offset) => {
+      const complete = index === entry.records.length;
+      return responseResult({ ...metadata, ...(metadata.deliveryId && !complete ? { nextAction: 'wait_codex_reply' } : {}), items, page: {
+        complete, nextCursor: complete ? null : this.token(entry, index, offset), remainingItems: entry.records.length - index,
+        expiresAt: complete ? null : new Date(entry.expires).toISOString(),
+      } });
+    };
+    let index = startIndex, offset = startOffset;
+    const items = [];
+    let result = envelope(items, index, offset);
+    if (index === entry.records.length && size(result) > limit) throw oversize(size(result), limit);
+    while (index < entry.records.length) {
+      const record = entry.records[index], header = JSON.parse(record.header);
+      if (!offset) {
+        const complete = { ...header, item: JSON.parse(record.body.toString('utf8')) };
+        const candidate = envelope([...items, complete], index + 1, 0);
+        if (size(candidate) <= limit) { items.push(complete); index++; result = candidate; continue; }
+        if (items.length && size(envelope([complete], index + 1, 0)) <= limit) break;
+      }
+      const fragmentAt = end => ({ ...header, fragment: { encoding: 'json', offsetBytes: offset, totalBytes: record.body.length, text: record.body.subarray(offset, end).toString('utf8') } });
+      const candidateAt = end => envelope([...items, fragmentAt(end)], end === record.body.length ? index + 1 : index, end === record.body.length ? 0 : end);
+      let low = offset + 1, high = record.body.length, best = offset;
+      while (low <= high) {
+        const middle = Math.floor((low + high) / 2);
+        let end = middle;
+        while (end > offset && end < record.body.length && (record.body[end] & 0xc0) === 0x80) end--;
+        if (end > offset && size(candidateAt(end)) <= limit) { best = Math.max(best, end); low = middle + 1; }
+        else if (end === offset) low = middle + 1;
+        else high = middle - 1;
+      }
+      if (best === offset) {
+        if (!items.length) throw oversize(size(candidateAt(Math.min(record.body.length, offset + 4))), limit);
+        break;
+      }
+      items.push(fragmentAt(best));
+      if (best === record.body.length) { index++; offset = 0; } else offset = best;
+      result = envelope(items, index, offset);
+      if (offset) break;
+    }
+    return result;
+  }
+}

package/src/thread-delivery.mjs

@@ -119,6 +119,7 @@ export class DesktopTaskDelivery {
       });
       return includeRelayContext ? { result: response.result, executorThreadId: response.executorThreadId } : response.result;
     } catch (err) {
+      if (err.code === "RESPONSE_TOO_LARGE") throw err;
       if (err.code?.startsWith("PROJECT_SCOPE_") || err.code === "CLAUDE_SENDER_CONTEXT_UNVERIFIED") throw err;
       throw new Error(`Codex Desktop operation ${operation} failed: ${err.message}. Desktop-only mode will not start or use an external app-server. Open Codex Desktop and reconnect its native relay, then inspect the existing task before retrying a send.`, { cause: err });
     }