agent-relay-server 0.4.15 → 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
 
@@ -111,7 +135,7 @@ The plugin or sidecar registers the agent and injects messaging context:
 
 ```
 Agent Relay active. Your agent ID: macmini2-cli-myproject-a1b2c3
-Relay URL: http://localhost:4850 | Server: 0.4.15 | Plugin: 0.4.15
+Relay URL: http://localhost:4850 | Server: 0.4.16 | Plugin: 0.4.16
 Approval mode: open
 ```
 
@@ -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.15",
+  "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

@@ -3,6 +3,7 @@
   const DEFAULT_COMPOSE = { from: "", to: "", body: "", channel: "", subject: "", claimable: false };
   const CLOSED_TASK_STATUSES = new Set(["done", "failed", "canceled"]);
   const STATUS_SORT_ORDER = { online: 0, idle: 1, busy: 2, offline: 3 };
+  const LIVE_REFRESH_MS = 5_000;
 
   function loadPref(key, fallback) {
     try {
@@ -32,6 +33,8 @@
       tasks: [],
       taskEvents: [],
       stats: {},
+      health: null,
+      now: Date.now(),
       authToken: loadPref("authToken", ""),
 
       selectedAgent: "",
@@ -57,12 +60,19 @@
 
       chartInstances: {},
       _es: null,
-      _statsTimer: null,
+      _clockTimer: null,
+      _refreshTimer: null,
+      _refreshInFlight: false,
     };
   }
 
   function watchPersistedPrefs(vm) {
     vm.$watch("showOffline", (value) => vm.save("showOffline", value));
+    vm.$watch("autoRefresh", (value) => {
+      vm.save("autoRefresh", value);
+      if (value) vm.startAutoRefresh();
+      else vm.stopAutoRefresh();
+    });
     vm.$watch("agentSort", (value) => vm.save("agentSort", value));
     vm.$watch("agentSortDir", (value) => vm.save("agentSortDir", value));
     vm.$watch("agentStatusFilter", (value) => vm.save("agentStatusFilter", value));
@@ -95,12 +105,31 @@
     else vm.tasks.unshift(task);
   }
 
+  function syncAgentStats(vm) {
+    vm.stats.agents = vm.agents.length;
+    vm.stats.online = vm.agents.filter((agent) => agent.status !== "offline").length;
+  }
+
+  function syncMessageStats(vm, msg) {
+    vm.stats.messages = (vm.stats.messages ?? 0) + 1;
+    const createdAt = new Date(msg.createdAt || Date.now()).getTime();
+    if (Number.isFinite(createdAt) && Date.now() - createdAt <= 86_400_000) {
+      vm.stats.messagesLast24h = (vm.stats.messagesLast24h ?? 0) + 1;
+    }
+  }
+
+  function refreshChartsIfVisible(vm) {
+    if (vm.view !== "analytics") return;
+    vm.$nextTick(() => vm.renderCharts());
+  }
+
   function createLifecycleMethods() {
     return {
       async init() {
         await this.refresh();
         this.connectSSE();
-        this._statsTimer = setInterval(() => this.fetchStats(), 30_000);
+        this.startClock();
+        this.startAutoRefresh();
         watchPersistedPrefs(this);
       },
 
@@ -113,6 +142,25 @@
         if (view === "messages") this.fetchMessages();
         if (view === "tasks") this.fetchTasks();
       },
+
+      startClock() {
+        if (this._clockTimer) return;
+        this._clockTimer = setInterval(() => {
+          this.now = Date.now();
+        }, 1_000);
+      },
+
+      startAutoRefresh() {
+        this.stopAutoRefresh();
+        if (!this.autoRefresh) return;
+        this._refreshTimer = setInterval(() => this.refreshLiveData(), LIVE_REFRESH_MS);
+      },
+
+      stopAutoRefresh() {
+        if (!this._refreshTimer) return;
+        clearInterval(this._refreshTimer);
+        this._refreshTimer = null;
+      },
     };
   }
 
@@ -139,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);
   }
@@ -156,22 +205,37 @@
 
     vm.messages.push(msg);
     if (vm.messages.length > 200) vm.messages.shift();
-    vm.stats.messages = (vm.stats.messages ?? 0) + 1;
+    syncMessageStats(vm, msg);
+    refreshChartsIfVisible(vm);
   }
 
   function handleAgentStatus(vm, agent) {
     upsertById(vm.agents, agent);
     vm.agentsById[agent.id] = agent;
+    syncAgentStats(vm);
+    refreshChartsIfVisible(vm);
   }
 
   function handleAgentRemoved(vm, data) {
     vm.agents = vm.agents.filter((agent) => agent.id !== data.id);
     delete vm.agentsById[data.id];
+    syncAgentStats(vm);
+    refreshChartsIfVisible(vm);
   }
 
   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) {
@@ -213,7 +277,18 @@
       },
 
       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() {
+        if (this._refreshInFlight || this.authNeeded) return;
+        this._refreshInFlight = true;
+        try {
+          await this.refresh();
+          refreshChartsIfVisible(this);
+        } finally {
+          this._refreshInFlight = false;
+        }
       },
 
       async fetchStats() {
@@ -222,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");
@@ -260,6 +341,7 @@
       uniqueLabels: { get: getUniqueLabels },
       uniqueCaps: { get: getUniqueCaps },
       uniqueTags: { get: getUniqueTags },
+      healthIssues: { get: getHealthIssues },
     };
   }
 
@@ -336,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":
@@ -359,6 +445,7 @@
       agentStatusTitle,
       timeAgo,
       fmtTime,
+      healthAlertClass,
     };
   }
 
@@ -392,7 +479,7 @@
     const lastSeenMs = new Date(agent.lastSeen).getTime();
     if (!Number.isFinite(lastSeenMs)) return "Trying to reconnect...";
 
-    const ageSec = Math.max(0, (Date.now() - lastSeenMs) / 1000);
+    const ageSec = Math.max(0, ((this.now || Date.now()) - lastSeenMs) / 1000);
     return ageSec <= 45 ? "Starting up..." : "Trying to reconnect...";
   }
 
@@ -401,7 +488,7 @@
     const ts = new Date(iso).getTime();
     if (!Number.isFinite(ts)) return "";
 
-    const diff = Math.max(0, (Date.now() - ts) / 1000);
+    const diff = Math.max(0, ((this.now || 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";
@@ -413,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

@@ -109,6 +109,12 @@
           <input type="checkbox" class="form-check-input" x-model="showOffline">
           <span class="form-check-label small">Show offline</span>
         </label>
+      </div>
+      <div class="d-flex align-items-center gap-2 mb-2">
+        <label class="form-check form-switch mb-0">
+          <input type="checkbox" class="form-check-input" x-model="autoRefresh">
+          <span class="form-check-label small">Auto refresh</span>
+        </label>
       </div>
 	    <div class="text-muted small" x-show="stats.version" x-text="'v' + stats.version"></div>
 	  </div>
@@ -201,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">
@@ -389,7 +414,7 @@
           <div class="ms-auto d-flex gap-2 align-items-center flex-wrap">
             <select class="form-select form-select-sm" style="width: auto; min-width: 160px" x-model="selectedAgent" @change="fetchMessages()">
               <option value="">All agents</option>
-              <template x-for="a in agents" :key="a.id">
+              <template x-for="a in composeAgents" :key="a.id">
                 <option :value="a.id" x-text="displayName(a) + ' [' + a.id.slice(-6) + ']'"></option>
               </template>
             </select>