agent-relay-server 0.3.9 → 0.3.11

package/README.md

@@ -201,7 +201,7 @@ 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 |
+| `STALE_TTL_MS` | `120000` | 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 |
@@ -311,6 +311,7 @@ claude/                              # Claude Code plugin
 ├── monitors/monitors.json           # Auto-start inbox monitor
 └── hooks/
     ├── relay-monitor.sh             # Register, inject context, poll
+    ├── set-status.sh                # Turn hooks: busy/idle status updates
     ├── session-end.sh               # Mark agent offline
     └── poll-inbox.sh                # Inbox poll loop
 

package/bin/agent-relay-codex.ts

@@ -14,6 +14,24 @@ type RelayStats = {
   version?: string;
 };
 
+type HookHandshake = {
+  status: "ok" | "error";
+  code: string;
+  message?: string;
+  pid?: number;
+  threadId?: string;
+  timestamp?: string;
+};
+
+type HookWaitResult = {
+  ok: boolean;
+  code: string;
+  message?: string;
+  pid?: number;
+};
+
+const DEFAULT_HOOK_HANDSHAKE_TIMEOUT_MS = 5000;
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const home = process.env.HOME || process.env.USERPROFILE || homedir();
@@ -76,6 +94,21 @@ function readJsonFile<T>(path: string, fallback: T): T {
   return JSON.parse(readFileSync(path, "utf8")) as T;
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function envPositiveInt(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function appendLauncherLog(runDir: string, line: string): void {
+  appendFileSync(join(runDir, "launcher.log"), `${new Date().toISOString()} ${line}\n`);
+}
+
 function isAgentRelaySessionStartCommand(command: string): boolean {
   return /agent-relay.*codex\/hooks\/session-start\.ts/.test(command);
 }
@@ -336,21 +369,35 @@ async function waitForPort(url: string, child: ReturnType<typeof Bun.spawn>): Pr
   throw new Error(`timed out waiting for ${url}`);
 }
 
-async function waitForSidecarPid(runDir: string, timeoutMs: number): Promise<boolean> {
-  const pidsPath = join(runDir, "sidecar-pids.txt");
+async function waitForHookHandshake(runDir: string, timeoutMs: number): Promise<HookWaitResult> {
+  const handshakePath = join(runDir, "session-start-handshake.json");
   const deadline = Date.now() + timeoutMs;
 
   while (Date.now() < deadline) {
-    if (existsSync(pidsPath)) {
-      for (const line of readFileSync(pidsPath, "utf8").split("\n")) {
-        const pid = Number(line.trim());
-        if (Number.isFinite(pid) && pid > 0 && isAlive(pid)) return true;
+    if (existsSync(handshakePath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(handshakePath, "utf8")) as HookHandshake;
+        const code = typeof parsed.code === "string" && parsed.code.trim() ? parsed.code.trim() : "HOOK_HANDSHAKE_INVALID";
+        const message = typeof parsed.message === "string" ? parsed.message : undefined;
+        const pid = typeof parsed.pid === "number" && Number.isFinite(parsed.pid) && parsed.pid > 0
+          ? parsed.pid
+          : undefined;
+
+        if (parsed.status === "ok") return { ok: true, code, message, pid };
+        if (parsed.status === "error") return { ok: false, code, message, pid };
+        return { ok: false, code: "HOOK_HANDSHAKE_INVALID", message: `unexpected status ${String((parsed as any).status)}` };
+      } catch (error) {
+        return { ok: false, code: "HOOK_HANDSHAKE_INVALID", message: errorMessage(error) };
       }
     }
     await Bun.sleep(100);
   }
 
-  return false;
+  return {
+    ok: false,
+    code: "HOOK_HANDSHAKE_TIMEOUT",
+    message: `no hook handshake observed within ${timeoutMs}ms`,
+  };
 }
 
 function spawnFallbackSidecar(runDir: string, env: Record<string, string | undefined>): number {
@@ -656,10 +703,39 @@ async function start(args: string[]): Promise<void> {
     stderr: "inherit",
   });
 
-  const sidecarDetected = await waitForSidecarPid(runDir, 2500);
-  if (!sidecarDetected && codex.exitCode === null) {
+  const hookTimeoutMs = envPositiveInt("AGENT_RELAY_CODEX_HOOK_TIMEOUT_MS", DEFAULT_HOOK_HANDSHAKE_TIMEOUT_MS);
+  const handshake = await waitForHookHandshake(runDir, hookTimeoutMs);
+  let fallbackReason: HookWaitResult | null = null;
+
+  if (!handshake.ok) {
+    fallbackReason = handshake;
+  } else if (handshake.pid === undefined) {
+    fallbackReason = {
+      ok: false,
+      code: "HOOK_HANDSHAKE_NO_PID",
+      message: "hook reported success without a sidecar pid",
+    };
+  } else if (!isAlive(handshake.pid)) {
+    fallbackReason = {
+      ok: false,
+      code: "HOOK_HANDSHAKE_PID_NOT_ALIVE",
+      message: `hook reported pid ${handshake.pid} but it is not running`,
+    };
+  } else {
+    appendLauncherLog(runDir, `HOOK_HANDSHAKE_OK code=${handshake.code} pid=${handshake.pid}`);
+  }
+
+  if (fallbackReason && codex.exitCode === null) {
     const pid = spawnFallbackSidecar(runDir, env);
-    console.error(`Agent Relay: SessionStart hook did not start sidecar; started fallback sidecar pid ${pid}`);
+    appendFileSync(
+      join(runDir, "launcher.log"),
+      `${new Date().toISOString()} HOOK_FALLBACK_STARTED reason=${fallbackReason.code} fallbackPid=${pid}${fallbackReason.message ? ` detail=${fallbackReason.message}` : ""}\n`,
+    );
+  } else if (fallbackReason) {
+    appendLauncherLog(
+      runDir,
+      `HOOK_FALLBACK_SKIPPED reason=${fallbackReason.code} codexExit=${codex.exitCode}${fallbackReason.message ? ` detail=${fallbackReason.message}` : ""}`,
+    );
   }
 
   const exitCode = await codex.exited;

package/codex/README.md

@@ -97,6 +97,7 @@ Useful environment variables:
 
 - `AGENT_RELAY_URL`
 - `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`
@@ -107,6 +108,10 @@ Useful environment variables:
 - `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.

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

@@ -0,0 +1,39 @@
+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

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

@@ -3,16 +3,15 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } fr
 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 HookInput = {
-  session_id?: string;
-  sessionId?: string;
-  thread_id?: string;
+type HookHandshake = {
+  status: "ok" | "error";
+  code: string;
+  message: string;
+  pid?: number;
   threadId?: string;
-  session?: { id?: string };
-  thread?: { id?: string };
-  cwd?: string;
-  model?: string;
+  timestamp: string;
 };
 
 function readStdin(): string {
@@ -45,19 +44,12 @@ 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 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 {
@@ -90,10 +82,19 @@ 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,
@@ -126,15 +127,36 @@ if (threadId) {
 }
 
 const logFile = Bun.file(logPath);
-const sidecar = Bun.spawn(["bun", "run", join(packageRoot, "codex", "live-sidecar.ts")], {
-  env: spawnEnv,
-  stdout: logFile,
-  stderr: logFile,
-});
-sidecar.unref();
-
-writeFileSync(pidPath, String(sidecar.pid));
-appendFileSync(join(runtimeDir, "sidecar-pids.txt"), `${sidecar.pid}\n`);
+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.`);

package/codex/smoke/fallback.ts

@@ -90,13 +90,10 @@ async function main(): Promise<void> {
     throw new Error(`missing runtime directory in launcher output\nstdout:\n${stdout}\nstderr:\n${stderr}`);
   }
 
-  if (!stderr.includes("SessionStart hook did not start sidecar; started fallback sidecar pid")) {
-    throw new Error(`fallback start message not found\nstderr:\n${stderr}`);
-  }
-
   const fallbackPidPath = join(runtimeDir, "auto", "sidecar.pid");
   const fallbackLogPath = join(runtimeDir, "auto", "sidecar.log");
   const sidecarPidsPath = join(runtimeDir, "sidecar-pids.txt");
+  const launcherLogPath = join(runtimeDir, "launcher.log");
 
   if (!existsSync(fallbackPidPath)) {
     throw new Error(`fallback pid file missing: ${fallbackPidPath}`);
@@ -104,12 +101,19 @@ async function main(): Promise<void> {
   if (!existsSync(sidecarPidsPath)) {
     throw new Error(`sidecar-pids missing: ${sidecarPidsPath}`);
   }
+  if (!existsSync(launcherLogPath)) {
+    throw new Error(`launcher log missing: ${launcherLogPath}`);
+  }
 
   const pid = readFileSync(fallbackPidPath, "utf8").trim();
   const pidsFile = readFileSync(sidecarPidsPath, "utf8");
+  const launcherLog = readFileSync(launcherLogPath, "utf8");
   if (!pid || !pidsFile.includes(pid)) {
     throw new Error(`fallback pid ${pid || "<empty>"} not recorded in sidecar-pids.txt`);
   }
+  if (!launcherLog.includes("HOOK_FALLBACK_STARTED reason=HOOK_HANDSHAKE_TIMEOUT")) {
+    throw new Error(`fallback reason code missing in launcher log\nlog:\n${launcherLog}`);
+  }
 
   log(`fallback sidecar created pid ${pid}`);
   if (existsSync(fallbackLogPath)) {

package/package.json

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

package/public/index.html

@@ -30,8 +30,8 @@
   .status-dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; flex-shrink: 0; }
   .status-dot.online { background: var(--tblr-success); box-shadow: 0 0 6px var(--tblr-success); }
   .status-dot.online.not-ready { animation: pulse-dot 1.5s ease-in-out infinite; }
-  .status-dot.idle { background: var(--tblr-warning); }
-  .status-dot.busy { background: var(--tblr-danger); }
+  .status-dot.idle { background: var(--tblr-success); }
+  .status-dot.busy { background: var(--tblr-warning); }
   .status-dot.offline { background: var(--tblr-secondary); opacity: 0.5; }
 
   @keyframes pulse-dot {
@@ -242,6 +242,20 @@
         <div class="d-flex align-items-center mb-3 gap-3 flex-wrap">
           <h2 class="page-title mb-0">Agents</h2>
           <div class="ms-auto d-flex gap-2 align-items-center">
+            <select class="form-select form-select-sm" style="width:auto; min-width: 140px" x-model="agentStatusFilter">
+              <option value="">Status: All</option>
+              <option value="starting">Status: Starting</option>
+              <option value="online">Status: Online</option>
+              <option value="idle">Status: Idle</option>
+              <option value="busy">Status: Busy</option>
+              <option value="offline">Status: Offline</option>
+            </select>
+            <select class="form-select form-select-sm" style="width:auto; min-width: 140px" x-model="agentTagFilter">
+              <option value="">Tag: All</option>
+              <template x-for="tag in uniqueTags" :key="tag">
+                <option :value="tag" x-text="'Tag: ' + tag"></option>
+              </template>
+            </select>
             <select class="form-select form-select-sm" style="width:auto" x-model="agentSort">
               <option value="status">Sort: Status</option>
               <option value="name">Sort: Name</option>
@@ -251,6 +265,14 @@
             <button class="btn btn-sm btn-ghost-secondary" @click="agentSortDir = agentSortDir === 'asc' ? 'desc' : 'asc'">
               <i class="ti" :class="agentSortDir === 'asc' ? 'ti-sort-ascending' : 'ti-sort-descending'"></i>
             </button>
+            <button
+              class="btn btn-sm btn-ghost-secondary"
+              x-show="agentStatusFilter || agentTagFilter"
+              @click="agentStatusFilter = ''; agentTagFilter = ''"
+              title="Clear filters"
+            >
+              <i class="ti ti-x me-1"></i>Clear
+            </button>
           </div>
         </div>
 
@@ -260,7 +282,7 @@
               <div class="card agent-card" :class="{ selected: selectedAgent === a.id }">
                 <div class="card-body">
                   <div class="d-flex align-items-start gap-2">
-                    <span class="status-dot mt-1" :class="[a.status, a.status !== 'offline' && !a.ready ? 'not-ready' : '']" :title="a.status !== 'offline' && !a.ready ? 'Starting up…' : a.status"></span>
+                    <span class="status-dot mt-1" :class="[a.status, a.status !== 'offline' && !a.ready ? 'not-ready' : '']" :title="agentStatusTitle(a)"></span>
                     <div class="flex-grow-1 min-width-0">
                       <div class="d-flex align-items-center gap-2">
                         <template x-if="a.label">
@@ -319,7 +341,10 @@
           <div class="card">
             <div class="card-body text-center text-secondary py-5">
               <i class="ti ti-robot-off" style="font-size:48px; opacity:0.3"></i>
-              <p class="mt-2" x-text="showOffline ? 'No agents registered' : 'No active agents — enable Show Offline'"></p>
+              <p
+                class="mt-2"
+                x-text="(agentStatusFilter || agentTagFilter) ? 'No agents match the current filters' : (showOffline ? 'No agents registered' : 'No active agents — enable Show Offline')"
+              ></p>
             </div>
           </div>
         </template>
@@ -699,6 +724,8 @@ function relay() {
     // Filters
     channelFilter: '',
     tagFilter: '',
+    agentStatusFilter: load('agentStatusFilter', ''),
+    agentTagFilter: load('agentTagFilter', ''),
 
     // Charts
     chartInstances: {},
@@ -716,6 +743,8 @@ function relay() {
       this.$watch('showOffline', v => this.save('showOffline', v));
       this.$watch('agentSort', v => this.save('agentSort', v));
       this.$watch('agentSortDir', v => this.save('agentSortDir', v));
+      this.$watch('agentStatusFilter', v => this.save('agentStatusFilter', v));
+      this.$watch('agentTagFilter', v => this.save('agentTagFilter', v));
       this.$watch('view', v => {
         this.save('view', v);
         if (v === 'analytics') this.$nextTick(() => this.renderCharts());
@@ -827,13 +856,23 @@ function relay() {
 
     get sortedAgents() {
       let list = this.showOffline ? [...this.agents] : this.agents.filter(a => a.status !== 'offline');
+      if (this.agentStatusFilter) {
+        if (this.agentStatusFilter === 'starting') {
+          list = list.filter(a => a.status !== 'offline' && !a.ready);
+        } else {
+          list = list.filter(a => a.status === this.agentStatusFilter);
+        }
+      }
+      if (this.agentTagFilter) {
+        list = list.filter(a => (a.tags || []).includes(this.agentTagFilter));
+      }
       const dir = this.agentSortDir === 'desc' ? -1 : 1;
       return list.sort((a, b) => {
         let cmp = 0;
         switch (this.agentSort) {
           case 'name': cmp = this.displayName(a).localeCompare(this.displayName(b)); break;
           case 'status': {
-            const order = { online: 0, busy: 1, idle: 2, offline: 3 };
+            const order = { online: 0, idle: 1, busy: 2, offline: 3 };
             cmp = (order[a.status] ?? 9) - (order[b.status] ?? 9);
             break;
           }
@@ -907,9 +946,21 @@ function relay() {
       return agent ? this.displayName(agent) : target.slice(-8);
     },
 
+    agentStatusTitle(agent) {
+      if (!agent) return '';
+      if (agent.status === 'offline') return 'offline';
+      if (agent.ready) return agent.status;
+      const lastSeenMs = new Date(agent.lastSeen).getTime();
+      if (!Number.isFinite(lastSeenMs)) return 'Trying to reconnect…';
+      const ageSec = Math.max(0, (Date.now() - lastSeenMs) / 1000);
+      return ageSec <= 45 ? 'Starting up…' : 'Trying to reconnect…';
+    },
+
     timeAgo(iso) {
       if (!iso) return '';
-      const diff = (Date.now() - new Date(iso).getTime()) / 1000;
+      const ts = new Date(iso).getTime();
+      if (!Number.isFinite(ts)) return '';
+      const diff = Math.max(0, (Date.now() - ts) / 1000);
       if (diff < 60) return Math.floor(diff) + 's ago';
       if (diff < 3600) return Math.floor(diff / 60) + 'm ago';
       if (diff < 86400) return Math.floor(diff / 3600) + 'h ago';
@@ -1084,7 +1135,7 @@ function relay() {
       for (const a of this.agents) counts[a.status] = (counts[a.status] || 0) + 1;
       const labels = Object.keys(counts).filter(k => counts[k] > 0);
       const series = labels.map(k => counts[k]);
-      const colorMap = { online: '#48bb78', idle: '#ecc94b', busy: '#f56565', offline: '#718096' };
+      const colorMap = { online: '#48bb78', idle: '#48bb78', busy: '#ecc94b', offline: '#718096' };
 
       this.chartInstances.status = new ApexCharts(el, {
         chart: { type: 'donut', height: 280, background: 'transparent' },

package/src/config.ts

@@ -17,7 +17,7 @@ function envPositiveInt(name: string, fallback: number): number {
   return Math.floor(parsed);
 }
 
-export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 600_000); // 10min without heartbeat → offline
+export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min 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