agent-relay-server 0.1.0 → 0.3.0

package/src/config.ts

@@ -1,5 +1,13 @@
 // Shared runtime constants. Import from here rather than redefining.
 
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
+export const VERSION: string = pkg.version;
+
 export const STALE_TTL_MS = 600_000; // 10min without heartbeat → offline
 export const REAP_INTERVAL_MS = 60_000; // reaper cadence
 export const DAY_MS = 86_400_000;

package/src/db.ts

@@ -1,7 +1,9 @@
 import { Database } from "bun:sqlite";
+import { VERSION } from "./config.ts";
 import type {
   AgentCard,
   Message,
+  MessageType,
   RegisterAgentInput,
   SendMessageInput,
   PollQuery,
@@ -33,6 +35,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       from_agent TEXT NOT NULL,
       to_target TEXT NOT NULL,
+      type TEXT NOT NULL DEFAULT 'message',
       channel TEXT,
       subject TEXT,
       body TEXT NOT NULL,
@@ -65,6 +68,10 @@ export function initDb(path: string = "agent-relay.db"): Database {
   }
   db.run("CREATE INDEX IF NOT EXISTS idx_msg_thread ON messages(thread_id)");
 
+  if (!colNames.includes("type")) {
+    db.run("ALTER TABLE messages ADD COLUMN type TEXT NOT NULL DEFAULT 'message'");
+  }
+
   // Backfill thread_id for pre-migration rows (self-threaded).
   db.run("UPDATE messages SET thread_id = id WHERE thread_id IS NULL");
 
@@ -85,18 +92,22 @@ export function initDb(path: string = "agent-relay.db"): Database {
   if (!agentColNames.includes("label")) {
     db.run("ALTER TABLE agents ADD COLUMN label TEXT");
   }
+  if (!agentColNames.includes("ready")) {
+    db.run("ALTER TABLE agents ADD COLUMN ready INTEGER NOT NULL DEFAULT 0");
+  }
   db.run("CREATE INDEX IF NOT EXISTS idx_agents_label ON agents(label)");
 
-  // Built-in "user" agent — represents the human operator driving the
-  // dashboard. Registered unconditionally so dashboard sends (from=user)
-  // pass the sendMessage validation. The reaper exempts this id so it
-  // never flips to offline.
+  // Built-in agents — registered unconditionally so sends from these ids
+  // pass the sendMessage validation. The reaper exempts these by checking
+  // meta.builtin (or by id for "user").
   const now = Date.now();
-  db.prepare(`
-    INSERT INTO agents (id, name, tags, machine, rig, capabilities, status, meta, last_seen, created_at)
-    VALUES ('user', 'User', '["human"]', NULL, NULL, '[]', 'online', '{"builtin":true}', ?, ?)
-    ON CONFLICT(id) DO UPDATE SET status = 'online', last_seen = excluded.last_seen
-  `).run(now, now);
+  const builtinStmt = db.prepare(`
+    INSERT INTO agents (id, name, tags, machine, rig, capabilities, ready, status, meta, last_seen, created_at)
+    VALUES (?, ?, ?, NULL, NULL, '[]', 1, 'online', '{"builtin":true}', ?, ?)
+    ON CONFLICT(id) DO UPDATE SET status = 'online', ready = 1, last_seen = excluded.last_seen
+  `);
+  builtinStmt.run("user", "User", '["human"]', now, now);
+  builtinStmt.run("system", "System", '["system"]', now, now);
 
   // One-shot migration: backfill message_reads from legacy read_by JSON
   // if that column still carries data. Safe to run repeatedly (INSERT OR IGNORE).
@@ -131,6 +142,7 @@ function rowToAgent(row: any): AgentCard {
     machine: row.machine ?? undefined,
     rig: row.rig ?? undefined,
     capabilities: parseJson(row.capabilities, []),
+    ready: row.ready === 1,
     status: row.status,
     meta: parseJson(row.meta, {}),
     lastSeen: row.last_seen,
@@ -143,6 +155,7 @@ function rowToMessage(row: any): Message {
     id: row.id,
     from: row.from_agent,
     to: row.to_target,
+    type: (row.type ?? "message") as MessageType,
     channel: row.channel ?? undefined,
     subject: row.subject ?? undefined,
     body: row.body,
@@ -168,9 +181,10 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   // Preserve the existing label across re-registrations unless the caller
   // explicitly sends one (including null to clear).
   const labelProvided = Object.prototype.hasOwnProperty.call(input, "label");
+  const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
   const stmt = db.prepare(`
-    INSERT INTO agents (id, name, label, tags, machine, rig, capabilities, status, meta, last_seen, created_at)
-    VALUES ($id, $name, $label, $tags, $machine, $rig, $capabilities, $status, $meta, $now, $now)
+    INSERT INTO agents (id, name, label, tags, machine, rig, capabilities, ready, status, meta, last_seen, created_at)
+    VALUES ($id, $name, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $meta, $now, $now)
     ON CONFLICT(id) DO UPDATE SET
       name = $name,
       label = CASE WHEN $labelProvided = 1 THEN $label ELSE agents.label END,
@@ -178,6 +192,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
       machine = coalesce($machine, agents.machine),
       rig = coalesce($rig, agents.rig),
       capabilities = $capabilities,
+      ready = CASE WHEN $readyProvided = 1 THEN $ready ELSE agents.ready END,
       status = $status,
       meta = $meta,
       last_seen = $now
@@ -192,6 +207,8 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
     $machine: input.machine ?? null,
     $rig: input.rig ?? null,
     $capabilities: JSON.stringify(input.capabilities ?? []),
+    $ready: input.ready ? 1 : 0,
+    $readyProvided: readyProvided ? 1 : 0,
     $status: input.status ?? "idle",
     $meta: JSON.stringify(input.meta ?? {}),
     $now: now,
@@ -238,11 +255,20 @@ export function listAgents(filter?: {
 }
 
 export function setStatus(id: string, status: AgentCard["status"]): boolean {
+  const now = Date.now();
+  const ready = status === "offline" ? 0 : undefined;
+  const sql = ready === 0
+    ? "UPDATE agents SET status = ?, ready = 0, last_seen = ? WHERE id = ?"
+    : "UPDATE agents SET status = ?, last_seen = ? WHERE id = ?";
+  return db.prepare(sql).run(status, now, id).changes > 0;
+}
+
+export function markReady(id: string, ready: boolean): boolean {
   const now = Date.now();
   return (
     db
-      .prepare("UPDATE agents SET status = ?, last_seen = ? WHERE id = ?")
-      .run(status, now, id).changes > 0
+      .prepare("UPDATE agents SET ready = ?, last_seen = ? WHERE id = ?")
+      .run(ready ? 1 : 0, now, id).changes > 0
   );
 }
 
@@ -253,13 +279,14 @@ export function heartbeat(id: string): boolean {
   return result.changes > 0;
 }
 
-export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): number {
+export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
   const cutoff = Date.now() - ttlMs;
-  return db
+  const rows = db
     .prepare(
-      "UPDATE agents SET status = 'offline' WHERE status != 'offline' AND last_seen < ? AND id != 'user'"
+      "UPDATE agents SET status = 'offline', ready = 0 WHERE status != 'offline' AND last_seen < ? AND id NOT IN ('user', 'system') RETURNING id"
     )
-    .run(cutoff).changes;
+    .all(cutoff) as any[];
+  return rows.map((r: any) => r.id);
 }
 
 export function findAgentsByCapability(capability: string, onlineOnly = true): AgentCard[] {
@@ -303,8 +330,8 @@ export function sendMessage(input: SendMessageInput): Message {
   }
 
   const insert = db.prepare(`
-    INSERT INTO messages (from_agent, to_target, channel, subject, body, thread_id, reply_to, claimable, meta, created_at)
-    VALUES ($from, $to, $channel, $subject, $body, $threadId, $replyTo, $claimable, $meta, $now)
+    INSERT INTO messages (from_agent, to_target, type, channel, subject, body, thread_id, reply_to, claimable, meta, created_at)
+    VALUES ($from, $to, $type, $channel, $subject, $body, $threadId, $replyTo, $claimable, $meta, $now)
   `);
   const setSelfThread = db.prepare("UPDATE messages SET thread_id = ? WHERE id = ?");
 
@@ -312,6 +339,7 @@ export function sendMessage(input: SendMessageInput): Message {
     const result = insert.run({
       $from: input.from,
       $to: input.to,
+      $type: input.type ?? "message",
       $channel: input.channel ?? null,
       $subject: input.subject ?? null,
       $body: input.body,
@@ -471,6 +499,7 @@ export function pruneOldMessages(maxAgeMs: number): number {
 }
 
 export function getStats(): {
+  version: string;
   agents: number;
   online: number;
   messages: number;
@@ -495,5 +524,5 @@ export function getStats(): {
       .get(Date.now() - DAY_MS) as any
   ).c;
 
-  return { agents, online, messages, messagesLast24h };
+  return { version: VERSION, agents, online, messages, messagesLast24h };
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { initDb, reapStaleAgents, pruneOldMessages } from "./db";
 import { matchRoute } from "./routes";
+import { emitAgentStatus } from "./sse";
 import { resolve, sep } from "path";
 import { REAP_INTERVAL_MS, STALE_TTL_MS, MAX_BODY_BYTES, DAY_MS } from "./config";
 
@@ -14,7 +15,10 @@ initDb(DB_PATH);
 
 setInterval(() => {
   const reaped = reapStaleAgents(STALE_TTL_MS);
-  if (reaped > 0) console.log(`reaped ${reaped} stale agent(s)`);
+  if (reaped.length > 0) {
+    console.log(`reaped ${reaped.length} stale agent(s)`);
+    for (const id of reaped) emitAgentStatus(id);
+  }
 }, REAP_INTERVAL_MS);
 
 // Daily message prune

package/src/routes.ts

@@ -5,6 +5,7 @@ import {
   findAgentsByCapability,
   setStatus,
   setLabel,
+  markReady,
   heartbeat,
   deleteAgent,
   sendMessage,
@@ -21,6 +22,14 @@ import {
 } from "./db";
 import type { RegisterAgentInput, SendMessageInput, PollQuery } from "./types";
 import { MAX_BODY_BYTES } from "./config";
+import {
+  createSSEStream,
+  emitNewMessage,
+  emitAgentStatus,
+  emitAgentRemoved,
+  emitMessageClaimed,
+  emitMessageDeleted,
+} from "./sse";
 
 type Handler = (
   req: Request,
@@ -110,7 +119,9 @@ const postAgent: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
   if (!body?.id || !body?.name) return error("id and name required");
-  return json(upsertAgent(body), 201);
+  const agent = upsertAgent(body);
+  emitAgentStatus(agent.id);
+  return json(agent, 201);
 };
 
 const getAgents: Handler = (req) => {
@@ -141,9 +152,9 @@ const patchAgentStatus: Handler = async (req, params) => {
   if (!body?.status) return error("status required");
   const valid = ["online", "idle", "busy", "offline"];
   if (!valid.includes(body.status)) return error(`status must be one of: ${valid.join(", ")}`);
-  return setStatus(params.id!, body.status as any)
-    ? json({ ok: true })
-    : error("agent not found", 404);
+  if (!setStatus(params.id!, body.status as any)) return error("agent not found", 404);
+  emitAgentStatus(params.id!);
+  return json({ ok: true });
 };
 
 const postHeartbeat: Handler = (_req, params) => {
@@ -155,20 +166,35 @@ const patchAgentLabel: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
   if (body === null || !("label" in body)) return error("label field required (string or null)");
-  return setLabel(params.id!, body.label)
-    ? json({ ok: true })
-    : error("agent not found", 404);
+  if (!setLabel(params.id!, body.label)) return error("agent not found", 404);
+  emitAgentStatus(params.id!);
+  return json({ ok: true });
+};
+
+const patchAgentReady: Handler = async (req, params) => {
+  const parsed = await parseBody<{ ready: boolean }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (body === null || typeof body.ready !== "boolean") return error("ready field required (boolean)");
+  if (!markReady(params.id!, body.ready)) return error("agent not found", 404);
+  emitAgentStatus(params.id!);
+  return json({ ok: true });
 };
 
 const deleteAgentById: Handler = (_req, params) => {
   const result = deleteAgent(params.id!);
-  if (result.ok) return json({ ok: true });
-  const status = result.error === "agent not found" ? 404 : 400;
-  return error(result.error!, status);
+  if (!result.ok) {
+    const status = result.error === "agent not found" ? 404 : 400;
+    return error(result.error!, status);
+  }
+  emitAgentRemoved(params.id!);
+  return json({ ok: true });
 };
 
 // --- Message routes ---
 
+const VALID_MSG_TYPES = ["message", "system"];
+
 const postMessage: Handler = async (req) => {
   const parsed = await parseBody<SendMessageInput>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -176,8 +202,34 @@ const postMessage: Handler = async (req) => {
   if (!body?.from || !body?.to || !body?.body) {
     return error("from, to, and body required");
   }
+  if (body.type && !VALID_MSG_TYPES.includes(body.type)) {
+    return error(`type must be one of: ${VALID_MSG_TYPES.join(", ")}`);
+  }
+  try {
+    const msg = sendMessage(body);
+    emitNewMessage(msg);
+    return json(msg, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postSystemBroadcast: Handler = async (req) => {
+  const parsed = await parseBody<{ body: string; subject?: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.body) return error("body required");
   try {
-    return json(sendMessage(body), 201);
+    const msg = sendMessage({
+      from: "system",
+      to: "broadcast",
+      type: "system",
+      subject: body.subject ?? undefined,
+      body: body.body,
+    });
+    emitNewMessage(msg);
+    return json(msg, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -199,10 +251,10 @@ const getMessages: Handler = (req) => {
   const since = sinceRaw ?? undefined;
 
   const sinceIdRaw = parseQueryInt(url.searchParams.get("sinceId"), {
-    min: 1,
+    min: 0,
     max: Number.MAX_SAFE_INTEGER,
   });
-  if (Number.isNaN(sinceIdRaw)) return error("sinceId must be a positive integer");
+  if (Number.isNaN(sinceIdRaw)) return error("sinceId must be a non-negative integer");
   const sinceId = sinceIdRaw ?? undefined;
 
   const channel = url.searchParams.get("channel") ?? undefined;
@@ -245,7 +297,10 @@ const postClaimMessage: Handler = async (req, params) => {
   const body = parsed.body;
   if (!body?.agentId) return error("agentId required");
   const result = claimMessage(id, body.agentId);
-  if (result.ok) return json({ ok: true });
+  if (result.ok) {
+    emitMessageClaimed(id, body.agentId);
+    return json({ ok: true });
+  }
   const status =
     result.error === "message not found" ? 404 :
     result.error === "claiming agent not found" ? 400 :
@@ -267,11 +322,21 @@ const patchMessage: Handler = async (req, params) => {
 const deleteMessageById: Handler = (_req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid message id");
-  return deleteMessage(id) ? json({ ok: true }) : error("message not found", 404);
+  if (!deleteMessage(id)) return error("message not found", 404);
+  emitMessageDeleted(id);
+  return json({ ok: true });
 };
 
 const getCursorRoute: Handler = () => json({ latestId: getLatestMessageId() });
 
+// --- SSE ---
+
+const getEvents: Handler = (req) => {
+  const url = new URL(req.url);
+  const agentId = url.searchParams.get("for") || null;
+  return createSSEStream(agentId);
+};
+
 // --- Stats ---
 
 const getStatsRoute: Handler = () => json(getStats());
@@ -304,10 +369,12 @@ const routes: Route[] = [
   route("GET", "/api/agents/find", findAgents),
   route("GET", "/api/agents/:id", getAgentById),
   route("PATCH", "/api/agents/:id/status", patchAgentStatus),
+  route("PATCH", "/api/agents/:id/ready", patchAgentReady),
   route("PATCH", "/api/agents/:id/label", patchAgentLabel),
   route("POST", "/api/agents/:id/heartbeat", postHeartbeat),
   route("DELETE", "/api/agents/:id", deleteAgentById),
 
+  route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("POST", "/api/messages", postMessage),
   route("GET", "/api/messages", getMessages),
   route("GET", "/api/messages/cursor", getCursorRoute),
@@ -317,6 +384,7 @@ const routes: Route[] = [
   route("PATCH", "/api/messages/:id", patchMessage),
   route("DELETE", "/api/messages/:id", deleteMessageById),
 
+  route("GET", "/api/events", getEvents),
   route("GET", "/api/stats", getStatsRoute),
 ];
 

package/src/sse.ts

@@ -0,0 +1,115 @@
+import { getAgent } from "./db";
+import type { Message } from "./types";
+
+interface Connection {
+  id: string;
+  agentId: string | null;
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  keepalive: Timer;
+}
+
+const connections = new Map<string, Connection>();
+const encoder = new TextEncoder();
+
+export function createSSEStream(agentId: string | null): Response {
+  let connId: string;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      connId = crypto.randomUUID();
+      const keepalive = setInterval(() => {
+        try { controller.enqueue(encoder.encode(": keepalive\n\n")); }
+        catch { removeConnection(connId); }
+      }, 30_000);
+
+      connections.set(connId, { id: connId, agentId, controller, keepalive });
+
+      controller.enqueue(encoder.encode(
+        `event: connected\ndata: ${JSON.stringify({ connectionId: connId })}\n\n`
+      ));
+    },
+    cancel() {
+      removeConnection(connId);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+      "Access-Control-Allow-Origin": "*",
+    },
+  });
+}
+
+function removeConnection(id: string) {
+  const conn = connections.get(id);
+  if (conn) {
+    clearInterval(conn.keepalive);
+    connections.delete(id);
+  }
+}
+
+function send(conn: Connection, event: string, data: unknown) {
+  try {
+    conn.controller.enqueue(encoder.encode(
+      `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+    ));
+  } catch {
+    removeConnection(conn.id);
+  }
+}
+
+function messageMatchesAgent(msg: Message, agentId: string): boolean {
+  const agent = getAgent(agentId);
+  if (!agent) return false;
+  if (msg.to === agentId || msg.from === agentId) return true;
+  if (msg.to === "broadcast") return true;
+  if (msg.to.startsWith("tag:") && agent.tags.includes(msg.to.slice(4))) return true;
+  if (msg.to.startsWith("cap:") && agent.capabilities.includes(msg.to.slice(4))) return true;
+  if (msg.to.startsWith("label:") && agent.label === msg.to.slice(6)) return true;
+  return false;
+}
+
+export function emitNewMessage(msg: Message) {
+  for (const conn of connections.values()) {
+    if (!conn.agentId) {
+      send(conn, "message.new", msg);
+      continue;
+    }
+    if (!messageMatchesAgent(msg, conn.agentId)) continue;
+    if (msg.claimable && msg.claimedBy && msg.claimedBy !== conn.agentId) continue;
+    send(conn, "message.new", msg);
+  }
+}
+
+export function emitAgentStatus(agentId: string) {
+  const agent = getAgent(agentId);
+  const data = agent ?? { id: agentId, status: "offline" };
+  for (const conn of connections.values()) {
+    send(conn, "agent.status", data);
+  }
+}
+
+export function emitAgentRemoved(agentId: string) {
+  for (const conn of connections.values()) {
+    send(conn, "agent.removed", { id: agentId });
+  }
+}
+
+export function emitMessageClaimed(messageId: number, claimedBy: string) {
+  for (const conn of connections.values()) {
+    send(conn, "message.claimed", { messageId, claimedBy });
+  }
+}
+
+export function emitMessageDeleted(messageId: number) {
+  for (const conn of connections.values()) {
+    send(conn, "message.deleted", { messageId });
+  }
+}
+
+export function getConnectionCount(): number {
+  return connections.size;
+}

package/src/types.ts

@@ -6,16 +6,20 @@ export interface AgentCard {
   machine?: string;
   rig?: string;
   capabilities: string[];
+  ready: boolean;
   status: "online" | "idle" | "busy" | "offline";
   meta?: Record<string, unknown>;
   lastSeen: number;
   createdAt: number;
 }
 
+export type MessageType = "message" | "system";
+
 export interface Message {
   id: number;
   from: string;
   to: string; // agent-id | "tag:<name>" | "broadcast" | "cap:<name>"
+  type: MessageType;
   channel?: string;
   subject?: string;
   body: string;
@@ -32,6 +36,7 @@ export interface Message {
 export interface SendMessageInput {
   from: string;
   to: string;
+  type?: MessageType;
   channel?: string;
   subject?: string;
   body: string;
@@ -57,6 +62,7 @@ export interface RegisterAgentInput {
   machine?: string;
   rig?: string;
   capabilities?: string[];
+  ready?: boolean;
   status?: AgentCard["status"];
   meta?: Record<string, unknown>;
 }