@4xeoz/re-entry 0.2.0

package/src/codex-discovery.mjs

@@ -0,0 +1,246 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join, normalize, resolve } from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+export const CODEX_BINARY_ENVIRONMENT_VARIABLE = "CODEX_BINARY";
+export const MINIMUM_NODE_MAJOR = 24;
+
+const CODEX_COMMAND = "codex";
+const CODEX_APP_BUNDLE_NAMES = Object.freeze(["ChatGPT.app", "Codex.app"]);
+const DEFAULT_COMMAND_DIRECTORIES = Object.freeze([
+  "/opt/homebrew/bin",
+  "/usr/local/bin",
+  "/usr/bin",
+  "/bin",
+]);
+const MAX_REFERENCE_BYTES = 4 * 1_024;
+const MAX_VERSION_BYTES = 512;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+
+export class CodexDiscoveryError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "CodexDiscoveryError";
+    this.code = code;
+  }
+}
+
+/**
+ * Find the Codex CLI without relying on one machine's ChatGPT installation path.
+ * Explicit CLI configuration wins, then CODEX_BINARY, PATH, and known macOS app bundles.
+ */
+export function discoverCodexExecutable(options = {}) {
+  const environment = options.environment ?? process.env;
+  const homeDirectory = options.homeDirectory ?? homedir();
+  const platform = options.platform ?? process.platform;
+  const applicationDirectories = options.applicationDirectories ?? [
+    "/Applications",
+    join(homeDirectory, "Applications"),
+  ];
+  const requested = options.requested !== undefined
+    ? options.requested
+    : environment[CODEX_BINARY_ENVIRONMENT_VARIABLE];
+
+  if (requested !== undefined) {
+    const reference = requireReference(requested, "Codex executable");
+    const candidates = reference.includes("/")
+      ? [resolveReference(reference, homeDirectory)]
+      : [
+        ...pathCandidates(reference, environment.PATH),
+        ...(reference === CODEX_COMMAND
+          ? DEFAULT_COMMAND_DIRECTORIES.map((directory) => join(directory, reference))
+          : []),
+      ];
+    const executable = firstExecutable(candidates);
+    if (executable) return executable;
+    throw codexFailure(
+      "connector_codex_binary_not_found",
+      "The configured Codex executable could not be found or is not executable.",
+    );
+  }
+
+  const candidates = [
+    ...pathCandidates(CODEX_COMMAND, environment.PATH),
+    ...DEFAULT_COMMAND_DIRECTORIES.map((directory) => join(directory, CODEX_COMMAND)),
+    ...(platform === "darwin" ? macOSBundleCandidates(applicationDirectories) : []),
+  ];
+  const executable = firstExecutable(candidates);
+  if (executable) return executable;
+
+  throw codexFailure(
+    "connector_codex_not_found",
+    "Codex CLI was not found. Install Codex, add it to PATH, or set CODEX_BINARY.",
+  );
+}
+
+/**
+ * Check the selected Codex binary before the Connector claims a delivery.
+ */
+export function verifyCodexExecutable(executable, options = {}) {
+  const normalizedExecutable = requireReference(executable, "Codex executable");
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 60_000) {
+    throw new TypeError("Codex version check timeout is invalid");
+  }
+  const spawnSyncCommand = options.spawnSyncCommand ?? spawnSync;
+  if (typeof spawnSyncCommand !== "function") {
+    throw new TypeError("Codex version check command must be a function");
+  }
+
+  let result;
+  try {
+    result = spawnSyncCommand(normalizedExecutable, ["--version"], {
+      encoding: "utf8",
+      env: options.environment ?? process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs,
+    });
+  } catch (error) {
+    throw codexFailure(
+      "connector_codex_unusable",
+      "The Codex CLI could not be started.",
+      error,
+    );
+  }
+
+  if (!result || result.error || result.status !== 0) {
+    throw codexFailure(
+      "connector_codex_unusable",
+      "The selected Codex CLI did not pass its version check.",
+      result?.error,
+    );
+  }
+
+  return Object.freeze({
+    executable: normalizedExecutable,
+    version: readVersion(result.stdout, result.stderr),
+  });
+}
+
+/**
+ * Validate the host project directory before a delivery is claimed.
+ */
+export function validateCodexWorkingDirectory(value, options = {}) {
+  const homeDirectory = options.homeDirectory ?? homedir();
+  const reference = requireReference(value, "Codex working directory");
+  const expanded = resolveReference(reference, homeDirectory);
+  if (!isAbsolute(expanded)) {
+    throw codexFailure(
+      "connector_codex_cd_absolute",
+      "The Codex working directory must be an absolute path.",
+    );
+  }
+  const workingDirectory = normalize(expanded);
+  const statFile = options.statSync ?? statSync;
+  const accessFile = options.accessSync ?? accessSync;
+  let stats;
+  try {
+    stats = statFile(workingDirectory);
+  } catch (error) {
+    throw codexFailure(
+      "connector_codex_cd_missing",
+      "The Codex working directory does not exist.",
+      error,
+    );
+  }
+  if (!stats?.isDirectory?.()) {
+    throw codexFailure(
+      "connector_codex_cd_invalid",
+      "The Codex working directory is not a directory.",
+    );
+  }
+  try {
+    accessFile(workingDirectory, constants.R_OK | constants.W_OK | constants.X_OK);
+  } catch (error) {
+    throw codexFailure(
+      "connector_codex_cd_unusable",
+      "The Codex working directory is not readable and writable.",
+      error,
+    );
+  }
+  return workingDirectory;
+}
+
+export function requireSupportedNode(version = process.versions.node) {
+  const major = Number.parseInt(String(version).split(".")[0], 10);
+  if (!Number.isSafeInteger(major) || major < MINIMUM_NODE_MAJOR) {
+    throw codexFailure(
+      "connector_node_unsupported",
+      `The Local Connector requires Node.js ${MINIMUM_NODE_MAJOR} or newer.`,
+    );
+  }
+  return String(version);
+}
+
+function macOSBundleCandidates(applicationDirectories) {
+  return CODEX_APP_BUNDLE_NAMES.flatMap((bundleName) => applicationDirectories.map((directory) => (
+    join(directory, bundleName, "Contents", "Resources", "codex")
+  )));
+}
+
+function pathCandidates(command, pathValue) {
+  const directories = [
+    ...(typeof pathValue === "string" ? pathValue.split(delimiter) : []),
+  ];
+  return directories
+    .filter((directory) => directory.length > 0)
+    .map((directory) => join(directory, command));
+}
+
+function firstExecutable(candidates) {
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const normalized = normalize(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    if (isExecutableFile(normalized)) return normalized;
+  }
+  return null;
+}
+
+function isExecutableFile(path) {
+  try {
+    accessSync(path, constants.F_OK | constants.X_OK);
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveReference(value, homeDirectory) {
+  if (value === "~") return homeDirectory;
+  if (value.startsWith("~/")) return join(homeDirectory, value.slice(2));
+  return value;
+}
+
+function readVersion(stdout, stderr) {
+  const value = typeof stdout === "string" && stdout.trim().length > 0
+    ? stdout
+    : typeof stderr === "string"
+      ? stderr
+      : "";
+  const firstLine = value.split(/\r?\n/, 1)[0].trim();
+  if (Buffer.byteLength(firstLine, "utf8") > MAX_VERSION_BYTES) {
+    return "available";
+  }
+  return firstLine || "available";
+}
+
+function requireReference(value, label) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    Buffer.byteLength(value, "utf8") > MAX_REFERENCE_BYTES ||
+    CONTROL_CHARACTER_PATTERN.test(value)
+  ) {
+    throw codexFailure("connector_configuration_invalid", `${label} is invalid.`);
+  }
+  return value;
+}
+
+function codexFailure(code, message, cause) {
+  return new CodexDiscoveryError(code, message, cause === undefined ? {} : { cause });
+}

package/src/codex-exec-adapter.mjs

@@ -0,0 +1,197 @@
+import { spawn } from "node:child_process";
+
+import {
+  AGENT_ACTIVATION_RESULT_TYPE,
+  validateAgentActivation,
+} from "@webmcp-challenge/reentry-core/agent-adapter";
+import {
+  discoverCodexExecutable,
+  validateCodexWorkingDirectory,
+} from "./codex-discovery.mjs";
+
+export const CODEX_EXEC_ADAPTER_ID = "codex_exec_local";
+
+const OPTION_FIELDS = Object.freeze([
+  "workingDirectory",
+  "executable",
+  "commandTimeoutMs",
+  "clock",
+  "spawnCommand",
+]);
+const MIN_COMMAND_TIMEOUT_MS = 100;
+const MAX_COMMAND_TIMEOUT_MS = 60_000;
+const MAX_REFERENCE_BYTES = 4 * 1_024;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+
+/**
+ * Create the fresh-session Codex adapter that lives inside the Local Connector process.
+ *
+ * Each activation starts a new `codex exec` process. The activation's validated page context
+ * becomes a fixed prompt; no existing Codex thread or session is looked up or resumed.
+ */
+export function createCodexExecAdapter(options) {
+  requireExactRecord(options, OPTION_FIELDS, ["workingDirectory"], "Codex exec adapter options");
+  const workingDirectory = validateCodexWorkingDirectory(options.workingDirectory);
+  const executable = options.executable === undefined
+    ? discoverCodexExecutable()
+    : requireReference(options.executable, "Codex executable");
+  const commandTimeoutMs = requireTimeout(options.commandTimeoutMs ?? 60_000);
+  const clock = options.clock ?? (() => new Date());
+  const spawnCommand = options.spawnCommand ?? spawn;
+  if (typeof clock !== "function") throw new TypeError("Codex exec adapter clock must be a function");
+  if (typeof spawnCommand !== "function") {
+    throw new TypeError("Codex exec adapter spawnCommand must be a function");
+  }
+
+  return Object.freeze({
+    async activate(rawActivation) {
+      const activation = validateAgentActivation(rawActivation);
+      const now = readClock(clock);
+      if (
+        Date.parse(activation.lease_expires_at) <= now.getTime() ||
+        Date.parse(activation.receipt.expires_at) <= now.getTime()
+      ) {
+        return activationResult(activation, "rejected", "activation_rejected", null);
+      }
+
+      await runCodexExec({
+        executable,
+        workingDirectory,
+        prompt: buildContinuationPrompt(activation),
+        timeoutMs: commandTimeoutMs,
+        spawnCommand,
+      });
+      return activationResult(
+        activation,
+        "accepted",
+        "activation_dispatch_accepted",
+        null,
+      );
+    },
+  });
+}
+
+function buildContinuationPrompt(activation) {
+  return [
+    "You are a Re-entry continuation agent.",
+    "This is a new session. Do not look for or resume another session.",
+    "Open the exact canonical page below and read its current state.",
+    "Continue the task using only the page's currently available WebMCP tools.",
+    "Prepare the next safe step, then stop before the human decision boundary.",
+    "Do not submit or perform the final consequential action.",
+    "",
+    "Re-entry context:",
+    `Workflow: ${activation.continuation.workflow_id}`,
+    `Event: ${activation.continuation.event_type}`,
+    `State version: ${activation.continuation.state_version}`,
+    `Canonical page: ${activation.continuation.canonical_url}`,
+    `Human boundary: ${activation.receipt.human_boundary}`,
+  ].join("\n");
+}
+
+function runCodexExec({ executable, workingDirectory, prompt, timeoutMs, spawnCommand }) {
+  return new Promise((resolve, reject) => {
+    let child;
+    let settled = false;
+    let timer;
+
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      callback(value);
+    };
+
+    try {
+      child = spawnCommand(
+        executable,
+        ["exec", "--cd", workingDirectory, prompt],
+        { stdio: ["ignore", "ignore", "ignore"] },
+      );
+    } catch (error) {
+      finish(reject, error);
+      return;
+    }
+
+    if (!child || typeof child.once !== "function") {
+      finish(reject, new Error("Codex exec process is invalid"));
+      return;
+    }
+
+    timer = setTimeout(() => {
+      try {
+        child.kill?.("SIGTERM");
+      } catch {
+        // The activation remains unknown even if the process cannot be terminated.
+      }
+      finish(reject, new Error("Codex exec process timed out"));
+    }, timeoutMs);
+
+    child.once("error", (error) => finish(reject, error));
+    child.once("close", (code, signal) => {
+      if (code === 0 && signal === null) {
+        finish(resolve);
+        return;
+      }
+      finish(reject, new Error("Codex exec process did not complete successfully"));
+    });
+  });
+}
+
+function activationResult(activation, outcome, code, unavailableCapability) {
+  return Object.freeze({
+    type: AGENT_ACTIVATION_RESULT_TYPE,
+    protocol_version: "0.1",
+    delivery_id: activation.delivery_id,
+    event_id: activation.event_id,
+    attempt: activation.attempt,
+    outcome,
+    code,
+    unavailable_capability: unavailableCapability,
+  });
+}
+
+function readClock(clock) {
+  const value = clock();
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError("Codex exec adapter clock must return a valid Date");
+  }
+  return new Date(value.getTime());
+}
+
+function requireTimeout(value) {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < MIN_COMMAND_TIMEOUT_MS ||
+    value > MAX_COMMAND_TIMEOUT_MS
+  ) {
+    throw new TypeError("Codex exec adapter commandTimeoutMs is invalid");
+  }
+  return value;
+}
+
+function requireReference(value, label) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    Buffer.byteLength(value, "utf8") > MAX_REFERENCE_BYTES ||
+    CONTROL_CHARACTER_PATTERN.test(value)
+  ) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function requireExactRecord(value, allowedFields, requiredFields, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  const fields = Object.keys(value);
+  if (
+    fields.some((field) => !allowedFields.includes(field)) ||
+    requiredFields.some((field) => !fields.includes(field))
+  ) {
+    throw new TypeError(`${label} fields are invalid`);
+  }
+}

package/src/codex-queue-adapter.mjs

@@ -0,0 +1,214 @@
+import { spawn } from "node:child_process";
+
+import {
+  AGENT_ACTIVATION_RESULT_TYPE,
+  validateAgentActivation,
+} from "@webmcp-challenge/reentry-core/agent-adapter";
+import { createManagedContextAdapter } from "@webmcp-challenge/reentry-core/managed-context-adapter";
+
+export const CODEX_QUEUE_ADAPTER_ID = "codex_queue_local";
+export const DEFAULT_CODEX_EXECUTABLE = "/Applications/ChatGPT.app/Contents/Resources/codex";
+
+const OPTION_FIELDS = Object.freeze([
+  "threadId",
+  "executable",
+  "commandTimeoutMs",
+  "clock",
+  "spawnCommand",
+]);
+const MIN_COMMAND_TIMEOUT_MS = 100;
+const MAX_COMMAND_TIMEOUT_MS = 60_000;
+const MAX_REFERENCE_BYTES = 4 * 1_024;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+
+/**
+ * Create the Codex adapter that lives inside the Local Connector process.
+ *
+ * This is a deliberately small local preview. The configured thread is private local binding
+ * state and never comes from the Receiver event or the Agent activation value. A future
+ * production adapter must replace the single-session binding with a Grant-scoped binding
+ * authority and prove Browser/WebMCP acquisition separately.
+ */
+export function createCodexQueueAdapter(options) {
+  requireExactRecord(options, OPTION_FIELDS, ["threadId"], "Codex queue adapter options");
+  const threadId = requireReference(options.threadId, "Codex thread");
+  const executable = requireReference(
+    options.executable ?? DEFAULT_CODEX_EXECUTABLE,
+    "Codex executable",
+  );
+  const commandTimeoutMs = requireTimeout(options.commandTimeoutMs ?? 5_000);
+  const clock = options.clock ?? (() => new Date());
+  const spawnCommand = options.spawnCommand ?? spawn;
+  if (typeof clock !== "function") throw new TypeError("Codex queue adapter clock must be a function");
+  if (typeof spawnCommand !== "function") {
+    throw new TypeError("Codex queue adapter spawnCommand must be a function");
+  }
+
+  const bindingsByGrant = new Map();
+  const managedAdapter = createManagedContextAdapter({
+    adapterId: CODEX_QUEUE_ADAPTER_ID,
+    bindingAuthority: {
+      resolveBinding({ grantId }) {
+        return bindingsByGrant.get(grantId) ?? null;
+      },
+    },
+    activateBoundContext({ activation, bindingRef }) {
+      return queueCodexMessage({
+        executable,
+        threadId: bindingRef,
+        message: buildContinuationMessage(activation),
+        timeoutMs: commandTimeoutMs,
+        spawnCommand,
+      }).then(() => activationResult(
+        activation,
+        "accepted",
+        "activation_dispatch_accepted",
+        null,
+      ));
+    },
+    clock,
+  });
+
+  return Object.freeze({
+    async activate(rawActivation) {
+      const activation = validateAgentActivation(rawActivation);
+      const now = readClock(clock);
+      if (
+        Date.parse(activation.lease_expires_at) <= now.getTime() ||
+        Date.parse(activation.receipt.expires_at) <= now.getTime()
+      ) {
+        return activationResult(activation, "rejected", "activation_rejected", null);
+      }
+
+      const grantId = activation.receipt.grant_id;
+      if (!bindingsByGrant.has(grantId)) {
+        bindingsByGrant.set(grantId, {
+          type: "webmcp.managed_context_binding",
+          protocol_version: "0.1",
+          grant_id: grantId,
+          adapter_id: CODEX_QUEUE_ADAPTER_ID,
+          binding_ref: threadId,
+          bound_at: now.toISOString(),
+          expires_at: activation.receipt.expires_at,
+        });
+      }
+      return managedAdapter.activate(activation);
+    },
+  });
+}
+
+function buildContinuationMessage(activation) {
+  return [
+    "Re-entry continuation is ready.",
+    "Open the exact canonical page below, read its current state, and continue the existing task.",
+    "Use only the page's current WebMCP tools and stop before the human decision boundary.",
+    `Canonical page: ${activation.continuation.canonical_url}`,
+  ].join("\n");
+}
+
+function queueCodexMessage({ executable, threadId, message, timeoutMs, spawnCommand }) {
+  return new Promise((resolve, reject) => {
+    let child;
+    let settled = false;
+    let timer;
+
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      callback(value);
+    };
+
+    try {
+      child = spawnCommand(
+        executable,
+        ["queue", "--thread", threadId, "--message", message],
+        { stdio: ["ignore", "ignore", "ignore"] },
+      );
+    } catch (error) {
+      finish(reject, error);
+      return;
+    }
+
+    if (!child || typeof child.once !== "function") {
+      finish(reject, new Error("Codex queue process is invalid"));
+      return;
+    }
+
+    timer = setTimeout(() => {
+      try {
+        child.kill?.("SIGTERM");
+      } catch {
+        // The activation remains unknown even if the process cannot be terminated.
+      }
+      finish(reject, new Error("Codex queue process timed out"));
+    }, timeoutMs);
+
+    child.once("error", (error) => finish(reject, error));
+    child.once("close", (code, signal) => {
+      if (code === 0 && signal === null) {
+        finish(resolve);
+        return;
+      }
+      finish(reject, new Error("Codex queue process did not complete successfully"));
+    });
+  });
+}
+
+function activationResult(activation, outcome, code, unavailableCapability) {
+  return Object.freeze({
+    type: AGENT_ACTIVATION_RESULT_TYPE,
+    protocol_version: "0.1",
+    delivery_id: activation.delivery_id,
+    event_id: activation.event_id,
+    attempt: activation.attempt,
+    outcome,
+    code,
+    unavailable_capability: unavailableCapability,
+  });
+}
+
+function readClock(clock) {
+  const value = clock();
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError("Codex queue adapter clock must return a valid Date");
+  }
+  return new Date(value.getTime());
+}
+
+function requireTimeout(value) {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < MIN_COMMAND_TIMEOUT_MS ||
+    value > MAX_COMMAND_TIMEOUT_MS
+  ) {
+    throw new TypeError("Codex queue adapter commandTimeoutMs is invalid");
+  }
+  return value;
+}
+
+function requireReference(value, label) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    Buffer.byteLength(value, "utf8") > MAX_REFERENCE_BYTES ||
+    CONTROL_CHARACTER_PATTERN.test(value)
+  ) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function requireExactRecord(value, allowedFields, requiredFields, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  const fields = Object.keys(value);
+  if (
+    fields.some((field) => !allowedFields.includes(field)) ||
+    requiredFields.some((field) => !fields.includes(field))
+  ) {
+    throw new TypeError(`${label} fields are invalid`);
+  }
+}