agent-relay-codex 0.4.23 → 0.4.25

package/README.md

@@ -25,6 +25,9 @@ bunx agent-relay-server@latest
 
 # start Codex with Agent Relay (after restarting your shell)
 codex-relay
+
+# start a relay-only Codex agent without opening a TUI
+codex-relay --headless
 ```
 
 Without restarting your shell:
@@ -76,6 +79,7 @@ Run with `AGENT_RELAY_PROFILE=frontend-developer agent-relay-codex start`.
 | `CODEX_THREAD_MODE` | `start` | Thread attach: `start`, `resume`, `auto` |
 | `CODEX_THREAD_ID` | — | Pin to a specific thread |
 | `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:4501` | App-server WebSocket URL |
+| `AGENT_RELAY_CODEX_HEADLESS` | — | Set to `1` to run without opening a TUI |
 
 ### Advanced tuning
 
@@ -87,7 +91,6 @@ Run with `AGENT_RELAY_PROFILE=frontend-developer agent-relay-codex start`.
 | `AGENT_RELAY_CODEX_COALESCE_WINDOW_MS` | `600` | Message batch window |
 | `AGENT_RELAY_CODEX_RELAY_BACKOFF_INITIAL_MS` | `2000` | Relay API retry backoff |
 | `AGENT_RELAY_CODEX_RELAY_BACKOFF_MAX_MS` | `60000` | Relay API retry backoff cap |
-| `AGENT_RELAY_CODEX_HOOK_TIMEOUT_MS` | `5000` | SessionStart handshake timeout |
 
 ## Approval mode
 
@@ -123,7 +126,13 @@ agent-relay-codex uninstall --purge  # also remove runtime state and PATH entrie
 
 ## How it works
 
-`codex-relay` launches `codex app-server`, opens Codex through `codex --remote`, and spawns a live sidecar that:
+`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.
+
+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.
+
+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.
+
+The live sidecar:
 
 - Registers the session as an Agent Relay agent
 - Polls the relay inbox and delivers messages into the active Codex thread

package/bin/agent-relay-codex.ts

@@ -16,24 +16,6 @@ type RelayStats = {
   version?: string;
 };
 
-type HookHandshake = {
-  status: "ok" | "error";
-  code: string;
-  message?: string;
-  pid?: number;
-  threadId?: string;
-  timestamp?: string;
-};
-
-type HookWaitResult = {
-  ok: boolean;
-  code: string;
-  message?: string;
-  pid?: number;
-};
-
-const DEFAULT_HOOK_HANDSHAKE_TIMEOUT_MS = 5000;
-
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const home = process.env.HOME || process.env.USERPROFILE || homedir();
@@ -55,14 +37,14 @@ function usage(exitCode = 0): never {
   console.log(`agent-relay-codex
 
 Usage:
-  agent-relay-codex [--relay-url URL] [--listen ws://127.0.0.1:PORT] [-- <codex args...>]
+  agent-relay-codex [--headless] [--relay-url URL] [--listen ws://127.0.0.1:PORT] [-- <codex args...>]
   agent-relay-codex install [--alias|--no-alias]
   agent-relay-codex uninstall [--purge]
   agent-relay-codex alias install
   agent-relay-codex alias remove
   agent-relay-codex doctor
-  agent-relay-codex start [--relay-url URL] [--listen ws://127.0.0.1:PORT] [--thread-mode auto|resume|start] [-- <codex args...>]
-  codex-relay [--relay-url URL] [--listen ws://127.0.0.1:PORT] [--thread-mode auto|resume|start] [-- <codex args...>]
+  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...>]
 
 With no subcommand, this launches Codex with live Agent Relay support.`);
   process.exit(exitCode);
@@ -99,21 +81,14 @@ function readJsonFile<T>(path: string, fallback: T): T {
   return JSON.parse(readFileSync(path, "utf8")) as T;
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function envPositiveInt(name: string, fallback: number): number {
-  const raw = process.env[name];
-  if (!raw) return fallback;
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}
-
 function appendLauncherLog(runDir: string, line: string): void {
   appendFileSync(join(runDir, "launcher.log"), `${new Date().toISOString()} ${line}\n`);
 }
 
+function sanitizeSessionKey(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 96) || "thread";
+}
+
 function isAgentRelaySessionStartCommand(command: string): boolean {
   return /agent-relay.*hooks\/session-start\.ts/.test(command);
 }
@@ -424,67 +399,43 @@ async function waitForPort(url: string, child: ReturnType<typeof Bun.spawn>): Pr
   throw new Error(`timed out waiting for ${url}`);
 }
 
-async function waitForHookHandshake(runDir: string, timeoutMs: number): Promise<HookWaitResult> {
-  const handshakePath = join(runDir, "session-start-handshake.json");
-  const deadline = Date.now() + timeoutMs;
-
-  while (Date.now() < deadline) {
-    if (existsSync(handshakePath)) {
-      try {
-        const parsed = JSON.parse(readFileSync(handshakePath, "utf8")) as HookHandshake;
-        const code = typeof parsed.code === "string" && parsed.code.trim() ? parsed.code.trim() : "HOOK_HANDSHAKE_INVALID";
-        const message = typeof parsed.message === "string" ? parsed.message : undefined;
-        const pid = typeof parsed.pid === "number" && Number.isFinite(parsed.pid) && parsed.pid > 0
-          ? parsed.pid
-          : undefined;
-
-        if (parsed.status === "ok") return { ok: true, code, message, pid };
-        if (parsed.status === "error") return { ok: false, code, message, pid };
-        return { ok: false, code: "HOOK_HANDSHAKE_INVALID", message: `unexpected status ${String((parsed as any).status)}` };
-      } catch (error) {
-        return { ok: false, code: "HOOK_HANDSHAKE_INVALID", message: errorMessage(error) };
-      }
-    }
-    await Bun.sleep(100);
-  }
-
-  return {
-    ok: false,
-    code: "HOOK_HANDSHAKE_TIMEOUT",
-    message: `no hook handshake observed within ${timeoutMs}ms`,
-  };
-}
+type SessionPermissions = {
+  approvalPolicy?: string;
+  sandbox?: string;
+};
 
-function spawnFallbackSidecar(runDir: string, env: Record<string, string | undefined>): number {
-  const autoDir = join(runDir, "auto");
-  mkdirSync(autoDir, { recursive: true });
+function spawnManagedSidecar(params: {
+  runDir: string;
+  env: Record<string, string | undefined>;
+  sessionDir: string;
+  statePath: string;
+  threadMode: string;
+  threadId?: string;
+}): number {
+  const { runDir, env, sessionDir, statePath, threadMode, threadId } = params;
+  mkdirSync(sessionDir, { recursive: true });
 
   const sidecarEnv: Record<string, string | undefined> = {
     ...env,
-    CODEX_THREAD_MODE: env.AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE || env.CODEX_THREAD_MODE || "start",
+    CODEX_THREAD_MODE: threadMode,
+    CODEX_THREAD_ID: threadId || undefined,
     AGENT_RELAY_CODEX_CWD: process.cwd(),
-    AGENT_RELAY_CODEX_STATE_PATH: join(autoDir, "live-state.json"),
+    AGENT_RELAY_CODEX_STATE_PATH: statePath,
   };
-  delete sidecarEnv.CODEX_THREAD_ID;
 
   const sidecar = Bun.spawn(["bun", "run", join(activePackageRoot(), "live-sidecar.ts")], {
     env: sidecarEnv,
-    stdout: Bun.file(join(autoDir, "sidecar.log")),
-    stderr: Bun.file(join(autoDir, "sidecar.log")),
+    stdout: Bun.file(join(sessionDir, "sidecar.log")),
+    stderr: Bun.file(join(sessionDir, "sidecar.log")),
   });
   sidecar.unref();
 
-  writeFileSync(join(autoDir, "sidecar.pid"), String(sidecar.pid));
+  writeFileSync(join(sessionDir, "sidecar.pid"), String(sidecar.pid));
   appendFileSync(join(runDir, "sidecar-pids.txt"), `${sidecar.pid}\n`);
 
   return sidecar.pid;
 }
 
-type SessionPermissions = {
-  approvalPolicy?: string;
-  sandbox?: string;
-};
-
 function hasCodexPermissionMode(codexArgs: string[]): boolean {
   for (const arg of codexArgs) {
     if (
@@ -549,6 +500,42 @@ function resolveSessionPermissions(codexArgs: string[]): SessionPermissions {
   return { approvalPolicy, sandbox };
 }
 
+function codexModelFromArgs(codexArgs: string[]): string | undefined {
+  for (let index = 0; index < codexArgs.length; index += 1) {
+    const arg = codexArgs[index]!;
+    if (arg === "--model" || arg === "-m") {
+      const next = codexArgs[index + 1];
+      if (next && !next.startsWith("-")) return next;
+      continue;
+    }
+    if (arg.startsWith("--model=")) return arg.slice("--model=".length);
+  }
+  return undefined;
+}
+
+async function waitForManagedAgent(statePath: string, sidecarPid: number, timeoutMs = 30000): Promise<{ threadId: string; agentId: string }> {
+  const deadline = Date.now() + timeoutMs;
+  let threadId = "";
+  while (Date.now() < deadline) {
+    if (!isAlive(sidecarPid)) {
+      throw new Error(`managed sidecar exited before registering with Agent Relay; inspect ${dirname(statePath)}/sidecar.log`);
+    }
+    if (existsSync(statePath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(statePath, "utf8")) as { threadId?: unknown; agentId?: unknown };
+        if (typeof parsed.threadId === "string" && parsed.threadId.trim()) threadId = parsed.threadId.trim();
+        if (threadId && typeof parsed.agentId === "string" && parsed.agentId.trim()) {
+          return { threadId, agentId: parsed.agentId.trim() };
+        }
+      } catch {
+        // The sidecar may be writing the state file; retry until timeout.
+      }
+    }
+    await Bun.sleep(100);
+  }
+  throw new Error(`timed out waiting for managed sidecar to register with Agent Relay; inspect ${dirname(statePath)}/sidecar.log`);
+}
+
 function cleanupRun(runDir: string, appServer: ReturnType<typeof Bun.spawn> | null): void {
   if (existsSync(runDir)) {
     const pidsPath = join(runDir, "sidecar-pids.txt");
@@ -792,6 +779,8 @@ async function start(args: string[]): Promise<void> {
   let relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
   let listenUrl = process.env.CODEX_APP_SERVER_URL || "";
   let threadMode = process.env.CODEX_THREAD_MODE || "start";
+  let headless = process.env.AGENT_RELAY_CODEX_HEADLESS === "1";
+  let threadId = process.env.CODEX_THREAD_ID || "";
   const cwd = process.cwd();
   const rig = process.env.AGENT_RELAY_CODEX_RIG || "codex-live";
   const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
@@ -814,6 +803,14 @@ async function start(args: string[]): Promise<void> {
       listenUrl = args[++index] || listenUrl;
       continue;
     }
+    if (arg === "--headless" || arg === "--no-tui") {
+      headless = true;
+      continue;
+    }
+    if (arg === "--thread-id") {
+      threadId = args[++index] || threadId;
+      continue;
+    }
     if (arg === "--thread-mode") {
       threadMode = args[++index] || threadMode;
       if (!["auto", "resume", "start"].includes(threadMode)) {
@@ -823,6 +820,7 @@ async function start(args: string[]): Promise<void> {
     }
     codexArgs.push(arg);
   }
+  if (!["auto", "resume", "start"].includes(threadMode)) threadMode = "start";
 
   if (!listenUrl) listenUrl = await pickLoopbackUrl();
   if (!hasCodexPermissionMode(codexArgs)) {
@@ -830,6 +828,7 @@ async function start(args: string[]): Promise<void> {
   }
   const permissions = resolveSessionPermissions(codexArgs);
   const effectiveApprovalMode = approvalModeFromPermissions(permissions);
+  const model = process.env.CODEX_MODEL || codexModelFromArgs(codexArgs);
   if (hasApprovalEnv && effectiveApprovalMode !== requestedApprovalMode) {
     throw new Error(
       `Codex permission flags resolve to AGENT_RELAY_APPROVAL=${effectiveApprovalMode}, but AGENT_RELAY_APPROVAL=${requestedApprovalMode} was requested.`,
@@ -849,9 +848,13 @@ async function start(args: string[]): Promise<void> {
     AGENT_RELAY_CODEX_RUNTIME_DIR: runDir,
     CODEX_APP_SERVER_URL: listenUrl,
     CODEX_THREAD_MODE: threadMode,
+    CODEX_THREAD_ID: threadId || undefined,
+    CODEX_MODEL: model || undefined,
     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),
   };
 
   const appLog = Bun.file(join(runDir, "app-server.log"));
@@ -874,51 +877,46 @@ async function start(args: string[]): Promise<void> {
   process.once("exit", shutdown);
 
   await waitForPort(listenUrl, appServer);
+  const initialSessionKey = threadId ? sanitizeSessionKey(threadId) : "managed";
+  const sidecarDir = join(runDir, initialSessionKey);
+  const statePath = join(sidecarDir, "live-state.json");
+  const sidecarPid = spawnManagedSidecar({
+    runDir,
+    env,
+    sessionDir: sidecarDir,
+    statePath,
+    threadMode,
+    threadId: threadId || undefined,
+  });
+  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}`);
 
-  const codex = Bun.spawn([codexBinary, "--remote", listenUrl, ...codexArgs], {
-    env,
+  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 hookTimeoutMs = envPositiveInt("AGENT_RELAY_CODEX_HOOK_TIMEOUT_MS", DEFAULT_HOOK_HANDSHAKE_TIMEOUT_MS);
-  const handshake = await waitForHookHandshake(runDir, hookTimeoutMs);
-  let fallbackReason: HookWaitResult | null = null;
-
-  if (!handshake.ok) {
-    fallbackReason = handshake;
-  } else if (handshake.pid === undefined) {
-    fallbackReason = {
-      ok: false,
-      code: "HOOK_HANDSHAKE_NO_PID",
-      message: "hook reported success without a sidecar pid",
-    };
-  } else if (!isAlive(handshake.pid)) {
-    fallbackReason = {
-      ok: false,
-      code: "HOOK_HANDSHAKE_PID_NOT_ALIVE",
-      message: `hook reported pid ${handshake.pid} but it is not running`,
-    };
-  } else {
-    appendLauncherLog(runDir, `HOOK_HANDSHAKE_OK code=${handshake.code} pid=${handshake.pid}`);
-  }
-
-  if (fallbackReason && codex.exitCode === null) {
-    const pid = spawnFallbackSidecar(runDir, env);
-    appendFileSync(
-      join(runDir, "launcher.log"),
-      `${new Date().toISOString()} HOOK_FALLBACK_STARTED reason=${fallbackReason.code} fallbackPid=${pid}${fallbackReason.message ? ` detail=${fallbackReason.message}` : ""}\n`,
-    );
-  } else if (fallbackReason) {
-    appendLauncherLog(
-      runDir,
-      `HOOK_FALLBACK_SKIPPED reason=${fallbackReason.code} codexExit=${codex.exitCode}${fallbackReason.message ? ` detail=${fallbackReason.message}` : ""}`,
-    );
-  }
-
   const exitCode = await codex.exited;
   shutdown();
   process.exit(exitCode);

package/hooks/session-start.ts

@@ -74,6 +74,11 @@ const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
 const profile = loadAgentRelayProfile(process.env, { provider: "codex", rig, project });
 const approvalMode = profile.approval ?? parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
 
+if (process.env.AGENT_RELAY_CODEX_MANAGED === "1") {
+  outputContext("Agent Relay is managed by codex-relay for this session; the launcher attached Relay and TUI to the same Codex App Server thread.");
+  process.exit(0);
+}
+
 if (!appServerUrl || !runId) {
   outputContext(
     "Agent Relay for Codex is installed. For live incoming relay messages, start Codex with `agent-relay-codex start` so a managed app-server and sidecar can attach to this session.",
@@ -129,6 +134,7 @@ const spawnEnv: Record<string, string | undefined> = {
   AGENT_RELAY_CODEX_STATE_PATH: statePath,
   CODEX_MODEL: input.model || process.env.CODEX_MODEL || "",
   AGENT_RELAY_APPROVAL: process.env.AGENT_RELAY_APPROVAL || profile.approval || "",
+  AGENT_RELAY_CODEX_PARENT_PID: String(process.ppid),
 };
 if (threadId) {
   spawnEnv.CODEX_THREAD_ID = threadId;

package/live-sidecar.ts

@@ -32,6 +32,7 @@ interface Config {
   approvalPolicy?: string;
   sandbox?: string;
   approvalMode: ApprovalMode;
+  parentPid?: number;
 }
 
 interface RuntimeState {
@@ -104,6 +105,10 @@ class CodexLiveSidecar {
     while (!this.stopping) {
       let sleepMs = this.config.pollIntervalMs;
       try {
+        if (this.parentExited()) {
+          await this.stop("parent-exit");
+          break;
+        }
         const now = Date.now();
         if (now - this.lastHeartbeatAt >= this.config.heartbeatIntervalMs) {
           await this.relay.heartbeat(this.agentId, this.agentSession());
@@ -145,7 +150,7 @@ class CodexLiveSidecar {
           this.log(`loop error: ${describeError(error)}; retrying in ${sleepMs}ms`);
         }
       }
-      await delay(sleepMs);
+      await this.delayWithParentCheck(sleepMs);
     }
   }
 
@@ -258,6 +263,21 @@ class CodexLiveSidecar {
     this.app.close();
   }
 
+  private parentExited(): boolean {
+    return Boolean(this.config.parentPid && !isAlive(this.config.parentPid));
+  }
+
+  private async delayWithParentCheck(ms: number): Promise<void> {
+    const deadline = Date.now() + ms;
+    while (!this.stopping && Date.now() < deadline) {
+      if (this.parentExited()) {
+        await this.stop("parent-exit");
+        return;
+      }
+      await delay(Math.min(500, Math.max(0, deadline - Date.now())));
+    }
+  }
+
   private async resumeKnownThread(threadId: string): Promise<Thread> {
     try {
       const resumed = await this.app.threadResume({
@@ -708,6 +728,15 @@ function envNumber(env: NodeJS.ProcessEnv, name: string, fallback: number): numb
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function parseThreadMode(raw: string | undefined): Config["threadMode"] {
   if (raw === "auto" || raw === "resume" || raw === "start") return raw;
   return "start";
@@ -749,6 +778,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
         approvalPolicy: env.AGENT_RELAY_CODEX_APPROVAL_POLICY,
         sandbox: env.AGENT_RELAY_CODEX_SANDBOX,
       }),
+    parentPid: envNumber(env, "AGENT_RELAY_CODEX_PARENT_PID", 0) || undefined,
   };
 }
 

package/package.json

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