@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0

package/src/remote-control/workspace-agent-protocol.ts

@@ -0,0 +1,246 @@
+import {
+  parseRemoteControlClientHello,
+  parseRemoteControlHostHello,
+  serializeRemoteControlHello,
+} from "./crypto";
+import {
+  isRemoteControlCommandProfile,
+  isRemoteControlUuid,
+  type RemoteControlClientHello,
+  type RemoteControlCommandProfile,
+  type RemoteControlHostHello,
+} from "./protocol";
+import {
+  parseRemoteWorkspaceCapabilities,
+  type RemoteWorkspaceCapability,
+} from "./workspace-tools";
+
+export const REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION = 1 as const;
+export const REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES = 96 * 1024;
+
+export type RemoteWorkspaceAgentProfile = Extract<RemoteControlCommandProfile, "codex" | "claude" | "pi">;
+
+export type RemoteWorkspaceHubMessage =
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "presence_ack";
+      capabilities: RemoteWorkspaceCapability[];
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_open";
+      rootId: string;
+      clientHello: RemoteControlClientHello;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "ciphertext";
+      sessionId: string;
+      payload: Uint8Array;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_close";
+      sessionId: string;
+      reason: string;
+    };
+
+export type RemoteWorkspaceAgentMessage =
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "presence";
+      capabilities: RemoteWorkspaceCapability[];
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_accept";
+      sessionId: string;
+      hostHello: RemoteControlHostHello;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "session_reject";
+      sessionId: string;
+      reason: string;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "ciphertext";
+      sessionId: string;
+      payload: Uint8Array;
+    }
+  | {
+      version: typeof REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION;
+      type: "heartbeat";
+      nonce: string;
+    };
+
+function identifier(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > 256 || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new Error(`invalid remote workspace ${label}`);
+  }
+  return value;
+}
+
+function reason(value: unknown): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > 512 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) {
+    throw new Error("invalid remote workspace close reason");
+  }
+  return value;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): void {
+  if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) {
+    throw new Error("invalid remote workspace control message fields");
+  }
+}
+
+function encodedHello(value: RemoteControlClientHello | RemoteControlHostHello): string {
+  return Buffer.from(serializeRemoteControlHello(value)).toString("base64url");
+}
+
+function decodedHello(value: unknown, kind: "client"): RemoteControlClientHello;
+function decodedHello(value: unknown, kind: "host"): RemoteControlHostHello;
+function decodedHello(value: unknown, kind: "client" | "host"): RemoteControlClientHello | RemoteControlHostHello {
+  if (typeof value !== "string" || value.length < 1 || value.length > 24 * 1024 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error("invalid remote workspace handshake encoding");
+  }
+  const bytes = Buffer.from(value, "base64url");
+  return kind === "client" ? parseRemoteControlClientHello(bytes) : parseRemoteControlHostHello(bytes);
+}
+
+function payload(value: unknown): Uint8Array {
+  if (typeof value !== "string" || value.length < 1 || value.length > 88 * 1024 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error("invalid remote workspace ciphertext encoding");
+  }
+  const decoded = Buffer.from(value, "base64url");
+  if (decoded.byteLength < 24 || decoded.byteLength > 64 * 1024) {
+    throw new Error("invalid remote workspace ciphertext length");
+  }
+  return decoded;
+}
+
+function parseObject(raw: string | Uint8Array): Record<string, unknown> {
+  const bytes = typeof raw === "string" ? Buffer.from(raw, "utf8") : Buffer.from(raw);
+  if (bytes.byteLength < 1 || bytes.byteLength > REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES) {
+    throw new Error("invalid remote workspace control message length");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("invalid remote workspace control message JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("invalid remote workspace control message");
+  }
+  const value = parsed as Record<string, unknown>;
+  if (value.version !== REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION) {
+    throw new Error("unsupported remote workspace agent protocol");
+  }
+  return value;
+}
+
+export function isRemoteWorkspaceAgentProfile(value: unknown): value is RemoteWorkspaceAgentProfile {
+  return isRemoteControlCommandProfile(value) && value !== "shell";
+}
+
+export function serializeRemoteWorkspaceHubMessage(message: RemoteWorkspaceHubMessage): string {
+  const value: Record<string, unknown> = { ...message };
+  if (message.type === "session_open") value.clientHello = encodedHello(message.clientHello);
+  if (message.type === "ciphertext") value.payload = Buffer.from(message.payload).toString("base64url");
+  const encoded = JSON.stringify(value);
+  if (Buffer.byteLength(encoded, "utf8") > REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES) {
+    throw new Error("remote workspace hub message is too large");
+  }
+  return encoded;
+}
+
+export function serializeRemoteWorkspaceAgentMessage(message: RemoteWorkspaceAgentMessage): string {
+  const value: Record<string, unknown> = { ...message };
+  if (message.type === "session_accept") value.hostHello = encodedHello(message.hostHello);
+  if (message.type === "ciphertext") value.payload = Buffer.from(message.payload).toString("base64url");
+  const encoded = JSON.stringify(value);
+  if (Buffer.byteLength(encoded, "utf8") > REMOTE_WORKSPACE_AGENT_MAX_CONTROL_BYTES) {
+    throw new Error("remote workspace agent message is too large");
+  }
+  return encoded;
+}
+
+export function parseRemoteWorkspaceHubMessage(raw: string | Uint8Array): RemoteWorkspaceHubMessage {
+  const value = parseObject(raw);
+  if (value.type === "presence_ack") {
+    exactKeys(value, ["version", "type", "capabilities"]);
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "presence_ack",
+      capabilities: parseRemoteWorkspaceCapabilities(value.capabilities),
+    };
+  }
+  if (value.type === "session_open") {
+    exactKeys(value, ["version", "type", "rootId", "clientHello"]);
+    const clientHello = decodedHello(value.clientHello, "client");
+    if (!isRemoteWorkspaceAgentProfile(clientHello.commandProfile)) {
+      throw new Error("invalid remote workspace session profile");
+    }
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "session_open",
+      rootId: identifier(value.rootId, "root ID"),
+      clientHello,
+    };
+  }
+  if (value.type === "ciphertext") {
+    exactKeys(value, ["version", "type", "sessionId", "payload"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "ciphertext", sessionId, payload: payload(value.payload) };
+  }
+  if (value.type === "session_close") {
+    exactKeys(value, ["version", "type", "sessionId", "reason"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "session_close", sessionId, reason: reason(value.reason) };
+  }
+  throw new Error("unsupported remote workspace hub message");
+}
+
+export function parseRemoteWorkspaceAgentMessage(raw: string | Uint8Array): RemoteWorkspaceAgentMessage {
+  const value = parseObject(raw);
+  if (value.type === "presence") {
+    exactKeys(value, ["version", "type", "capabilities"]);
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "presence",
+      capabilities: parseRemoteWorkspaceCapabilities(value.capabilities),
+    };
+  }
+  if (value.type === "session_accept") {
+    exactKeys(value, ["version", "type", "sessionId", "hostHello"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return {
+      version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION,
+      type: "session_accept",
+      sessionId,
+      hostHello: decodedHello(value.hostHello, "host"),
+    };
+  }
+  if (value.type === "session_reject") {
+    exactKeys(value, ["version", "type", "sessionId", "reason"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "session_reject", sessionId, reason: reason(value.reason) };
+  }
+  if (value.type === "ciphertext") {
+    exactKeys(value, ["version", "type", "sessionId", "payload"]);
+    const sessionId = identifier(value.sessionId, "session ID");
+    if (!isRemoteControlUuid(sessionId)) throw new Error("invalid remote workspace session ID");
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "ciphertext", sessionId, payload: payload(value.payload) };
+  }
+  if (value.type === "heartbeat") {
+    exactKeys(value, ["version", "type", "nonce"]);
+    return { version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "heartbeat", nonce: identifier(value.nonce, "heartbeat nonce") };
+  }
+  throw new Error("unsupported remote workspace agent message");
+}

package/src/remote-control/workspace-rpc-framing.ts

@@ -0,0 +1,128 @@
+import { randomBytes } from "node:crypto";
+import { REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES } from "./protocol";
+
+const RPC_FRAME_MAGIC = Uint8Array.of(0x4f, 0x43, 0x58, 0x52); // OCXR
+const RPC_FRAME_VERSION = 1;
+const RPC_FRAME_HEADER_BYTES = 30;
+const RPC_FRAME_MESSAGE_ID_BYTES = 16;
+const RPC_FRAME_MESSAGE_ID_OFFSET = 6;
+const RPC_FRAME_TOTAL_BYTES_OFFSET = 22;
+const RPC_FRAME_CHUNK_OFFSET = 26;
+const RPC_ENCRYPTION_OVERHEAD_BYTES = 24;
+const RPC_MAX_PLAINTEXT_FRAME_BYTES = REMOTE_CONTROL_MAX_RELAY_PAYLOAD_BYTES - RPC_ENCRYPTION_OVERHEAD_BYTES;
+const RPC_MAX_CHUNK_BYTES = RPC_MAX_PLAINTEXT_FRAME_BYTES - RPC_FRAME_HEADER_BYTES;
+const RPC_MAX_INCOMPLETE_MESSAGES = 8;
+const RPC_INCOMPLETE_MESSAGE_TTL_MS = 30_000;
+
+// A 256 KiB UTF-8 write can expand by up to 6x when JSON escapes control bytes.
+// Keep the wire contract bounded while still carrying every executor-approved text file.
+export const REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES = 2 * 1024 * 1024;
+
+interface IncompleteMessage {
+  buffer: Uint8Array;
+  nextOffset: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+function hasMagic(value: Uint8Array): boolean {
+  return RPC_FRAME_MAGIC.every((byte, index) => value[index] === byte);
+}
+
+function messageKey(frame: Uint8Array): string {
+  return Buffer.from(
+    frame.subarray(RPC_FRAME_MESSAGE_ID_OFFSET, RPC_FRAME_MESSAGE_ID_OFFSET + RPC_FRAME_MESSAGE_ID_BYTES),
+  ).toString("hex");
+}
+
+function writeHeader(frame: Uint8Array, messageId: Uint8Array, totalBytes: number, offset: number): void {
+  frame.set(RPC_FRAME_MAGIC, 0);
+  frame[4] = RPC_FRAME_VERSION;
+  frame[5] = 0;
+  frame.set(messageId, RPC_FRAME_MESSAGE_ID_OFFSET);
+  const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+  view.setUint32(RPC_FRAME_TOTAL_BYTES_OFFSET, totalBytes);
+  view.setUint32(RPC_FRAME_CHUNK_OFFSET, offset);
+}
+
+/**
+ * Splits one logical RPC message without retaining a second full-size copy.
+ * Each yielded plaintext fits one authenticated relay frame.
+ */
+export function* frameRemoteWorkspaceRpcMessage(message: Uint8Array): Generator<Uint8Array> {
+  if (!(message instanceof Uint8Array)
+    || message.byteLength < 1
+    || message.byteLength > REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES) {
+    throw new Error("invalid remote workspace RPC message length");
+  }
+  const messageId = randomBytes(RPC_FRAME_MESSAGE_ID_BYTES);
+  for (let offset = 0; offset < message.byteLength; offset += RPC_MAX_CHUNK_BYTES) {
+    const end = Math.min(offset + RPC_MAX_CHUNK_BYTES, message.byteLength);
+    const frame = new Uint8Array(RPC_FRAME_HEADER_BYTES + end - offset);
+    writeHeader(frame, messageId, message.byteLength, offset);
+    frame.set(message.subarray(offset, end), RPC_FRAME_HEADER_BYTES);
+    yield frame;
+  }
+}
+
+/** Bounded, ordered reassembly for authenticated RPC fragments. */
+export class RemoteWorkspaceRpcReassembler {
+  private readonly incomplete = new Map<string, IncompleteMessage>();
+
+  accept(frame: Uint8Array): Uint8Array | null {
+    if (!(frame instanceof Uint8Array)
+      || frame.byteLength <= RPC_FRAME_HEADER_BYTES
+      || frame.byteLength > RPC_MAX_PLAINTEXT_FRAME_BYTES
+      || !hasMagic(frame)
+      || frame[4] !== RPC_FRAME_VERSION
+      || frame[5] !== 0) {
+      throw new Error("invalid remote workspace RPC frame");
+    }
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    const totalBytes = view.getUint32(RPC_FRAME_TOTAL_BYTES_OFFSET);
+    const offset = view.getUint32(RPC_FRAME_CHUNK_OFFSET);
+    const payload = frame.subarray(RPC_FRAME_HEADER_BYTES);
+    if (totalBytes < 1
+      || totalBytes > REMOTE_WORKSPACE_RPC_MAX_MESSAGE_BYTES
+      || offset >= totalBytes
+      || payload.byteLength > totalBytes - offset
+      || (offset + payload.byteLength < totalBytes && payload.byteLength !== RPC_MAX_CHUNK_BYTES)) {
+      throw new Error("invalid remote workspace RPC fragment bounds");
+    }
+    if (offset === 0 && payload.byteLength === totalBytes) return payload;
+
+    const key = messageKey(frame);
+    let state = this.incomplete.get(key);
+    if (!state) {
+      if (offset !== 0) throw new Error("remote workspace RPC fragment started out of order");
+      if (this.incomplete.size >= RPC_MAX_INCOMPLETE_MESSAGES) {
+        throw new Error("remote workspace RPC fragment limit reached");
+      }
+      const timer = setTimeout(() => this.drop(key), RPC_INCOMPLETE_MESSAGE_TTL_MS);
+      timer.unref?.();
+      state = { buffer: new Uint8Array(totalBytes), nextOffset: 0, timer };
+      this.incomplete.set(key, state);
+    } else if (state.buffer.byteLength !== totalBytes || state.nextOffset !== offset) {
+      this.drop(key);
+      throw new Error("remote workspace RPC fragments are inconsistent or out of order");
+    }
+
+    state.buffer.set(payload, offset);
+    state.nextOffset += payload.byteLength;
+    if (state.nextOffset !== totalBytes) return null;
+    this.incomplete.delete(key);
+    clearTimeout(state.timer);
+    return state.buffer;
+  }
+
+  clear(): void {
+    for (const state of this.incomplete.values()) clearTimeout(state.timer);
+    this.incomplete.clear();
+  }
+
+  private drop(key: string): void {
+    const state = this.incomplete.get(key);
+    if (!state) return;
+    clearTimeout(state.timer);
+    this.incomplete.delete(key);
+  }
+}

package/src/remote-control/workspace-tools.ts

@@ -0,0 +1,237 @@
+export const REMOTE_WORKSPACE_TOOL_NAMESPACE = "ocx_remote_workspace" as const;
+export const REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES = 256 * 1024;
+
+export const REMOTE_WORKSPACE_CAPABILITIES = [
+  "workspace.read",
+  "workspace.write",
+  "workspace.exec",
+] as const;
+
+export type RemoteWorkspaceCapability = typeof REMOTE_WORKSPACE_CAPABILITIES[number];
+
+export type RemoteWorkspaceToolName =
+  | "list_directory"
+  | "read_file"
+  | "write_file"
+  | "exec";
+
+export interface RemoteWorkspaceDynamicToolFunction {
+  type: "function";
+  name: RemoteWorkspaceToolName;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface RemoteWorkspaceDynamicToolNamespace {
+  type: "namespace";
+  name: typeof REMOTE_WORKSPACE_TOOL_NAMESPACE;
+  description: string;
+  tools: RemoteWorkspaceDynamicToolFunction[];
+}
+
+export interface RemoteWorkspaceToolCallParams {
+  threadId: string;
+  turnId: string;
+  callId: string;
+  namespace: typeof REMOTE_WORKSPACE_TOOL_NAMESPACE;
+  tool: RemoteWorkspaceToolName;
+  arguments: unknown;
+}
+
+export type RemoteWorkspaceToolResult =
+  | { ok: true; value?: unknown; error?: never }
+  | { ok: false; error: string; value?: never };
+
+const RELATIVE_PATH = {
+  type: "string",
+  minLength: 1,
+  maxLength: 4096,
+  description: "Path relative to the workspace root. Absolute paths and parent traversal are rejected.",
+} as const;
+
+export const REMOTE_WORKSPACE_DYNAMIC_TOOLS: readonly [RemoteWorkspaceDynamicToolNamespace] = [{
+  type: "namespace",
+  name: REMOTE_WORKSPACE_TOOL_NAMESPACE,
+  description: "Operate only on the selected remote OpenCodex executor workspace.",
+  tools: [
+    {
+      type: "function",
+      name: "list_directory",
+      description: "List one directory inside the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: { path: { ...RELATIVE_PATH, default: "." } },
+        additionalProperties: false,
+      },
+    },
+    {
+      type: "function",
+      name: "read_file",
+      description: "Read a bounded UTF-8 regular file from the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: RELATIVE_PATH,
+          maxBytes: { type: "integer", minimum: 1, maximum: REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES },
+        },
+        required: ["path"],
+        additionalProperties: false,
+      },
+    },
+    {
+      type: "function",
+      name: "write_file",
+      description: "Atomically replace a bounded UTF-8 file in the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: RELATIVE_PATH,
+          content: { type: "string", maxLength: REMOTE_WORKSPACE_MAX_TOOL_RESULT_BYTES },
+          expectedSha256: {
+            type: ["string", "null"],
+            pattern: "^[0-9a-f]{64}$",
+            description: "Expected current file hash, or null when the file must not already exist.",
+          },
+        },
+        required: ["path", "content", "expectedSha256"],
+        additionalProperties: false,
+      },
+    },
+    {
+      type: "function",
+      name: "exec",
+      description: "Execute an argv vector in a directory inside the selected remote workspace.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: {
+            type: "array",
+            minItems: 1,
+            maxItems: 64,
+            items: { type: "string", minLength: 1, maxLength: 4096 },
+          },
+          cwd: { ...RELATIVE_PATH, default: "." },
+          timeoutMs: { type: "integer", minimum: 1, maximum: 60_000 },
+        },
+        required: ["command"],
+        additionalProperties: false,
+      },
+    },
+  ],
+}];
+
+const TOOL_CAPABILITY: Readonly<Record<RemoteWorkspaceToolName, RemoteWorkspaceCapability>> = {
+  list_directory: "workspace.read",
+  read_file: "workspace.read",
+  write_file: "workspace.write",
+  exec: "workspace.exec",
+};
+
+export function parseRemoteWorkspaceCapabilities(
+  value: unknown,
+  fallback: readonly RemoteWorkspaceCapability[] = ["workspace.read", "workspace.write"],
+): RemoteWorkspaceCapability[] {
+  if (value === undefined) return [...fallback];
+  if (!Array.isArray(value) || value.length < 1 || value.length > REMOTE_WORKSPACE_CAPABILITIES.length) {
+    throw new Error("invalid remote workspace capabilities");
+  }
+  const result = new Set<RemoteWorkspaceCapability>();
+  for (const capability of value) {
+    if (!isRemoteWorkspaceCapability(capability)) {
+      throw new Error("invalid remote workspace capability");
+    }
+    result.add(capability);
+  }
+  if (!result.has("workspace.read")) {
+    throw new Error("remote workspace executors must support workspace.read");
+  }
+  return REMOTE_WORKSPACE_CAPABILITIES.filter(capability => result.has(capability));
+}
+
+export function remoteWorkspaceToolsForCapabilities(
+  capabilities: readonly RemoteWorkspaceCapability[],
+): RemoteWorkspaceToolName[] {
+  const allowed = new Set(parseRemoteWorkspaceCapabilities(capabilities));
+  return REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools
+    .filter(tool => allowed.has(TOOL_CAPABILITY[tool.name]))
+    .map(tool => tool.name);
+}
+
+export function remoteWorkspaceDynamicToolsForCapabilities(
+  capabilities: readonly RemoteWorkspaceCapability[],
+): readonly [RemoteWorkspaceDynamicToolNamespace] {
+  const names = new Set(remoteWorkspaceToolsForCapabilities(capabilities));
+  return [{
+    ...REMOTE_WORKSPACE_DYNAMIC_TOOLS[0],
+    tools: REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.filter(tool => names.has(tool.name)),
+  }];
+}
+
+export function remoteWorkspaceCapabilityForTool(tool: RemoteWorkspaceToolName): RemoteWorkspaceCapability {
+  return TOOL_CAPABILITY[tool];
+}
+
+const TOOL_NAMES: ReadonlySet<string> = new Set(
+  REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
+);
+
+export function isRemoteWorkspaceCapability(value: unknown): value is RemoteWorkspaceCapability {
+  return value === "workspace.read" || value === "workspace.write" || value === "workspace.exec";
+}
+
+export function isRemoteWorkspaceToolName(value: unknown): value is RemoteWorkspaceToolName {
+  return typeof value === "string" && TOOL_NAMES.has(value);
+}
+
+function boundedIdentifier(value: unknown): value is string {
+  return typeof value === "string" && value.length >= 1 && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+export function parseRemoteWorkspaceToolCall(value: unknown): RemoteWorkspaceToolCallParams {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("invalid remote workspace tool call");
+  }
+  const raw = value as Record<string, unknown>;
+  if (
+    !boundedIdentifier(raw.threadId)
+    || !boundedIdentifier(raw.turnId)
+    || !boundedIdentifier(raw.callId)
+    || raw.namespace !== REMOTE_WORKSPACE_TOOL_NAMESPACE
+    || !isRemoteWorkspaceToolName(raw.tool)
+  ) throw new Error("invalid remote workspace tool call identity");
+  return {
+    threadId: raw.threadId,
+    turnId: raw.turnId,
+    callId: raw.callId,
+    namespace: REMOTE_WORKSPACE_TOOL_NAMESPACE,
+    tool: raw.tool,
+    arguments: raw.arguments,
+  };
+}
+
+export function remoteWorkspaceDeveloperInstructions(
+  deviceName: string,
+  tools: readonly RemoteWorkspaceToolName[] = REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
+): string {
+  const safeName = deviceName.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 120) || "remote executor";
+  const allowed = tools.map(tool => `${REMOTE_WORKSPACE_TOOL_NAMESPACE}.${tool}`).join(", ");
+  return [
+    `This thread operates on the OpenCodex remote executor named ${JSON.stringify(safeName)}.`,
+    `Its available remote tools are: ${allowed}. Use no other tool for filesystem or command work.`,
+    "The coordinator filesystem is an empty isolation boundary and is not the user's workspace.",
+    "Never use local shell, local file, or local patch tools for this thread.",
+    "If a remote tool is unavailable, stop and report that the executor is offline; never fall back locally.",
+  ].join(" ");
+}
+
+export function remoteWorkspaceCodexDeveloperInstructions(
+  deviceName: string,
+  tools: readonly RemoteWorkspaceToolName[] = REMOTE_WORKSPACE_DYNAMIC_TOOLS[0].tools.map(tool => tool.name),
+): string {
+  const nestedTools = tools.map(tool => `tools.mcp__${REMOTE_WORKSPACE_TOOL_NAMESPACE}__${tool}`).join(", ");
+  return [
+    remoteWorkspaceDeveloperInstructions(deviceName, tools),
+    `Current Codex versions expose MCP through the functions.exec code-mode tool. Inside it, call only: ${nestedTools}.`,
+    "Do not call exec_command, apply_patch, view_image, browser, apps, plugins, or any other nested helper on the Hub.",
+  ].join(" ");
+}

package/src/remote-control/workspace-utf8.ts

@@ -0,0 +1,24 @@
+import { Buffer } from "node:buffer";
+
+export function truncateRemoteWorkspaceUtf8(value: string, maximumBytes: number): string {
+  if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0) {
+    throw new Error("invalid remote workspace UTF-8 limit");
+  }
+  if (Buffer.byteLength(value, "utf8") <= maximumBytes) return value;
+  let low = 0;
+  let high = Math.min(value.length, maximumBytes);
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(value.slice(0, middle), "utf8") <= maximumBytes) low = middle;
+    else high = middle - 1;
+  }
+  if (
+    low > 0
+    && low < value.length
+    && value.charCodeAt(low - 1) >= 0xd800
+    && value.charCodeAt(low - 1) <= 0xdbff
+    && value.charCodeAt(low) >= 0xdc00
+    && value.charCodeAt(low) <= 0xdfff
+  ) low -= 1;
+  return value.slice(0, low);
+}

package/src/responses/custom-tool-compat.ts

@@ -261,6 +261,29 @@ export function rewriteRoutedCustomToolsForUpstream(
   return { body: rewriteForUpstream(body, conversionNames, callIds), names, repairNames };
 }
 
+/**
+ * A delta result has no tool name. Without its call, lowering cannot tell whether it belongs
+ * to a converted function or a native custom tool. Request full replay instead of guessing.
+ */
+export function hasUnmappedRoutedCustomToolOutput(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): boolean {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return false;
+  if (collectRoutedCustomToolNames(body, supportsResponsesCustomTools).size === 0) return false;
+  const callIds = new Set<string>();
+  for (const item of body.input) {
+    if (isPlainObject(item)
+      && (item.type === "custom_tool_call" || item.type === "function_call")
+      && typeof item.call_id === "string") callIds.add(item.call_id);
+  }
+  return body.input.some(item => isPlainObject(item)
+    && item.type === "custom_tool_call_output"
+    && typeof item.call_id === "string"
+    && item.call_id.length > 0
+    && !callIds.has(item.call_id));
+}
+
 export function restoreRoutedCustomCalls(
   value: unknown,
   names: ReadonlySet<string>,