agent-relay-codex 0.4.14

package/hooks/session-start-lib.ts

@@ -0,0 +1,25 @@
+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/hooks/session-start.ts

@@ -0,0 +1,194 @@
+#!/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 { describeApprovalMode, parseApprovalMode } from "../approval.ts";
+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.AGENT_RELAY_CODEX_RIG || "codex-live";
+const approvalMode = parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
+
+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(buildStartupContext(identity.id, relayUrl, approvalMode));
+  }
+  outputContext(`Agent Relay sidecar already running (pid ${activePid}). Relay URL: ${relayUrl}. Approval mode: ${approvalMode} (${describeApprovalMode(approvalMode)}).`);
+}
+
+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",
+  AGENT_RELAY_CODEX_CWD: cwd,
+  AGENT_RELAY_CODEX_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(buildStartupContext(identity.id, relayUrl, approvalMode));
+
+function buildStartupContext(agentId: string, url: string, mode: string): string {
+  return [
+    "Agent Relay active.",
+    `Agent ID: ${agentId}`,
+    `Relay URL: ${url}`,
+    `Approval mode: ${mode} (${describeApprovalMode(parseApprovalMode(mode))})`,
+    "Incoming messages will arrive as live user turns.",
+    `To send a message, POST JSON to ${url}/api/messages with from="${agentId}", to, subject, and body.`,
+    "Targets can be an agent id, tag:name, cap:name, label:name, or broadcast.",
+    "To reply to a specific incoming message, include replyTo set to that message id.",
+    "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.",
+  ].join(" ");
+}

package/install-codex.ps1

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

package/install-codex.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="${AGENT_RELAY_CODEX_PACKAGE:-agent-relay-codex@latest}"
+INSTALL_ARGS=(install)
+
+usage() {
+  cat <<'EOF'
+Install Agent Relay for Codex.
+
+Usage:
+  curl -fsSL https://unpkg.com/agent-relay-codex@latest/codex/install-codex.sh | bash
+  curl -fsSL https://unpkg.com/agent-relay-codex@latest/codex/install-codex.sh | bash -s -- --alias
+  curl -fsSL https://unpkg.com/agent-relay-codex@latest/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[@]}"