agent-relay-server 0.4.10 → 0.4.12

package/README.md

@@ -224,6 +224,9 @@ time, it starts a new thread by default to avoid surprising cwd-based attachment
 to an unrelated loaded session. Use `codex-relay --thread-mode auto` or
 `AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE=auto` when you deliberately want the
 fallback sidecar to attach to the newest loaded thread for the current cwd.
+The lower-level sidecar also defaults to `CODEX_THREAD_MODE=start`; `auto` is an
+explicit opt-in because it may deliver relay messages into an already-open Codex
+session for the same directory.
 
 ### Codex approval mode
 
@@ -311,7 +314,18 @@ agent-relay-codex uninstall
 ```
 
 This removes the Codex SessionStart hook, local plugin marketplace files, and
-launcher shims. It leaves shell profile PATH edits visible for manual cleanup.
+launcher shims. It leaves shell profile PATH edits and runtime logs in place.
+
+Full managed cleanup:
+
+```bash
+agent-relay-codex uninstall --purge
+```
+
+Purge also removes Agent Relay-managed shell profile PATH snippets, Codex runtime
+logs, the launcher directory, and empty install directories. It only removes
+profile snippets written by the installer marker; manual PATH edits are left
+alone.
 
 ## What the Agent Sees
 

package/bin/agent-relay-codex.ts

@@ -55,7 +55,7 @@ function usage(exitCode = 0): never {
 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
+  agent-relay-codex uninstall [--purge]
   agent-relay-codex alias install
   agent-relay-codex alias remove
   agent-relay-codex doctor
@@ -66,6 +66,8 @@ 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;
 }
@@ -633,26 +635,110 @@ function installPathEntry(): boolean {
   }
 
   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`;
+  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${marker}\nfish_add_path ${shellQuote(aliasBinDir)}\n`;
+    snippet = `\n${pathMarker}\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)) {
+  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();
@@ -846,7 +932,11 @@ async function install(args: string[]): Promise<void> {
   }
 }
 
-function uninstall(): void {
+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");
@@ -854,14 +944,24 @@ function uninstall(): void {
   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.");
-  console.log(`PATH entries are left untouched; remove ${aliasBinDir} from your shell profile if you no longer want it there.`);
+
+  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();
+  if (command === "uninstall") return uninstall(args);
   if (command === "alias" && args[0] === "install") {
     installCodexSupport(false);
     return installCodexAlias();

package/codex/README.md

@@ -12,9 +12,9 @@ This sidecar connects to a Codex app-server session and to Agent Relay, then del
 
 ## Current 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
+- starts a new thread by default
+- resumes the actual launched thread when the SessionStart hook provides a thread id
+- only attaches to loaded/latest same-cwd threads when `CODEX_THREAD_MODE=auto`
 - registers a relay agent with `client: codex-live`
 - marks the relay agent `ready=true` once app-server + thread are attached
 - polls relay inbox and delivers messages into the live thread
@@ -52,6 +52,22 @@ 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.
 
+Uninstall the Codex hook, local plugin marketplace files, and launcher shims:
+
+```bash
+agent-relay-codex uninstall
+```
+
+Remove all Agent Relay-managed Codex install state, including installer-written
+PATH snippets and runtime logs:
+
+```bash
+agent-relay-codex uninstall --purge
+```
+
+Purge only removes shell profile snippets written with the Agent Relay installer
+marker. Manual PATH edits are left alone.
+
 ## Approval mode
 
 Relay replies are usually sent with a shell command (`curl` to
@@ -131,6 +147,6 @@ startup in time.
 
 Current sidecar behavior is stable for live delivery. Remaining gaps are advanced 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.
+- `CODEX_THREAD_MODE=start` is the safe default: the sidecar creates its own thread unless the hook supplied an explicit thread id.
+- `CODEX_THREAD_MODE=auto` will attach to an already loaded thread for the same `cwd`. That can be useful for advanced live control, but it also means relay messages can enter your current interactive Codex session if one is already open.
 - 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.

package/codex/live-sidecar.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "bun:test";
+import { loadConfig, parseThreadMode } from "./live-sidecar";
+
+describe("codex live sidecar config", () => {
+  it("defaults to starting an isolated thread", () => {
+    const config = loadConfig({
+      CODEX_LIVE_CWD: "/tmp/agent-relay-test",
+    });
+
+    expect(config.threadMode).toBe("start");
+  });
+
+  it("only accepts known thread attachment modes", () => {
+    expect(parseThreadMode("auto")).toBe("auto");
+    expect(parseThreadMode("resume")).toBe("resume");
+    expect(parseThreadMode("start")).toBe("start");
+    expect(parseThreadMode("latest")).toBe("start");
+    expect(parseThreadMode(undefined)).toBe("start");
+  });
+});

package/codex/live-sidecar.ts

@@ -572,38 +572,43 @@ function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function envNumber(name: string, fallback: number): number {
-  const raw = process.env[name];
+function envNumber(env: NodeJS.ProcessEnv, name: string, fallback: number): number {
+  const raw = env[name];
   if (!raw) return fallback;
   const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
-function loadConfig(): Config {
-  const cwd = process.env.CODEX_LIVE_CWD || process.cwd();
-  const capabilities = (process.env.AGENT_RELAY_CAPS || "chat")
+export function parseThreadMode(raw: string | undefined): Config["threadMode"] {
+  if (raw === "auto" || raw === "resume" || raw === "start") return raw;
+  return "start";
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
+  const cwd = env.CODEX_LIVE_CWD || process.cwd();
+  const capabilities = (env.AGENT_RELAY_CAPS || "chat")
     .split(",")
     .map((value) => value.trim())
     .filter(Boolean);
 
   return {
-    relayUrl: process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850",
-    appServerUrl: process.env.CODEX_APP_SERVER_URL || "ws://127.0.0.1:4501",
+    relayUrl: env.AGENT_RELAY_URL || "http://127.0.0.1:4850",
+    appServerUrl: env.CODEX_APP_SERVER_URL || "ws://127.0.0.1:4501",
     cwd,
-    rig: process.env.CODEX_LIVE_RIG || "codex-live",
+    rig: env.CODEX_LIVE_RIG || "codex-live",
     capabilities,
-    tags: ["codex", process.env.CODEX_LIVE_RIG || "codex-live", cwd.split("/").filter(Boolean).at(-1) || "unknown"],
-    statePath: process.env.CODEX_LIVE_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
-    pollIntervalMs: envNumber("CODEX_LIVE_POLL_INTERVAL_MS", 2000),
-    heartbeatIntervalMs: envNumber("CODEX_LIVE_HEARTBEAT_INTERVAL_MS", 30000),
-    coalesceWindowMs: envNumber("CODEX_LIVE_COALESCE_WINDOW_MS", 600),
-    reconnectInitialDelayMs: envNumber("CODEX_LIVE_RECONNECT_INITIAL_MS", 1000),
-    reconnectMaxDelayMs: envNumber("CODEX_LIVE_RECONNECT_MAX_MS", 10000),
-    threadMode: (process.env.CODEX_THREAD_MODE as Config["threadMode"]) || "auto",
-    threadId: process.env.CODEX_THREAD_ID || undefined,
-    model: process.env.CODEX_MODEL || undefined,
-    approvalPolicy: process.env.CODEX_LIVE_APPROVAL_POLICY || undefined,
-    sandbox: process.env.CODEX_LIVE_SANDBOX || undefined,
+    tags: ["codex", env.CODEX_LIVE_RIG || "codex-live", cwd.split("/").filter(Boolean).at(-1) || "unknown"],
+    statePath: env.CODEX_LIVE_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
+    pollIntervalMs: envNumber(env, "CODEX_LIVE_POLL_INTERVAL_MS", 2000),
+    heartbeatIntervalMs: envNumber(env, "CODEX_LIVE_HEARTBEAT_INTERVAL_MS", 30000),
+    coalesceWindowMs: envNumber(env, "CODEX_LIVE_COALESCE_WINDOW_MS", 600),
+    reconnectInitialDelayMs: envNumber(env, "CODEX_LIVE_RECONNECT_INITIAL_MS", 1000),
+    reconnectMaxDelayMs: envNumber(env, "CODEX_LIVE_RECONNECT_MAX_MS", 10000),
+    threadMode: parseThreadMode(env.CODEX_THREAD_MODE),
+    threadId: env.CODEX_THREAD_ID || undefined,
+    model: env.CODEX_MODEL || undefined,
+    approvalPolicy: env.CODEX_LIVE_APPROVAL_POLICY || undefined,
+    sandbox: env.CODEX_LIVE_SANDBOX || undefined,
   };
 }
 
@@ -613,7 +618,9 @@ async function main(): Promise<void> {
   await sidecar.run();
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.stack || error.message : String(error));
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.stack || error.message : String(error));
+    process.exit(1);
+  });
+}

package/codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",