codexteer 0.14.1

package/src/thread-id.mjs

@@ -0,0 +1,35 @@
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function normalizeThreadId(input) {
+  if (typeof input !== "string" || input.trim() === "") {
+    throw new Error("Thread ID is required.");
+  }
+
+  let value = input.trim();
+  if (value.startsWith("codex://")) {
+    let url;
+    try {
+      url = new URL(value);
+    } catch {
+      throw new Error(`Invalid Codex thread URL: ${input}`);
+    }
+    if (url.hostname !== "threads") {
+      throw new Error(`Expected codex://threads/<thread-id>: ${input}`);
+    }
+    value = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+  }
+
+  if (!UUID_PATTERN.test(value)) {
+    throw new Error(`Invalid local Codex thread ID: ${input}`);
+  }
+  return value.toLowerCase();
+}
+
+export function threadDeepLink(threadId) {
+  return `codex://threads/${normalizeThreadId(threadId)}`;
+}
+
+export function threadComposerDeepLink(threadId, prompt = "") {
+  const query = new URLSearchParams({ prompt });
+  return `${threadDeepLink(threadId)}?${query}`;
+}

package/src/thread-store.mjs

@@ -0,0 +1,72 @@
+import { open, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { codexHome } from "./runtime.mjs";
+
+const UUID_IN_FILENAME = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+async function walk(directory, output) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+
+  await Promise.all(entries.map(async (entry) => {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) await walk(entryPath, output);
+    else if (entry.isFile() && UUID_IN_FILENAME.test(entry.name)) output.push(entryPath);
+  }));
+}
+
+async function readSessionMetadata(filePath) {
+  const handle = await open(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(128 * 1024);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const firstLine = buffer.subarray(0, bytesRead).toString("utf8").split("\n", 1)[0];
+    const record = JSON.parse(firstLine);
+    return record.type === "session_meta" ? record.payload : {};
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function listLocalThreads({
+  limit = 20,
+  desktopOnly = false,
+  sessionsRoot = path.join(codexHome(), "sessions"),
+} = {}) {
+  const files = [];
+  await walk(sessionsRoot, files);
+  const recent = await Promise.all(files.map(async (filePath) => ({
+    filePath,
+    info: await stat(filePath),
+  })));
+  recent.sort((a, b) => b.info.mtimeMs - a.info.mtimeMs);
+
+  const threads = [];
+  for (const item of recent) {
+    if (threads.length >= limit) break;
+    let metadata;
+    try {
+      metadata = await readSessionMetadata(item.filePath);
+    } catch {
+      continue;
+    }
+    if (desktopOnly && metadata.originator !== "Codex Desktop") continue;
+    const filenameId = UUID_IN_FILENAME.exec(item.filePath)?.[1];
+    const threadId = metadata.id ?? metadata.session_id ?? filenameId;
+    if (!threadId) continue;
+    threads.push({
+      thread_id: threadId,
+      updated_at: item.info.mtime.toISOString(),
+      created_at: metadata.timestamp ?? null,
+      cwd: metadata.cwd ?? null,
+      originator: metadata.originator ?? null,
+      deep_link: `codex://threads/${threadId}`,
+    });
+  }
+  return threads;
+}

package/src/version.mjs

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+
+const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const VERSION = metadata.version;
+export const PACKAGE_NAME = metadata.name;
+const safeVersion = value => typeof value === "string" && value.length <= 100 && /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(value);
+if (!safeVersion(VERSION)) throw new Error("Invalid package version.");
+
+export function versionCompatibility(state) {
+  const runningVersion = safeVersion(state?.codex_steer_version) ? state.codex_steer_version : null;
+  const runningPackage = typeof state?.codex_steer_package === "string" && /^(@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(state.codex_steer_package) && state.codex_steer_package.length <= 214 ? state.codex_steer_package : null;
+  const unknown = !runningVersion || !runningPackage;
+  const matches = runningVersion === VERSION && runningPackage === PACKAGE_NAME;
+  return {
+    status: unknown ? "unverified" : matches ? "matched" : "mismatch",
+    client: { package: PACKAGE_NAME, version: VERSION },
+    runtime: { package: runningPackage, version: runningVersion },
+  };
+}

package/src/wrapper.mjs

@@ -0,0 +1,149 @@
+import { spawn, spawnSync } from "node:child_process";
+import { chmod, stat } from "node:fs/promises";
+import { once } from "node:events";
+import { setTimeout as delay } from "node:timers/promises";
+import { claimRuntime } from "./runtime.mjs";
+import { connectSocket } from "./rpc.mjs";
+import { relay } from "./bridge.mjs";
+import { DesktopSubscriptions, serveSubscriptions } from "./subscription.mjs";
+import { VERSION, PACKAGE_NAME } from "./version.mjs";
+import { RUNTIME_PROTOCOL, RUNTIME_CAPABILITIES } from "./compatibility.mjs";
+import { describeDistribution } from "./distribution.mjs";
+
+export const BUNDLED_CLI = "/Applications/ChatGPT.app/Contents/Resources/codex";
+export const BUNDLED_NODE = "/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node";
+const DESKTOP_EXECUTABLE = "/Applications/ChatGPT.app/Contents/MacOS/ChatGPT";
+
+export function isDesktopProcess({ parentPid = process.ppid, run = spawnSync } = {}) {
+  const parent = run("/bin/ps", ["-p", String(parentPid), "-o", "comm="], { encoding: "utf8", timeout: 3000 });
+  return parent.status === 0 && parent.stdout.trim() === DESKTOP_EXECUTABLE;
+}
+
+async function forwardInvocation(executable, args, env) {
+  const child = spawn(executable, args, { env, stdio: "inherit" });
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = signals.map(signal => () => child.kill(signal));
+  signals.forEach((signal, index) => process.on(signal, handlers[index]));
+  try {
+    const [code, signal] = await once(child, "exit");
+    return code ?? (signal ? 1 : 0);
+  } finally {
+    signals.forEach((signal, index) => process.off(signal, handlers[index]));
+  }
+}
+
+export function serverArguments(args, socketPath) {
+  // Parse CLI/global options, not substrings of TOML values or user prompts.
+  const values = new Set(["-c", "--config", "--enable", "--disable"]);
+  let index = 0;
+  while (index < args.length && args[index].startsWith("-")) {
+    if (values.has(args[index])) index += 2;
+    else if (/^--(?:config|enable|disable)=/.test(args[index])) index++;
+    else return null;
+  }
+  if (args[index] !== "app-server") return null;
+  const transformed = args.slice(0, index + 1);
+  for (let i = index + 1; i < args.length; i++) {
+    const arg = args[i];
+    if (["--help", "-h", "--version", "-V"].includes(arg)) return null;
+    if (!arg.startsWith("-")) return null; // daemon, proxy, schema generation, help
+    if (arg === "--stdio") continue;
+    if (arg === "--listen" || arg.startsWith("--listen=")) {
+      const value = arg === "--listen" ? args[++i] : arg.slice(9);
+      if (value !== "stdio://") throw new Error("Desktop requested a conflicting App Server transport.");
+      continue;
+    }
+    transformed.push(arg);
+    if (values.has(arg) || ["--code-mode-host", "--ws-auth", "--ws-token-file", "--ws-token-sha256", "--ws-shared-secret-file", "--ws-issuer", "--ws-audience", "--ws-max-clock-skew-seconds"].includes(arg)) {
+      if (args[i + 1] == null) throw new Error("Incomplete App Server startup arguments.");
+      transformed.push(args[++i]);
+    }
+  }
+  return [...transformed, "--listen", `unix://${socketPath}`];
+}
+
+export async function stopChild(child) {
+  if (!child?.pid) return;
+  const signal = name => {
+    try { process.kill(-child.pid, name); } catch (error) { if (error.code !== "ESRCH") throw error; }
+  };
+  signal("SIGTERM");
+  if (child.exitCode == null && child.signalCode == null) {
+    await Promise.race([once(child, "exit").catch(() => {}), delay(2000)]);
+  }
+  // Include only the process group created for this server, including its hosts.
+  signal("SIGKILL");
+}
+
+export async function runWrapper(args, { executable = BUNDLED_CLI, env = process.env, input = process.stdin, output = process.stdout, desktopProcess } = {}) {
+  // CODEX_CLI_PATH is inherited by MCP/Computer Use helpers which launch their
+  // own stdio servers. Only Desktop's direct child owns the shared runtime.
+  // Check origin before parsing/changing transports so helper calls remain exact.
+  if (!(desktopProcess ?? isDesktopProcess()) || !serverArguments(args, "/unused")) {
+    return forwardInvocation(executable, args, env);
+  }
+  // Desktop's app-tools peer authorization checks the process ancestry.
+  if (process.execPath !== BUNDLED_NODE) {
+    throw new Error("Run the Desktop wrapper directly so it uses Desktop's bundled Node runtime.");
+  }
+  const version = spawnSync(executable, ["--version"], { encoding: "utf8", timeout: 5000, env });
+  const cliVersion = version.stdout?.match(/codex-cli ([\w.+-]+)/)?.[1];
+  if (version.status !== 0 || !cliVersion) throw new Error("Could not verify the bundled Codex CLI.");
+  const distribution = await describeDistribution();
+  const lease = await claimRuntime(env.CODEX_HOME, {
+    cli_version: cliVersion, node_path: process.execPath, node_version: process.versions.node,
+    codex_steer_package: PACKAGE_NAME, codex_steer_version: VERSION, codex_steer_protocol: RUNTIME_PROTOCOL,
+    codex_steer_capabilities: RUNTIME_CAPABILITIES,
+    distribution_sha256: distribution.sha256,
+  });
+  let child;
+  let socket;
+  let stopSubscriptions;
+  let subscriptions;
+  let interrupted;
+  const signal = () => { interrupted = true; socket?.terminate(); input.destroy(); };
+  process.on("SIGTERM", signal);
+  process.on("SIGINT", signal);
+  try {
+    child = spawn(executable, serverArguments(args, lease.paths.socket), {
+      env, detached: true, stdio: ["ignore", "ignore", "inherit"],
+    });
+    let spawnError;
+    child.on("error", error => { spawnError = error; });
+    for (let i = 0; i < 100; i++) {
+      if (interrupted || spawnError || child.exitCode != null || child.signalCode != null) throw new Error("App Server exited during startup.");
+      if (await stat(lease.paths.socket).catch(() => null)) break;
+      await delay(100);
+    }
+    await chmod(lease.paths.socket, 0o600);
+    await lease.update({ server_pid: child.pid });
+    socket = await connectSocket(lease.paths.socket);
+    subscriptions = new DesktopSubscriptions(socket);
+    stopSubscriptions = await serveSubscriptions(lease.paths.control, subscriptions);
+    let initId;
+    await relay(input, output, socket, {
+      onDesktopMessage(message) {
+        if (message.method === "initialize") initId = message.id;
+      },
+      onServerMessage(message) {
+        // Desktop 26.903.71938 sends initialize and considers its response the
+        // handshake completion; it does not emit the optional initialized
+        // notification shown in the public client example. Forward either form.
+        if (!message.method && initId != null && message.id === initId && message.result) {
+          subscriptions.ready = true;
+          lease.update({ desktop_connected: true }).catch(() => socket.terminate());
+        }
+        return subscriptions.consume(message);
+      },
+    });
+    return 0;
+  } finally {
+    process.off("SIGTERM", signal);
+    process.off("SIGINT", signal);
+    await lease.update({ desktop_connected: false }).catch(() => {});
+    socket?.terminate();
+    await stopSubscriptions?.();
+    await stopChild(child);
+    await lease.release();
+  }
+}