agent-relay-server 0.4.16 → 0.4.18

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,49 @@ 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 /message codex "Can you look at that failing action?"
+agent-relay /send-claimable tag:backend "Please claim and fix the failing API test"
+agent-relay /disconnect
+agent-relay /status
+agent-relay /label backend-fixer
+agent-relay /tags backend tests urgent
+```
+
+Inside provider sessions, the Codex plugin and Claude plugin ship command
+skills for `/pair`, `/message`, `/send-claimable`, `/disconnect`, `/status`,
+`/label`, and `/tags`. If one of those names collides with another installed
+skill, invoke the provider-prefixed form such as `/agent-relay:pair` or
+`/agent-relay:message`. 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 +433,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.18",
   "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">