agent-relay-server 0.1.0 → 0.3.0

package/bin/agent-relay-codex.ts

@@ -0,0 +1,547 @@
+#!/usr/bin/env bun
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, 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";
+
+type HooksJson = {
+  hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<Record<string, unknown>> }>>;
+};
+
+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, "codex", "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 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] [-- <codex args...>]
+  codex-relay [--relay-url URL] [--listen ws://127.0.0.1:PORT] [-- <codex args...>]
+
+With no subcommand, this launches Codex with live Agent Relay support.`);
+  process.exit(exitCode);
+}
+
+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 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 response = await fetch(new URL("/api/stats", relayUrl), { signal: controller.signal });
+    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`);
+    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");
+    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;
+
+  rmSync(join(installedPackageRoot, "codex"), { recursive: true, force: true });
+  rmSync(join(installedPackageRoot, "bin"), { recursive: true, force: true });
+  cpSync(join(packageRoot, "codex"), join(installedPackageRoot, "codex"), { recursive: true });
+  cpSync(join(packageRoot, "bin"), join(installedPackageRoot, "bin"), { 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 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, "codex", "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 hooksPath = join(home, ".codex", "hooks.json");
+  const hooksJson = readJsonFile<HooksJson>(hooksPath, { hooks: {} });
+  hooksJson.hooks ??= {};
+  hooksJson.hooks.SessionStart ??= [];
+
+  const command = `bun ${shellQuote(installedHookScript)}`;
+  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 !/agent-relay.*codex\/hooks\/session-start\.ts/.test(hook.command);
+      }),
+    }))
+    .filter((group) => (group.hooks ?? []).length > 0);
+
+  hooksJson.hooks.SessionStart.push({
+    matcher: "startup|resume",
+    hooks: [
+      {
+        type: "command",
+        command,
+        statusMessage: "Starting Agent Relay",
+        timeout: 10,
+      },
+    ],
+  });
+
+  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}`);
+}
+
+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 installCodexSupport(quiet = false): void {
+  if (!commandExists("bun")) throw new Error("Bun is required: https://bun.sh");
+  findCodexBinary();
+  installMarketplace(quiet);
+  installHook();
+}
+
+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");
+  else removeLauncherShim("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 marker = "# Agent Relay Codex alias";
+  const exportLine = `export PATH=${shellQuote(aliasBinDir)}:$PATH`;
+  let profilePath = join(home, ".profile");
+  let snippet = `\n${marker}\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${marker}\nfish_add_path ${shellQuote(aliasBinDir)}\n`;
+  }
+
+  mkdirSync(dirname(profilePath), { recursive: true });
+  const current = existsSync(profilePath) ? readFileSync(profilePath, "utf8") : "";
+  if (!current.includes(marker) && !current.includes(aliasBinDir)) {
+    writeFileSync(profilePath, `${current.replace(/\s*$/, "")}${snippet}`);
+  }
+  return true;
+}
+
+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 || "";
+  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;
+    }
+    codexArgs.push(arg);
+  }
+
+  if (!listenUrl) listenUrl = await pickLoopbackUrl();
+
+  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,
+  };
+
+  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.error(`Agent Relay Codex session: ${listenUrl}`);
+  console.error(`Runtime: ${runDir}`);
+
+  const codex = Bun.spawn([codexBinary, "--remote", listenUrl, ...codexArgs], {
+    env,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  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"]);
+  checks.push(["hook", existsSync(join(home, ".codex", "hooks.json")), "~/.codex/hooks.json exists"]);
+  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");
+  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-server 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`.");
+  }
+}
+
+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 === "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);
+});

package/codex/README.md

@@ -0,0 +1,80 @@
+# Codex Live Sidecar
+
+First real Codex integration for Agent Relay.
+
+## Purpose
+
+This sidecar connects to a Codex app-server session and to Agent Relay, then delivers incoming relay messages into the active Codex thread using:
+
+- `turn/start`
+- `turn/steer`
+- `turn/interrupt`
+
+## Current MVP behavior
+
+- attaches to a loaded thread for the current `cwd` when one exists
+- otherwise resumes the newest thread for the current `cwd`
+- otherwise creates a new thread
+- registers a relay agent with `client: codex-live`
+- polls relay inbox and delivers messages into the live thread
+- coalesces ordinary relay bursts into one delivery turn
+- reconnects to the app-server with exponential backoff after disconnects
+- writes runtime state to `codex/runtime/live-state.json`
+
+## Delivery behavior
+
+- idle thread: `turn/start`
+- active thread: `turn/steer`
+- urgent or `meta.delivery = "interrupt"`: `turn/interrupt` then `turn/start`
+
+## Run
+
+```bash
+codex/start-live.sh
+```
+
+## Installable workflow
+
+The packaged Codex path is:
+
+```bash
+bunx agent-relay-server
+curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash
+# after restarting your shell
+codex-relay
+```
+
+The installer always adds a `codex-relay` launcher and asks whether plain
+`codex` should also route through Agent Relay. `codex-relay` idempotently
+installs or refreshes the Codex hook/plugin, then launches `codex app-server`,
+starts Codex with
+`--remote`, lets the SessionStart hook attach a sidecar to the actual thread,
+and kills sidecars plus the app-server when Codex exits.
+
+For local development from this repo:
+
+```bash
+bun run bin/agent-relay-codex.ts
+```
+
+Useful environment variables:
+
+- `AGENT_RELAY_URL`
+- `AGENT_RELAY_CAPS`
+- `CODEX_APP_SERVER_URL`
+- `CODEX_THREAD_ID`
+- `CODEX_THREAD_MODE=auto|resume|start`
+- `CODEX_LIVE_STATE_PATH`
+- `CODEX_LIVE_COALESCE_WINDOW_MS`
+- `CODEX_LIVE_RECONNECT_INITIAL_MS`
+- `CODEX_LIVE_RECONNECT_MAX_MS`
+- `CODEX_LIVE_RIG`
+- `CODEX_MODEL`
+
+## Notes
+
+This is still an early sidecar cut. It now handles reconnects and basic coalescing, but it still lacks richer policies such as batching by sender, message prioritization queues, and more nuanced retry/backoff behavior.
+
+- `CODEX_THREAD_MODE=auto` will attach to an already loaded thread for the same `cwd`. That is what you want for real live control, but it also means the sidecar can attach to your current interactive Codex session if one is already open.
+- For isolated testing, set `CODEX_THREAD_MODE=start` so the sidecar always creates its own thread.
+- A brand-new thread is not materialized for `includeTurns` reads until the first turn starts. That is an app-server behavior, not a relay bug.