agent-relay-server 0.1.0 → 0.3.0

package/codex/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/codex/hooks/session-start.ts

@@ -0,0 +1,114 @@
+#!/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";
+
+type HookInput = {
+  session_id?: string;
+  cwd?: string;
+  model?: 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);
+}
+
+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 = input.session_id || "";
+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 || !threadId) {
+  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 sessionDir = join(runtimeDir, sanitize(threadId));
+const pidPath = join(sessionDir, "sidecar.pid");
+const statePath = join(sessionDir, "live-state.json");
+const logPath = join(sessionDir, "sidecar.log");
+mkdirSync(sessionDir, { recursive: true });
+
+if (existsSync(pidPath)) {
+  const existingPid = Number(readFileSync(pidPath, "utf8").trim());
+  if (Number.isFinite(existingPid) && isAlive(existingPid)) {
+    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}.`);
+  }
+}
+
+const logFile = Bun.file(logPath);
+const sidecar = Bun.spawn(["bun", "run", join(packageRoot, "codex", "live-sidecar.ts")], {
+  env: {
+    ...process.env,
+    AGENT_RELAY_URL: relayUrl,
+    CODEX_APP_SERVER_URL: appServerUrl,
+    CODEX_THREAD_ID: threadId,
+    CODEX_THREAD_MODE: "resume",
+    CODEX_LIVE_CWD: cwd,
+    CODEX_LIVE_STATE_PATH: statePath,
+    CODEX_MODEL: input.model || process.env.CODEX_MODEL || "",
+  },
+  stdout: logFile,
+  stderr: logFile,
+});
+sidecar.unref();
+
+writeFileSync(pidPath, String(sidecar.pid));
+appendFileSync(join(runtimeDir, "sidecar-pids.txt"), `${sidecar.pid}\n`);
+
+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.`);

package/codex/install-codex.ps1

@@ -0,0 +1,47 @@
+param(
+  [switch]$Alias,
+  [switch]$NoAlias
+)
+
+$ErrorActionPreference = "Stop"
+
+$Package = if ($env:AGENT_RELAY_PACKAGE) { $env:AGENT_RELAY_PACKAGE } else { "agent-relay-server" }
+$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

package/codex/install-codex.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="${AGENT_RELAY_PACKAGE:-agent-relay-server}"
+INSTALL_ARGS=(install)
+
+usage() {
+  cat <<'EOF'
+Install Agent Relay for Codex.
+
+Usage:
+  curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash
+  curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash -s -- --alias
+  curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash -s -- --no-alias
+
+Options:
+  --alias     Install a PATH shim so plain `codex` starts with Agent Relay.
+  --no-alias  Keep plain `codex` unchanged. You can still use `codex-relay`.
+EOF
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --alias|--no-alias)
+      INSTALL_ARGS+=("$arg")
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $arg" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if ! command -v bun >/dev/null 2>&1; then
+  cat >&2 <<'EOF'
+Error: Bun is required to install Agent Relay for Codex.
+
+Install Bun first:
+  curl -fsSL https://bun.sh/install | bash
+
+Then rerun this installer.
+EOF
+  exit 1
+fi
+
+if ! command -v codex >/dev/null 2>&1; then
+  cat >&2 <<'EOF'
+Error: Codex CLI is required before installing Agent Relay for Codex.
+
+Install and log in to Codex first, then rerun this installer.
+EOF
+  exit 1
+fi
+
+if [[ " ${INSTALL_ARGS[*]} " != *" --alias "* && " ${INSTALL_ARGS[*]} " != *" --no-alias "* ]]; then
+  if [[ "${AGENT_RELAY_CODEX_ALIAS:-}" == "1" || "${AGENT_RELAY_CODEX_ALIAS:-}" == "true" ]]; then
+    INSTALL_ARGS+=(--alias)
+  elif [[ -r /dev/tty && -w /dev/tty ]]; then
+    printf 'Make plain `codex` start with Agent Relay? You can still use `codex-relay` either way. [y/N] ' >/dev/tty
+    read -r answer </dev/tty || answer=""
+    case "${answer,,}" in
+      y|yes) INSTALL_ARGS+=(--alias) ;;
+      *) INSTALL_ARGS+=(--no-alias) ;;
+    esac
+  else
+    INSTALL_ARGS+=(--no-alias)
+  fi
+fi
+
+exec bunx -p "$PACKAGE" agent-relay-codex "${INSTALL_ARGS[@]}"