@minhspark/codex-mcp-bridge 1.21.5 → 1.22.0

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.5";
+const VERSION = "1.22.0";
 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,57 +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) }, { deadline });
-        return 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);
-    }
-  },
-);
 
 registerTool(
   "interrupt_codex_turn",

package/src/native-relay-companion.mjs

@@ -8,7 +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,
@@ -36,11 +38,12 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.22.0";
 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) {
@@ -102,7 +105,7 @@ export function createNativeScopeAuthorizer({ dispatchDesktop, env = process.env
   };
   const threadFor = async (executorThreadId, threadId, accountContext, projects) => {
     if (typeof threadId !== "string" || !threadId) fail("Operation has no target task");
-    const result = await call(executorThreadId, "read_thread", { threadId, hostId: "local", turnLimit: 1 }, accountContext);
+    const result = await call(executorThreadId, "read_thread", { threadId, hostId: "local", turnLimit: 1, includeOutputs: false, maxOutputCharsPerItem: 1 }, accountContext);
     return validateThread(result?.thread, threadId, projects);
   };
   const targetIds = (operation, args, targetThreadId) => {
@@ -265,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);
   }
 
   /**
@@ -293,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);
   }
 }
 
@@ -310,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");
@@ -364,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);
   }
 }
 
@@ -567,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);
@@ -613,7 +616,13 @@ export class RelaySocketServer {
 
   #reply(socket, response) {
     if (socket.destroyed) return;
-    socket.end(`${JSON.stringify(response)}\n`);
+    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(line);
   }
 
   stop() {

package/src/native-relay.mjs

@@ -39,13 +39,10 @@ export const NATIVE_DISPATCH_METHOD = "tools/call";
 export const RELAY_PROTOCOL_VERSION = 1;
 export const ACCOUNT_RELAY_PROTOCOL_VERSION = 2;
 
-/**
- * A relay frame carries one chat message, so a megabyte-scale line is either a
- * bug or something trying to make the companion buffer without limit. The cap
- * is applied on both halves: the client refuses to send an oversized message,
- * and the companion refuses to accumulate one.
- */
-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";
@@ -53,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");
 }
@@ -86,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;
 }
@@ -617,7 +621,11 @@ export class NativeToolsClient {
         buffer = Buffer.concat([buffer, chunk]);
         while (buffer.length >= 4) {
           const length = buffer.readUInt32LE(0);
-          if (!length || length > MAX_FRAME_BYTES) {
+          if (length > MAX_RESPONSE_FRAME_BYTES) {
+            fail(responseTooLargeError("native-pipe", length));
+            return;
+          }
+          if (!length) {
             fail(new NativeRelayError("Invalid Codex Desktop native frame length", "NATIVE_BAD_RESPONSE"));
             return;
           }
@@ -675,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 {
@@ -820,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",
       );
     }
@@ -835,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;
@@ -885,16 +893,14 @@ export class NativeDesktopRelay {
         })();
       });
       socket.on("data", (chunk) => {
-        buffer = Buffer.concat([buffer, chunk]);
-        if (buffer.length > MAX_FRAME_BYTES) {
-          finish(
-            reject,
-            new NativeRelayError("The Codex Desktop relay answered with an oversized frame", "RELAY_BAD_RESPONSE", {
-              reachedCompanion: true,
-            }),
-          );
+        if (settled) return;
+        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, responseTooLargeError("companion-to-bridge", buffer.length + frameChunk.length));
           return;
         }
+        buffer = Buffer.concat([buffer, frameChunk]);
         const index = buffer.indexOf(10);
         if (index < 0) return;
         try {

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/rollout-segments.mjs

@@ -37,7 +37,7 @@ export function findRolloutSegments(sessions, threadId) {
       }
     }
   }
-  if (!matches.length) throw new Error("No rollout matches the calling Codex task");
+  if (!matches.length) throw new Error(`No rollout matches the calling Codex task [check=rollout_discovery; directoriesScanned=${directories}; entriesScanned=${entries}; layout=sessions/YYYY/MM/DD/rollout-*-taskId[_continuationId].jsonl]`);
   return matches.sort();
 }