agent-relay-server 0.4.16 → 0.4.17

package/README.md

@@ -82,18 +82,42 @@ Open a second session and say:
 
 ## Configuration
 
-Both integrations share the same four env vars:
+Both integrations share the same provider env vars:
 
 | Env var | Default | Purpose |
 |---------|---------|---------|
 | `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
 | `AGENT_RELAY_TOKEN` | unset | Auth token (required for remote relays) |
 | `AGENT_RELAY_CAPS` | `chat` | Comma-separated agent capabilities |
+| `AGENT_RELAY_TAGS` | unset | Extra comma-separated tags added to provider defaults |
+| `AGENT_RELAY_LABEL` | unset | Human-friendly agent label set at registration |
+| `AGENT_RELAY_CHANNELS` | all | Comma-separated channel subscriptions; unchannelled direct work still arrives |
+| `AGENT_RELAY_PROFILE` | unset | Named profile loaded from the profiles file |
+| `AGENT_RELAY_PROFILES_FILE` | `~/.config/agent-relay/profiles.json` | JSON profile file |
 | `AGENT_RELAY_APPROVAL` | `open` | Approval mode: `open`, `guarded`, `read-only` |
 
+Profiles preconfigure labels, tags, capabilities, channels, approval mode, and meta fields:
+
+```json
+{
+  "backend-tester": {
+    "label": "backend tester",
+    "tags": ["backend", "api", "test"],
+    "capabilities": ["chat", "review", "test", "backend"],
+    "channels": ["backend", "qa"],
+    "approval": "guarded",
+    "meta": { "role": "backend-tester" }
+  }
+}
+```
+
+Launch with `AGENT_RELAY_PROFILE=backend-tester codex` or
+`AGENT_RELAY_PROFILE=backend-tester claude`. Explicit env vars override the
+profile where they overlap.
+
 Codex has additional tuning vars documented in [codex/README.md](codex/README.md).
 
-Agent IDs are deterministic: `{hostname}-{rig}-{project}-{session-hash}`.
+Agent IDs are deterministic: `{hostname}-{project}-{session-hash}`.
 
 ## Message Targeting
 
@@ -167,6 +191,14 @@ claimable message. Posting `"status": "resolved"` marks the active task `done`.
 When an integration has `callbackUrl`, Agent Relay posts task lifecycle events
 (creation, claim, status changes) back to the caller.
 
+Integration tokens can also be used as scoped API tokens when the full admin
+`AGENT_RELAY_TOKEN` would be too broad. Supported scopes include `stats:read`,
+`health:read`, `events:read`, `agents:read`, `agents:write`, `messages:read`,
+`messages:write`, `tasks:read`, `tasks:write`, `pairs:read`, `pairs:write`,
+`system:write`, and `*`.
+The event ingress endpoint also accepts the legacy `tasks:create` and
+`events:create` scopes.
+
 Task lifecycle API:
 
 | Method | Path | Purpose |
@@ -281,6 +313,46 @@ curl -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" http://localhost:4850/api/stat
 | `DELETE` | `/messages/:id` | Delete message |
 | `GET` | `/messages/cursor` | Latest message ID (for poller bootstrap) |
 
+### Pair Sessions
+
+Pair sessions are exclusive two-agent live chats backed by normal relay
+messages. They are useful when you want two agent-sessions to collaborate
+in real time without turning the relay into a group chat.
+The sessions can be claude to codex, codex to codex or claude to claude,
+since agent-relay is provider-independent.
+
+```bash
+agent-relay /pair codex "Debug flaky auth tests"
+agent-relay pair codex --objective "Debug flaky auth tests"
+agent-relay pair accept PAIR_ID --agent "$AGENT_RELAY_ID"
+agent-relay pair send PAIR_ID --from "$AGENT_RELAY_ID" --body "What do you see?"
+agent-relay /disconnect
+agent-relay /status
+agent-relay /label backend-fixer
+agent-relay /tags backend tests urgent
+```
+
+Inside provider sessions, the Codex skill and Claude plugin context instruct
+agents to treat slash-style user messages like `/pair codex`, `/status`,
+`/label backend-fixer`, and `/tags backend tests` as relay commands and run the
+CLI. The CLI tries to auto-detect the current agent id from provider state; pass
+`--from` or `--agent` if you want to be explicit.
+
+If the target is already in a pending or active pair, the relay returns
+`409 Busy`. If a target like `codex` matches multiple available agents, the
+relay asks for a more specific target such as `id:...`, `label:...`, `tag:...`,
+`cap:...` or `machine:...`.
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/pairs` | Create a pair invite |
+| `GET` | `/pairs` | List pairs (`?agent=`, `?status=`) |
+| `GET` | `/pairs/:id` | Get one pair |
+| `POST` | `/pairs/:id/accept` | Accept a pending pair |
+| `POST` | `/pairs/:id/reject` | Reject a pending pair |
+| `POST` | `/pairs/:id/messages` | Send a pair message |
+| `POST` | `/pairs/:id/hangup` | End a pending or active pair |
+
 ### Tasks
 
 | Method | Path | Purpose |
@@ -358,3 +430,10 @@ claude --plugin-dir ./claude   # test plugin locally
 ## License
 
 AGPL-3.0-or-later. See [LICENSE](LICENSE).
+
+## Related
+
+- **[callmux](https://github.com/edimuj/callmux)** - MCP multiplexer: parallel execution, batching, caching, pipelining, and shared infrastructure for any AI agent
+- **[tokenlean](https://github.com/edimuj/tokenlean)** -  Make agents less wasteful: Token-efficient CLI tool-toolbox for AI agents
+- **[claude-mneme](https://github.com/edimuj/claude-mneme) / [codex-mneme](https://github.com/edimuj/codex-mneme)** - Lightweight persistent agent memory: so every session picks up where the last one left off
+- **[agent-awareness](https://github.com/edimuj/agent-awareness)** - Real-time situational awareness for your agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -19,7 +19,7 @@
   "scripts": {
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
-    "test": "bun test src/",
+    "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "keywords": [

package/public/dashboard.js

@@ -33,6 +33,7 @@
       tasks: [],
       taskEvents: [],
       stats: {},
+      health: null,
       now: Date.now(),
       authToken: loadPref("authToken", ""),
 
@@ -186,6 +187,7 @@
     es.addEventListener("agent.status", (event) => handleAgentStatus(this, parseEventData(event)));
     es.addEventListener("agent.removed", (event) => handleAgentRemoved(this, parseEventData(event)));
     es.addEventListener("message.claimed", (event) => handleMessageClaimed(this, parseEventData(event)));
+    es.addEventListener("message.claim_released", (event) => handleMessageClaimReleased(this, parseEventData(event)));
     es.addEventListener("message.deleted", (event) => handleMessageDeleted(this, parseEventData(event)));
     registerTaskEvents(this, es);
   }
@@ -223,7 +225,17 @@
 
   function handleMessageClaimed(vm, data) {
     const msg = vm.messages.find((item) => item.id === data.messageId);
-    if (msg) msg.claimedBy = data.claimedBy;
+    if (!msg) return;
+    msg.claimedBy = data.claimedBy;
+    msg.claimExpiresAt = data.claimExpiresAt;
+  }
+
+  function handleMessageClaimReleased(vm, data) {
+    const msg = vm.messages.find((item) => item.id === data.messageId);
+    if (!msg) return;
+    delete msg.claimedBy;
+    delete msg.claimedAt;
+    delete msg.claimExpiresAt;
   }
 
   function handleMessageDeleted(vm, data) {
@@ -265,7 +277,7 @@
       },
 
       async refresh() {
-        await Promise.all([this.fetchStats(), this.fetchAgents(), this.fetchMessages(), this.fetchTasks()]);
+        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchMessages(), this.fetchTasks()]);
       },
 
       async refreshLiveData() {
@@ -285,6 +297,12 @@
         } catch {}
       },
 
+      async fetchHealth() {
+        try {
+          this.health = await this.api("GET", "/health");
+        } catch {}
+      },
+
       async fetchAgents() {
         try {
           this.agents = await this.api("GET", "/agents");
@@ -323,6 +341,7 @@
       uniqueLabels: { get: getUniqueLabels },
       uniqueCaps: { get: getUniqueCaps },
       uniqueTags: { get: getUniqueTags },
+      healthIssues: { get: getHealthIssues },
     };
   }
 
@@ -399,6 +418,10 @@
     return [...new Set(this.agents.flatMap((agent) => agent.tags || []))];
   }
 
+  function getHealthIssues() {
+    return (this.health?.checks || []).filter((check) => check.status !== "ok");
+  }
+
   function compareAgents(vm, a, b) {
     switch (vm.agentSort) {
       case "name":
@@ -422,6 +445,7 @@
       agentStatusTitle,
       timeAgo,
       fmtTime,
+      healthAlertClass,
     };
   }
 
@@ -476,6 +500,12 @@
     return new Date(iso).toLocaleString();
   }
 
+  function healthAlertClass(status) {
+    if (status === "error") return "alert-danger";
+    if (status === "degraded") return "alert-warning";
+    return "alert-success";
+  }
+
   function createMessageActions() {
     return {
       openCompose,

package/public/index.html

@@ -207,6 +207,25 @@
           </div>
         </div>
 
+        <template x-if="health">
+          <div class="alert d-flex align-items-start gap-3 mb-4" :class="healthAlertClass(health.status)">
+            <i class="ti ti-heartbeat mt-1"></i>
+            <div class="flex-grow-1">
+              <div class="fw-bold" x-text="'Relay health: ' + health.status"></div>
+              <template x-if="healthIssues.length === 0">
+                <div class="small">All checks passing</div>
+              </template>
+              <template x-if="healthIssues.length > 0">
+                <div class="small">
+                  <template x-for="check in healthIssues" :key="check.name">
+                    <span class="me-3" x-text="check.detail || check.name"></span>
+                  </template>
+                </div>
+              </template>
+            </div>
+          </div>
+        </template>
+
         <!-- Two-column: Agents + Recent messages -->
         <div class="row g-3">
           <div class="col-lg-5">

package/src/cli.ts

@@ -1,5 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 import {
   createDaemonPlan,
   detectDaemonEnvironment,
@@ -23,8 +25,25 @@ Usage:
   agent-relay [start]
   agent-relay setup [--yes] [--dry-run] [--force] [--env-file PATH] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
   agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]
+  agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
+  agent-relay /pair <target|accept|reject|send|status> [...]
+  agent-relay /disconnect [PAIR_ID]
+  agent-relay /status
+  agent-relay /label [LABEL]
+  agent-relay /tags [TAG ...]
   agent-relay --help
 
+Pair examples:
+  agent-relay pair codex --objective "Debug flaky tests"
+  agent-relay /pair codex "Debug flaky tests"
+  agent-relay pair status
+  agent-relay pair accept PAIR_ID --agent AGENT_ID
+  agent-relay pair send PAIR_ID --from AGENT_ID --body "What do you see?"
+  agent-relay /disconnect
+  agent-relay /status
+  agent-relay /label backend-fixer
+  agent-relay /tags backend tests urgent
+
 Daemon options:
   --env-file PATH   Env file sourced by the daemon (default: platform user config dir)
   --binary PATH     Stable agent-relay binary/script path for the service
@@ -71,9 +90,41 @@ export async function handleCli(args: string[]): Promise<"start" | "handled"> {
     await handleDaemonCommand(args.slice(1));
     return "handled";
   }
+  if (command === "pair" || command === "/pair" || command === "/disconnect") {
+    await handleSlashOrPairCommand(command, args.slice(1));
+    return "handled";
+  }
+  if (command === "/status" || command === "status") {
+    await handleStatusCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/label" || command === "label") {
+    await handleLabelCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/tags" || command === "tags") {
+    await handleTagsCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/reconnect") {
+    console.log("Reconnect is handled automatically by provider sidecars; use `agent-relay pair status` to inspect current pair state.");
+    return "handled";
+  }
   throw new Error(`Unknown command "${command}". Run agent-relay --help.`);
 }
 
+async function handleSlashOrPairCommand(command: string, args: string[]): Promise<void> {
+  if (command === "/disconnect") {
+    await handlePairCommand(["hangup", ...args]);
+    return;
+  }
+  if (command === "/pair") {
+    await handlePairCommand(args);
+    return;
+  }
+  await handlePairCommand(args);
+}
+
 async function handleSetupCommand(args: string[]): Promise<void> {
   let envFile: string | undefined;
   let host: string | undefined;
@@ -205,6 +256,339 @@ function parseDaemonAction(value: string | undefined): DaemonAction {
   return value as DaemonAction;
 }
 
+async function handlePairCommand(args: string[]): Promise<void> {
+  if (!args.length) throw new Error("Usage: agent-relay pair <target|create|status|accept|reject|hangup|send> [options]");
+  const knownActions = new Set(["create", "status", "list", "accept", "reject", "hangup", "disconnect", "send"]);
+  const action = knownActions.has(args[0]!) ? args[0]! : "create";
+  const rest = action === "create" && args[0] !== "create" ? args : args.slice(1);
+
+  if (action === "status" || action === "list") {
+    let agent: string | undefined = await detectAgentId();
+    let status: string | undefined;
+    let json = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--agent" && i + 1 < rest.length) agent = rest[++i];
+      else if (arg === "--status" && i + 1 < rest.length) status = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown pair status option "${arg}"`);
+    }
+    const query = new URLSearchParams();
+    if (agent) query.set("agent", agent);
+    if (status) query.set("status", status);
+    const pairs = await apiRequest("GET", `/api/pairs${query.size ? `?${query}` : ""}`);
+    if (json) console.log(JSON.stringify(pairs, null, 2));
+    else console.log(formatPairs(pairs as any[]));
+    return;
+  }
+
+  if (action === "create") {
+    const target = rest[0];
+    if (!target || target.startsWith("--")) throw new Error("Usage: agent-relay pair <target> [--from AGENT_ID] [--objective TEXT]");
+    let from = await detectAgentId();
+    let objective: string | undefined;
+    let ttlMs: number | undefined;
+    let json = false;
+    const objectiveParts: string[] = [];
+    for (let i = 1; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--from" && i + 1 < rest.length) from = rest[++i];
+      else if (arg === "--objective" && i + 1 < rest.length) objective = rest[++i];
+      else if (arg === "--ttl-ms" && i + 1 < rest.length) ttlMs = parseInt(rest[++i]!, 10);
+      else if (arg === "--json") json = true;
+      else objectiveParts.push(arg!);
+    }
+    objective ??= objectiveParts.length ? objectiveParts.join(" ") : undefined;
+    if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+    const result = await apiRequest("POST", "/api/pairs", { from, target, objective, ttlMs });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const pair = (result as any).pair;
+      console.log(`Pair invite ${pair.id} sent: ${pair.requesterId} -> ${pair.targetId}`);
+    }
+    return;
+  }
+
+  if (action === "accept" || action === "reject" || action === "hangup" || action === "disconnect") {
+    const pairId = rest[0];
+    let agentId = await detectAgentId();
+    let reason: string | undefined;
+    let json = false;
+    let startIndex = 0;
+    if (pairId && !pairId.startsWith("--")) startIndex = 1;
+    for (let i = startIndex; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--agent" && i + 1 < rest.length) agentId = rest[++i];
+      else if (arg === "--reason" && i + 1 < rest.length) reason = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown pair ${action} option "${arg}"`);
+    }
+    if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+    const resolvedPairId = pairId && !pairId.startsWith("--") ? pairId : await detectActivePairId(agentId);
+    if (!resolvedPairId) throw new Error(`Usage: agent-relay pair ${action} PAIR_ID --agent AGENT_ID`);
+    const endpoint = action === "disconnect" ? "hangup" : action;
+    const pair = await apiRequest("POST", `/api/pairs/${encodeURIComponent(resolvedPairId)}/${endpoint}`, { agentId, reason });
+    if (json) console.log(JSON.stringify(pair, null, 2));
+    else console.log(`Pair ${resolvedPairId}: ${(pair as any).status}`);
+    return;
+  }
+
+  if (action === "send") {
+    const pairId = rest[0];
+    if (!pairId || pairId.startsWith("--")) throw new Error("Usage: agent-relay pair send PAIR_ID --from AGENT_ID --body TEXT");
+    let from = await detectAgentId();
+    let body: string | undefined;
+    let subject: string | undefined;
+    let json = false;
+    for (let i = 1; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--from" && i + 1 < rest.length) from = rest[++i];
+      else if (arg === "--body" && i + 1 < rest.length) body = rest[++i];
+      else if (arg === "--subject" && i + 1 < rest.length) subject = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown pair send option "${arg}"`);
+    }
+    if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+    if (!body) throw new Error("--body TEXT required");
+    const result = await apiRequest("POST", `/api/pairs/${encodeURIComponent(pairId)}/messages`, { from, body, subject });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Pair message sent: ${(result as any).message.id}`);
+    return;
+  }
+}
+
+async function handleStatusCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown status option "${arg}"`);
+  }
+
+  const [stats, health, pairs, agent] = await Promise.all([
+    apiRequest("GET", "/api/stats"),
+    apiRequest("GET", "/api/health"),
+    agentId ? apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}`) : Promise.resolve([]),
+    agentId ? apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`).catch(() => null) : Promise.resolve(null),
+  ]);
+  const payload = { agent, stats, health, pairs };
+  if (json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(formatStatus(payload));
+}
+
+async function handleLabelCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let label: string | null | undefined;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--clear") label = null;
+    else if (arg === "--json") json = true;
+    else if (label === undefined) label = args.slice(i).join(" ");
+  }
+  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+  if (label === undefined) {
+    const agent = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { label?: string };
+    console.log(agent.label ?? "(no label)");
+    return;
+  }
+  const result = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/label`, { label });
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else console.log(label ? `Label set: ${label}` : "Label cleared.");
+}
+
+async function handleTagsCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let json = false;
+  let listOnly = false;
+  let add: string[] = [];
+  let remove: string[] = [];
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--json") json = true;
+    else if (arg === "--list") listOnly = true;
+    else if (arg === "--add" && i + 1 < args.length) add = add.concat(splitTagArgs(args[++i]!));
+    else if (arg === "--remove" && i + 1 < args.length) remove = remove.concat(splitTagArgs(args[++i]!));
+    else positional.push(...splitTagArgs(arg!));
+  }
+  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+  const current = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { tags?: string[] };
+  if (listOnly || (positional.length === 0 && add.length === 0 && remove.length === 0)) {
+    console.log((current.tags ?? []).join(", ") || "(no tags)");
+    return;
+  }
+  const next = positional.length > 0
+    ? uniqueStrings(positional)
+    : uniqueStrings([...(current.tags ?? []), ...add]).filter((tag) => !remove.includes(tag));
+  const updated = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/tags`, { tags: next });
+  if (json) console.log(JSON.stringify(updated, null, 2));
+  else console.log(`Tags: ${next.join(", ") || "(none)"}`);
+}
+
+async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const headers: Record<string, string> = {};
+  const token = process.env.AGENT_RELAY_TOKEN;
+  if (token) headers["X-Agent-Relay-Token"] = token;
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+  const response = await fetch(new URL(path, baseUrl), {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const message = payload && typeof payload === "object" && "error" in payload ? String((payload as any).error) : text;
+    throw new Error(`agent-relay ${method} ${path} failed (${response.status}): ${message}`);
+  }
+  return payload;
+}
+
+function splitTagArgs(raw: string): string[] {
+  return raw.split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+async function detectActivePairId(agentId: string): Promise<string | undefined> {
+  const pairs = await apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}&status=active`) as Array<{ id?: string }>;
+  return Array.isArray(pairs) && typeof pairs[0]?.id === "string" ? pairs[0].id : undefined;
+}
+
+async function detectAgentId(): Promise<string | undefined> {
+  const explicit = process.env.AGENT_RELAY_ID;
+  if (explicit) return explicit;
+
+  const cwd = process.cwd();
+  const stateCandidates = [
+    process.env.AGENT_RELAY_CODEX_STATE_PATH,
+    resolve(cwd, "codex/runtime/live-state.json"),
+    ...collectCodexStateFiles(),
+  ].filter((path): path is string => Boolean(path));
+
+  const codexMatch = newestCodexAgentId(stateCandidates, cwd);
+  if (codexMatch) return codexMatch;
+
+  const claudeMatch = newestClaudeAgentId();
+  if (claudeMatch) return claudeMatch;
+
+  try {
+    const agents = await apiRequest("GET", "/api/agents") as Array<{ id?: string; status?: string; ready?: boolean; meta?: { cwd?: unknown }; lastSeen?: number }>;
+    const cwdAgents = agents
+      .filter((agent) => agent.status !== "offline" && agent.ready !== false && agent.meta?.cwd === cwd && typeof agent.id === "string")
+      .sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
+    return cwdAgents[0]?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+function newestCodexAgentId(paths: string[], cwd: string): string | undefined {
+  const states = paths
+    .map((path) => readCodexState(path))
+    .filter((state): state is { agentId: string; cwd?: string; updatedAtMs: number } => Boolean(state))
+    .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+  return states.find((state) => state.cwd === cwd)?.agentId ?? states[0]?.agentId;
+}
+
+function readCodexState(path: string): { agentId: string; cwd?: string; updatedAtMs: number } | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { agentId?: unknown; cwd?: unknown; updatedAt?: unknown };
+    if (typeof parsed.agentId !== "string" || !parsed.agentId) return null;
+    const stat = statSync(path);
+    const updatedAt = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : Number.NaN;
+    return {
+      agentId: parsed.agentId,
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined,
+      updatedAtMs: Number.isFinite(updatedAt) ? updatedAt : stat.mtimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function collectCodexStateFiles(): string[] {
+  const roots = [
+    join(process.env.HOME || "", ".agent-relay", "codex", "runtime"),
+    resolve(process.cwd(), "codex", "runtime"),
+  ].filter((root) => root && existsSync(root));
+  const files: string[] = [];
+  for (const root of roots) collectFiles(root, "live-state.json", files, 4);
+  return files;
+}
+
+function collectFiles(dir: string, name: string, output: string[], depth: number): void {
+  if (depth < 0) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    try {
+      const stat = statSync(path);
+      if (stat.isDirectory()) collectFiles(path, name, output, depth - 1);
+      else if (entry === name) output.push(path);
+    } catch {
+      // Ignore state files that disappear while scanning.
+    }
+  }
+}
+
+function newestClaudeAgentId(): string | undefined {
+  if (!existsSync("/tmp")) return undefined;
+  try {
+    const candidates = readdirSync("/tmp")
+      .filter((entry) => entry.startsWith("agent-relay-instance-") && entry.endsWith(".state"))
+      .map((entry) => join("/tmp", entry))
+      .map((path) => ({ path, mtimeMs: statSync(path).mtimeMs }))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const candidate of candidates) {
+      const id = readFileSync(candidate.path, "utf8").split(/\r?\n/)[0]?.trim();
+      if (id) return id;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function formatPairs(pairs: any[]): string {
+  if (!pairs.length) return "No pair sessions.";
+  return pairs
+    .map((pair) => `${pair.id}  ${pair.status}  ${pair.requesterId} <-> ${pair.targetId}${pair.objective ? `  ${pair.objective}` : ""}`)
+    .join("\n");
+}
+
+function formatStatus(payload: any): string {
+  const agent = payload.agent;
+  const stats = payload.stats ?? {};
+  const health = payload.health ?? {};
+  const pairs = Array.isArray(payload.pairs) ? payload.pairs : [];
+  const activePair = pairs.find((pair: any) => pair.status === "active") ?? pairs.find((pair: any) => pair.status === "pending");
+  return [
+    `Relay: ${health.status ?? "unknown"}  version=${stats.version ?? "unknown"}`,
+    `Agents: ${stats.online ?? "?"}/${stats.agents ?? "?"} online  Messages: ${stats.messages ?? "?"}  Tasks: ${stats.openTasks ?? "?"}/${stats.tasks ?? "?"} open`,
+    agent
+      ? `Current: ${agent.id}  status=${agent.status}  ready=${agent.ready ? "yes" : "no"}  label=${agent.label ?? "(none)"}  tags=${(agent.tags ?? []).join(", ") || "(none)"}`
+      : "Current: unknown",
+    activePair
+      ? `Pair: ${activePair.id}  ${activePair.status}  ${activePair.requesterId} <-> ${activePair.targetId}`
+      : "Pair: none active",
+  ].join("\n");
+}
+
 async function confirm(message: string): Promise<boolean> {
   if (!input.isTTY) return false;
   const rl = createInterface({ input, output });

package/src/config.ts

@@ -20,6 +20,7 @@ function envPositiveInt(name: string, fallback: number): number {
 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
+export const CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_CLAIM_LEASE_MS", 1_800_000); // 30min claim lease
 
 // Max body size for any POST/PATCH request (64 KiB).
 export const MAX_BODY_BYTES = 64 * 1024;