agent-relay-codex 0.4.25 → 0.4.26

package/README.md

@@ -126,9 +126,9 @@ agent-relay-codex uninstall --purge  # also remove runtime state and PATH entrie
 
 ## How it works
 
-`codex-relay` launches `codex app-server`, starts the live sidecar as the long-lived App Server client, waits for it to resolve one canonical Codex thread, then opens the TUI with `codex resume <thread-id> --remote <app-server-url>`. Agent Relay messages and direct TUI messages therefore share the same Codex context.
+`codex-relay` launches `codex app-server`, then opens the TUI with `codex --remote <app-server-url>`. The normal SessionStart hook registers the visible TUI thread with Agent Relay, so Agent Relay messages and direct TUI messages share the same Codex context.
 
-Use `codex-relay --headless` on servers where Agent Relay is the only interaction surface. It starts the same app-server and sidecar session but does not open a TUI; the launcher prints the attach command if you later want to connect one.
+Use `codex-relay --headless` on servers where Agent Relay is the only interaction surface. It starts the same app-server and sidecar session but does not open a TUI; the launcher prints `codex resume --remote <app-server-url>` if you later want to attach one.
 
 The installed SessionStart hook remains for plain `codex` launches. In that mode, the hook registers the visible Codex session with Agent Relay without requiring the managed `codex-relay` launcher.
 

package/bin/agent-relay-codex.ts

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import net from "node:net";
+import { CodexAppClient } from "../app-client";
 import { approvalModeFromPermissions, codexArgsForApprovalMode, parseApprovalMode } from "../approval";
 import { loadAgentRelayProfile } from "../profile";
 
@@ -43,6 +44,7 @@ Usage:
   agent-relay-codex alias install
   agent-relay-codex alias remove
   agent-relay-codex doctor
+  agent-relay-codex upgrade [--dry-run] [--version VERSION] [--no-restart] [--yes]
   agent-relay-codex start [--headless] [--relay-url URL] [--listen ws://127.0.0.1:PORT] [--thread-mode auto|resume|start] [--thread-id ID] [-- <codex args...>]
   codex-relay [--headless] [--relay-url URL] [--listen ws://127.0.0.1:PORT] [--thread-mode auto|resume|start] [--thread-id ID] [-- <codex args...>]
 
@@ -536,6 +538,41 @@ async function waitForManagedAgent(statePath: string, sidecarPid: number, timeou
   throw new Error(`timed out waiting for managed sidecar to register with Agent Relay; inspect ${dirname(statePath)}/sidecar.log`);
 }
 
+async function loadedThreadIds(listenUrl: string): Promise<string[]> {
+  const client = new CodexAppClient(listenUrl);
+  try {
+    await client.connect();
+    await client.initialize();
+    const loaded = await client.threadLoadedList(50);
+    return loaded.data.filter((id) => typeof id === "string" && id.trim());
+  } finally {
+    client.close();
+  }
+}
+
+async function waitForRemoteTuiThread(
+  listenUrl: string,
+  beforeIds: Set<string>,
+  codex: ReturnType<typeof Bun.spawn>,
+  timeoutMs = 15000,
+): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    try {
+      const loaded = await loadedThreadIds(listenUrl);
+      const candidate = loaded.find((id) => !beforeIds.has(id)) ?? loaded[0];
+      if (candidate) return candidate;
+    } catch {
+      // The remote TUI may still be negotiating its app-server connection.
+    }
+    if (codex.exitCode !== null) return null;
+    await Bun.sleep(250);
+  }
+
+  return null;
+}
+
 function cleanupRun(runDir: string, appServer: ReturnType<typeof Bun.spawn> | null): void {
   if (existsSync(runDir)) {
     const pidsPath = join(runDir, "sidecar-pids.txt");
@@ -777,7 +814,7 @@ async function start(args: string[]): Promise<void> {
   installCodexSupport(true);
 
   let relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-  let listenUrl = process.env.CODEX_APP_SERVER_URL || "";
+  let listenUrl = process.env.AGENT_RELAY_CODEX_LISTEN || "";
   let threadMode = process.env.CODEX_THREAD_MODE || "start";
   let headless = process.env.AGENT_RELAY_CODEX_HEADLESS === "1";
   let threadId = process.env.CODEX_THREAD_ID || "";
@@ -853,7 +890,6 @@ async function start(args: string[]): Promise<void> {
     AGENT_RELAY_CODEX_APPROVAL_POLICY: permissions.approvalPolicy,
     AGENT_RELAY_CODEX_SANDBOX: permissions.sandbox,
     AGENT_RELAY_APPROVAL: effectiveApprovalMode,
-    AGENT_RELAY_CODEX_MANAGED: "1",
     AGENT_RELAY_CODEX_PARENT_PID: String(process.pid),
   };
 
@@ -877,12 +913,61 @@ async function start(args: string[]): Promise<void> {
   process.once("exit", shutdown);
 
   await waitForPort(listenUrl, appServer);
+
+  console.log(`Agent Relay Codex session: ${listenUrl}`);
+  console.log(`Runtime: ${runDir}`);
+
+  if (!headless) {
+    const loadedBefore = new Set(await loadedThreadIds(listenUrl).catch(() => []));
+    const codex = Bun.spawn([codexBinary, "--remote", listenUrl, ...codexArgs], {
+      env,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+
+    const tuiThreadId = await waitForRemoteTuiThread(listenUrl, loadedBefore, codex);
+    if (tuiThreadId) {
+      const sidecarDir = join(runDir, sanitizeSessionKey(tuiThreadId));
+      const statePath = join(sidecarDir, "live-state.json");
+      const sidecarPid = spawnManagedSidecar({
+        runDir,
+        env: { ...env, AGENT_RELAY_CODEX_MANAGED: "1" },
+        sessionDir: sidecarDir,
+        statePath,
+        threadMode: "resume",
+        threadId: tuiThreadId,
+      });
+      appendLauncherLog(runDir, `REMOTE_TUI_THREAD_BOUND thread=${tuiThreadId} sidecarPid=${sidecarPid}`);
+    } else {
+      const fallbackDir = join(runDir, "auto");
+      const fallbackStatePath = join(fallbackDir, "live-state.json");
+      const fallbackPid = spawnManagedSidecar({
+        runDir,
+        env: { ...env, AGENT_RELAY_CODEX_MANAGED: "1" },
+        sessionDir: fallbackDir,
+        statePath: fallbackStatePath,
+        threadMode,
+        threadId: threadId || undefined,
+      });
+      appendLauncherLog(runDir, `REMOTE_TUI_FALLBACK_STARTED reason=THREAD_DISCOVERY_TIMEOUT sidecarPid=${fallbackPid}`);
+    }
+
+    const exitCode = await codex.exited;
+    shutdown();
+    process.exit(exitCode);
+  }
+
+  const managedSidecarEnv = {
+    ...env,
+    AGENT_RELAY_CODEX_MANAGED: "1",
+  };
   const initialSessionKey = threadId ? sanitizeSessionKey(threadId) : "managed";
   const sidecarDir = join(runDir, initialSessionKey);
   const statePath = join(sidecarDir, "live-state.json");
   const sidecarPid = spawnManagedSidecar({
     runDir,
-    env,
+    env: managedSidecarEnv,
     sessionDir: sidecarDir,
     statePath,
     threadMode,
@@ -890,34 +975,14 @@ async function start(args: string[]): Promise<void> {
   });
   const managedAgent = await waitForManagedAgent(statePath, sidecarPid);
   const canonicalThreadId = managedAgent.threadId;
-  const managedEnv = {
-    ...env,
-    CODEX_THREAD_MODE: "resume",
-    CODEX_THREAD_ID: canonicalThreadId,
-  };
 
-  console.log(`Agent Relay Codex session: ${listenUrl}`);
   console.log(`Thread: ${canonicalThreadId}`);
   console.log(`Agent: ${managedAgent.agentId}`);
-  console.log(`Runtime: ${runDir}`);
   appendLauncherLog(runDir, `MANAGED_THREAD thread=${canonicalThreadId} agent=${managedAgent.agentId} sidecarPid=${sidecarPid} headless=${headless}`);
 
-  if (headless) {
-    console.log(`Headless relay sidecar pid: ${sidecarPid}`);
-    console.log(`Attach TUI with: ${codexBinary} resume ${canonicalThreadId} --remote ${listenUrl}`);
-    const exitCode = await appServer.exited;
-    shutdown();
-    process.exit(exitCode);
-  }
-
-  const codex = Bun.spawn([codexBinary, "resume", canonicalThreadId, "--remote", listenUrl, ...codexArgs], {
-    env: managedEnv,
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-
-  const exitCode = await codex.exited;
+  console.log(`Headless relay sidecar pid: ${sidecarPid}`);
+  console.log(`Attach TUI with: ${codexBinary} resume --remote ${listenUrl}`);
+  const exitCode = await appServer.exited;
   shutdown();
   process.exit(exitCode);
 }
@@ -941,6 +1006,11 @@ async function doctor(): Promise<void> {
   }
 }
 
+function upgrade(args: string[]): void {
+  const hasProviderOverride = args.some((arg) => arg === "--providers" || arg === "--provider" || arg === "--codex" || arg === "--claude" || arg === "--all");
+  runChecked(["agent-relay", "upgrade", ...(hasProviderOverride ? [] : ["--providers", "codex"]), ...args]);
+}
+
 async function install(args: string[]): Promise<void> {
   const installAlias = args.includes("--alias");
   const skipAlias = args.includes("--no-alias");
@@ -1000,6 +1070,7 @@ async function main(): Promise<void> {
   }
   if (command === "alias" && args[0] === "remove") return removeCodexAlias();
   if (command === "doctor") return doctor();
+  if (command === "upgrade") return upgrade(args);
   if (command === "start") return start(args);
   return start(command ? [command, ...args] : []);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-codex",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "Codex integration for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
   "type": "module",
   "bin": {

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"