agent-relay-server 0.1.0

package/src/db.ts

@@ -0,0 +1,499 @@
+import { Database } from "bun:sqlite";
+import type {
+  AgentCard,
+  Message,
+  RegisterAgentInput,
+  SendMessageInput,
+  PollQuery,
+} from "./types";
+import { STALE_TTL_MS, DAY_MS } from "./config";
+
+let db: Database;
+
+export function initDb(path: string = "agent-relay.db"): Database {
+  db = new Database(path, { create: true });
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA foreign_keys = ON");
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS agents (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      tags TEXT NOT NULL DEFAULT '[]',
+      machine TEXT,
+      rig TEXT,
+      capabilities TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'idle',
+      meta TEXT NOT NULL DEFAULT '{}',
+      last_seen INTEGER NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      from_agent TEXT NOT NULL,
+      to_target TEXT NOT NULL,
+      channel TEXT,
+      subject TEXT,
+      body TEXT NOT NULL,
+      thread_id INTEGER,
+      reply_to INTEGER REFERENCES messages(id),
+      claimable INTEGER NOT NULL DEFAULT 0,
+      claimed_by TEXT,
+      claimed_at INTEGER,
+      meta TEXT NOT NULL DEFAULT '{}',
+      read_by TEXT NOT NULL DEFAULT '[]',
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_msg_to ON messages(to_target);
+    CREATE INDEX IF NOT EXISTS idx_msg_created ON messages(created_at);
+    CREATE INDEX IF NOT EXISTS idx_msg_channel ON messages(channel);
+  `);
+
+  // Migrations
+  const cols = db.prepare("PRAGMA table_info(messages)").all() as any[];
+  const colNames = cols.map((c: any) => c.name);
+  if (!colNames.includes("thread_id")) {
+    db.run("ALTER TABLE messages ADD COLUMN thread_id INTEGER");
+    db.run("ALTER TABLE messages ADD COLUMN reply_to INTEGER REFERENCES messages(id)");
+  }
+  if (!colNames.includes("claimable")) {
+    db.run("ALTER TABLE messages ADD COLUMN claimable INTEGER NOT NULL DEFAULT 0");
+    db.run("ALTER TABLE messages ADD COLUMN claimed_by TEXT");
+    db.run("ALTER TABLE messages ADD COLUMN claimed_at INTEGER");
+  }
+  db.run("CREATE INDEX IF NOT EXISTS idx_msg_thread ON messages(thread_id)");
+
+  // Backfill thread_id for pre-migration rows (self-threaded).
+  db.run("UPDATE messages SET thread_id = id WHERE thread_id IS NULL");
+
+  // message_reads: relational replacement for the read_by JSON array.
+  db.run(`
+    CREATE TABLE IF NOT EXISTS message_reads (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent_id TEXT NOT NULL,
+      read_at INTEGER NOT NULL,
+      PRIMARY KEY (message_id, agent_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_mr_agent ON message_reads(agent_id);
+  `);
+
+  // Migration: agents.label
+  const agentCols = db.prepare("PRAGMA table_info(agents)").all() as any[];
+  const agentColNames = agentCols.map((c: any) => c.name);
+  if (!agentColNames.includes("label")) {
+    db.run("ALTER TABLE agents ADD COLUMN label TEXT");
+  }
+  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.
+  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);
+
+  // One-shot migration: backfill message_reads from legacy read_by JSON
+  // if that column still carries data. Safe to run repeatedly (INSERT OR IGNORE).
+  if (colNames.includes("read_by")) {
+    db.run(`
+      INSERT OR IGNORE INTO message_reads (message_id, agent_id, read_at)
+      SELECT m.id, je.value, m.created_at
+      FROM messages m, json_each(m.read_by) je
+      WHERE json_valid(m.read_by)
+    `);
+  }
+
+  return db;
+}
+
+export class ValidationError extends Error {}
+
+function parseJson<T>(raw: string, fallback: T): T {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+function rowToAgent(row: any): AgentCard {
+  return {
+    id: row.id,
+    name: row.name,
+    label: row.label ?? undefined,
+    tags: parseJson(row.tags, []),
+    machine: row.machine ?? undefined,
+    rig: row.rig ?? undefined,
+    capabilities: parseJson(row.capabilities, []),
+    status: row.status,
+    meta: parseJson(row.meta, {}),
+    lastSeen: row.last_seen,
+    createdAt: row.created_at,
+  };
+}
+
+function rowToMessage(row: any): Message {
+  return {
+    id: row.id,
+    from: row.from_agent,
+    to: row.to_target,
+    channel: row.channel ?? undefined,
+    subject: row.subject ?? undefined,
+    body: row.body,
+    threadId: row.thread_id ?? undefined,
+    replyTo: row.reply_to ?? undefined,
+    claimable: row.claimable === 1 ? true : undefined,
+    claimedBy: row.claimed_by ?? undefined,
+    claimedAt: row.claimed_at ?? undefined,
+    meta: parseJson(row.meta, {}),
+    readBy: parseJson(row.read_by_agents ?? "[]", []),
+    createdAt: row.created_at,
+  };
+}
+
+const MSG_SELECT = `SELECT m.*, (
+  SELECT json_group_array(agent_id) FROM message_reads WHERE message_id = m.id
+) AS read_by_agents FROM messages m`;
+
+// --- Agents ---
+
+export function upsertAgent(input: RegisterAgentInput): AgentCard {
+  const now = Date.now();
+  // 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 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)
+    ON CONFLICT(id) DO UPDATE SET
+      name = $name,
+      label = CASE WHEN $labelProvided = 1 THEN $label ELSE agents.label END,
+      tags = $tags,
+      machine = coalesce($machine, agents.machine),
+      rig = coalesce($rig, agents.rig),
+      capabilities = $capabilities,
+      status = $status,
+      meta = $meta,
+      last_seen = $now
+  `);
+
+  stmt.run({
+    $id: input.id,
+    $name: input.name,
+    $label: input.label ?? null,
+    $labelProvided: labelProvided ? 1 : 0,
+    $tags: JSON.stringify(input.tags ?? []),
+    $machine: input.machine ?? null,
+    $rig: input.rig ?? null,
+    $capabilities: JSON.stringify(input.capabilities ?? []),
+    $status: input.status ?? "idle",
+    $meta: JSON.stringify(input.meta ?? {}),
+    $now: now,
+  });
+
+  return getAgent(input.id)!;
+}
+
+export function setLabel(id: string, label: string | null): boolean {
+  const normalized = label && label.trim() ? label.trim() : null;
+  return (
+    db.prepare("UPDATE agents SET label = ? WHERE id = ?").run(normalized, id).changes > 0
+  );
+}
+
+export function getAgent(id: string): AgentCard | null {
+  const row = db.prepare("SELECT * FROM agents WHERE id = ?").get(id) as any;
+  return row ? rowToAgent(row) : null;
+}
+
+export function listAgents(filter?: {
+  tag?: string;
+  machine?: string;
+  status?: string;
+}): AgentCard[] {
+  let sql = "SELECT * FROM agents WHERE 1=1";
+  const params: any[] = [];
+
+  if (filter?.tag) {
+    sql += " AND EXISTS (SELECT 1 FROM json_each(tags) WHERE value = ?)";
+    params.push(filter.tag);
+  }
+  if (filter?.machine) {
+    sql += " AND machine = ?";
+    params.push(filter.machine);
+  }
+  if (filter?.status) {
+    sql += " AND status = ?";
+    params.push(filter.status);
+  }
+
+  sql += " ORDER BY last_seen DESC";
+  return (db.prepare(sql).all(...params) as any[]).map(rowToAgent);
+}
+
+export function setStatus(id: string, status: AgentCard["status"]): boolean {
+  const now = Date.now();
+  return (
+    db
+      .prepare("UPDATE agents SET status = ?, last_seen = ? WHERE id = ?")
+      .run(status, now, id).changes > 0
+  );
+}
+
+export function heartbeat(id: string): boolean {
+  const result = db
+    .prepare("UPDATE agents SET last_seen = ? WHERE id = ?")
+    .run(Date.now(), id);
+  return result.changes > 0;
+}
+
+export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): number {
+  const cutoff = Date.now() - ttlMs;
+  return db
+    .prepare(
+      "UPDATE agents SET status = 'offline' WHERE status != 'offline' AND last_seen < ? AND id != 'user'"
+    )
+    .run(cutoff).changes;
+}
+
+export function findAgentsByCapability(capability: string, onlineOnly = true): AgentCard[] {
+  let sql = `SELECT * FROM agents WHERE EXISTS (SELECT 1 FROM json_each(capabilities) WHERE value = ?)`;
+  const params: any[] = [capability];
+  if (onlineOnly) {
+    sql += ` AND status != 'offline' AND last_seen > ?`;
+    params.push(Date.now() - STALE_TTL_MS);
+  }
+  sql += " ORDER BY last_seen DESC";
+  return (db.prepare(sql).all(...params) as any[]).map(rowToAgent);
+}
+
+export function deleteAgent(id: string): { ok: boolean; error?: string } {
+  if (id === "user") return { ok: false, error: "built-in user agent cannot be deleted" };
+  const deleted = db.transaction(() => {
+    // Release any claims held by this agent so the tasks become claimable again.
+    // from_agent is left intact as historical record.
+    db.prepare("UPDATE messages SET claimed_by = NULL, claimed_at = NULL WHERE claimed_by = ?").run(id);
+    return db.prepare("DELETE FROM agents WHERE id = ?").run(id).changes > 0;
+  })();
+  return deleted ? { ok: true } : { ok: false, error: "agent not found" };
+}
+
+// --- Messages ---
+
+export function sendMessage(input: SendMessageInput): Message {
+  const now = Date.now();
+
+  if (!getAgent(input.from)) {
+    throw new ValidationError(`sender agent ${input.from} not registered`);
+  }
+
+  // Resolve thread: if replying, inherit from parent; reject unknown replyTo
+  // rather than silently orphaning the message (leaves thread_id NULL).
+  let threadId: number | null = null;
+  if (input.replyTo !== undefined && input.replyTo !== null) {
+    const parent = getMessage(input.replyTo);
+    if (!parent) throw new ValidationError(`replyTo message ${input.replyTo} not found`);
+    threadId = parent.threadId ?? parent.id;
+  }
+
+  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)
+  `);
+  const setSelfThread = db.prepare("UPDATE messages SET thread_id = ? WHERE id = ?");
+
+  const id = db.transaction(() => {
+    const result = insert.run({
+      $from: input.from,
+      $to: input.to,
+      $channel: input.channel ?? null,
+      $subject: input.subject ?? null,
+      $body: input.body,
+      $threadId: threadId,
+      $replyTo: input.replyTo ?? null,
+      $claimable: input.claimable ? 1 : 0,
+      $meta: JSON.stringify(input.meta ?? {}),
+      $now: now,
+    });
+    const newId = Number(result.lastInsertRowid);
+    if (threadId === null) setSelfThread.run(newId, newId);
+    return newId;
+  })();
+
+  return getMessage(id)!;
+}
+
+export function getThread(messageId: number): Message[] {
+  const msg = getMessage(messageId);
+  if (!msg) return [];
+  const threadId = msg.threadId ?? msg.id;
+  return (
+    db
+      .prepare(`${MSG_SELECT} WHERE m.thread_id = ? ORDER BY m.created_at ASC`)
+      .all(threadId) as any[]
+  ).map(rowToMessage);
+}
+
+export function claimMessage(messageId: number, agentId: string): { ok: boolean; error?: string } {
+  if (!getAgent(agentId)) return { ok: false, error: "claiming agent not found" };
+
+  const msg = getMessage(messageId);
+  if (!msg) return { ok: false, error: "message not found" };
+  if (!msg.claimable) return { ok: false, error: "message is not claimable" };
+  if (msg.claimedBy) return { ok: false, error: `already claimed by ${msg.claimedBy}` };
+
+  const result = db.prepare(
+    "UPDATE messages SET claimed_by = ?, claimed_at = ? WHERE id = ? AND claimed_by IS NULL"
+  ).run(agentId, Date.now(), messageId);
+
+  // Atomic: if changes === 0, someone else claimed it between our read and write
+  if (result.changes === 0) return { ok: false, error: "claim race — already claimed" };
+  return { ok: true };
+}
+
+export function getMessage(id: number): Message | null {
+  const row = db.prepare(`${MSG_SELECT} WHERE m.id = ?`).get(id) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+export function listRecentMessages(limit: number = 100, since?: number, channel?: string): Message[] {
+  const conditions: string[] = [];
+  const params: any[] = [];
+
+  if (since !== undefined) {
+    conditions.push("created_at > ?");
+    params.push(since);
+  }
+  if (channel) {
+    conditions.push("channel = ?");
+    params.push(channel);
+  }
+
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  const sql = `${MSG_SELECT} ${where} ORDER BY m.created_at DESC LIMIT ?`;
+  params.push(limit);
+
+  return (db.prepare(sql).all(...params) as any[]).map(rowToMessage).reverse();
+}
+
+export function pollMessages(query: PollQuery): Message[] {
+  const agent = getAgent(query.for);
+  const agentTags = agent?.tags ?? [];
+  const agentCaps = agent?.capabilities ?? [];
+  const agentLabel = agent?.label;
+
+  const conditions: string[] = [];
+  const params: any[] = [];
+
+  // Build target matching: direct + broadcast + tag + capability + label
+  const targetClauses = ["to_target = ?", "to_target = 'broadcast'"];
+  params.push(query.for);
+
+  for (const tag of agentTags) {
+    targetClauses.push("to_target = ?");
+    params.push(`tag:${tag}`);
+  }
+  for (const cap of agentCaps) {
+    targetClauses.push("to_target = ?");
+    params.push(`cap:${cap}`);
+  }
+  if (agentLabel) {
+    targetClauses.push("to_target = ?");
+    params.push(`label:${agentLabel}`);
+  }
+  conditions.push(`(${targetClauses.join(" OR ")})`);
+
+  // Hide claimable messages that were claimed by someone else
+  conditions.push(`(claimable = 0 OR claimed_by IS NULL OR claimed_by = ?)`);
+  params.push(query.for);
+
+  if (query.sinceId !== undefined) {
+    conditions.push("id > ?");
+    params.push(query.sinceId);
+  } else if (query.since !== undefined) {
+    conditions.push("created_at > ?");
+    params.push(query.since);
+  }
+
+  if (query.unread) {
+    conditions.push(
+      "NOT EXISTS (SELECT 1 FROM message_reads WHERE message_id = m.id AND agent_id = ?)"
+    );
+    params.push(query.for);
+  }
+
+  if (query.channel) {
+    conditions.push("channel = ?");
+    params.push(query.channel);
+  }
+
+  const limit = query.limit ?? 50;
+  const sql = `${MSG_SELECT} WHERE ${conditions.join(" AND ")} ORDER BY m.created_at ASC LIMIT ?`;
+  params.push(limit);
+
+  return (db.prepare(sql).all(...params) as any[]).map(rowToMessage);
+}
+
+export function markRead(messageId: number, agentId: string): boolean {
+  const exists = db.prepare("SELECT 1 FROM messages WHERE id = ?").get(messageId);
+  if (!exists) return false;
+  db.prepare(
+    "INSERT OR IGNORE INTO message_reads (message_id, agent_id, read_at) VALUES (?, ?, ?)"
+  ).run(messageId, agentId, Date.now());
+  return true;
+}
+
+export function deleteMessage(id: number): boolean {
+  return db.transaction(() => {
+    // Break reply_to references from children so the FK doesn't block delete.
+    // Children keep their thread_id — the thread shows up minus this message.
+    db.prepare("UPDATE messages SET reply_to = NULL WHERE reply_to = ?").run(id);
+    return db.prepare("DELETE FROM messages WHERE id = ?").run(id).changes > 0;
+  })();
+}
+
+export function getLatestMessageId(): number {
+  const row = db.prepare("SELECT MAX(id) as id FROM messages").get() as any;
+  return row?.id ?? 0;
+}
+
+export function pruneOldMessages(maxAgeMs: number): number {
+  const cutoff = Date.now() - maxAgeMs;
+  return db
+    .prepare("DELETE FROM messages WHERE created_at < ?")
+    .run(cutoff).changes;
+}
+
+export function getStats(): {
+  agents: number;
+  online: number;
+  messages: number;
+  messagesLast24h: number;
+} {
+  const agents = (
+    db.prepare("SELECT COUNT(*) as c FROM agents").get() as any
+  ).c;
+  const online = (
+    db
+      .prepare(
+        "SELECT COUNT(*) as c FROM agents WHERE status != 'offline' AND last_seen > ?"
+      )
+      .get(Date.now() - STALE_TTL_MS) as any
+  ).c;
+  const messages = (
+    db.prepare("SELECT COUNT(*) as c FROM messages").get() as any
+  ).c;
+  const messagesLast24h = (
+    db
+      .prepare("SELECT COUNT(*) as c FROM messages WHERE created_at > ?")
+      .get(Date.now() - DAY_MS) as any
+  ).c;
+
+  return { agents, online, messages, messagesLast24h };
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+import { initDb, reapStaleAgents, pruneOldMessages } from "./db";
+import { matchRoute } from "./routes";
+import { resolve, sep } from "path";
+import { REAP_INTERVAL_MS, STALE_TTL_MS, MAX_BODY_BYTES, DAY_MS } from "./config";
+
+const PORT = Number(process.env.PORT) || 4850;
+const HOST = process.env.HOST || "127.0.0.1";
+const DB_PATH = process.env.DB_PATH || "agent-relay.db";
+const RETENTION_DAYS = Number(process.env.RETENTION_DAYS) || 30;
+const LOG_REQUESTS = process.env.AGENT_RELAY_LOG_REQUESTS === "1";
+
+initDb(DB_PATH);
+
+setInterval(() => {
+  const reaped = reapStaleAgents(STALE_TTL_MS);
+  if (reaped > 0) console.log(`reaped ${reaped} stale agent(s)`);
+}, REAP_INTERVAL_MS);
+
+// Daily message prune
+setInterval(() => {
+  const pruned = pruneOldMessages(RETENTION_DAYS * DAY_MS);
+  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);
+
+    // CORS
+    if (req.method === "OPTIONS") {
+      return new Response(null, {
+        headers: {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type",
+        },
+      });
+    }
+
+    // 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 },
+        );
+      }
+    }
+
+    // API routes
+    const matched = matchRoute(req.method, url.pathname);
+    if (matched) {
+      const response = await matched.handler(req, matched.params);
+      response.headers.set("Access-Control-Allow-Origin", "*");
+      if (LOG_REQUESTS && url.pathname.startsWith("/api/")) {
+        console.log(`${req.method} ${url.pathname} → ${response.status}`);
+      }
+      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);
+
+    return Response.json({ error: "not found" }, { status: 404 });
+  },
+});
+
+console.log(`agent-relay running on http://localhost:${PORT}`);