agent-relay-server 0.3.8 → 0.3.9

package/README.md

@@ -77,16 +77,24 @@ codex-relay
 incoming messages as live turns, and cleans up sidecar processes when Codex
 exits.
 
-### Codex approval prompts
+### Codex approval mode
 
 Replying to relay messages is usually done with a shell command (`curl` to
 `/api/messages`), so Codex may prompt for approval in stricter modes.
 
-`codex-relay` now forwards your Codex runtime mode to the sidecar, including
-`--ask-for-approval`, `--sandbox`, `--full-auto`, and `--yolo`.
+By default, `codex-relay` starts Codex with
+`--dangerously-bypass-approvals-and-sandbox` so relay turns do not get stuck on
+approval prompts. If you pass an explicit Codex runtime mode, `codex-relay`
+leaves it alone and forwards it to the sidecar, including `--ask-for-approval`,
+`--sandbox`, `--full-auto`, and `--yolo`.
 
 Useful setups:
 
+```bash
+# default: no approval prompts, no Codex sandbox
+codex-relay
+```
+
 ```bash
 # no approval prompts, still sandboxed to workspace boundaries
 codex-relay -- --ask-for-approval never --sandbox workspace-write

package/bin/agent-relay-codex.ts

@@ -383,6 +383,25 @@ type SessionPermissions = {
   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;
@@ -488,7 +507,6 @@ function installLauncherShims(includeCodexAlias: boolean): void {
   mkdirSync(aliasBinDir, { recursive: true });
   writeLauncherShim("codex-relay");
   if (includeCodexAlias) writeLauncherShim("codex");
-  else removeLauncherShim("codex");
 }
 
 function isAliasBinOnPath(): boolean {
@@ -589,6 +607,7 @@ async function start(args: string[]): Promise<void> {
   }
 
   if (!listenUrl) listenUrl = await pickLoopbackUrl();
+  if (!hasCodexPermissionMode(codexArgs)) codexArgs.unshift("--dangerously-bypass-approvals-and-sandbox");
   const permissions = resolveSessionPermissions(codexArgs);
 
   mkdirSync(runtimeRoot, { recursive: true });
@@ -627,8 +646,8 @@ async function start(args: string[]): Promise<void> {
   process.once("exit", shutdown);
 
   await waitForPort(listenUrl, appServer);
-  console.error(`Agent Relay Codex session: ${listenUrl}`);
-  console.error(`Runtime: ${runDir}`);
+  console.log(`Agent Relay Codex session: ${listenUrl}`);
+  console.log(`Runtime: ${runDir}`);
 
   const codex = Bun.spawn([codexBinary, "--remote", listenUrl, ...codexArgs], {
     env,

package/codex/README.md

@@ -0,0 +1,116 @@
+# Codex Live Sidecar
+
+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 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`
+- marks the relay agent `ready=true` once app-server + thread are attached
+- 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@latest
+curl -fsSL https://unpkg.com/agent-relay-server@latest/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.
+
+## Approval mode
+
+Relay replies are usually sent with a shell command (`curl` to
+`/api/messages`), so Codex can prompt for approval in stricter modes.
+
+By default, `codex-relay` starts Codex with
+`--dangerously-bypass-approvals-and-sandbox` so relay turns do not get stuck on
+approval prompts. If you pass an explicit Codex runtime mode, `codex-relay`
+leaves it alone and forwards it to the sidecar, including `--ask-for-approval`,
+`--sandbox`, `--full-auto`, and `--yolo`.
+
+Default:
+
+```bash
+codex-relay
+```
+
+Example: no prompt loop, still workspace sandboxing:
+
+```bash
+codex-relay -- --ask-for-approval never --sandbox workspace-write
+```
+
+If you prefer prompts for everything else but want relay sends auto-approved,
+add a rule in `~/.codex/rules/default.rules` (adjust URL when using a remote relay):
+
+```python
+prefix_rule(
+    pattern = ["curl", "-sS", "-X", "POST", "http://127.0.0.1:4850/api/messages"],
+    decision = "allow",
+    justification = "Allow local Agent Relay message posts",
+)
+```
+
+For local development from this repo:
+
+```bash
+bun run bin/agent-relay-codex.ts
+bun run codex:smoke:fallback
+```
+
+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
+
+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.
+- 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/smoke/fallback.ts

@@ -48,8 +48,8 @@ exit 64
   chmodSync(path, 0o755);
 }
 
-function parseRuntimeDir(stderr: string): string | null {
-  const match = stderr.match(/^Runtime:\s+(.+)$/m);
+function parseRuntimeDir(output: string): string | null {
+  const match = output.match(/^Runtime:\s+(.+)$/m);
   return match?.[1]?.trim() || null;
 }
 
@@ -85,9 +85,9 @@ async function main(): Promise<void> {
     throw new Error(`launcher exited ${exitCode}\nstdout:\n${stdout}\nstderr:\n${stderr}`);
   }
 
-  const runtimeDir = parseRuntimeDir(stderr);
+  const runtimeDir = parseRuntimeDir(`${stdout}\n${stderr}`);
   if (!runtimeDir) {
-    throw new Error(`missing runtime directory in launcher output\nstderr:\n${stderr}`);
+    throw new Error(`missing runtime directory in launcher output\nstdout:\n${stdout}\nstderr:\n${stderr}`);
   }
 
   if (!stderr.includes("SessionStart hook did not start sidecar; started fallback sidecar pid")) {
@@ -122,4 +122,3 @@ main().catch((error) => {
   log(error instanceof Error ? error.stack || error.message : String(error));
   process.exitCode = 1;
 });
-

package/package.json

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