agent-relay-server 0.4.13 → 0.4.15

package/codex/README.md

@@ -1,152 +0,0 @@
-# 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
-
-- 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
-- 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.
-
-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
-`/api/messages`), so Codex can prompt for approval in stricter modes.
-
-By default, `codex-relay` starts Codex with `--ask-for-approval never --sandbox
-workspace-write` so relay turns do not get stuck on approval prompts while
-still keeping Codex inside workspace boundaries. 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
-```
-
-Trusted private rig only:
-
-```bash
-codex-relay -- --dangerously-bypass-approvals-and-sandbox
-```
-
-Thread attachment defaults are conservative. The SessionStart hook resumes the
-actual launched Codex thread when Codex provides a thread id. If the launcher has
-to use the fallback sidecar because the hook does not report in time, it starts a
-new thread by default instead of attaching to whichever loaded thread happens to
-match the cwd. Set `AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE=auto` or run
-`codex-relay --thread-mode auto` if you explicitly want cwd-based attachment.
-
-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_TOKEN`
-- `AGENT_RELAY_CAPS`
-- `AGENT_RELAY_CODEX_HOOK_TIMEOUT_MS` (launcher wait for SessionStart handshake, default `5000`)
-- `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`
-
-Fallback reason codes are written to `runtime/<run>/launcher.log` when the
-launcher has to start a sidecar because the SessionStart hook did not confirm
-startup in time.
-
-## 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=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/app-client.ts

@@ -1,239 +0,0 @@
-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/codex/hooks/session-start-lib.test.ts

@@ -1,39 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { pickThreadId } from "./session-start-lib.ts";
-
-describe("pickThreadId", () => {
-  it("prefers explicit thread ids over session ids", () => {
-    const threadId = pickThreadId({
-      session_id: "session-123",
-      thread_id: "thread-456",
-    });
-
-    expect(threadId).toBe("thread-456");
-  });
-
-  it("uses nested thread id when present", () => {
-    const threadId = pickThreadId({
-      session: { id: "session-123" },
-      thread: { id: "thread-789" },
-    });
-
-    expect(threadId).toBe("thread-789");
-  });
-
-  it("falls back to session id when thread id is missing", () => {
-    const threadId = pickThreadId({
-      sessionId: "session-abc",
-    });
-
-    expect(threadId).toBe("session-abc");
-  });
-
-  it("ignores blank candidates", () => {
-    const threadId = pickThreadId({
-      threadId: "   ",
-      session_id: "  session-trimmed  ",
-    });
-
-    expect(threadId).toBe("session-trimmed");
-  });
-});

package/codex/hooks/session-start-lib.ts

@@ -1,25 +0,0 @@
-export type HookInput = {
-  session_id?: string;
-  sessionId?: string;
-  thread_id?: string;
-  threadId?: string;
-  session?: { id?: string };
-  thread?: { id?: string };
-  cwd?: string;
-  model?: string;
-};
-
-export function pickThreadId(input: HookInput): string {
-  const candidates = [
-    input.thread_id,
-    input.threadId,
-    input.thread?.id,
-    input.session_id,
-    input.sessionId,
-    input.session?.id,
-  ];
-  for (const value of candidates) {
-    if (typeof value === "string" && value.trim()) return value.trim();
-  }
-  return "";
-}

package/codex/hooks/session-start.ts

@@ -1,176 +0,0 @@
-#!/usr/bin/env bun
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { buildAgentIdentity } from "../relay.ts";
-import { pickThreadId, type HookInput } from "./session-start-lib.ts";
-
-type HookHandshake = {
-  status: "ok" | "error";
-  code: string;
-  message: string;
-  pid?: number;
-  threadId?: string;
-  timestamp: string;
-};
-
-function readStdin(): string {
-  return readFileSync(0, "utf8");
-}
-
-function sanitize(value: string): string {
-  return value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120) || "session";
-}
-
-function isAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function outputContext(context: string): never {
-  console.log(
-    JSON.stringify({
-      continue: true,
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: context,
-      },
-    }),
-  );
-  process.exit(0);
-}
-
-function handshakePath(runtimeDir: string): string {
-  return join(runtimeDir, "session-start-handshake.json");
-}
-
-function writeHandshake(runtimeDir: string, payload: HookHandshake): void {
-  writeFileSync(handshakePath(runtimeDir), `${JSON.stringify(payload, null, 2)}\n`);
-}
-
-function existingAlivePid(pidPath: string): number | null {
-  if (!existsSync(pidPath)) return null;
-  const existingPid = Number(readFileSync(pidPath, "utf8").trim());
-  if (!Number.isFinite(existingPid) || !isAlive(existingPid)) return null;
-  return existingPid;
-}
-
-const input = JSON.parse(readStdin() || "{}") as HookInput;
-const packageRoot =
-  process.env.AGENT_RELAY_CODEX_PACKAGE_ROOT || resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const appServerUrl = process.env.CODEX_APP_SERVER_URL;
-const runId = process.env.AGENT_RELAY_CODEX_RUN_ID;
-const cwd = input.cwd || process.cwd();
-const threadId = pickThreadId(input);
-const relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-const rig = process.env.CODEX_LIVE_RIG || "codex-live";
-
-if (!appServerUrl || !runId) {
-  outputContext(
-    "Agent Relay for Codex is installed. For live incoming relay messages, start Codex with `agent-relay-codex start` so a managed app-server and sidecar can attach to this session.",
-  );
-}
-
-const runtimeDir = process.env.AGENT_RELAY_CODEX_RUNTIME_DIR || join(process.env.HOME || ".", ".agent-relay", "codex", "runtime", runId);
-const sessionKey = sanitize(threadId || "auto");
-const sessionDir = join(runtimeDir, sessionKey);
-const pidPath = join(sessionDir, "sidecar.pid");
-const statePath = join(sessionDir, "live-state.json");
-const logPath = join(sessionDir, "sidecar.log");
-mkdirSync(sessionDir, { recursive: true });
-mkdirSync(runtimeDir, { recursive: true });
-
-const autoPidPath = join(runtimeDir, "auto", "sidecar.pid");
-const activePid = existingAlivePid(pidPath) ?? (threadId ? existingAlivePid(autoPidPath) : null);
-if (activePid !== null) {
-  writeHandshake(runtimeDir, {
-    status: "ok",
-    code: "HOOK_SIDECAR_REUSED",
-    message: `using existing sidecar pid ${activePid}`,
-    pid: activePid,
-    threadId: threadId || undefined,
-    timestamp: new Date().toISOString(),
-  });
-  if (threadId) {
-    const identity = buildAgentIdentity({
-      relayUrl,
-      cwd,
-      rig,
-      capabilities: (process.env.AGENT_RELAY_CAPS || "chat").split(",").map((value) => value.trim()).filter(Boolean),
-      tags: ["codex", rig, cwd.split("/").filter(Boolean).at(-1) || "unknown"],
-      threadId,
-      model: input.model,
-      appServerUrl,
-    });
-    outputContext(`Agent Relay active for this Codex session. Agent ID: ${identity.id}. Relay URL: ${relayUrl}.`);
-  }
-  outputContext(`Agent Relay sidecar already running (pid ${activePid}). Relay URL: ${relayUrl}.`);
-}
-
-const spawnEnv: Record<string, string | undefined> = {
-  ...process.env,
-  AGENT_RELAY_URL: relayUrl,
-  CODEX_APP_SERVER_URL: appServerUrl,
-  CODEX_THREAD_MODE: threadId ? "resume" : process.env.CODEX_THREAD_MODE || "start",
-  CODEX_LIVE_CWD: cwd,
-  CODEX_LIVE_STATE_PATH: statePath,
-  CODEX_MODEL: input.model || process.env.CODEX_MODEL || "",
-};
-if (threadId) {
-  spawnEnv.CODEX_THREAD_ID = threadId;
-} else {
-  delete spawnEnv.CODEX_THREAD_ID;
-}
-
-const logFile = Bun.file(logPath);
-let sidecarPid = 0;
-try {
-  const sidecar = Bun.spawn(["bun", "run", join(packageRoot, "codex", "live-sidecar.ts")], {
-    env: spawnEnv,
-    stdout: logFile,
-    stderr: logFile,
-  });
-  sidecar.unref();
-  sidecarPid = sidecar.pid;
-
-  writeFileSync(pidPath, String(sidecarPid));
-  appendFileSync(join(runtimeDir, "sidecar-pids.txt"), `${sidecarPid}\n`);
-  writeHandshake(runtimeDir, {
-    status: "ok",
-    code: "HOOK_SIDECAR_STARTED",
-    message: `spawned sidecar pid ${sidecarPid}`,
-    pid: sidecarPid,
-    threadId: threadId || undefined,
-    timestamp: new Date().toISOString(),
-  });
-} catch (error) {
-  writeHandshake(runtimeDir, {
-    status: "error",
-    code: "HOOK_SIDECAR_SPAWN_FAILED",
-    message: error instanceof Error ? error.message : String(error),
-    threadId: threadId || undefined,
-    timestamp: new Date().toISOString(),
-  });
-  throw error;
-}
-
-if (!threadId) {
-  outputContext(`Agent Relay sidecar started in auto-thread mode. Relay URL: ${relayUrl}. Incoming messages will arrive as live user turns once the sidecar resolves the active thread.`);
-}
-
-const identity = buildAgentIdentity({
-  relayUrl,
-  cwd,
-  rig,
-  capabilities: (process.env.AGENT_RELAY_CAPS || "chat").split(",").map((value) => value.trim()).filter(Boolean),
-  tags: ["codex", rig, cwd.split("/").filter(Boolean).at(-1) || "unknown"],
-  threadId,
-  model: input.model,
-  appServerUrl,
-});
-
-outputContext(`Agent Relay active. Agent ID: ${identity.id}. Relay URL: ${relayUrl}. Incoming messages will arrive as live user turns. To reply or send a message, POST JSON to ${relayUrl}/api/messages with from="${identity.id}", to, subject, and body. If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header. Message etiquette: acknowledge incoming agent messages briefly unless they are obvious noise. Anti-loop rule: do not auto-reply to pure acknowledgements/thanks/received messages; acknowledge once, then follow up only when there is new work, a decision, or a deliverable.`);

package/codex/install-codex.ps1

@@ -1,47 +0,0 @@
-param(
-  [switch]$Alias,
-  [switch]$NoAlias
-)
-
-$ErrorActionPreference = "Stop"
-
-$Package = if ($env:AGENT_RELAY_PACKAGE) { $env:AGENT_RELAY_PACKAGE } else { "agent-relay-server@latest" }
-$InstallArgs = New-Object System.Collections.Generic.List[string]
-$InstallArgs.Add("install")
-
-if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
-  Write-Error @"
-Bun is required to install Agent Relay for Codex.
-
-Install Bun first:
-  powershell -c "irm bun.sh/install.ps1 | iex"
-
-Then rerun this installer.
-"@
-}
-
-if (-not (Get-Command codex -ErrorAction SilentlyContinue)) {
-  Write-Error "Codex CLI is required before installing Agent Relay for Codex. Install and log in to Codex first, then rerun this installer."
-}
-
-if ($Alias -and $NoAlias) {
-  Write-Error "Use only one of -Alias or -NoAlias."
-}
-
-if ($Alias) {
-  $InstallArgs.Add("--alias")
-} elseif ($NoAlias) {
-  $InstallArgs.Add("--no-alias")
-} elseif ($env:AGENT_RELAY_CODEX_ALIAS -eq "1" -or $env:AGENT_RELAY_CODEX_ALIAS -eq "true") {
-  $InstallArgs.Add("--alias")
-} else {
-  $answer = Read-Host "Make plain 'codex' start with Agent Relay? You can still use 'codex-relay' either way. [y/N]"
-  if ($answer -match "^(y|yes)$") {
-    $InstallArgs.Add("--alias")
-  } else {
-    $InstallArgs.Add("--no-alias")
-  }
-}
-
-& bunx -p $Package agent-relay-codex @InstallArgs
-exit $LASTEXITCODE