agent-relay-codex 0.6.1 → 0.10.0

package/bin/agent-relay-codex.ts

@@ -1,1155 +1,56 @@
 #!/usr/bin/env bun
-import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-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";
 
-type HooksJson = {
-  hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<Record<string, unknown>> }>>;
-};
+const HELP = `
+agent-relay-codex
 
-type RelayStats = {
-  version?: string;
-};
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const packageRoot = resolve(__dirname, "..");
-const home = process.env.HOME || process.env.USERPROFILE || homedir();
-const installRoot = join(home, ".agent-relay", "codex");
-const installedPackageRoot = join(installRoot, "package");
-const aliasBinDir = join(installRoot, "bin");
-const marketplaceRoot = join(installRoot, "marketplace");
-const marketplacePluginRoot = join(marketplaceRoot, "plugins", "agent-relay");
-const marketplaceFile = join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
-const runtimeRoot = join(installRoot, "runtime");
-const installedHookScript = join(installedPackageRoot, "hooks", "session-start.ts");
-const packageVersion = readJsonFile<{ version: string }>(join(packageRoot, "package.json"), { version: "0.0.0" }).version;
-
-function activePackageRoot(): string {
-  return process.env.AGENT_RELAY_CODEX_PACKAGE_ROOT || packageRoot;
-}
-
-function usage(exitCode = 0): never {
-  console.log(`agent-relay-codex
+Codex lifecycle is owned by the unified Agent Relay runner.
 
 Usage:
-  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 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...>]
-
-With no subcommand, this launches Codex with live Agent Relay support.`);
-  process.exit(exitCode);
-}
-
-const pathMarker = "# Agent Relay Codex alias";
-
-function commandExists(command: string): boolean {
-  return findOnPath(command) !== null;
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}
-
-function runChecked(args: string[], options: { cwd?: string; env?: Record<string, string | undefined>; quiet?: boolean } = {}): void {
-  const result = Bun.spawnSync(args, {
-    cwd: options.cwd,
-    env: { ...process.env, ...options.env },
-    stdout: options.quiet ? "pipe" : "inherit",
-    stderr: options.quiet ? "pipe" : "inherit",
-  });
-  if (result.exitCode !== 0) {
-    if (options.quiet) {
-      const stderr = result.stderr?.toString().trim() || "";
-      if (stderr) console.error(stderr);
-    }
-    throw new Error(`${args.join(" ")} failed with exit code ${result.exitCode}`);
-  }
-}
-
-function readJsonFile<T>(path: string, fallback: T): T {
-  if (!existsSync(path)) return fallback;
-  return JSON.parse(readFileSync(path, "utf8")) as T;
-}
-
-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);
-}
-
-function isSessionStartGroupHeader(header: string | null | undefined): boolean {
-  return header?.trim() === "[[hooks.SessionStart]]";
-}
-
-function isSessionStartHookHeader(header: string | null | undefined): boolean {
-  return header?.trim() === "[[hooks.SessionStart.hooks]]";
-}
-
-export function removeAgentRelaySessionStartToml(input: string): string {
-  const lines = input.split(/\r?\n/);
-  const blocks: Array<{ header: string | null; text: string }> = [];
-
-  for (let index = 0; index < lines.length; ) {
-    const line = lines[index] ?? "";
-    const header = /^\[\[?/.test(line) ? line : null;
-    const block: string[] = [];
-    do {
-      block.push(lines[index] ?? "");
-      index += 1;
-    } while (index < lines.length && !/^\[\[?/.test(lines[index] ?? ""));
-    blocks.push({ header, text: block.join("\n") });
-  }
-
-  let output = "";
-  for (let index = 0; index < blocks.length; ) {
-    const block = blocks[index];
-    if (isSessionStartGroupHeader(block?.header)) {
-      const group = block!;
-      const hooks: typeof blocks = [];
-      index += 1;
-      while (index < blocks.length && isSessionStartHookHeader(blocks[index]?.header)) {
-        hooks.push(blocks[index]!);
-        index += 1;
-      }
-
-      const keptHooks = hooks.filter((hook) => !isAgentRelaySessionStartCommand(hook.text));
-      const groupIsAgentRelay = isAgentRelaySessionStartCommand(group.text) || (hooks.length > 0 && keptHooks.length === 0);
-      if (!groupIsAgentRelay || keptHooks.length > 0) {
-        output += `${group.text}\n`;
-        for (const hook of keptHooks) output += `${hook.text}\n`;
-      }
-      continue;
-    }
-
-    if (isSessionStartHookHeader(block?.header) && isAgentRelaySessionStartCommand(block?.text ?? "")) {
-      index += 1;
-      continue;
-    }
-
-    output += `${block?.text ?? ""}\n`;
-    index += 1;
-  }
-
-  return output.replace(/\s+$/, "\n");
-}
-
-function compareVersions(left: string, right: string): number {
-  const leftParts = left.split(/[.-]/).map((part) => Number.parseInt(part, 10) || 0);
-  const rightParts = right.split(/[.-]/).map((part) => Number.parseInt(part, 10) || 0);
-  const length = Math.max(leftParts.length, rightParts.length);
-  for (let index = 0; index < length; index += 1) {
-    const diff = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
-    if (diff !== 0) return diff > 0 ? 1 : -1;
-  }
-  return 0;
-}
-
-async function getRelayStats(relayUrl: string): Promise<RelayStats | null> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 1500);
-  try {
-    const headers: Record<string, string> = {};
-    if (process.env.AGENT_RELAY_TOKEN) headers["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
-    const response = await fetch(new URL("/api/stats", relayUrl), { signal: controller.signal, headers });
-    if (!response.ok) return null;
-    return (await response.json()) as RelayStats;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function checkRelayServer(): Promise<"missing" | "current" | "old" | "unknown"> {
-  const relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-  const stats = await getRelayStats(relayUrl);
-  if (!stats) {
-    console.log(`No Agent Relay server detected at ${relayUrl}. Start it with: bunx agent-relay-server@latest`);
-    return "missing";
-  }
-
-  const serverVersion = stats.version || "unknown";
-  if (serverVersion === "unknown") {
-    console.log(`Agent Relay server detected at ${relayUrl}, but its version is unknown. Current package: ${packageVersion}.`);
-    return "unknown";
-  }
-
-  const comparison = compareVersions(serverVersion, packageVersion);
-  if (comparison < 0) {
-    console.log(`Agent Relay server at ${relayUrl} is older (${serverVersion}); current package is ${packageVersion}.`);
-    console.log("Restart that server with the latest package when convenient: bunx agent-relay-server@latest");
-    return "old";
-  }
-
-  console.log(`Agent Relay server at ${relayUrl} is current (${serverVersion}).`);
-  return "current";
-}
-
-function syncInstalledPackage(): void {
-  mkdirSync(installedPackageRoot, { recursive: true });
-  if (samePath(packageRoot, installedPackageRoot)) return;
-
-  for (const entry of readdirSync(installedPackageRoot)) {
-    rmSync(join(installedPackageRoot, entry), { recursive: true, force: true });
-  }
-  cpSync(packageRoot, installedPackageRoot, { recursive: true });
-}
-
-function pathEntries(): string[] {
-  return (process.env.PATH || "")
-    .split(process.platform === "win32" ? ";" : ":")
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-}
-
-function samePath(left: string, right: string): boolean {
-  const a = resolve(left);
-  const b = resolve(right);
-  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
-}
-
-function isAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function candidateNames(command: string): string[] {
-  if (process.platform !== "win32") return [command];
-  const extensions = (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD;.PS1").split(";").filter(Boolean);
-  if (extensions.some((extension) => command.toLowerCase().endsWith(extension.toLowerCase()))) return [command];
-  return [command, ...extensions.map((extension) => `${command}${extension.toLowerCase()}`)];
-}
-
-function findOnPath(command: string, excludeDirs: string[] = []): string | null {
-  for (const dir of pathEntries()) {
-    if (excludeDirs.some((excluded) => samePath(dir, excluded))) continue;
-    for (const candidate of candidateNames(command)) {
-      const path = join(dir, candidate);
-      if (existsSync(path)) return path;
-    }
-  }
-  return null;
-}
-
-function findCodexBinary(): string {
-  const codex = findOnPath("codex", [aliasBinDir]);
-  if (!codex) throw new Error("Codex CLI is required");
-  return codex;
-}
-
-function isRelayDisabled(env: Record<string, string | undefined> = process.env): boolean {
-  return env.AGENT_RELAY_DISABLED === "1";
-}
-
-const relayBypassSubcommands = new Set([
-  "a",
-  "app-server",
-  "apply",
-  "cloud",
-  "completion",
-  "debug",
-  "e",
-  "exec",
-  "exec-server",
-  "features",
-  "login",
-  "logout",
-  "mcp",
-  "mcp-server",
-  "plugin",
-  "remote-control",
-  "review",
-  "sandbox",
-  "update",
-]);
-
-function codexSubcommand(args: string[]): string {
-  const optionsWithValues = new Set([
-    "-c",
-    "--config",
-    "-m",
-    "--model",
-    "-p",
-    "--profile",
-    "-s",
-    "--sandbox",
-    "-C",
-    "--cd",
-    "--add-dir",
-  ]);
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === "--") return "";
-    if (optionsWithValues.has(arg)) {
-      index += 1;
-      continue;
-    }
-    if (arg.startsWith("-")) continue;
-    return arg;
-  }
-
-  return "";
-}
+  codex-relay [--headless] [--cwd PATH] [--relay-url URL] [-- CODEx_ARGS...]
+  agent-relay provider wrap codex
+  agent-relay provider unwrap codex
+  agent-relay-codex upgrade [--dry-run]
+`.trim();
 
 export function shouldBypassRelay(args: string[], env: Record<string, string | undefined> = process.env): boolean {
-  return isRelayDisabled(env) || relayBypassSubcommands.has(codexSubcommand(args));
-}
-
-async function runCodexPassthrough(args: string[]): Promise<void> {
-  const codex = Bun.spawn([findCodexBinary(), ...args], {
-    env: { ...process.env, AGENT_RELAY_DISABLED: "1" },
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-  process.exit(await codex.exited);
+  if (env.AGENT_RELAY_DISABLED === "1") return true;
+  const commands = args.filter((arg) => !arg.startsWith("-"));
+  return ["exec", "e", "review", "plugin"].includes(commands[0] ?? "");
 }
 
-function installMarketplace(quiet = false): void {
-  syncInstalledPackage();
-
-  mkdirSync(marketplacePluginRoot, { recursive: true });
-  rmSync(marketplacePluginRoot, { recursive: true, force: true });
-  cpSync(join(installedPackageRoot, "plugin"), marketplacePluginRoot, { recursive: true });
-  mkdirSync(dirname(marketplaceFile), { recursive: true });
-
-  writeFileSync(
-    marketplaceFile,
-    `${JSON.stringify(
-      {
-        name: "agent-relay",
-        interface: { displayName: "Agent Relay" },
-        plugins: [
-          {
-            name: "agent-relay",
-            source: { source: "local", path: "./plugins/agent-relay" },
-            policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
-            category: "Productivity",
-          },
-        ],
-      },
-      null,
-      2,
-    )}\n`,
-  );
-
-  runChecked([findCodexBinary(), "plugin", "marketplace", "add", marketplaceRoot], { quiet });
-}
-
-function installHook(): void {
-  mkdirSync(join(home, ".codex"), { recursive: true });
-  const command = `bun ${shellQuote(installedHookScript)}`;
-
-  const configPath = join(home, ".codex", "config.toml");
-  const existingConfig = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-  let output = removeAgentRelaySessionStartToml(existingConfig);
-  if (!output.endsWith("\n\n")) output += output.endsWith("\n") ? "\n" : "\n\n";
-  output += `[[hooks.SessionStart]]
-matcher = "startup|resume"
-
-[[hooks.SessionStart.hooks]]
-type = "command"
-command = "${command.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"
-statusMessage = "Starting Agent Relay"
-timeout = 10
-`;
-
-  writeFileSync(configPath, output);
-
-  const hooksPath = join(home, ".codex", "hooks.json");
-  if (!existsSync(hooksPath)) return;
-
-  const hooksJson = readJsonFile<HooksJson>(hooksPath, { hooks: {} });
-  hooksJson.hooks ??= {};
-  hooksJson.hooks.SessionStart = (hooksJson.hooks.SessionStart ?? [])
-    .map((group) => ({
-      ...group,
-      hooks: (group.hooks ?? []).filter((hook) => {
-        if (hook.type !== "command" || typeof hook.command !== "string") return true;
-        return !isAgentRelaySessionStartCommand(hook.command);
-      }),
-    }))
-    .filter((group) => (group.hooks ?? []).length > 0);
-
-  if (hooksJson.hooks.SessionStart.length === 0) delete hooksJson.hooks.SessionStart;
-
-  if (Object.keys(hooksJson.hooks).length === 0) rmSync(hooksPath, { force: true });
-  else writeFileSync(hooksPath, `${JSON.stringify(hooksJson, null, 2)}\n`);
-}
-
-function removeHook(): void {
-  const configPath = join(home, ".codex", "config.toml");
-  if (existsSync(configPath)) {
-    const cleaned = removeAgentRelaySessionStartToml(readFileSync(configPath, "utf8"));
-    if (cleaned.trim()) writeFileSync(configPath, cleaned);
-    else rmSync(configPath, { force: true });
-  }
-
-  const hooksPath = join(home, ".codex", "hooks.json");
-  if (!existsSync(hooksPath)) return;
-
-  const hooksJson = readJsonFile<HooksJson>(hooksPath, { hooks: {} });
-  hooksJson.hooks ??= {};
-  hooksJson.hooks.SessionStart = (hooksJson.hooks.SessionStart ?? [])
-    .map((group) => ({
-      ...group,
-      hooks: (group.hooks ?? []).filter((hook) => {
-        if (hook.type !== "command" || typeof hook.command !== "string") return true;
-        return !isAgentRelaySessionStartCommand(hook.command);
-      }),
-    }))
-    .filter((group) => (group.hooks ?? []).length > 0);
-
-  if (hooksJson.hooks.SessionStart.length === 0) delete hooksJson.hooks.SessionStart;
-
-  if (Object.keys(hooksJson.hooks).length === 0) rmSync(hooksPath, { force: true });
-  else writeFileSync(hooksPath, `${JSON.stringify(hooksJson, null, 2)}\n`);
-}
-
-async function pickLoopbackUrl(): Promise<string> {
-  const port = await new Promise<number>((resolvePort, reject) => {
-    const server = net.createServer();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      server.close(() => {
-        if (!address || typeof address === "string") reject(new Error("failed to allocate local port"));
-        else resolvePort(address.port);
-      });
-    });
-  });
-  return `ws://127.0.0.1:${port}`;
-}
-
-async function waitForPort(url: string, child: ReturnType<typeof Bun.spawn>): Promise<void> {
-  const parsed = new URL(url);
-  const port = Number(parsed.port);
-  const host = parsed.hostname;
-
-  for (let attempt = 0; attempt < 100; attempt += 1) {
-    if (child.exitCode !== null) throw new Error("codex app-server exited before accepting connections");
-    const ok = await new Promise<boolean>((resolveAttempt) => {
-      const socket = net.connect({ host, port });
-      socket.once("connect", () => {
-        socket.destroy();
-        resolveAttempt(true);
-      });
-      socket.once("error", () => resolveAttempt(false));
-      socket.setTimeout(200, () => {
-        socket.destroy();
-        resolveAttempt(false);
-      });
-    });
-    if (ok) return;
-    await Bun.sleep(100);
-  }
-
-  throw new Error(`timed out waiting for ${url}`);
-}
-
-type SessionPermissions = {
-  approvalPolicy?: string;
-  sandbox?: string;
-};
-
-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: threadMode,
-    CODEX_THREAD_ID: threadId || undefined,
-    AGENT_RELAY_CODEX_CWD: process.cwd(),
-    AGENT_RELAY_CODEX_STATE_PATH: statePath,
-  };
-
-  const sidecar = Bun.spawn(["bun", "run", join(activePackageRoot(), "live-sidecar.ts")], {
-    env: sidecarEnv,
-    stdout: Bun.file(join(sessionDir, "sidecar.log")),
-    stderr: Bun.file(join(sessionDir, "sidecar.log")),
-  });
-  sidecar.unref();
-
-  writeFileSync(join(sessionDir, "sidecar.pid"), String(sidecar.pid));
-  appendFileSync(join(runDir, "sidecar-pids.txt"), `${sidecar.pid}\n`);
-
-  return sidecar.pid;
-}
-
-function hasCodexPermissionMode(codexArgs: string[]): boolean {
-  for (const arg of codexArgs) {
-    if (
-      arg === "--yolo" ||
-      arg === "--dangerously-bypass-approvals-and-sandbox" ||
-      arg === "--full-auto" ||
-      arg === "--ask-for-approval" ||
-      arg === "-a" ||
-      arg.startsWith("--ask-for-approval=") ||
-      arg === "--sandbox" ||
-      arg === "-s" ||
-      arg.startsWith("--sandbox=")
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function resolveSessionPermissions(codexArgs: string[]): SessionPermissions {
-  let approvalPolicy: string | undefined;
-  let sandbox: string | undefined;
-
-  for (let index = 0; index < codexArgs.length; index += 1) {
-    const arg = codexArgs[index]!;
-    if (arg === "--yolo" || arg === "--dangerously-bypass-approvals-and-sandbox") {
-      approvalPolicy = "never";
-      sandbox = "danger-full-access";
-      continue;
-    }
-    if (arg === "--full-auto") {
-      approvalPolicy = "on-request";
-      sandbox = "workspace-write";
-      continue;
-    }
-    if (arg === "--ask-for-approval" || arg === "-a") {
-      const next = codexArgs[index + 1];
-      if (next && !next.startsWith("-")) {
-        approvalPolicy = next;
-        index += 1;
-      }
-      continue;
-    }
-    if (arg.startsWith("--ask-for-approval=")) {
-      approvalPolicy = arg.slice("--ask-for-approval=".length);
-      continue;
-    }
-    if (arg === "--sandbox" || arg === "-s") {
-      const next = codexArgs[index + 1];
-      if (next && !next.startsWith("-")) {
-        sandbox = next;
-        index += 1;
-      }
-      continue;
-    }
-    if (arg.startsWith("--sandbox=")) {
-      sandbox = arg.slice("--sandbox=".length);
-      continue;
-    }
-  }
-
-  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`);
-}
-
-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");
-    if (existsSync(pidsPath)) {
-      for (const line of readFileSync(pidsPath, "utf8").split("\n")) {
-        const pid = Number(line.trim());
-        if (!Number.isFinite(pid) || pid <= 0) continue;
-        try {
-          process.kill(pid, "SIGTERM");
-        } catch {
-          // Sidecar already exited.
-        }
-      }
-    }
-  }
-
-  if (appServer && appServer.exitCode === null) {
-    try {
-      appServer.kill("SIGTERM");
-    } catch {
-      // App server already exited.
-    }
-  }
-}
-
-function stopRuntimeSidecars(): void {
-  if (!existsSync(runtimeRoot)) return;
-  for (const entry of readdirSync(runtimeRoot, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const pidsPath = join(runtimeRoot, entry.name, "sidecar-pids.txt");
-    if (!existsSync(pidsPath)) continue;
-    for (const line of readFileSync(pidsPath, "utf8").split("\n")) {
-      const pid = Number(line.trim());
-      if (!Number.isFinite(pid) || pid <= 0) continue;
-      try {
-        process.kill(pid, "SIGTERM");
-      } catch {
-        // Sidecar already exited.
-      }
-    }
-  }
-}
-
-function installCodexSupport(quiet = false): void {
-  if (!commandExists("bun")) throw new Error("Bun is required: https://bun.sh");
-  findCodexBinary();
-  syncInstalledPackage();
-  installHook();
-  installMarketplace(quiet);
-}
-
-function writeLauncherShim(name: string): void {
-  const cliPath = join(installedPackageRoot, "bin", "agent-relay-codex.ts");
-
-  if (process.platform === "win32") {
-    writeFileSync(join(aliasBinDir, `${name}.cmd`), `@echo off\r\nbun "${cliPath}" %*\r\n`);
-    writeFileSync(join(aliasBinDir, `${name}.ps1`), `& bun "${cliPath}" @args\r\nexit $LASTEXITCODE\r\n`);
-    return;
-  }
-
-  const shimPath = join(aliasBinDir, name);
-  writeFileSync(shimPath, `#!/usr/bin/env sh\nexec bun ${shellQuote(cliPath)} "$@"\n`);
-  chmodSync(shimPath, 0o755);
+export function removeAgentRelaySessionStartToml(input: string): string {
+  const blocks = input.split(/\n(?=\[\[hooks\.)/g);
+  return blocks
+    .filter((block) => !/hooks\/session-start\.ts/.test(block) && !/agent-relay.*SessionStart/i.test(block))
+    .join("\n")
+    .trimEnd() + "\n";
 }
 
-function removeLauncherShim(name: string): void {
-  if (process.platform === "win32") {
-    rmSync(join(aliasBinDir, `${name}.cmd`), { force: true });
-    rmSync(join(aliasBinDir, `${name}.ps1`), { force: true });
+async function main(args = process.argv.slice(2)): Promise<void> {
+  const command = args[0] ?? "help";
+  if (command === "help" || command === "--help" || command === "-h") {
+    console.log(HELP);
     return;
   }
-  rmSync(join(aliasBinDir, name), { force: true });
-}
-
-function installLauncherShims(includeCodexAlias: boolean): void {
-  mkdirSync(aliasBinDir, { recursive: true });
-  writeLauncherShim("codex-relay");
-  if (includeCodexAlias) writeLauncherShim("codex");
-}
-
-function isAliasBinOnPath(): boolean {
-  return pathEntries().some((entry) => samePath(entry, aliasBinDir));
-}
-
-function installPathEntry(): boolean {
-  if (isAliasBinOnPath()) return true;
-
-  if (process.platform === "win32") {
-    const script = [
-      "$dir = [Environment]::GetEnvironmentVariable('AGENT_RELAY_CODEX_BIN', 'User')",
-      `$new = ${JSON.stringify(aliasBinDir)}`,
-      "$path = [Environment]::GetEnvironmentVariable('Path', 'User')",
-      "if (-not $path) { $path = '' }",
-      "$parts = $path -split ';' | Where-Object { $_ }",
-      "if ($parts -notcontains $new) {",
-      "  [Environment]::SetEnvironmentVariable('Path', ($new + ';' + $path).TrimEnd(';'), 'User')",
-      "}",
-      "[Environment]::SetEnvironmentVariable('AGENT_RELAY_CODEX_BIN', $new, 'User')",
-    ].join("; ");
-    const result = Bun.spawnSync(["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    return result.exitCode === 0;
-  }
-
-  const shell = process.env.SHELL || "";
-  const exportLine = `export PATH=${shellQuote(aliasBinDir)}:$PATH`;
-  let profilePath = join(home, ".profile");
-  let snippet = `\n${pathMarker}\n${exportLine}\n`;
-
-  if (shell.includes("zsh")) profilePath = join(home, ".zshrc");
-  if (shell.includes("bash")) profilePath = join(home, ".bashrc");
-  if (shell.includes("fish")) {
-    profilePath = join(home, ".config", "fish", "config.fish");
-    snippet = `\n${pathMarker}\nfish_add_path ${shellQuote(aliasBinDir)}\n`;
-  }
-
-  mkdirSync(dirname(profilePath), { recursive: true });
-  const current = existsSync(profilePath) ? readFileSync(profilePath, "utf8") : "";
-  if (!current.includes(pathMarker) && !current.includes(aliasBinDir)) {
-    writeFileSync(profilePath, `${current.replace(/\s*$/, "")}${snippet}`);
-  }
-  return true;
-}
-
-function managedProfilePaths(): string[] {
-  return [
-    join(home, ".profile"),
-    join(home, ".bashrc"),
-    join(home, ".zshrc"),
-    join(home, ".config", "fish", "config.fish"),
-  ];
-}
-
-function removeManagedPathSnippet(input: string): string {
-  const hadTrailingNewline = /\r?\n$/.test(input);
-  const lines = input.split(/\r?\n/);
-  const output: string[] = [];
-
-  for (let index = 0; index < lines.length; index += 1) {
-    const line = lines[index]!;
-    if (line === pathMarker) {
-      const next = lines[index + 1] || "";
-      if (next.includes(aliasBinDir)) index += 1;
-      continue;
-    }
-    output.push(line);
-  }
-
-  const cleaned = output.join("\n").replace(/\n{3,}/g, "\n\n").replace(/[ \t]+\n/g, "\n");
-  return hadTrailingNewline && cleaned ? `${cleaned.replace(/\n*$/, "")}\n` : cleaned.replace(/\n*$/, "");
-}
-
-function removeUnixPathEntries(): number {
-  let changed = 0;
-  for (const profilePath of managedProfilePaths()) {
-    if (!existsSync(profilePath)) continue;
-    const current = readFileSync(profilePath, "utf8");
-    if (!current.includes(pathMarker)) continue;
-    const cleaned = removeManagedPathSnippet(current);
-    if (cleaned !== current) {
-      writeFileSync(profilePath, cleaned);
-      changed += 1;
-    }
-  }
-  return changed;
-}
-
-function removeWindowsPathEntry(): boolean {
-  const script = [
-    `$target = ${JSON.stringify(aliasBinDir)}`,
-    "$path = [Environment]::GetEnvironmentVariable('Path', 'User')",
-    "if ($path) {",
-    "  $parts = $path -split ';' | Where-Object { $_ -and ($_ -ne $target) }",
-    "  [Environment]::SetEnvironmentVariable('Path', ($parts -join ';'), 'User')",
-    "}",
-    "$bin = [Environment]::GetEnvironmentVariable('AGENT_RELAY_CODEX_BIN', 'User')",
-    "if ($bin -eq $target) { [Environment]::SetEnvironmentVariable('AGENT_RELAY_CODEX_BIN', $null, 'User') }",
-  ].join("; ");
-  const result = Bun.spawnSync(["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script], {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  return result.exitCode === 0;
-}
-
-function removeManagedPathEntries(): string {
-  if (process.platform === "win32") {
-    return removeWindowsPathEntry() ? "Removed managed Windows user PATH entries." : "Could not update Windows user PATH entries.";
-  }
-  const changed = removeUnixPathEntries();
-  return changed > 0 ? `Removed managed PATH snippets from ${changed} shell profile(s).` : "No managed shell profile PATH snippets found.";
-}
-
-function removeEmptyDirectory(path: string): boolean {
-  if (!existsSync(path)) return false;
-  try {
-    if (readdirSync(path).length > 0) return false;
-    rmSync(path, { recursive: false, force: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function removeEmptyInstallParents(): void {
-  removeEmptyDirectory(installRoot);
-  removeEmptyDirectory(dirname(installRoot));
-}
-
-function installCodexAlias(): void {
-  installLauncherShims(true);
-  const updated = installPathEntry();
-  console.log("Installed codex alias shim.");
-  if (!updated || !isAliasBinOnPath()) {
-    console.log(`Restart your shell, or add this directory to PATH: ${aliasBinDir}`);
-  }
-}
-
-function removeCodexAlias(): void {
-  removeLauncherShim("codex");
-  console.log("Removed Agent Relay codex alias shims.");
-  console.log("The `codex-relay` launcher remains installed.");
-}
-
-async function askYesNo(question: string): Promise<boolean> {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    rl.close();
-  }
-}
-
-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.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 || "";
-  const cwd = process.cwd();
-  const rig = process.env.AGENT_RELAY_CODEX_RIG || "codex-live";
-  const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
-  const profile = loadAgentRelayProfile(process.env, { provider: "codex", rig, project });
-  const requestedApprovalMode = profile.approval ?? parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
-  const hasApprovalEnv = process.env.AGENT_RELAY_APPROVAL !== undefined || profile.approval !== undefined;
-  const codexArgs: string[] = [];
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === "--") {
-      codexArgs.push(...args.slice(index + 1));
-      break;
-    }
-    if (arg === "--relay-url") {
-      relayUrl = args[++index] || relayUrl;
-      continue;
-    }
-    if (arg === "--listen") {
-      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)) {
-        throw new Error("--thread-mode must be one of: auto, resume, start");
-      }
-      continue;
-    }
-    codexArgs.push(arg);
-  }
-  if (!["auto", "resume", "start"].includes(threadMode)) threadMode = "start";
-
-  if (!listenUrl) listenUrl = await pickLoopbackUrl();
-  if (!hasCodexPermissionMode(codexArgs)) {
-    codexArgs.unshift(...codexArgsForApprovalMode(requestedApprovalMode));
-  }
-  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.`,
-    );
-  }
-
-  mkdirSync(runtimeRoot, { recursive: true });
-  const runId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  const runDir = join(runtimeRoot, runId);
-  mkdirSync(runDir, { recursive: true });
-
-  const env = {
-    ...process.env,
-    AGENT_RELAY_URL: relayUrl,
-    AGENT_RELAY_CODEX_PACKAGE_ROOT: activePackageRoot(),
-    AGENT_RELAY_CODEX_RUN_ID: runId,
-    AGENT_RELAY_CODEX_RUNTIME_DIR: runDir,
-    AGENT_RELAY_CONTEXT_PATH: join(runDir, "agent-context.json"),
-    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_PARENT_PID: String(process.pid),
-  };
-
-  const appLog = Bun.file(join(runDir, "app-server.log"));
-  const codexBinary = findCodexBinary();
-  const appServer = Bun.spawn([codexBinary, "app-server", "--listen", listenUrl], {
-    env,
-    stdout: appLog,
-    stderr: appLog,
-  });
-
-  const shutdown = () => cleanupRun(runDir, appServer);
-  process.once("SIGINT", () => {
-    shutdown();
-    process.exit(130);
-  });
-  process.once("SIGTERM", () => {
-    shutdown();
-    process.exit(143);
-  });
-  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,
+  if (command === "upgrade") {
+    const proc = Bun.spawn(["agent-relay", "upgrade", "--providers", "codex", ...args.slice(1)], {
       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);
+    process.exit(await proc.exited);
   }
-
-  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: managedSidecarEnv,
-    sessionDir: sidecarDir,
-    statePath,
-    threadMode,
-    threadId: threadId || undefined,
-  });
-  const managedAgent = await waitForManagedAgent(statePath, sidecarPid);
-  const canonicalThreadId = managedAgent.threadId;
-
-  console.log(`Thread: ${canonicalThreadId}`);
-  console.log(`Agent: ${managedAgent.agentId}`);
-  appendLauncherLog(runDir, `MANAGED_THREAD thread=${canonicalThreadId} agent=${managedAgent.agentId} sidecarPid=${sidecarPid} headless=${headless}`);
-
-  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);
-}
-
-async function doctor(): Promise<void> {
-  const checks: Array<[string, boolean, string]> = [];
-  checks.push(["bun", commandExists("bun"), "Bun is required to run the sidecar"]);
-  checks.push(["codex", findOnPath("codex", [aliasBinDir]) !== null, "Codex CLI is required"]);
-  const configPath = join(home, ".codex", "config.toml");
-  const config = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-  checks.push(["hook", isAgentRelaySessionStartCommand(config), "~/.codex/config.toml has Agent Relay SessionStart hook"]);
-  checks.push(["marketplace", existsSync(marketplaceFile), "Agent Relay marketplace is installed"]);
-  checks.push(["launcher", existsSync(join(aliasBinDir, process.platform === "win32" ? "codex-relay.cmd" : "codex-relay")), "codex-relay launcher shim"]);
-
-  const relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-  const stats = await getRelayStats(relayUrl);
-  checks.push(["relay", stats !== null, stats?.version ? `${relayUrl}/api/stats responds; version ${stats.version}` : `${relayUrl}/api/stats responds`]);
-
-  for (const [name, ok, detail] of checks) {
-    console.log(`${ok ? "ok " : "err"} ${name}: ${detail}`);
-  }
-}
-
-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");
-  installCodexSupport(false);
-  installLauncherShims(false);
-  installPathEntry();
-  console.log("Installed Agent Relay for Codex.");
-  const relayStatus = await checkRelayServer();
-  if (relayStatus === "unknown") console.log("If this server is old, restart it with: bunx agent-relay-server@latest");
-  if (isAliasBinOnPath()) {
-    console.log("Start Codex sessions with: codex-relay");
-  } else {
-    console.log("Restart your shell, then start Codex sessions with: codex-relay");
-    console.log("Without restarting your shell, use: bunx -p agent-relay-codex@latest codex-relay");
-  }
-
-  if (installAlias || (!skipAlias && await askYesNo("Make plain `codex` start with Agent Relay by installing a PATH shim?"))) {
-    installCodexAlias();
-  } else {
-    console.log("Skipped plain `codex` alias. You can always use `codex-relay`.");
-  }
-}
-
-function uninstall(args: string[] = []): void {
-  const purge = args.includes("--purge");
-  const unknown = args.filter((arg) => arg !== "--purge");
-  if (unknown.length > 0) throw new Error(`Unknown uninstall option: ${unknown.join(" ")}`);
-
-  stopRuntimeSidecars();
-  removeHook();
-  removeLauncherShim("codex");
-  removeLauncherShim("codex-relay");
-  rmSync(marketplaceRoot, { recursive: true, force: true });
-  rmSync(installedPackageRoot, { recursive: true, force: true });
-  console.log("Uninstalled Agent Relay Codex hook, plugin marketplace files, and launcher shims.");
-
-  if (!purge) {
-    console.log(`PATH entries and runtime logs are left untouched. Run agent-relay-codex uninstall --purge for full managed cleanup.`);
+  if (command === "install") {
+    console.log("Codex relay lifecycle now ships in agent-relay-runner. Use: agent-relay provider wrap codex");
     return;
   }
-
-  rmSync(runtimeRoot, { recursive: true, force: true });
-  rmSync(aliasBinDir, { recursive: true, force: true });
-  console.log(removeManagedPathEntries());
-  removeEmptyInstallParents();
-  console.log("Purged Agent Relay Codex runtime files, launcher directory, and empty install directories.");
-}
-
-async function main(): Promise<void> {
-  const [command, ...args] = process.argv.slice(2);
-  const codexArgs = command ? [command, ...args] : [];
-  if (command === "help" || command === "--help" || command === "-h") usage(0);
-  if (command === "install") return install(args);
-  if (command === "uninstall") return uninstall(args);
-  if (command === "alias" && args[0] === "install") {
-    installCodexSupport(false);
-    return installCodexAlias();
+  if (command === "uninstall") {
+    console.log("Use: agent-relay provider unwrap codex");
+    return;
   }
-  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);
-  if (shouldBypassRelay(codexArgs)) return runCodexPassthrough(codexArgs);
-  return start(codexArgs);
+  throw new Error("codex-relay is provided by agent-relay-runner; run `codex-relay --help`.");
 }
 
 if (import.meta.main) {
-  main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  });
+  await main();
 }