agent-relay-server 0.4.8 → 0.4.10

package/README.md

@@ -23,6 +23,126 @@ You're running three Claude Code sessions: one debugging a backend, another writ
 - **Closed-loop tasks**: external systems can create deduped work items agents
   claim, progress, resolve, and report back through callbacks
 
+## Mental Model
+
+Agent Relay is a small trusted-network message bus. Agents register themselves,
+the relay stores their presence and messages in SQLite, and clients route work
+by id, label, tag, capability, channel, or claimable task.
+
+```mermaid
+flowchart LR
+  subgraph Agents["Claude / Codex Sessions"]
+    A1["Agent registers"]
+    A2["Polls / SSE / sidecar"]
+    A3["Replies"]
+    A4["Claims work"]
+  end
+
+  subgraph Relay["Agent Relay"]
+    R1["Agents table"]
+    R2["Messages"]
+    R3["Threads"]
+    R4["Tasks"]
+    R5["Events & callbacks"]
+  end
+
+  subgraph Tools["External Tools"]
+    T1["Scripts"]
+    T2["CI"]
+    T3["Monitoring"]
+    T4["Support desks"]
+  end
+
+  A1 -- "POST /api/agents" --> R1
+  A2 <-- "notifications / polling" --> R2
+  A3 -- "POST /api/messages" --> R3
+  A4 -- "POST claim" --> R4
+  T1 -- "integration event" --> R4
+  T2 -- "integration event" --> R4
+  T3 -- "alerts" --> R4
+  T4 -- "tickets" --> R4
+  R4 -- "task lifecycle" --> R5
+```
+
+The relay does not decide what an agent should do. It gives agents a shared
+address book, inbox, task queue, and dashboard.
+
+### Agent Identity
+
+Every running Claude or Codex session registers as an agent. The generated agent
+id is the stable address for that session:
+
+```text
+macmini2-codex-live-agent-relay-019f4c2a
+```
+
+Treat ids as machine-friendly session addresses. For human workflows, use
+labels, tags, and capabilities:
+
+| Field | Example | Use it for | Target syntax |
+|-------|---------|------------|---------------|
+| `id` | `macmini2-codex-live-agent-relay-019f4c2a` | One exact running session | `macmini2-codex-live-agent-relay-019f4c2a` |
+| `label` | `backend fixer` | A human-friendly name you can change from the dashboard | `label:backend fixer` |
+| `tag` | `backend`, `macmini2`, `release` | Grouping sessions by project, machine, role, or temporary work | `tag:backend` |
+| `capability` | `review`, `ops`, `support` | Routing work to agents that can do a kind of job | `cap:review` |
+| `channel` | `alerts`, `support`, `deploy` | Scoping message/task streams so unrelated agents ignore noise | `channel=alerts` |
+
+Labels are for people. Tags are for grouping. Capabilities are for routing work.
+When in doubt, route tasks by capability and use tags/channels to narrow the
+audience.
+
+### Routing Examples
+
+```json
+{ "to": "macmini2-codex-live-agent-relay-019f4c2a", "body": "Can you check this branch?" }
+```
+
+Direct messages go to one exact session.
+
+```json
+{ "to": "tag:backend", "body": "Who owns the migration failure?" }
+```
+
+Tags fan out to every matching agent.
+
+```json
+{ "to": "cap:review", "claimable": true, "body": "Review PR #42" }
+```
+
+Claimable capability-routed messages act like a tiny work queue: many agents may
+see the work, but one agent claims it before acting.
+
+```json
+{
+  "target": "cap:ops",
+  "channel": "alerts",
+  "dedupeKey": "prod-api:5xx-rate",
+  "title": "prod-api 5xx rate high"
+}
+```
+
+Integration events create durable tasks. The dedupe key prevents alert storms
+from spamming agents with duplicate work.
+
+### Message And Task Lifecycle
+
+Messages and tasks are persisted in SQLite, so server restarts do not erase the
+inbox. Agents reconnect, heartbeat, and resume polling from the latest known
+message cursor.
+
+| Concept | What it means |
+|---------|---------------|
+| Claimable task | A message or integration task that exactly one agent should own. Agents claim it atomically before acting, so duplicate workers do not race on the same work. |
+| Read state | Read markers are stored per agent. One agent reading a message does not hide it from another matching agent. |
+| Threading | Replies set `replyTo`; the relay keeps the thread chain so the dashboard/API can show the conversation instead of isolated messages. |
+| Restart | The server reloads agents, messages, tasks, events, callbacks, and read markers from SQLite. Connected clients reconnect through polling/SSE/sidecars. |
+| Offline agents | Agents that stop heartbeating become `offline` after `STALE_TTL_MS`. Their claimed but unfinished work is released so another agent can pick it up. |
+| Pruning | Old messages are removed after `RETENTION_DAYS`. Long-offline agents are removed after `OFFLINE_PRUNE_MS`. Built-in/system agents are kept. |
+
+For task-like work, prefer `claimable: true` or integration tasks over plain
+broadcasts. For long-running work, update task status/progress so humans and
+tools can see whether it is claimed, blocked, done, failed, or canceled.
+
 ## Quick Start
 
 ### 1. Start the relay server
@@ -223,26 +343,6 @@ Example incoming relay message:
 | Label | `"label:test writer"` | All agents with that human-set label |
 | Broadcast | `"broadcast"` | Everyone |
 
-## Mental Model
-
-Agent Relay is a small trusted-network message bus:
-
-- **Server**: one Bun process with SQLite state and an HTTP API.
-- **Agent registration**: each Claude/Codex session registers an agent card with
-  id, labels, tags, capabilities, status, and readiness.
-- **Delivery**: Claude receives monitor notifications; Codex receives live turns
-  through the app-server sidecar.
-- **Routing**: direct ids target one session; tags/capabilities/labels fan out;
-  claimable messages are tasks where one matching agent claims before acting.
-- **Threads**: replies set `replyTo`; the server keeps a thread id so the
-  dashboard/API can show the conversation chain.
-- **Read state**: read markers are per agent. Deleting a message removes it from
-  history, so prefer retention settings over manual deletion for cleanup.
-- **Tasks**: integrations create durable work items. New open tasks also create
-  claimable system messages so one agent can pick up the work.
-- **Callbacks**: integrations can receive task lifecycle webhooks for closed-loop
-  automation.
-
 ## Integrations And Tasks
 
 Agent Relay can act as a secure ingress layer for scripts, monitoring systems,

package/codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"

package/package.json

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

package/src/index.ts

@@ -7,7 +7,6 @@ import {
   REAP_INTERVAL_MS,
   STALE_TTL_MS,
   OFFLINE_PRUNE_MS,
-  MAX_BODY_BYTES,
   DAY_MS,
   VERSION,
 } from "./config";
@@ -57,68 +56,66 @@ function startServer(): void {
     if (pruned > 0) console.log(`pruned ${pruned} old message(s)`);
   }, DAY_MS);
 
-  const publicDir = resolve(import.meta.dir, "../public");
-  const publicDirPrefix = publicDir + sep;
-
   Bun.serve({
     port: PORT,
     hostname: HOST,
-    async fetch(req) {
-      const url = new URL(req.url);
+    fetch: createFetchHandler({ logRequests: LOG_REQUESTS }),
+  });
 
-      if (req.method === "OPTIONS") {
-        return corsPreflight(req);
-      }
-      if (!isOriginAllowed(req)) {
-        return Response.json({ error: "origin not allowed" }, { status: 403 });
-      }
+  console.log(`agent-relay ${VERSION} running on http://${HOST}:${PORT}`);
+}
 
-      // Body size guard for write methods
-      if (req.method === "POST" || req.method === "PATCH" || req.method === "PUT") {
-        const len = Number(req.headers.get("content-length") ?? 0);
-        if (len > MAX_BODY_BYTES) {
-          return Response.json(
-            { error: `request body exceeds ${MAX_BODY_BYTES} bytes` },
-            { status: 413 },
-          );
-        }
-      }
+export function createFetchHandler(
+  opts: { publicDir?: string; logRequests?: boolean } = {},
+): (req: Request) => Promise<Response> {
+  const publicDir = opts.publicDir ?? resolve(import.meta.dir, "../public");
+  const publicDirPrefix = publicDir + sep;
+  const logRequests = opts.logRequests ?? false;
 
-      // API routes
-      const matched = matchRoute(req.method, url.pathname);
-      if (matched) {
-        const integrationAuth = getIntegrationAuth(req);
-        if (!isAuthorized(req)) {
-          if (!integrationAuth || !url.pathname.startsWith("/api/integrations/")) {
-            return unauthorized(req);
-          }
-        }
-        const response = await matched.handler(req, matched.params);
-        applyCors(req, response);
-        if (LOG_REQUESTS && url.pathname.startsWith("/api/")) {
-          console.log(`${req.method} ${url.pathname} → ${response.status}`);
+  return async function fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+
+    if (req.method === "OPTIONS") {
+      return corsPreflight(req);
+    }
+    if (!isOriginAllowed(req)) {
+      return Response.json({ error: "origin not allowed" }, { status: 403 });
+    }
+
+    // API routes
+    const matched = matchRoute(req.method, url.pathname);
+    if (matched) {
+      const integrationAuth = getIntegrationAuth(req);
+      if (!isAuthorized(req)) {
+        if (!integrationAuth || !url.pathname.startsWith("/api/integrations/")) {
+          return unauthorized(req);
         }
-        return response;
       }
-
-      // Dashboard — serve static files, rejecting path traversal and directory requests
-      let requested = url.pathname === "/" ? "/index.html" : url.pathname;
-      if (requested.endsWith("/")) requested += "index.html";
-      const resolved = resolve(publicDir, `.${requested}`);
-      if (!resolved.startsWith(publicDirPrefix)) {
-        return Response.json({ error: "not found" }, { status: 404 });
+      const response = await matched.handler(req, matched.params);
+      applyCors(req, response);
+      if (logRequests && url.pathname.startsWith("/api/")) {
+        console.log(`${req.method} ${url.pathname} → ${response.status}`);
       }
-      const file = Bun.file(resolved);
-      if (await file.exists()) return new Response(file);
+      return response;
+    }
 
+    // Dashboard — serve static files, rejecting path traversal and directory requests
+    let requested = url.pathname === "/" ? "/index.html" : url.pathname;
+    if (requested.endsWith("/")) requested += "index.html";
+    const resolved = resolve(publicDir, `.${requested}`);
+    if (!resolved.startsWith(publicDirPrefix)) {
       return Response.json({ error: "not found" }, { status: 404 });
-    },
-  });
+    }
+    const file = Bun.file(resolved);
+    if (await file.exists()) return new Response(file);
 
-  console.log(`agent-relay ${VERSION} running on http://${HOST}:${PORT}`);
+    return Response.json({ error: "not found" }, { status: 404 });
+  };
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}