@minhspark/codex-mcp-bridge 1.22.12 → 1.22.14

package/src/rollout-reader.mjs

@@ -1,31 +1,40 @@
 import fs from "node:fs";
+import zlib from "node:zlib";
 import { fileIdentity } from "./file-identity.mjs";
 
 const CHUNK_BYTES = 256 * 1024;
+const COMPRESSED_SUFFIX = ".zst";
 const VERSION_FIELDS = ["size", "mtimeNs", "ctimeNs", "ino", "dev"];
 const sameVersion = (a, b) => VERSION_FIELDS.every((key) => a[key] === b[key]);
+const versionKey = (version) => VERSION_FIELDS.map((key) => String(version[key])).join(":");
+const VANISHED_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const COMPRESSED_SCAN_CACHE_ENTRIES = 16;
+const compressedScans = new Map();
 
-// Scan the complete history, but retain at most one bounded JSONL record.
-// Skipping the middle of a rollout would miss duplicate identities or corruption.
-export function scanRollout(file, { maxRecordBytes, onRecord, onChunk = () => {} }) {
-  if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1) throw new Error("The rollout record read limit is invalid");
-  const named = fs.lstatSync(file, { bigint: true });
-  if (!named.isFile() || named.isSymbolicLink()) throw new Error("The rollout is not a regular file");
-  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
-  try {
-    const before = fs.fstatSync(descriptor, { bigint: true });
-    if (!before.isFile()) throw new Error("The opened rollout is not a regular file");
-    if (!sameVersion(named, before)) throw new Error("The rollout changed while opening");
-    if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("The rollout exceeds the safe size range");
-    const size = Number(before.size);
-    if (size === 0) throw new Error("The rollout is empty (0 bytes)");
-    let parts = [], length = 0, start = 0, position = 0;
-    const decoder = new TextDecoder("utf-8", { fatal: true });
-    while (position < size) {
-      const buffer = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, size - position));
-      const count = fs.readSync(descriptor, buffer, 0, buffer.length, position);
-      if (!count) throw new Error("The rollout changed while reading");
-      const chunk = buffer.subarray(0, count);
+export const MAX_DECOMPRESSED_ROLLOUT_BYTES = 256 * 1024 * 1024;
+
+export function isCompressedRollout(file) {
+  return typeof file === "string" && file.endsWith(`.jsonl${COMPRESSED_SUFFIX}`);
+}
+
+export function rolloutBasePath(file) {
+  return isCompressedRollout(file) ? file.slice(0, -COMPRESSED_SUFFIX.length) : file;
+}
+
+export function asRolloutChange(error, message = "The rollout changed while reading") {
+  return VANISHED_CODES.has(error?.code) ? new Error(message) : error;
+}
+
+function zstdUnsupported() {
+  return new Error(`Reading a compressed Codex rollout (.jsonl.zst) requires Node.js with zstd support (22.15+ or 23.8+); this runtime is ${process.version} [check=rollout_zstd_unsupported]`);
+}
+
+function recordParser(size, { maxRecordBytes, onRecord, onChunk }) {
+  let parts = [], length = 0, start = 0;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  return {
+    push(chunk, position) {
+      const count = chunk.length;
       onChunk(chunk, position);
       let offset = 0;
       while (offset < count) {
@@ -46,15 +55,142 @@ export function scanRollout(file, { maxRecordBytes, onRecord, onChunk = () => {}
         offset = newline + 1;
         start = position + offset;
       }
-      position += count;
+    },
+    finish() {
+      if (start !== size) throw new Error("The rollout has an incomplete final record");
+    },
+  };
+}
+
+function readExactly(descriptor, size) {
+  const buffer = Buffer.allocUnsafe(size);
+  for (let position = 0; position < size;) {
+    const count = fs.readSync(descriptor, buffer, position, size - position, position);
+    if (!count) throw new Error("The rollout changed while reading");
+    position += count;
+  }
+  return buffer;
+}
+
+function decompressRollout(descriptor, storedSize, { zstdDecompress, maxDecompressedBytes }) {
+  if (storedSize > maxDecompressedBytes) throw new Error(`The compressed rollout exceeds the ${maxDecompressedBytes}-byte decompression limit [check=rollout_zstd_limit]`);
+  const stored = readExactly(descriptor, storedSize);
+  try {
+    return zstdDecompress(stored, { maxOutputLength: maxDecompressedBytes });
+  } catch (error) {
+    if (error?.code === "ERR_BUFFER_TOO_LARGE") throw new Error(`The compressed rollout expands beyond the ${maxDecompressedBytes}-byte decompression limit [check=rollout_zstd_limit]`);
+    throw new Error(`The compressed rollout could not be decompressed (${error?.code ?? "invalid data"}) [check=rollout_zstd_invalid]`);
+  }
+}
+
+function scanContent(descriptor, size, parser) {
+  for (let position = 0; position < size;) {
+    const buffer = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, size - position));
+    const count = fs.readSync(descriptor, buffer, 0, buffer.length, position);
+    if (!count) throw new Error("The rollout changed while reading");
+    parser.push(buffer.subarray(0, count), position);
+    position += count;
+  }
+}
+
+async function readHead(file, maxBytes, createZstdDecompress) {
+  if (!isCompressedRollout(file)) {
+    const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+    try {
+      const buffer = Buffer.alloc(maxBytes);
+      return buffer.subarray(0, fs.readSync(descriptor, buffer, 0, maxBytes, 0));
+    } finally { fs.closeSync(descriptor); }
+  }
+  if (typeof createZstdDecompress !== "function") throw zstdUnsupported();
+  const decompressor = createZstdDecompress();
+  const source = fs.createReadStream(file, { flags: fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0) });
+  source.on("error", (error) => decompressor.destroy(error));
+  const stream = source.pipe(decompressor);
+  const parts = [];
+  let length = 0;
+  try {
+    for await (const chunk of stream) {
+      parts.push(chunk);
+      length += chunk.length;
+      if (length >= maxBytes || chunk.includes(0x0a)) break;
+    }
+  } finally {
+    source.destroy();
+    stream.destroy();
+  }
+  return Buffer.concat(parts, length).subarray(0, maxBytes);
+}
+
+export async function readRolloutFirstRecord(file, { maxBytes = 64 * 1024, createZstdDecompress = zlib.createZstdDecompress } = {}) {
+  const named = fs.lstatSync(file);
+  if (!named.isFile() || named.isSymbolicLink()) throw new Error("The rollout is not a regular file");
+  const head = await readHead(file, maxBytes, createZstdDecompress);
+  const newline = head.indexOf(0x0a);
+  if (newline < 0) throw new Error("The rollout's first record is incomplete or exceeds its read limit");
+  return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(head.subarray(0, newline)));
+}
+
+// Scan the complete history, but retain at most one bounded JSONL record.
+// Skipping the middle of a rollout would miss duplicate identities or corruption.
+export function scanRollout(file, options) {
+  try {
+    return scanRolloutOnce(file, options);
+  } catch (error) {
+    throw asRolloutChange(error);
+  }
+}
+
+export function memoizeCompressedScan(file, key, scan, { keep = () => true } = {}) {
+  if (!isCompressedRollout(file)) return scan();
+  let named;
+  try { named = fs.lstatSync(file, { bigint: true }); }
+  catch (error) { throw asRolloutChange(error); }
+  const entry = `${file}\0${key}`;
+  const cached = compressedScans.get(entry);
+  compressedScans.delete(entry);
+  if (cached?.version === versionKey(named)) {
+    compressedScans.set(entry, cached);
+    return cached.value;
+  }
+  const value = scan();
+  if (versionKey(value.version) === versionKey(named) && keep(value)) {
+    compressedScans.set(entry, { version: versionKey(named), value });
+    if (compressedScans.size > COMPRESSED_SCAN_CACHE_ENTRIES) compressedScans.delete(compressedScans.keys().next().value);
+  }
+  return value;
+}
+
+function scanRolloutOnce(file, { maxRecordBytes, onRecord, onChunk = () => {}, zstdDecompress = zlib.zstdDecompressSync, maxDecompressedBytes = MAX_DECOMPRESSED_ROLLOUT_BYTES }) {
+  if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1) throw new Error("The rollout record read limit is invalid");
+  if (!Number.isSafeInteger(maxDecompressedBytes) || maxDecompressedBytes < 1) throw new Error("The rollout decompression limit is invalid");
+  const compressed = isCompressedRollout(file);
+  if (compressed && typeof zstdDecompress !== "function") throw zstdUnsupported();
+  const named = fs.lstatSync(file, { bigint: true });
+  if (!named.isFile() || named.isSymbolicLink()) throw new Error("The rollout is not a regular file");
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+  try {
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    if (!before.isFile()) throw new Error("The opened rollout is not a regular file");
+    if (!sameVersion(named, before)) throw new Error("The rollout changed while opening");
+    if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("The rollout exceeds the safe size range");
+    const storedSize = Number(before.size);
+    if (storedSize === 0) throw new Error("The rollout is empty (0 bytes)");
+    const content = compressed ? decompressRollout(descriptor, storedSize, { zstdDecompress, maxDecompressedBytes }) : null;
+    const size = content ? content.length : storedSize;
+    if (size === 0) throw new Error("The rollout is empty (0 bytes)");
+    const parser = recordParser(size, { maxRecordBytes, onRecord, onChunk });
+    if (content) {
+      for (let position = 0; position < size; position += CHUNK_BYTES) parser.push(content.subarray(position, Math.min(size, position + CHUNK_BYTES)), position);
+    } else {
+      scanContent(descriptor, size, parser);
     }
-    if (start !== size) throw new Error("The rollout has an incomplete final record");
+    parser.finish();
     const after = fs.fstatSync(descriptor, { bigint: true });
     const current = fs.lstatSync(file, { bigint: true });
     if (!current.isFile() || current.isSymbolicLink() || !sameVersion(before, after) || !sameVersion(after, current)) {
       throw new Error("The rollout changed while reading");
     }
-    return { size, identity: fileIdentity(before),
+    return { size, storedSize, compressed, identity: fileIdentity(before),
       version: Object.fromEntries(VERSION_FIELDS.map((key) => [key, String(before[key])])) };
   } finally {
     fs.closeSync(descriptor);

package/src/rollout-segments.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { isCompressedRollout, rolloutBasePath, asRolloutChange, readRolloutFirstRecord } from "./rollout-reader.mjs";
 
 const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
 
@@ -10,8 +11,8 @@ export function findRolloutSegments(sessions, threadId) {
   const root = fs.lstatSync(sessions);
   if (!root.isDirectory() || root.isSymbolicLink()) throw new Error("The Codex sessions path is not a regular directory");
   const canonical = fs.realpathSync.native(sessions);
-  const pattern = new RegExp(`^rollout-.+-${threadId}(?:_${UUID})?\\.jsonl$`);
-  const queue = [{ directory: canonical, depth: 0 }], matches = [];
+  const pattern = new RegExp(`^rollout-.+-${threadId}(?:_${UUID})?\\.jsonl(?:\\.zst)?$`);
+  const queue = [{ directory: canonical, depth: 0 }], matches = new Map();
   let entries = 0, directories = 0;
   while (queue.length) {
     const { directory, depth } = queue.pop();
@@ -32,13 +33,14 @@ export function findRolloutSegments(sessions, threadId) {
       }
       if (depth === 3 && pattern.test(child.name)) {
         if (!child.isFile() || child.isSymbolicLink()) throw new Error("The Codex rollout is not a regular file");
-        matches.push(candidate);
-        if (matches.length > 64) throw new Error("The Codex task exceeds the 64-segment discovery limit");
+        const base = rolloutBasePath(candidate);
+        if (!matches.has(base) || isCompressedRollout(matches.get(base))) matches.set(base, candidate);
+        if (matches.size > 64) throw new Error("The Codex task exceeds the 64-segment discovery limit");
       }
     }
   }
-  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();
+  if (!matches.size) throw new Error(`No rollout file (plain .jsonl or compressed .jsonl.zst) matches the Codex task [check=rollout_discovery; directoriesScanned=${directories}; entriesScanned=${entries}; layout=sessions/YYYY/MM/DD/rollout-*-taskId[_continuationId].jsonl[.zst]]`);
+  return [...matches].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([, file]) => file);
 }
 
 // Only independently retrieved native metadata may be supplied here. Tool
@@ -86,7 +88,33 @@ export function assertRolloutSetStable(sessions, threadId, snapshots) {
   const files = findRolloutSegments(sessions, threadId);
   if (files.length !== snapshots.length || files.some((file, i) => file !== snapshots[i].file)) throw new Error("The rollout segment set changed while reading");
   for (const { file, version } of snapshots) {
-    const current = fs.lstatSync(file, { bigint: true });
+    let current;
+    try { current = fs.lstatSync(file, { bigint: true }); }
+    catch (error) { throw asRolloutChange(error, "A rollout segment changed while reading"); }
     if (!current.isFile() || current.isSymbolicLink() || Object.entries(version).some(([key, value]) => typeof value !== "string" || String(current[key]) !== value)) throw new Error("A rollout segment changed while reading");
   }
 }
+
+export async function readRolloutHeads(sessions) {
+  const queue = [{ directory: sessions, depth: 0 }];
+  const heads = [];
+  let count = 0;
+  while (queue.length) {
+    const { directory, depth } = queue.pop();
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    const plain = new Set(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl")).map((entry) => entry.name));
+    for (const entry of entries) {
+      if (++count > 100000) throw new Error("Session scan limit exceeded");
+      if (entry.isSymbolicLink()) continue;
+      const file = path.join(directory, entry.name);
+      if (depth < 3 && entry.isDirectory() && /^\d{2,4}$/.test(entry.name)) queue.push({ directory: file, depth: depth + 1 });
+      if (depth !== 3 || !entry.isFile() || !(entry.name.endsWith(".jsonl") || isCompressedRollout(entry.name))) continue;
+      if (isCompressedRollout(entry.name) && plain.has(rolloutBasePath(entry.name))) continue;
+      let first;
+      try { first = await readRolloutFirstRecord(file); }
+      catch { continue; }
+      heads.push(first);
+    }
+  }
+  return heads;
+}

package/src/thread-delivery.mjs

@@ -72,8 +72,14 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
   return matches[0];
 }
 
+export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening: Codex Desktop runs codex-native-relay only while a task has its MCP servers loaded. Open any regular project task (not the internal Native Relay executor task) and send it a turn or reconnect its MCP servers, then retry.";
+
+function relayUnreachable(error) {
+  return error?.code === "RELAY_UNREACHABLE" && error.sent === false;
+}
+
 export class DesktopTaskDelivery {
-  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext, senderContext, captureResponse = captureCodexRolloutWatermark, readResponse = readCodexNativeTurnResponse, inspectResponse = inspectCodexNativeTurn, resolveResponse = readResponse === readCodexNativeTurnResponse ? resolveCodexNativeDispatchResponse : null } = {}) {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext, senderContext, captureResponse = captureCodexRolloutWatermark, readResponse = readCodexNativeTurnResponse, inspectResponse = inspectCodexNativeTurn, resolveResponse = readResponse === readCodexNativeTurnResponse ? resolveCodexNativeDispatchResponse : null, wakeRelay = null } = {}) {
     this.relay = relay;
     this.security = security;
     this.sleep = sleep;
@@ -86,6 +92,7 @@ export class DesktopTaskDelivery {
     this.readResponse = readResponse;
     this.inspectResponse = inspectResponse;
     this.resolveResponse = resolveResponse;
+    this.wakeRelay = wakeRelay;
     this.threadOperations = new Map();
   }
 
@@ -120,7 +127,7 @@ export class DesktopTaskDelivery {
       const remaining = deadline === undefined ? undefined : deadline - this.now();
       if (remaining !== undefined && remaining <= 0) throw Object.assign(new Error("The bridge's response deadline has elapsed; this operation was not sent"), { code: "DESKTOP_RESPONSE_DEADLINE" });
       const accountContext = this.accountContext?.();
-      const response = await this.relay.requestDesktop(operation, args, {
+      const send = () => this.relay.requestDesktop(operation, args, {
         ...(remaining === undefined ? {} : { timeoutMs: remaining }),
         ...(this.beforeRequest || projectScope || scopeBinding ? { beforeSend: async () => {
           await this.beforeRequest?.({ operation, args, phase: "write" });
@@ -134,11 +141,21 @@ export class DesktopTaskDelivery {
         ...(accountContext ? { accountContext } : {}),
         ...(creationReceiptId ? { creationReceiptId } : {}),
       });
+      let response;
+      try {
+        response = await send();
+      } catch (error) {
+        if (!relayUnreachable(error) || typeof this.wakeRelay !== "function") throw error;
+        const socketPath = accountContext ? this.relay.accountSocketPath : this.relay.socketPath;
+        if (!await this.wakeRelay({ operation, socketPath, threadId: args?.threadId, deadline })) throw error;
+        response = await send();
+      }
       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 });
+      const guidance = relayUnreachable(err) ? `${RELAY_DOWN_GUIDANCE} ` : "";
+      throw new Error(`Codex Desktop operation ${operation} failed: ${String(err.message).replace(/[.\s]+$/, "")}. Desktop-only mode will not start or use an external app-server. ${guidance}Inspect the existing task before retrying a send.`, { cause: err });
     }
   }
 

package/src/vscode-bridge.mjs

@@ -6,7 +6,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { VSCodeIpc } from "./vscode-ipc.mjs";
 import { classifyClaudeDelivery, classifyCodexCompletion } from "./vscode-delivery.mjs";
-import { findRollout, readState, readCodexSenderContext } from "./codex-sender-context.mjs";
+import { readCodexSenderContext, readTaskState } from "./codex-sender-context.mjs";
+import { readRolloutHeads } from "./rollout-segments.mjs";
 import { readProcessAncestry } from "./claude-sender-context.mjs";
 import { listClaudeSessions, assertClaudeSessionCwd, assertClaudeSessionProcess, PeerEndpoint } from "./peer-protocol.mjs";
 import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
@@ -50,34 +51,19 @@ async function caller(meta) {
 
 function codexTask(threadId, cwd) {
   if (!/^[0-9a-f-]{36}$/.test(threadId)) throw new Error("Invalid task ID");
-  const file = findRollout(sessions, threadId);
-  const state = readState(file, 64 * 1024 * 1024);
+  const state = readTaskState(sessions, threadId, 64 * 1024 * 1024);
+  const { file } = state;
   if (state.session?.id !== threadId || state.session.originator !== "codex_vscode" || state.session.source !== "vscode") throw new Error("The target is not a Codex VS Code task");
   assertRoot(state.session.cwd);
   if (!samePath(state.session.cwd, cwd) || !samePath(state.context.cwd, cwd)) throw new Error("Target and caller must use the same project directory");
   return { ...state, file };
 }
 
-function taskCandidates(cwd) {
-  const queue = [{ directory: sessions, depth: 0 }];
+async function taskCandidates(cwd) {
   const rows = [];
-  let count = 0;
-  while (queue.length) {
-    const { directory, depth } = queue.pop();
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      if (++count > 100000) throw new Error("Session scan limit exceeded");
-      if (entry.isSymbolicLink()) continue;
-      const file = path.join(directory, entry.name);
-      if (depth < 3 && entry.isDirectory() && /^\d{2,4}$/.test(entry.name)) queue.push({ directory: file, depth: depth + 1 });
-      if (depth !== 3 || !entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
-      const fd = fs.openSync(file, "r");
-      let first;
-      try { const data = Buffer.alloc(65536); const size = fs.readSync(fd, data); first = JSON.parse(data.subarray(0, size).toString("utf8").split("\n")[0]); }
-      catch { continue; }
-      finally { fs.closeSync(fd); }
-      const session = first.payload;
-      if (first.type === "session_meta" && session?.originator === "codex_vscode" && session.source === "vscode" && samePath(session.cwd, cwd)) rows.push({ threadId: session.id, cwd: session.cwd });
-    }
+  for (const first of await readRolloutHeads(sessions)) {
+    const session = first?.payload;
+    if (first?.type === "session_meta" && session?.originator === "codex_vscode" && session.source === "vscode" && samePath(session.cwd, cwd)) rows.push({ threadId: session.id, cwd: session.cwd });
   }
   return rows.slice(-50);
 }
@@ -95,7 +81,7 @@ tool("vscode_bridge_status", "Verify this extension caller and list same-project
   const ipc = await new VSCodeIpc().connect();
   try {
     const tasks = [];
-    for (const candidate of taskCandidates(sender.cwd)) {
+    for (const candidate of await taskCandidates(sender.cwd)) {
       try { await ipc.owner(candidate.threadId); tasks.push(candidate); } catch {}
     }
     return { host, cwd: sender.cwd, tasks };