agent-relay-codex 0.4.14

package/bin/agent-relay-codex.ts

@@ -0,0 +1,988 @@
+#!/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 { approvalModeFromPermissions, codexArgsForApprovalMode, parseApprovalMode } from "../approval";
+
+type HooksJson = {
+  hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<Record<string, unknown>> }>>;
+};
+
+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();
+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
+
+Usage:
+  agent-relay-codex [--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...>]
+
+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 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 isAgentRelaySessionStartCommand(command: string): boolean {
+  return /agent-relay.*hooks\/session-start\.ts/.test(command);
+}
+
+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 (block?.header?.startsWith("[[hooks.SessionStart")) {
+      const group: typeof blocks = [];
+      while (index < blocks.length && blocks[index]?.header?.startsWith("[[hooks.SessionStart")) {
+        group.push(blocks[index]!);
+        index += 1;
+      }
+
+      const groupText = group.map((block) => block.text).join("\n");
+      if (!isAgentRelaySessionStartCommand(groupText)) output += `${groupText}\n`;
+      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 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}`);
+}
+
+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`,
+  };
+}
+
+function spawnFallbackSidecar(runDir: string, env: Record<string, string | undefined>): number {
+  const autoDir = join(runDir, "auto");
+  mkdirSync(autoDir, { recursive: true });
+
+  const sidecarEnv: Record<string, string | undefined> = {
+    ...env,
+    CODEX_THREAD_MODE: env.AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE || env.CODEX_THREAD_MODE || "start",
+    AGENT_RELAY_CODEX_CWD: process.cwd(),
+    AGENT_RELAY_CODEX_STATE_PATH: join(autoDir, "live-state.json"),
+  };
+  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")),
+  });
+  sidecar.unref();
+
+  writeFileSync(join(autoDir, "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 (
+      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 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);
+}
+
+function removeLauncherShim(name: string): void {
+  if (process.platform === "win32") {
+    rmSync(join(aliasBinDir, `${name}.cmd`), { force: true });
+    rmSync(join(aliasBinDir, `${name}.ps1`), { force: true });
+    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.CODEX_APP_SERVER_URL || "";
+  let threadMode = process.env.CODEX_THREAD_MODE || "start";
+  const requestedApprovalMode = parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
+  const hasApprovalEnv = process.env.AGENT_RELAY_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 === "--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 (!listenUrl) listenUrl = await pickLoopbackUrl();
+  if (!hasCodexPermissionMode(codexArgs)) {
+    codexArgs.unshift(...codexArgsForApprovalMode(requestedApprovalMode));
+  }
+  const permissions = resolveSessionPermissions(codexArgs);
+  const effectiveApprovalMode = approvalModeFromPermissions(permissions);
+  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,
+    CODEX_APP_SERVER_URL: listenUrl,
+    CODEX_THREAD_MODE: threadMode,
+    AGENT_RELAY_CODEX_APPROVAL_POLICY: permissions.approvalPolicy,
+    AGENT_RELAY_CODEX_SANDBOX: permissions.sandbox,
+    AGENT_RELAY_APPROVAL: effectiveApprovalMode,
+  };
+
+  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}`);
+
+  const codex = Bun.spawn([codexBinary, "--remote", listenUrl, ...codexArgs], {
+    env,
+    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);
+}
+
+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}`);
+  }
+}
+
+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.`);
+    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);
+  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 === "alias" && args[0] === "remove") return removeCodexAlias();
+  if (command === "doctor") return doctor();
+  if (command === "start") return start(args);
+  return start(command ? [command, ...args] : []);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});