agent-relay-server 0.3.12 → 0.4.0

package/src/index.ts

@@ -11,88 +11,114 @@ import {
   DAY_MS,
   VERSION,
 } from "./config";
+import {
+  applyCors,
+  assertSafeNetworkConfig,
+  corsPreflight,
+  getIntegrationAuth,
+  isAuthorized,
+  isOriginAllowed,
+  unauthorized,
+} from "./security";
+import { handleCli } from "./cli";
 
-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";
+async function main(): Promise<void> {
+  const result = await handleCli(process.argv.slice(2));
+  if (result === "handled") return;
+  startServer();
+}
 
-initDb(DB_PATH);
+function startServer(): void {
+  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";
 
-setInterval(() => {
-  const reaped = reapStaleAgents(STALE_TTL_MS);
-  if (reaped.length > 0) {
-    console.log(`reaped ${reaped.length} stale agent(s)`);
-    for (const id of reaped) emitAgentStatus(id);
-  }
-  const pruned = pruneOfflineAgents(OFFLINE_PRUNE_MS);
-  if (pruned.length > 0) {
-    console.log(`pruned ${pruned.length} offline agent(s)`);
-    for (const id of pruned) emitAgentRemoved(id);
-  }
-}, REAP_INTERVAL_MS);
+  assertSafeNetworkConfig(HOST);
+  initDb(DB_PATH);
 
-// Daily message prune
-setInterval(() => {
-  const pruned = pruneOldMessages(RETENTION_DAYS * DAY_MS);
-  if (pruned > 0) console.log(`pruned ${pruned} old message(s)`);
-}, DAY_MS);
+  setInterval(() => {
+    const reaped = reapStaleAgents(STALE_TTL_MS);
+    if (reaped.length > 0) {
+      console.log(`reaped ${reaped.length} stale agent(s)`);
+      for (const id of reaped) emitAgentStatus(id);
+    }
+    const pruned = pruneOfflineAgents(OFFLINE_PRUNE_MS);
+    if (pruned.length > 0) {
+      console.log(`pruned ${pruned.length} offline agent(s)`);
+      for (const id of pruned) emitAgentRemoved(id);
+    }
+  }, REAP_INTERVAL_MS);
 
-const publicDir = resolve(import.meta.dir, "../public");
-const publicDirPrefix = publicDir + sep;
+  // Daily message prune
+  setInterval(() => {
+    const pruned = pruneOldMessages(RETENTION_DAYS * DAY_MS);
+    if (pruned > 0) console.log(`pruned ${pruned} old message(s)`);
+  }, DAY_MS);
 
-Bun.serve({
-  port: PORT,
-  hostname: HOST,
-  async fetch(req) {
-    const url = new URL(req.url);
+  const publicDir = resolve(import.meta.dir, "../public");
+  const publicDirPrefix = publicDir + sep;
 
-    // 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",
-        },
-      });
-    }
+  Bun.serve({
+    port: PORT,
+    hostname: HOST,
+    async fetch(req) {
+      const url = new URL(req.url);
 
-    // 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 },
-        );
+      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 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}`);
+      // 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 },
+          );
+        }
       }
-      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)) {
+      // 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 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 });
-    }
-    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 ${VERSION} running on http://${HOST}:${PORT}`);
+}
 
-console.log(`agent-relay ${VERSION} running on http://${HOST}:${PORT}`);
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/routes.ts

@@ -18,10 +18,23 @@ import {
   deleteMessage,
   getStats,
   getLatestMessageId,
+  ingestIntegrationEvent,
+  listTasks,
+  getTask,
+  listTaskEvents,
+  claimTask,
+  updateTaskStatus,
+  createCallbackDelivery,
+  finishCallbackDelivery,
   ValidationError,
 } from "./db";
-import type { RegisterAgentInput, SendMessageInput, PollQuery } from "./types";
-import { MAX_BODY_BYTES } from "./config";
+import type { IntegrationEventInput, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
+import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
+import {
+  getIntegrationAuth,
+  hasIntegrationScope,
+  isIntegrationAllowed,
+} from "./security";
 import {
   createSSEStream,
   emitNewMessage,
@@ -29,6 +42,7 @@ import {
   emitAgentRemoved,
   emitMessageClaimed,
   emitMessageDeleted,
+  emitTaskChanged,
 } from "./sse";
 
 type Handler = (
@@ -112,16 +126,227 @@ function parseQueryInt(
   return n;
 }
 
+const VALID_AGENT_STATUSES = ["online", "idle", "busy", "offline"] as const;
+const VALID_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
+const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "done", "failed", "canceled"] as const;
+const integrationRateBuckets = new Map<string, { windowStart: number; count: number }>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cleanString(
+  value: unknown,
+  field: string,
+  opts: { required?: boolean; max?: number } = {},
+): string | undefined {
+  if (value === undefined || value === null) {
+    if (opts.required) throw new ValidationError(`${field} required`);
+    return undefined;
+  }
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const trimmed = value.trim();
+  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
+  if (opts.max && trimmed.length > opts.max) {
+    throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
+  }
+  return trimmed || undefined;
+}
+
+function cleanNullableString(value: unknown, field: string, max: number): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  return cleanString(value, field, { max }) ?? null;
+}
+
+function cleanStringArray(value: unknown, field: string): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
+  const cleaned = value.map((item) => cleanString(item, `${field} item`, { max: 80 })).filter(Boolean) as string[];
+  if (cleaned.length > 50) throw new ValidationError(`${field} can contain at most 50 values`);
+  return [...new Set(cleaned)];
+}
+
+function cleanMeta(value: unknown): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("meta must be an object");
+  if (JSON.stringify(value).length > 8192) throw new ValidationError("meta is too large");
+  return value;
+}
+
+function cleanEnum<T extends readonly string[]>(
+  value: unknown,
+  field: string,
+  valid: T,
+  fallback?: T[number],
+): T[number] | undefined {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "string" || !valid.includes(value)) {
+    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
+  }
+  return value as T[number];
+}
+
+function cleanPositiveId(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError(`${field} must be a positive integer`);
+  }
+  return value;
+}
+
+function normalizeAgentInput(body: unknown): RegisterAgentInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const status = cleanString(body.status, "status", { max: 20 });
+  if (status && !VALID_AGENT_STATUSES.includes(status as any)) {
+    throw new ValidationError(`status must be one of: ${VALID_AGENT_STATUSES.join(", ")}`);
+  }
+  if (body.ready !== undefined && typeof body.ready !== "boolean") {
+    throw new ValidationError("ready must be a boolean");
+  }
+
+  const input: RegisterAgentInput = {
+    id: cleanString(body.id, "id", { required: true, max: 200 })!,
+    name: cleanString(body.name, "name", { required: true, max: 200 })!,
+    status: status as RegisterAgentInput["status"] | undefined,
+    ready: body.ready as boolean | undefined,
+  };
+
+  const label = cleanNullableString(body.label, "label", 120);
+  if (label !== undefined) input.label = label;
+  const tags = cleanStringArray(body.tags, "tags");
+  if (tags) input.tags = tags;
+  const capabilities = cleanStringArray(body.capabilities, "capabilities");
+  if (capabilities) input.capabilities = capabilities;
+  const machine = cleanString(body.machine, "machine", { max: 120 });
+  if (machine) input.machine = machine;
+  const rig = cleanString(body.rig, "rig", { max: 120 });
+  if (rig) input.rig = rig;
+  const meta = cleanMeta(body.meta);
+  if (meta) input.meta = meta;
+
+  return input;
+}
+
+function normalizeMessageInput(body: unknown): SendMessageInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const type = cleanString(body.type, "type", { max: 20 });
+  if (type && !VALID_MSG_TYPES.includes(type)) {
+    throw new ValidationError(`type must be one of: ${VALID_MSG_TYPES.join(", ")}`);
+  }
+  if (body.claimable !== undefined && typeof body.claimable !== "boolean") {
+    throw new ValidationError("claimable must be a boolean");
+  }
+
+  const input: SendMessageInput = {
+    from: cleanString(body.from, "from", { required: true, max: 200 })!,
+    to: cleanString(body.to, "to", { required: true, max: 200 })!,
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    type: type as SendMessageInput["type"] | undefined,
+    replyTo: cleanPositiveId(body.replyTo, "replyTo"),
+    claimable: body.claimable as boolean | undefined,
+  };
+
+  const channel = cleanString(body.channel, "channel", { max: 120 });
+  if (channel) input.channel = channel;
+  const subject = cleanString(body.subject, "subject", { max: 200 });
+  if (subject) input.subject = subject;
+  const meta = cleanMeta(body.meta);
+  if (meta) input.meta = meta;
+
+  return input;
+}
+
+function normalizeIntegrationEvent(body: unknown): IntegrationEventInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const status = cleanEnum(body.status, "status", [...VALID_TASK_STATUSES, "resolved"] as const);
+  return {
+    source: cleanString(body.source, "source", { max: 120 }),
+    type: cleanString(body.type, "type", { max: 80 }) ?? "event",
+    severity: cleanEnum(body.severity, "severity", VALID_TASK_SEVERITIES, "info"),
+    status,
+    title: cleanString(body.title, "title", { required: true, max: 240 })!,
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    target: cleanString(body.target, "target", { required: true, max: 200 })!,
+    channel: cleanString(body.channel, "channel", { max: 120 }),
+    dedupeKey: cleanString(body.dedupeKey, "dedupeKey", { max: 240 }),
+    externalUrl: cleanString(body.externalUrl, "externalUrl", { max: 1000 }),
+    metadata: cleanMeta(body.metadata),
+  };
+}
+
+function normalizeTaskStatusInput(body: unknown): TaskStatusInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const status = cleanEnum(body.status, "status", VALID_TASK_STATUSES);
+  if (!status) throw new ValidationError("status required");
+  return {
+    status: status as TaskStatus,
+    agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    result: cleanString(body.result, "result", { max: MAX_BODY_BYTES }),
+    body: cleanString(body.body, "body", { max: MAX_BODY_BYTES }),
+    metadata: cleanMeta(body.metadata),
+  };
+}
+
+function checkIntegrationRateLimit(name: string): boolean {
+  const now = Date.now();
+  const windowMs = 60_000;
+  const bucket = integrationRateBuckets.get(name);
+  if (!bucket || now - bucket.windowStart >= windowMs) {
+    integrationRateBuckets.set(name, { windowStart: now, count: 1 });
+    return true;
+  }
+  bucket.count += 1;
+  return bucket.count <= INTEGRATION_RATE_LIMIT_PER_MINUTE;
+}
+
+async function dispatchTaskCallbacks(taskId: number, eventType: string): Promise<void> {
+  const task = getTask(taskId);
+  if (!task) return;
+  const integrations = getIntegrationTokens()
+    .filter((integration) => integration.name === task.source)
+    .filter((integration) => integration.callbackUrl)
+    .filter((integration) => !integration.targets?.length || integration.targets.includes(task.target))
+    .filter((integration) => !integration.channels?.length || !task.channel || integration.channels.includes(task.channel));
+
+  for (const integration of integrations) {
+    const payload = { event: eventType, task };
+    const deliveryId = createCallbackDelivery(task.id, integration.callbackUrl!, eventType, payload);
+    void postCallback(deliveryId, integration.callbackUrl!, payload);
+  }
+}
+
+async function postCallback(deliveryId: number, url: string, payload: unknown): Promise<void> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    finishCallbackDelivery(deliveryId, response.ok, response.ok ? undefined : `${response.status} ${response.statusText}`);
+  } catch (e) {
+    finishCallbackDelivery(deliveryId, false, e instanceof Error ? e.message : String(e));
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 // --- Agent routes ---
 
 const postAgent: Handler = async (req) => {
-  const parsed = await parseBody<RegisterAgentInput>(req);
+  const parsed = await parseBody<unknown>(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");
-  const agent = upsertAgent(body);
-  emitAgentStatus(agent.id);
-  return json(agent, 201);
+  try {
+    const agent = upsertAgent(normalizeAgentInput(parsed.body));
+    emitAgentStatus(agent.id);
+    return json(agent, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
 };
 
 const getAgents: Handler = (req) => {
@@ -196,17 +421,10 @@ const deleteAgentById: Handler = (_req, params) => {
 const VALID_MSG_TYPES = ["message", "system"];
 
 const postMessage: Handler = async (req) => {
-  const parsed = await parseBody<SendMessageInput>(req);
+  const parsed = await parseBody<unknown>(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");
-  }
-  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);
+    const msg = sendMessage(normalizeMessageInput(parsed.body));
     emitNewMessage(msg);
     return json(msg, 201);
   } catch (e) {
@@ -299,6 +517,10 @@ const postClaimMessage: Handler = async (req, params) => {
   const result = claimMessage(id, body.agentId);
   if (result.ok) {
     emitMessageClaimed(id, body.agentId);
+    if (result.task) {
+      emitTaskChanged(result.task, "task.claimed");
+      void dispatchTaskCallbacks(result.task.id, "task.claimed");
+    }
     return json({ ok: true });
   }
   const status =
@@ -329,6 +551,94 @@ const deleteMessageById: Handler = (_req, params) => {
 
 const getCursorRoute: Handler = () => json({ latestId: getLatestMessageId() });
 
+// --- Tasks and integrations ---
+
+const postIntegrationEvent: Handler = async (req) => {
+  const auth = getIntegrationAuth(req);
+  if (!auth) return error("integration token required", 401);
+  if (!checkIntegrationRateLimit(auth.name)) return error("integration rate limit exceeded", 429);
+  if (!hasIntegrationScope(auth, "tasks:create") && !hasIntegrationScope(auth, "events:create")) {
+    return error("integration token missing tasks:create scope", 403);
+  }
+
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const input = { ...normalizeIntegrationEvent(parsed.body), source: auth.name };
+    if (!isIntegrationAllowed(auth, { target: input.target, channel: input.channel })) {
+      return error("integration token cannot target this task", 403);
+    }
+    const result = ingestIntegrationEvent(input, auth.name);
+    if (result.message) emitNewMessage(result.message);
+    emitTaskChanged(result.task, result.created ? "task.created" : "task.updated");
+    void dispatchTaskCallbacks(result.task.id, result.created ? "task.created" : "task.updated");
+    return json(result, result.created ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getTasks: Handler = (req) => {
+  const url = new URL(req.url);
+  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");
+  return json(listTasks({
+    status: url.searchParams.get("status") ?? undefined,
+    source: url.searchParams.get("source") ?? undefined,
+    target: url.searchParams.get("target") ?? undefined,
+    limit: limitRaw ?? 100,
+  }));
+};
+
+const getTaskById: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const task = getTask(id);
+  return task ? json(task) : error("task not found", 404);
+};
+
+const getTaskEvents: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  if (!getTask(id)) return error("task not found", 404);
+  return json(listTaskEvents(id));
+};
+
+const postClaimTask: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<{ agentId: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const agentId = parsed.body?.agentId;
+  if (!agentId) return error("agentId required");
+  const result = claimTask(id, agentId);
+  if (!result.ok) {
+    const status = result.error === "task not found" ? 404 : result.error?.includes("race") ? 409 : 400;
+    return error(result.error!, status);
+  }
+  emitTaskChanged(result.task!, "task.claimed");
+  void dispatchTaskCallbacks(id, "task.claimed");
+  return json(result.task);
+};
+
+const patchTaskStatus: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = updateTaskStatus(id, normalizeTaskStatusInput(parsed.body));
+    if (!result.ok) return error(result.error!, result.error === "task not found" ? 404 : 400);
+    emitTaskChanged(result.task!, "task.status");
+    void dispatchTaskCallbacks(id, "task.status");
+    return json({ task: result.task, event: result.event });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 // --- SSE ---
 
 const getEvents: Handler = (req) => {
@@ -384,6 +694,13 @@ const routes: Route[] = [
   route("PATCH", "/api/messages/:id", patchMessage),
   route("DELETE", "/api/messages/:id", deleteMessageById),
 
+  route("POST", "/api/integrations/events", postIntegrationEvent),
+  route("GET", "/api/tasks", getTasks),
+  route("GET", "/api/tasks/:id", getTaskById),
+  route("GET", "/api/tasks/:id/events", getTaskEvents),
+  route("POST", "/api/tasks/:id/claim", postClaimTask),
+  route("PATCH", "/api/tasks/:id/status", patchTaskStatus),
+
   route("GET", "/api/events", getEvents),
   route("GET", "/api/stats", getStatsRoute),
 ];