agent-relay-server 0.1.0

package/src/routes.ts

@@ -0,0 +1,343 @@
+import {
+  upsertAgent,
+  getAgent,
+  listAgents,
+  findAgentsByCapability,
+  setStatus,
+  setLabel,
+  heartbeat,
+  deleteAgent,
+  sendMessage,
+  getMessage,
+  getThread,
+  claimMessage,
+  listRecentMessages,
+  pollMessages,
+  markRead,
+  deleteMessage,
+  getStats,
+  getLatestMessageId,
+  ValidationError,
+} from "./db";
+import type { RegisterAgentInput, SendMessageInput, PollQuery } from "./types";
+import { MAX_BODY_BYTES } from "./config";
+
+type Handler = (
+  req: Request,
+  params: Record<string, string>
+) => Response | Promise<Response>;
+
+const json = (data: unknown, status = 200) =>
+  Response.json(data, { status });
+
+const error = (msg: string, status = 400) =>
+  json({ error: msg }, status);
+
+type ParseBodyResult<T> =
+  | { ok: true; body: T | null }
+  | { ok: false; status: number; error: string };
+
+async function parseBody<T>(req: Request): Promise<ParseBodyResult<T>> {
+  if (!req.body) return { ok: true, body: null };
+
+  const reader = req.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+
+    totalBytes += value.byteLength;
+    if (totalBytes > MAX_BODY_BYTES) {
+      try {
+        await reader.cancel();
+      } catch {
+        // Ignore cancellation errors — we already know this request is too large.
+      }
+      return {
+        ok: false,
+        status: 413,
+        error: `request body exceeds ${MAX_BODY_BYTES} bytes`,
+      };
+    }
+
+    chunks.push(value);
+  }
+
+  if (totalBytes === 0) return { ok: true, body: null };
+
+  const merged = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  try {
+    const decoded = new TextDecoder().decode(merged);
+    return { ok: true, body: JSON.parse(decoded) as T };
+  } catch {
+    return { ok: false, status: 400, error: "invalid JSON body" };
+  }
+}
+
+function parseId(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0 || n > Number.MAX_SAFE_INTEGER) return null;
+  return n;
+}
+
+function parseQueryInt(
+  raw: string | null,
+  opts: { min: number; max: number }
+): number | null {
+  if (raw === null) return null;
+  if (!/^-?\d+$/.test(raw)) return Number.NaN;
+
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n)) return Number.NaN;
+  if (n < opts.min || n > opts.max) return Number.NaN;
+  return n;
+}
+
+// --- Agent routes ---
+
+const postAgent: Handler = async (req) => {
+  const parsed = await parseBody<RegisterAgentInput>(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 getAgents: Handler = (req) => {
+  const url = new URL(req.url);
+  const tag = url.searchParams.get("tag") ?? undefined;
+  const machine = url.searchParams.get("machine") ?? undefined;
+  const status = url.searchParams.get("status") ?? undefined;
+  return json(listAgents({ tag, machine, status }));
+};
+
+const findAgents: Handler = (req) => {
+  const url = new URL(req.url);
+  const capability = url.searchParams.get("capability");
+  if (!capability) return error("capability query param required");
+  const onlineOnly = url.searchParams.get("all") !== "true";
+  return json(findAgentsByCapability(capability, onlineOnly));
+};
+
+const getAgentById: Handler = (_req, params) => {
+  const agent = getAgent(params.id!);
+  return agent ? json(agent) : error("agent not found", 404);
+};
+
+const patchAgentStatus: Handler = async (req, params) => {
+  const parsed = await parseBody<{ status: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  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);
+};
+
+const postHeartbeat: Handler = (_req, params) => {
+  return heartbeat(params.id!) ? json({ ok: true }) : error("agent not found", 404);
+};
+
+const patchAgentLabel: Handler = async (req, params) => {
+  const parsed = await parseBody<{ label: string | null }>(req);
+  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);
+};
+
+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);
+};
+
+// --- Message routes ---
+
+const postMessage: Handler = async (req) => {
+  const parsed = await parseBody<SendMessageInput>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.from || !body?.to || !body?.body) {
+    return error("from, to, and body required");
+  }
+  try {
+    return json(sendMessage(body), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getMessages: Handler = (req) => {
+  const url = new URL(req.url);
+  const forAgent = url.searchParams.get("for");
+  const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
+  if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+  const limit = limitRaw ?? undefined;
+
+  const sinceRaw = parseQueryInt(url.searchParams.get("since"), {
+    min: 0,
+    max: Number.MAX_SAFE_INTEGER,
+  });
+  if (Number.isNaN(sinceRaw)) return error("since must be a non-negative integer");
+  const since = sinceRaw ?? undefined;
+
+  const sinceIdRaw = parseQueryInt(url.searchParams.get("sinceId"), {
+    min: 1,
+    max: Number.MAX_SAFE_INTEGER,
+  });
+  if (Number.isNaN(sinceIdRaw)) return error("sinceId must be a positive integer");
+  const sinceId = sinceIdRaw ?? undefined;
+
+  const channel = url.searchParams.get("channel") ?? undefined;
+
+  // No agent filter — return all recent messages
+  if (!forAgent) {
+    return json(listRecentMessages(limit ?? 100, since, channel));
+  }
+
+  return json(pollMessages({
+    for: forAgent,
+    since,
+    sinceId,
+    unread: url.searchParams.get("unread") === "true",
+    channel,
+    limit,
+  }));
+};
+
+const getMessageById: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const msg = getMessage(id);
+  return msg ? json(msg) : error("message not found", 404);
+};
+
+const getMessageThread: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const thread = getThread(id);
+  if (!thread.length) return error("message not found", 404);
+  return json(thread);
+};
+
+const postClaimMessage: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<{ agentId: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.agentId) return error("agentId required");
+  const result = claimMessage(id, body.agentId);
+  if (result.ok) return json({ ok: true });
+  const status =
+    result.error === "message not found" ? 404 :
+    result.error === "claiming agent not found" ? 400 :
+    result.error === "message is not claimable" ? 400 :
+    409;
+  return error(result.error!, status);
+};
+
+const patchMessage: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<{ readBy: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.readBy) return error("readBy required");
+  return markRead(id, body.readBy) ? json({ ok: true }) : error("message not found", 404);
+};
+
+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);
+};
+
+const getCursorRoute: Handler = () => json({ latestId: getLatestMessageId() });
+
+// --- Stats ---
+
+const getStatsRoute: Handler = () => json(getStats());
+
+// --- Router ---
+
+interface Route {
+  method: string;
+  pattern: RegExp;
+  paramNames: string[];
+  handler: Handler;
+}
+
+function route(method: string, path: string, handler: Handler): Route {
+  const paramNames: string[] = [];
+  const pattern = new RegExp(
+    "^" +
+      path.replace(/:(\w+)/g, (_, name) => {
+        paramNames.push(name);
+        return "([^/]+)";
+      }) +
+      "$"
+  );
+  return { method, pattern, paramNames, handler };
+}
+
+const routes: Route[] = [
+  route("POST", "/api/agents", postAgent),
+  route("GET", "/api/agents", getAgents),
+  route("GET", "/api/agents/find", findAgents),
+  route("GET", "/api/agents/:id", getAgentById),
+  route("PATCH", "/api/agents/:id/status", patchAgentStatus),
+  route("PATCH", "/api/agents/:id/label", patchAgentLabel),
+  route("POST", "/api/agents/:id/heartbeat", postHeartbeat),
+  route("DELETE", "/api/agents/:id", deleteAgentById),
+
+  route("POST", "/api/messages", postMessage),
+  route("GET", "/api/messages", getMessages),
+  route("GET", "/api/messages/cursor", getCursorRoute),
+  route("GET", "/api/messages/:id", getMessageById),
+  route("GET", "/api/messages/:id/thread", getMessageThread),
+  route("POST", "/api/messages/:id/claim", postClaimMessage),
+  route("PATCH", "/api/messages/:id", patchMessage),
+  route("DELETE", "/api/messages/:id", deleteMessageById),
+
+  route("GET", "/api/stats", getStatsRoute),
+];
+
+export function matchRoute(
+  method: string,
+  pathname: string
+): { handler: Handler; params: Record<string, string> } | null {
+  for (const r of routes) {
+    if (r.method !== method) continue;
+    const match = pathname.match(r.pattern);
+    if (!match) continue;
+
+    const params: Record<string, string> = {};
+    try {
+      r.paramNames.forEach((name, i) => {
+        params[name] = decodeURIComponent(match[i + 1]!);
+      });
+    } catch {
+      return { handler: () => error("invalid url encoding"), params: {} };
+    }
+    return { handler: r.handler, params };
+  }
+  return null;
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+export interface AgentCard {
+  id: string;
+  name: string;
+  label?: string; // human-friendly alias; acts as a fan-out target ("label:foo")
+  tags: string[];
+  machine?: string;
+  rig?: string;
+  capabilities: string[];
+  status: "online" | "idle" | "busy" | "offline";
+  meta?: Record<string, unknown>;
+  lastSeen: number;
+  createdAt: number;
+}
+
+export interface Message {
+  id: number;
+  from: string;
+  to: string; // agent-id | "tag:<name>" | "broadcast" | "cap:<name>"
+  channel?: string;
+  subject?: string;
+  body: string;
+  threadId?: number;
+  replyTo?: number;
+  claimable?: boolean;
+  claimedBy?: string;
+  claimedAt?: number;
+  meta?: Record<string, unknown>;
+  readBy: string[];
+  createdAt: number;
+}
+
+export interface SendMessageInput {
+  from: string;
+  to: string;
+  channel?: string;
+  subject?: string;
+  body: string;
+  replyTo?: number;
+  claimable?: boolean;
+  meta?: Record<string, unknown>;
+}
+
+export interface PollQuery {
+  for: string; // agent-id
+  since?: number; // unix ms (createdAt cursor)
+  sinceId?: number; // monotonic message id cursor (preferred — avoids same-ms collisions)
+  unread?: boolean;
+  channel?: string;
+  limit?: number;
+}
+
+export interface RegisterAgentInput {
+  id: string;
+  name: string;
+  label?: string;
+  tags?: string[];
+  machine?: string;
+  rig?: string;
+  capabilities?: string[];
+  status?: AgentCard["status"];
+  meta?: Record<string, unknown>;
+}