agent-relay-codex 0.4.25 → 0.4.27

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", AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD: "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/live-sidecar.ts

@@ -33,6 +33,7 @@ interface Config {
   sandbox?: string;
   approvalMode: ApprovalMode;
   parentPid?: number;
+  assumeLoadedThread: boolean;
 }
 
 interface RuntimeState {
@@ -90,10 +91,14 @@ class CodexLiveSidecar {
   constructor(private readonly config: Config) {
     this.relay = new RelayClient(config.relayUrl, (msg) => this.log(msg));
     this.app = this.createAppClient();
+    this.threadId = config.threadId || "";
   }
 
   async run(): Promise<void> {
     mkdirSync(dirname(this.config.statePath), { recursive: true });
+    if (this.config.assumeLoadedThread && this.config.threadId) {
+      this.log(`assuming remote TUI thread ${this.config.threadId} is already loaded`);
+    }
 
     process.on("SIGINT", () => void this.stop("SIGINT"));
     process.on("SIGTERM", () => void this.stop("SIGTERM"));
@@ -231,7 +236,7 @@ class CodexLiveSidecar {
         }
 
         const thread = this.threadId
-          ? await this.resumeKnownThread(this.threadId)
+          ? await this.attachKnownThread(this.threadId)
           : await this.resolveThread();
         this.threadId = thread.id;
         this.syncThreadState(thread);
@@ -278,7 +283,11 @@ class CodexLiveSidecar {
     }
   }
 
-  private async resumeKnownThread(threadId: string): Promise<Thread> {
+  private async attachKnownThread(threadId: string): Promise<Thread> {
+    if (this.config.assumeLoadedThread) {
+      return this.readThreadWithFallback(threadId).catch(() => syntheticLoadedThread(threadId, this.config.cwd));
+    }
+
     try {
       const resumed = await this.app.threadResume({
         threadId,
@@ -288,6 +297,13 @@ class CodexLiveSidecar {
       });
       return normalizeThread(resumed.thread);
     } catch (error) {
+      if (isThreadMissingRolloutError(error)) {
+        try {
+          return await this.readThreadWithFallback(threadId);
+        } catch {
+          // Fall through to normal resolution when the thread is neither loaded nor persisted.
+        }
+      }
       this.log(`resume failed for thread ${threadId}: ${describeError(error)}; falling back to thread resolution`);
       this.threadId = "";
       return this.resolveThread();
@@ -713,10 +729,25 @@ function normalizeThread(thread: Thread): Thread {
   };
 }
 
+function syntheticLoadedThread(threadId: string, cwd: string): Thread {
+  return {
+    id: threadId,
+    cwd,
+    status: { type: "idle" },
+    updatedAt: Date.now(),
+    preview: "",
+    turns: [],
+  };
+}
+
 function isThreadMaterializationError(error: unknown): boolean {
   return describeError(error).includes("not materialized yet");
 }
 
+function isThreadMissingRolloutError(error: unknown): boolean {
+  return describeError(error).includes("no rollout found for thread id");
+}
+
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -779,6 +810,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
         sandbox: env.AGENT_RELAY_CODEX_SANDBOX,
       }),
     parentPid: envNumber(env, "AGENT_RELAY_CODEX_PARENT_PID", 0) || undefined,
+    assumeLoadedThread: env.AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD === "1" || env.AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD === "true",
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-codex",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "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.27",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"