agent-relay-server 0.3.8 → 0.3.10

package/README.md

@@ -77,16 +77,24 @@ codex-relay
 incoming messages as live turns, and cleans up sidecar processes when Codex
 exits.
 
-### Codex approval prompts
+### Codex approval mode
 
 Replying to relay messages is usually done with a shell command (`curl` to
 `/api/messages`), so Codex may prompt for approval in stricter modes.
 
-`codex-relay` now forwards your Codex runtime mode to the sidecar, including
-`--ask-for-approval`, `--sandbox`, `--full-auto`, and `--yolo`.
+By default, `codex-relay` starts Codex with
+`--dangerously-bypass-approvals-and-sandbox` so relay turns do not get stuck on
+approval prompts. 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`.
 
 Useful setups:
 
+```bash
+# default: no approval prompts, no Codex sandbox
+codex-relay
+```
+
 ```bash
 # no approval prompts, still sandboxed to workspace boundaries
 codex-relay -- --ask-for-approval never --sandbox workspace-write
@@ -193,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 |

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 {
@@ -383,6 +430,25 @@ type SessionPermissions = {
   sandbox?: string;
 };
 
+function hasCodexPermissionMode(codexArgs: string[]): boolean {
+  for (const arg of codexArgs) {
+    if (
+      arg === "--yolo" ||
+      arg === "--dangerously-bypass-approvals-and-sandbox" ||
+      arg === "--full-auto" ||
+      arg === "--ask-for-approval" ||
+      arg === "-a" ||
+      arg.startsWith("--ask-for-approval=") ||
+      arg === "--sandbox" ||
+      arg === "-s" ||
+      arg.startsWith("--sandbox=")
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function resolveSessionPermissions(codexArgs: string[]): SessionPermissions {
   let approvalPolicy: string | undefined;
   let sandbox: string | undefined;
@@ -488,7 +554,6 @@ function installLauncherShims(includeCodexAlias: boolean): void {
   mkdirSync(aliasBinDir, { recursive: true });
   writeLauncherShim("codex-relay");
   if (includeCodexAlias) writeLauncherShim("codex");
-  else removeLauncherShim("codex");
 }
 
 function isAliasBinOnPath(): boolean {
@@ -589,6 +654,7 @@ async function start(args: string[]): Promise<void> {
   }
 
   if (!listenUrl) listenUrl = await pickLoopbackUrl();
+  if (!hasCodexPermissionMode(codexArgs)) codexArgs.unshift("--dangerously-bypass-approvals-and-sandbox");
   const permissions = resolveSessionPermissions(codexArgs);
 
   mkdirSync(runtimeRoot, { recursive: true });
@@ -627,8 +693,8 @@ async function start(args: string[]): Promise<void> {
   process.once("exit", shutdown);
 
   await waitForPort(listenUrl, appServer);
-  console.error(`Agent Relay Codex session: ${listenUrl}`);
-  console.error(`Runtime: ${runDir}`);
+  console.log(`Agent Relay Codex session: ${listenUrl}`);
+  console.log(`Runtime: ${runDir}`);
 
   const codex = Bun.spawn([codexBinary, "--remote", listenUrl, ...codexArgs], {
     env,
@@ -637,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

@@ -0,0 +1,121 @@
+# 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
+
+- attaches to a loaded thread for the current `cwd` when one exists
+- otherwise resumes the newest thread for the current `cwd`
+- otherwise creates a new thread
+- 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.
+
+## 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
+`--dangerously-bypass-approvals-and-sandbox` so relay turns do not get stuck on
+approval prompts. 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
+```
+
+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_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=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.
+- 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/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

@@ -48,8 +48,8 @@ exit 64
   chmodSync(path, 0o755);
 }
 
-function parseRuntimeDir(stderr: string): string | null {
-  const match = stderr.match(/^Runtime:\s+(.+)$/m);
+function parseRuntimeDir(output: string): string | null {
+  const match = output.match(/^Runtime:\s+(.+)$/m);
   return match?.[1]?.trim() || null;
 }
 
@@ -85,18 +85,15 @@ async function main(): Promise<void> {
     throw new Error(`launcher exited ${exitCode}\nstdout:\n${stdout}\nstderr:\n${stderr}`);
   }
 
-  const runtimeDir = parseRuntimeDir(stderr);
+  const runtimeDir = parseRuntimeDir(`${stdout}\n${stderr}`);
   if (!runtimeDir) {
-    throw new Error(`missing runtime directory in launcher output\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}`);
+    throw new Error(`missing runtime directory in launcher output\nstdout:\n${stdout}\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)) {
@@ -122,4 +126,3 @@ main().catch((error) => {
   log(error instanceof Error ? error.stack || error.message : String(error));
   process.exitCode = 1;
 });
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "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>
 
@@ -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;
           }
@@ -909,7 +948,9 @@ function relay() {
 
     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 +1125,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