agent-relay-server 0.8.0 → 0.9.0

package/package.json

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

package/public/index.html

@@ -305,7 +305,7 @@
   </div>
 
   <!-- Main content -->
-  <main class="ar-main flex-grow-1 overflow-auto">
+  <main class="ar-main flex-grow-1" style="overflow-y:scroll;overflow-x:hidden">
     <div class="container-xl py-3">
       <template x-if="authNeeded">
         <div class="alert alert-warning d-flex align-items-center gap-2 mb-3">

package/src/config.ts

@@ -22,6 +22,7 @@ export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min wit
 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
+export const POOL_CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_POOL_CLAIM_LEASE_MS", STALE_TTL_MS * 3); // pool binding lease
 
 // Max body size for any POST/PATCH request (64 KiB).
 export const MAX_BODY_BYTES = 64 * 1024;

package/src/db.ts

@@ -41,7 +41,7 @@ import type {
   InboxThreadState,
   TaskStatusInput,
 } from "./types";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS } from "./config";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS } from "./config";
 
 let db: Database;
 
@@ -307,6 +307,14 @@ export function initDb(path: string = "agent-relay.db"): Database {
   db.run("CREATE INDEX IF NOT EXISTS idx_channel_bindings_channel ON channel_bindings(channel_id, priority)");
   db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_bindings_target ON channel_bindings(channel_id, conversation_key, target_type, target_id)");
 
+  const bindingColNames = (db.prepare("PRAGMA table_info(channel_bindings)").all() as any[]).map((c: any) => c.name);
+  if (!bindingColNames.includes("pool_selector")) {
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_selector TEXT");
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_agent_id TEXT");
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_agent_epoch INTEGER");
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_claim_expires_at INTEGER");
+  }
+
   if (!colNames.includes("kind")) {
     db.run("ALTER TABLE messages ADD COLUMN kind TEXT NOT NULL DEFAULT 'chat'");
   }
@@ -608,7 +616,7 @@ function rowToChannelBinding(row: any): ChannelBinding {
   const target = row.target_type === "broadcast"
     ? { type: "broadcast" } as ChannelRouteTarget
     : { type: row.target_type, id: row.target_id } as ChannelRouteTarget;
-  return {
+  const binding: ChannelBinding = {
     id: row.id,
     channelId: row.channel_id,
     conversationId: row.conversation_id ?? undefined,
@@ -618,6 +626,13 @@ function rowToChannelBinding(row: any): ChannelBinding {
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
+  if (row.pool_selector) {
+    binding.poolSelector = row.pool_selector;
+    binding.poolAgentId = row.pool_agent_id ?? undefined;
+    binding.poolAgentEpoch = row.pool_agent_epoch ?? undefined;
+    binding.poolClaimExpiresAt = row.pool_claim_expires_at ?? undefined;
+  }
+  return binding;
 }
 
 function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
@@ -627,6 +642,7 @@ function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
   if (target.type === "capability") return `cap:${target.id}`;
   if (target.type === "broadcast") return "broadcast";
   if (target.type === "orchestrator") return `orchestrator:${target.id}`;
+  if (target.type === "pool") return `pool:${target.id}`;
   return "";
 }
 
@@ -641,6 +657,7 @@ function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
     const agent = getAgent(target.id);
     return agent ? [agent] : [];
   }
+  if (target.type === "pool") return poolSelectorMatches(target.id, candidates);
   if (target.type === "label") return candidates.filter((agent) => agent.label === target.id);
   if (target.type === "tag") return candidates.filter((agent) => agent.tags.includes(target.id));
   if (target.type === "capability") return candidates.filter((agent) => agent.capabilities.includes(target.id));
@@ -648,6 +665,14 @@ function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
   return [];
 }
 
+function poolSelectorMatches(selector: string, candidates: AgentCard[]): AgentCard[] {
+  if (selector.startsWith("label:")) return candidates.filter((a) => a.label === selector.slice("label:".length));
+  if (selector.startsWith("tag:")) return candidates.filter((a) => a.tags.includes(selector.slice("tag:".length)));
+  if (selector.startsWith("cap:")) return candidates.filter((a) => a.capabilities.includes(selector.slice("cap:".length)));
+  const agent = getAgent(selector);
+  return agent ? [agent] : [];
+}
+
 function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
   return {
     id: agent.id,
@@ -675,6 +700,25 @@ function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()):
   const matches = channelTargetMatches(target);
   const snapshots = matches.map(channelTargetMatchSnapshot);
 
+  if (target.type === "pool") {
+    const healthyEligibles = matches.filter((a) => isHealthyChannelTarget(a, now));
+    if (!binding.poolAgentId) {
+      if (matches.length === 0) return { status: "error", detail: `Pool ${targetLabel}: no eligible agents`, target, matches: [] };
+      return { status: "error", detail: `Pool ${targetLabel}: ${healthyEligibles.length} eligible but slot unclaimed`, target, matches: snapshots };
+    }
+    const holder = getAgent(binding.poolAgentId);
+    if (!holder || holder.status === "offline") {
+      return { status: "error", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} is offline`, target, matches: snapshots };
+    }
+    if (!holder.ready) {
+      return { status: "warning", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} online but not ready`, target, matches: snapshots };
+    }
+    if (binding.poolAgentEpoch !== undefined && holder.epoch !== binding.poolAgentEpoch) {
+      return { status: "warning", detail: `Pool ${targetLabel}: holder epoch changed (stale claim)`, target, matches: snapshots };
+    }
+    return { status: "ok", detail: `Pool ${targetLabel}: claimed by ${binding.poolAgentId}`, target, matches: snapshots };
+  }
+
   if (target.type === "agent" || target.type === "orchestrator") {
     const agent = matches[0];
     if (!agent) {
@@ -729,6 +773,10 @@ function rowToChannelSummary(row: any): ChannelSummary {
     priority: row.binding_priority,
     created_at: row.binding_created_at,
     updated_at: row.binding_updated_at,
+    pool_selector: row.binding_pool_selector,
+    pool_agent_id: row.binding_pool_agent_id,
+    pool_agent_epoch: row.binding_pool_agent_epoch,
+    pool_claim_expires_at: row.binding_pool_claim_expires_at,
   }) : undefined;
 
   return {
@@ -817,6 +865,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
 
   const agent = getAgent(input.id)!;
   if (agent.kind === "channel") upsertChannelForAgent(agent);
+  evaluatePoolBindings();
   return agent;
 }
 
@@ -949,6 +998,7 @@ function channelDirectionForAgent(agent: AgentCard): ChannelSummary["direction"]
 
 function routeTargetFromLegacyTarget(target: string | undefined): ChannelRouteTarget | undefined {
   if (!target) return undefined;
+  if (target.startsWith("pool:")) return { type: "pool", id: target.slice("pool:".length) };
   if (target.startsWith("label:")) return { type: "label", id: target.slice("label:".length) };
   if (target.startsWith("tag:")) return { type: "tag", id: target.slice("tag:".length) };
   if (target.startsWith("cap:")) return { type: "capability", id: target.slice("cap:".length) };
@@ -1002,7 +1052,7 @@ function upsertChannelForAgent(agent: AgentCard): void {
     upsertChannelBinding({
       channelId,
       target: defaultTarget,
-      mode: defaultTarget.type === "agent" ? "exclusive" : defaultTarget.type === "broadcast" ? "broadcast" : "claimable",
+      mode: (defaultTarget.type === "agent" || defaultTarget.type === "pool") ? "exclusive" : defaultTarget.type === "broadcast" ? "broadcast" : "claimable",
     });
   }
 }
@@ -1024,7 +1074,11 @@ export function listChannels(): ChannelSummary[] {
       b.mode AS binding_mode,
       b.priority AS binding_priority,
       b.created_at AS binding_created_at,
-      b.updated_at AS binding_updated_at
+      b.updated_at AS binding_updated_at,
+      b.pool_selector AS binding_pool_selector,
+      b.pool_agent_id AS binding_pool_agent_id,
+      b.pool_agent_epoch AS binding_pool_agent_epoch,
+      b.pool_claim_expires_at AS binding_pool_claim_expires_at
     FROM channels c
     JOIN agents a ON a.id = c.agent_id
     LEFT JOIN channel_bindings b ON b.channel_id = c.id AND b.conversation_key = ''
@@ -1057,17 +1111,20 @@ export function upsertChannelBinding(input: {
   const targetKey = input.target.type === "broadcast" ? "broadcast" : `${input.target.type}:${targetId}`;
   const id = `${input.channelId}:${conversationKey || "default"}:${targetKey}`;
   const mode = input.mode ?? "exclusive";
+  const isPool = input.target.type === "pool";
+  const poolSelector = isPool ? targetId : null;
   const now = Date.now();
   db.transaction(() => {
     if (mode === "exclusive") {
       db.prepare("DELETE FROM channel_bindings WHERE channel_id = ? AND conversation_key = ?").run(input.channelId, conversationKey);
     }
     db.prepare(`
-      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
-      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $now, $now)
+      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, pool_selector, created_at, updated_at)
+      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $poolSelector, $now, $now)
       ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
         mode = $mode,
         priority = $priority,
+        pool_selector = $poolSelector,
         updated_at = $now
     `).run({
       $id: id,
@@ -1078,6 +1135,7 @@ export function upsertChannelBinding(input: {
       $targetId: targetId,
       $mode: mode,
       $priority: input.priority ?? 0,
+      $poolSelector: poolSelector,
       $now: now,
     });
   })();
@@ -1086,6 +1144,67 @@ export function upsertChannelBinding(input: {
   return rowToChannelBinding(row);
 }
 
+export interface PoolBindingChange {
+  bindingId: string;
+  channelId: string;
+  previousAgentId: string | null;
+  newAgentId: string | null;
+}
+
+export function evaluatePoolBindings(now: number = Date.now()): PoolBindingChange[] {
+  const rows = db.prepare("SELECT * FROM channel_bindings WHERE target_type = 'pool'").all() as any[];
+  const changes: PoolBindingChange[] = [];
+
+  for (const row of rows) {
+    const bindingId = row.id as string;
+    const channelId = row.channel_id as string;
+    const selector = row.pool_selector ?? row.target_id;
+    const currentAgentId: string | null = row.pool_agent_id;
+    const currentEpoch: number | null = row.pool_agent_epoch;
+
+    let holderValid = false;
+    if (currentAgentId) {
+      const holder = getAgent(currentAgentId);
+      if (holder && holder.status !== "offline" && holder.ready && holder.lastSeen > now - STALE_TTL_MS) {
+        if (currentEpoch === null || holder.epoch === currentEpoch) {
+          db.prepare("UPDATE channel_bindings SET pool_claim_expires_at = ? WHERE id = ?")
+            .run(now + POOL_CLAIM_LEASE_MS, bindingId);
+          holderValid = true;
+        }
+      }
+    }
+
+    if (!holderValid && currentAgentId) {
+      db.prepare("UPDATE channel_bindings SET pool_agent_id = NULL, pool_agent_epoch = NULL, pool_claim_expires_at = NULL WHERE id = ?")
+        .run(bindingId);
+      changes.push({ bindingId, channelId, previousAgentId: currentAgentId, newAgentId: null });
+    }
+
+    if (!holderValid) {
+      const candidates = listAgents().filter((a) =>
+        a.id !== "user" && a.id !== "system" && a.kind !== "channel" && a.meta?.kind !== "channel"
+      );
+      const eligible = poolSelectorMatches(selector, candidates)
+        .filter((a) => a.status !== "offline" && a.ready && a.lastSeen > now - STALE_TTL_MS)
+        .sort((a, b) => b.lastSeen - a.lastSeen);
+
+      if (eligible.length > 0) {
+        const picked = eligible[0]!;
+        db.prepare("UPDATE channel_bindings SET pool_agent_id = ?, pool_agent_epoch = ?, pool_claim_expires_at = ? WHERE id = ?")
+          .run(picked.id, picked.epoch, now + POOL_CLAIM_LEASE_MS, bindingId);
+        const lastChange = changes[changes.length - 1];
+        if (lastChange && lastChange.bindingId === bindingId && lastChange.newAgentId === null) {
+          lastChange.newAgentId = picked.id;
+        } else {
+          changes.push({ bindingId, channelId, previousAgentId: currentAgentId, newAgentId: picked.id });
+        }
+      }
+    }
+  }
+
+  return changes;
+}
+
 export function resolveChannelRoutes(channelId: string, conversationId?: string): ChannelBinding[] {
   const rows = conversationId
     ? db.prepare(`
@@ -2503,6 +2622,7 @@ export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrat
     machine: input.hostname,
     capabilities: ["orchestrator", "spawn"],
     status: "online",
+    ready: true,
     meta: {
       orchestratorId: input.id,
       builtin: true,

package/src/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages, releaseExpiredClaims } from "./db";
+import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages, releaseExpiredClaims, evaluatePoolBindings } from "./db";
 import { matchRoute } from "./routes";
-import { emitAgentStatus, emitAgentRemoved, emitMessageClaimReleased, emitTaskChanged } from "./sse";
+import { emitAgentStatus, emitAgentRemoved, emitMessageClaimReleased, emitTaskChanged, emitPoolBindingChanged } from "./sse";
 import { resolve, sep } from "path";
 import {
   REAP_INTERVAL_MS,
@@ -57,6 +57,12 @@ function startServer(): void {
       console.log(`pruned ${pruned.length} offline agent(s)`);
       for (const id of pruned) emitAgentRemoved(id);
     }
+
+    const poolChanges = evaluatePoolBindings();
+    for (const change of poolChanges) {
+      console.log(`pool binding ${change.bindingId}: ${change.previousAgentId ?? "none"} → ${change.newAgentId ?? "none"}`);
+      emitPoolBindingChanged(change.bindingId, change.channelId, change.previousAgentId, change.newAgentId);
+    }
   }, REAP_INTERVAL_MS);
 
   // Daily message prune

package/src/routes.ts

@@ -60,6 +60,7 @@ import {
   orchestratorHeartbeat,
   updateManagedAgents,
   deleteOrchestrator,
+  evaluatePoolBindings,
   ValidationError,
 } from "./db";
 import {
@@ -90,6 +91,7 @@ import {
   emitChannelActivity,
   emitOrchestratorStatus,
   emitOrchestratorRemoved,
+  emitPoolBindingChanged,
 } from "./sse";
 
 type Handler = (
@@ -175,7 +177,7 @@ function parseQueryInt(
 
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "offline"] as const;
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
-const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator"] as const;
+const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator", "pool"] as const;
 const VALID_CHANNEL_BINDING_MODES = ["exclusive", "claimable", "broadcast"] as const;
 const VALID_AGENT_ACTIONS = ["restart", "shutdown"] as const;
 const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
@@ -404,6 +406,7 @@ function normalizeChannelBindingInput(body: unknown): {
 }
 
 function routeTargetFromAddress(target: string): ChannelRouteTarget {
+  if (target.startsWith("pool:")) return { type: "pool", id: target.slice("pool:".length) };
   if (target.startsWith("label:")) return { type: "label", id: target.slice("label:".length) };
   if (target.startsWith("tag:")) return { type: "tag", id: target.slice("tag:".length) };
   if (target.startsWith("cap:")) return { type: "capability", id: target.slice("cap:".length) };
@@ -412,8 +415,12 @@ function routeTargetFromAddress(target: string): ChannelRouteTarget {
   return { type: "agent", id: target };
 }
 
-function messageTargetForChannelTarget(target: ChannelRouteTarget): string {
+function messageTargetForChannelTarget(target: ChannelRouteTarget, binding?: ChannelBinding): string {
   if (target.type === "orchestrator") throw new ValidationError("orchestrator channel targets are not supported yet");
+  if (target.type === "pool") {
+    if (!binding?.poolAgentId) throw new ValidationError("pool slot is unclaimed — no eligible agent available");
+    return binding.poolAgentId;
+  }
   if (target.type === "label") return `label:${target.id}`;
   if (target.type === "tag") return `tag:${target.id}`;
   if (target.type === "capability") return `cap:${target.id}`;
@@ -1762,7 +1769,7 @@ const postChannelEvent: Handler = async (req, params) => {
     if (!bindings.length) return error("channel has no binding", 409);
     const results = bindings.map((binding) => sendMessageWithResult({
       from: channel.agentId,
-      to: messageTargetForChannelTarget(binding.target),
+      to: messageTargetForChannelTarget(binding.target, binding),
       kind: "channel.event",
       channel: channel.id,
       body: input.body,
@@ -2123,6 +2130,8 @@ const postSystemReap: Handler = () => {
   for (const task of released.tasks) emitTaskChanged(task, "task.updated");
   for (const id of reapedAgentIds) emitAgentStatus(id);
   for (const id of reapedOrchestratorIds) emitOrchestratorStatus(id);
+  const poolChanges = evaluatePoolBindings();
+  for (const change of poolChanges) emitPoolBindingChanged(change.bindingId, change.channelId, change.previousAgentId, change.newAgentId);
   auditEvent({
     clientId: "server-system-reap-" + Date.now(),
     kind: "state",

package/src/sse.ts

@@ -155,3 +155,9 @@ export function emitOrchestratorRemoved(orchestratorId: string) {
     send(conn, "orchestrator.removed", { id: orchestratorId });
   }
 }
+
+export function emitPoolBindingChanged(bindingId: string, channelId: string, previousAgentId: string | null, newAgentId: string | null) {
+  for (const conn of connections.values()) {
+    send(conn, "channel.pool.changed", { bindingId, channelId, previousAgentId, newAgentId, at: Date.now() });
+  }
+}

package/src/types.ts

@@ -275,7 +275,8 @@ export type ChannelRouteTarget =
   | { type: "tag"; id: string }
   | { type: "capability"; id: string }
   | { type: "broadcast" }
-  | { type: "orchestrator"; id: string };
+  | { type: "orchestrator"; id: string }
+  | { type: "pool"; id: string };
 
 export type ChannelBindingMode = "exclusive" | "claimable" | "broadcast";
 
@@ -288,6 +289,10 @@ export interface ChannelBinding {
   priority: number;
   createdAt: number;
   updatedAt: number;
+  poolSelector?: string;
+  poolAgentId?: string;
+  poolAgentEpoch?: number;
+  poolClaimExpiresAt?: number;
 }
 
 export interface ChannelTargetHealth {