agent-relay-server 0.3.2 → 0.3.3

package/README.md

@@ -51,15 +51,22 @@ Open a second Claude Code session and say:
 
 ## Codex Quick Start
 
-Codex support uses the same relay server, plus a Codex plugin, a SessionStart
-hook, and a managed app-server launcher.
+Codex live support uses the same relay server plus:
+
+- `codex-relay` launcher
+- a `SessionStart` hook
+- the live sidecar (`codex/live-sidecar.ts`)
+
+The installer also adds a Codex plugin skill bundle. That plugin is optional:
+it adds in-session guidance, but live agent registration and incoming-message
+delivery are handled by the hook + sidecar path.
 
 ```bash
 # terminal 1: central relay server
 bunx agent-relay-server@latest
 
 # one-time installer
-curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash
+curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash
 
 # start Codex with live Agent Relay support after restarting your shell
 codex-relay
@@ -87,7 +94,7 @@ codex-relay
 On Windows PowerShell:
 
 ```powershell
-irm https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.ps1 | iex
+irm https://unpkg.com/agent-relay-server@latest/codex/install-codex.ps1 | iex
 codex-relay
 ```
 
@@ -102,23 +109,28 @@ bunx -p agent-relay-server@latest codex-relay
 Non-interactive alias opt-in:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash -s -- --alias
+curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash -s -- --alias
 ```
 
 ```powershell
-$env:AGENT_RELAY_CODEX_ALIAS = "1"; irm https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.ps1 | iex
+$env:AGENT_RELAY_CODEX_ALIAS = "1"; irm https://unpkg.com/agent-relay-server@latest/codex/install-codex.ps1 | iex
 ```
 
 ## What the Agent Sees
 
-When a session starts, the plugin's background monitor registers the agent and outputs its identity and messaging instructions as a notification. The agent is immediately aware of the relay and ready to communicate:
+For Claude Code sessions, the plugin monitor registers the agent and outputs its
+identity and messaging instructions as a notification:
 
 ```
 Agent Relay active. Your agent ID: macmini2-cli-myproject-a1b2c3
 Relay URL: http://localhost:4850 | Server: 0.3.2 | Plugin: 0.3.2
 ```
 
-Incoming messages arrive as monitor notifications. The agent sees them without being prompted:
+In Claude, incoming messages arrive as monitor notifications.
+
+In Codex, incoming messages are delivered as live turns by the sidecar.
+
+Example incoming relay message:
 
 ```
 [msg:42] from backend-agent: Migration looks clean, tests pass. Ready to merge.
@@ -156,6 +168,9 @@ export AGENT_RELAY_URL=http://100.x.y.z:4850
 | `PORT` | `4850` | Server port |
 | `HOST` | `127.0.0.1` | Bind address |
 | `DB_PATH` | `agent-relay.db` | SQLite database path |
+| `STALE_TTL_MS` | `600000` | Mark agents offline after this heartbeat gap |
+| `OFFLINE_PRUNE_MS` | `86400000` | Delete offline agents older than this |
+| `REAP_INTERVAL_MS` | `60000` | Reaper cadence for stale/offline cleanup |
 | `RETENTION_DAYS` | `30` | Auto-prune messages older than this |
 
 ### Plugin environment variables

package/codex/README.md

@@ -1,6 +1,6 @@
 # Codex Live Sidecar
 
-First real Codex integration for Agent Relay.
+Codex integration for Agent Relay.
 
 ## Purpose
 
@@ -10,7 +10,7 @@ This sidecar connects to a Codex app-server session and to Agent Relay, then del
 - `turn/steer`
 - `turn/interrupt`
 
-## Current MVP behavior
+## Current behavior
 
 - attaches to a loaded thread for the current `cwd` when one exists
 - otherwise resumes the newest thread for the current `cwd`
@@ -39,7 +39,7 @@ The packaged Codex path is:
 
 ```bash
 bunx agent-relay-server@latest
-curl -fsSL https://raw.githubusercontent.com/edimuj/agent-relay/main/codex/install-codex.sh | bash
+curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash
 # after restarting your shell
 codex-relay
 ```
@@ -73,7 +73,7 @@ Useful environment variables:
 
 ## Notes
 
-This is still an early sidecar cut. It now handles reconnects and basic coalescing, but it still lacks richer policies such as batching by sender, message prioritization queues, and more nuanced retry/backoff behavior.
+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.

package/codex/hooks/session-start.ts

@@ -6,6 +6,11 @@ import { buildAgentIdentity } from "../relay.ts";
 
 type HookInput = {
   session_id?: string;
+  sessionId?: string;
+  thread_id?: string;
+  threadId?: string;
+  session?: { id?: string };
+  thread?: { id?: string };
   cwd?: string;
   model?: string;
 };
@@ -40,32 +45,56 @@ function outputContext(context: string): never {
   process.exit(0);
 }
 
+function pickThreadId(input: HookInput): string {
+  const candidates = [
+    input.session_id,
+    input.sessionId,
+    input.thread_id,
+    input.threadId,
+    input.session?.id,
+    input.thread?.id,
+  ];
+  for (const value of candidates) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
+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 = input.session_id || "";
+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 || !threadId) {
+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 sessionDir = join(runtimeDir, sanitize(threadId));
+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 });
 
-if (existsSync(pidPath)) {
-  const existingPid = Number(readFileSync(pidPath, "utf8").trim());
-  if (Number.isFinite(existingPid) && isAlive(existingPid)) {
+const autoPidPath = join(runtimeDir, "auto", "sidecar.pid");
+const activePid = existingAlivePid(pidPath) ?? (threadId ? existingAlivePid(autoPidPath) : null);
+if (activePid !== null) {
+  if (threadId) {
     const identity = buildAgentIdentity({
       relayUrl,
       cwd,
@@ -78,20 +107,27 @@ if (existsSync(pidPath)) {
     });
     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" : "auto",
+  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);
 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 || "",
-  },
+  env: spawnEnv,
   stdout: logFile,
   stderr: logFile,
 });
@@ -100,6 +136,10 @@ sidecar.unref();
 writeFileSync(pidPath, String(sidecar.pid));
 appendFileSync(join(runtimeDir, "sidecar-pids.txt"), `${sidecar.pid}\n`);
 
+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,

package/codex/install-codex.sh

@@ -9,9 +9,9 @@ usage() {
 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
+  curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash
+  curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash -s -- --alias
+  curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash -s -- --no-alias
 
 Options:
   --alias     Install a PATH shim so plain `codex` starts with Agent Relay.

package/codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"

package/package.json

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

package/src/config.ts

@@ -8,9 +8,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
 export const VERSION: string = pkg.version;
 
-export const STALE_TTL_MS = 600_000; // 10min without heartbeat → offline
-export const REAP_INTERVAL_MS = 60_000; // reaper cadence
 export const DAY_MS = 86_400_000;
+function envPositiveInt(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.floor(parsed);
+}
+
+export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 600_000); // 10min without heartbeat → offline
+export const OFFLINE_PRUNE_MS = envPositiveInt("OFFLINE_PRUNE_MS", DAY_MS); // 24h offline → delete
+export const REAP_INTERVAL_MS = envPositiveInt("REAP_INTERVAL_MS", 60_000); // reaper cadence
 
 // Max body size for any POST/PATCH request (64 KiB).
 export const MAX_BODY_BYTES = 64 * 1024;

package/src/db.ts

@@ -289,6 +289,33 @@ export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
   return rows.map((r: any) => r.id);
 }
 
+export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
+  const cutoff = Date.now() - maxOfflineMs;
+  return db.transaction(() => {
+    const rows = db
+      .prepare(
+        "SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')"
+      )
+      .all(cutoff) as any[];
+    if (rows.length === 0) return [];
+
+    // Release claims held by pruned agents so work becomes claimable again.
+    db
+      .prepare(
+        "UPDATE messages SET claimed_by = NULL, claimed_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system'))"
+      )
+      .run(cutoff);
+
+    db
+      .prepare(
+        "DELETE FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')"
+      )
+      .run(cutoff);
+
+    return rows.map((r: any) => r.id);
+  })();
+}
+
 export function findAgentsByCapability(capability: string, onlineOnly = true): AgentCard[] {
   let sql = `SELECT * FROM agents WHERE EXISTS (SELECT 1 FROM json_each(capabilities) WHERE value = ?)`;
   const params: any[] = [capability];

package/src/index.ts

@@ -1,9 +1,16 @@
 #!/usr/bin/env bun
-import { initDb, reapStaleAgents, pruneOldMessages } from "./db";
+import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages } from "./db";
 import { matchRoute } from "./routes";
-import { emitAgentStatus } from "./sse";
+import { emitAgentStatus, emitAgentRemoved } from "./sse";
 import { resolve, sep } from "path";
-import { REAP_INTERVAL_MS, STALE_TTL_MS, MAX_BODY_BYTES, DAY_MS, VERSION } from "./config";
+import {
+  REAP_INTERVAL_MS,
+  STALE_TTL_MS,
+  OFFLINE_PRUNE_MS,
+  MAX_BODY_BYTES,
+  DAY_MS,
+  VERSION,
+} from "./config";
 
 const PORT = Number(process.env.PORT) || 4850;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -19,6 +26,11 @@ setInterval(() => {
     console.log(`reaped ${reaped.length} stale agent(s)`);
     for (const id of reaped) emitAgentStatus(id);
   }
+  const pruned = pruneOfflineAgents(OFFLINE_PRUNE_MS);
+  if (pruned.length > 0) {
+    console.log(`pruned ${pruned.length} offline agent(s)`);
+    for (const id of pruned) emitAgentRemoved(id);
+  }
 }, REAP_INTERVAL_MS);
 
 // Daily message prune