agent-relay-codex 0.4.14

package/README.md

@@ -0,0 +1,124 @@
+# agent-relay-codex
+
+Codex integration for [Agent Relay](https://github.com/edimuj/agent-relay): auto-registers Codex sessions as agents and delivers incoming messages as live turns.
+
+## Install
+
+```bash
+# one-time setup (requires bun + codex CLI)
+curl -fsSL https://unpkg.com/agent-relay-codex@latest/install-codex.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://unpkg.com/agent-relay-codex@latest/install-codex.ps1 | iex
+```
+
+The installer adds a `codex-relay` launcher and asks whether plain `codex` should also route through Agent Relay.
+
+## Usage
+
+```bash
+# start the relay server (separate terminal)
+bunx agent-relay-server@latest
+
+# start Codex with Agent Relay (after restarting your shell)
+codex-relay
+```
+
+Without restarting your shell:
+
+```bash
+bunx -p agent-relay-codex@latest codex-relay
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
+| `AGENT_RELAY_TOKEN` | — | Auth token (for remote relays) |
+| `AGENT_RELAY_CAPS` | `chat` | Comma-separated capabilities |
+| `AGENT_RELAY_APPROVAL` | `open` | Approval mode: `open`, `guarded`, `read-only` |
+
+These four env vars are shared with the [Claude plugin](https://www.npmjs.com/package/agent-relay-plugin).
+
+### Codex-specific
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CODEX_MODEL` | — | Model override |
+| `CODEX_THREAD_MODE` | `start` | Thread attach: `start`, `resume`, `auto` |
+| `CODEX_THREAD_ID` | — | Pin to a specific thread |
+| `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:4501` | App-server WebSocket URL |
+
+### Advanced tuning
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `AGENT_RELAY_CODEX_RIG` | `codex-live` | Rig name on agent card |
+| `AGENT_RELAY_CODEX_POLL_INTERVAL_MS` | `2000` | Inbox poll cadence |
+| `AGENT_RELAY_CODEX_HEARTBEAT_INTERVAL_MS` | `30000` | Heartbeat cadence |
+| `AGENT_RELAY_CODEX_COALESCE_WINDOW_MS` | `600` | Message batch window |
+| `AGENT_RELAY_CODEX_RELAY_BACKOFF_INITIAL_MS` | `2000` | Relay API retry backoff |
+| `AGENT_RELAY_CODEX_RELAY_BACKOFF_MAX_MS` | `60000` | Relay API retry backoff cap |
+| `AGENT_RELAY_CODEX_HOOK_TIMEOUT_MS` | `5000` | SessionStart handshake timeout |
+
+## Approval mode
+
+`codex-relay` maps `AGENT_RELAY_APPROVAL` to Codex runtime flags:
+
+| Mode | Codex flags |
+|------|-------------|
+| `open` | `--ask-for-approval never --sandbox danger-full-access` |
+| `guarded` | `--ask-for-approval on-request --sandbox workspace-write` |
+| `read-only` | `--ask-for-approval never --sandbox read-only` |
+
+Pass explicit Codex flags to override:
+
+```bash
+# trusted private rig: no sandbox
+codex-relay -- --dangerously-bypass-approvals-and-sandbox
+
+# full-auto mode
+codex-relay -- --full-auto
+```
+
+If `AGENT_RELAY_APPROVAL` is set, explicit Codex permission flags must resolve
+to the same effective mode.
+
+The approval mode is registered on the agent card as `meta.approvalMode` (`open`, `guarded`, or `read-only`), visible in the dashboard.
+
+## Uninstall
+
+```bash
+agent-relay-codex uninstall          # remove hooks, plugins, shims
+agent-relay-codex uninstall --purge  # also remove runtime state and PATH entries
+```
+
+## How it works
+
+`codex-relay` launches `codex app-server`, opens Codex through `codex --remote`, and spawns a live sidecar that:
+
+- Registers the session as an Agent Relay agent
+- Polls the relay inbox and delivers messages into the active Codex thread
+- Coalesces rapid message bursts into a single turn
+- Claims claimable tasks before delivery
+- Reconnects with exponential backoff after disconnects
+- Marks the agent offline on exit
+
+Message delivery adapts to thread state: `turn/start` when idle, `turn/steer` when active, `turn/interrupt` for urgent messages.
+
+## Development
+
+```bash
+# run sidecar directly
+bash codex/start-live.sh
+
+# run tests
+bun test codex/
+
+# doctor check
+bun run codex/bin/agent-relay-codex.ts doctor
+```

package/app-client.ts

@@ -0,0 +1,239 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+type JsonRpcId = number | string;
+
+type JsonRpcRequest = {
+  id: JsonRpcId;
+  method: string;
+  params?: unknown;
+};
+
+type JsonRpcResponse = {
+  id: JsonRpcId;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+type JsonRpcNotification = {
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+export type ThreadStatus =
+  | { type: "notLoaded" }
+  | { type: "idle" }
+  | { type: "systemError" }
+  | { type: "active"; activeFlags: string[] };
+
+export type TurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
+
+export interface Turn {
+  id: string;
+  status: TurnStatus;
+  startedAt: number | null;
+  completedAt: number | null;
+}
+
+export interface Thread {
+  id: string;
+  cwd: string;
+  status: ThreadStatus;
+  updatedAt: number;
+  preview: string;
+  turns?: Turn[];
+}
+
+export type ClientEvent =
+  | { type: "notification"; message: JsonRpcNotification }
+  | { type: "server-request"; message: JsonRpcRequest }
+  | { type: "response"; message: JsonRpcResponse };
+
+export interface TurnStartResponse {
+  turn: Turn;
+}
+
+export interface ThreadStartResponse {
+  thread: Thread;
+}
+
+export interface ThreadResumeResponse {
+  thread: Thread;
+}
+
+export interface ThreadReadResponse {
+  thread: Thread;
+}
+
+export interface ThreadListResponse {
+  data: Thread[];
+  nextCursor: string | null;
+}
+
+export interface ThreadLoadedListResponse {
+  data: string[];
+  nextCursor: string | null;
+}
+
+export class CodexAppClient {
+  private ws!: WebSocket;
+  private nextId = 1;
+  private pending = new Map<JsonRpcId, { resolve: (value: any) => void; reject: (err: unknown) => void }>();
+  private events: ClientEvent[] = [];
+  private listeners = new Set<(event: ClientEvent) => void>();
+  private connected = false;
+  private connectionListeners = new Set<(connected: boolean) => void>();
+
+  constructor(private readonly url: string, private readonly log: (msg: string) => void = () => {}) {}
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+
+      ws.onopen = () => {
+        this.connected = true;
+        this.emitConnection(true);
+        resolve();
+      };
+      ws.onerror = (event) => reject(new Error(`websocket error: ${String((event as ErrorEvent).message || "unknown")}`));
+      ws.onclose = (event) => {
+        this.connected = false;
+        this.emitConnection(false);
+        const err = new Error(`websocket closed code=${event.code} reason=${event.reason || "(none)"}`);
+        for (const pending of this.pending.values()) pending.reject(err);
+        this.pending.clear();
+      };
+      ws.onmessage = (event) => this.handleMessage(String(event.data));
+    });
+  }
+
+  close(): void {
+    if (!this.ws) return;
+    this.ws.close();
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async initialize(): Promise<unknown> {
+    return this.request("initialize", {
+      clientInfo: {
+        name: "agent-relay-codex-live",
+        title: "Agent Relay Codex Live",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+      },
+    });
+  }
+
+  onEvent(listener: (event: ClientEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  onConnectionChange(listener: (connected: boolean) => void): () => void {
+    this.connectionListeners.add(listener);
+    return () => this.connectionListeners.delete(listener);
+  }
+
+  getEvents(): ClientEvent[] {
+    return [...this.events];
+  }
+
+  async settle(ms = 150): Promise<void> {
+    await delay(ms);
+  }
+
+  async threadStart(params: Record<string, unknown>): Promise<ThreadStartResponse> {
+    return this.request<ThreadStartResponse>("thread/start", params);
+  }
+
+  async threadResume(params: Record<string, unknown>): Promise<ThreadResumeResponse> {
+    return this.request<ThreadResumeResponse>("thread/resume", params);
+  }
+
+  async threadRead(threadId: string, includeTurns = false): Promise<ThreadReadResponse> {
+    return this.request<ThreadReadResponse>("thread/read", { threadId, includeTurns });
+  }
+
+  async threadList(params: Record<string, unknown>): Promise<ThreadListResponse> {
+    return this.request<ThreadListResponse>("thread/list", params);
+  }
+
+  async threadLoadedList(limit = 20): Promise<ThreadLoadedListResponse> {
+    return this.request<ThreadLoadedListResponse>("thread/loaded/list", { limit });
+  }
+
+  async turnStart(threadId: string, text: string): Promise<TurnStartResponse> {
+    return this.request<TurnStartResponse>("turn/start", {
+      threadId,
+      input: [{ type: "text", text }],
+    });
+  }
+
+  async turnSteer(threadId: string, turnId: string, text: string): Promise<{ turnId: string }> {
+    return this.request<{ turnId: string }>("turn/steer", {
+      threadId,
+      expectedTurnId: turnId,
+      input: [{ type: "text", text }],
+    });
+  }
+
+  async turnInterrupt(threadId: string, turnId: string): Promise<Record<string, never>> {
+    return this.request<Record<string, never>>("turn/interrupt", { threadId, turnId });
+  }
+
+  private async request<T = unknown>(method: string, params?: unknown): Promise<T> {
+    if (!this.connected) {
+      throw new Error("websocket not connected");
+    }
+    const id = this.nextId++;
+    const payload: JsonRpcRequest = { id, method, params };
+    const promise = new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+    });
+    this.ws.send(JSON.stringify(payload));
+    return promise;
+  }
+
+  private handleMessage(raw: string): void {
+    const parsed = JSON.parse(raw) as JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+
+    if ("id" in parsed && ("result" in parsed || "error" in parsed)) {
+      const pending = this.pending.get(parsed.id);
+      if (pending) {
+        this.pending.delete(parsed.id);
+        if (parsed.error) {
+          pending.reject(new Error(`${parsed.error.message} (${parsed.error.code})`));
+        } else {
+          pending.resolve(parsed.result);
+        }
+      }
+      this.record({ type: "response", message: parsed });
+      return;
+    }
+
+    if ("id" in parsed && "method" in parsed) {
+      this.log(`server-request ${parsed.method}`);
+      this.record({ type: "server-request", message: parsed });
+      return;
+    }
+
+    if ("method" in parsed) {
+      this.record({ type: "notification", message: parsed });
+    }
+  }
+
+  private record(event: ClientEvent): void {
+    this.events.push(event);
+    for (const listener of this.listeners) listener(event);
+  }
+
+  private emitConnection(connected: boolean): void {
+    for (const listener of this.connectionListeners) listener(connected);
+  }
+}

package/approval.ts

@@ -0,0 +1,29 @@
+export type ApprovalMode = "open" | "guarded" | "read-only";
+
+export type SessionPermissions = {
+  approvalPolicy?: string;
+  sandbox?: string;
+};
+
+export function parseApprovalMode(raw: string | undefined): ApprovalMode {
+  if (raw === "guarded" || raw === "read-only" || raw === "open") return raw;
+  return "open";
+}
+
+export function codexArgsForApprovalMode(mode: ApprovalMode): string[] {
+  if (mode === "read-only") return ["--ask-for-approval", "never", "--sandbox", "read-only"];
+  if (mode === "guarded") return ["--ask-for-approval", "on-request", "--sandbox", "workspace-write"];
+  return ["--ask-for-approval", "never", "--sandbox", "danger-full-access"];
+}
+
+export function approvalModeFromPermissions(permissions: SessionPermissions): ApprovalMode {
+  if (permissions.sandbox === "read-only") return "read-only";
+  if (permissions.sandbox === "workspace-write") return "guarded";
+  return "open";
+}
+
+export function describeApprovalMode(mode: ApprovalMode): string {
+  if (mode === "read-only") return "observe, analyze, and report only; no file writes or mutation";
+  if (mode === "guarded") return "workspace sandboxing with approval prompts for operations Codex considers risky";
+  return "no Agent Relay restrictions; Codex runs without sandbox restrictions";
+}