agent-relay-server 0.4.22 → 0.4.24

package/src/routes.ts

@@ -36,12 +36,20 @@ import {
   rejectPair,
   endPair,
   sendPairMessage,
+  getInboxState,
+  setInboxThreadState,
+  setInboxDraft,
+  deleteInboxDraft,
+  listActivityEvents,
+  createActivityEvent,
   createCallbackDelivery,
   finishCallbackDelivery,
+  reapStaleAgents,
+  releaseExpiredClaims,
   validateAgentSession,
   ValidationError,
 } from "./db";
-import type { AgentSessionGuard, CreatePairInput, IntegrationEventInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
+import type { ActivityEventInput, ActivityKind, AgentSessionGuard, CreatePairInput, IntegrationEventInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
 import {
   getIntegrationAuth,
@@ -54,6 +62,7 @@ import {
   emitAgentStatus,
   emitAgentRemoved,
   emitMessageClaimed,
+  emitMessageClaimReleased,
   emitMessageDeleted,
   emitTaskChanged,
 } from "./sse";
@@ -143,6 +152,7 @@ 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 VALID_PAIR_STATUSES = ["pending", "active", "ended", "rejected", "expired"] as const;
+const VALID_ACTIVITY_KINDS = ["message", "reply", "question", "operator", "pair", "task", "state"] as const;
 const integrationRateBuckets = new Map<string, { windowStart: number; count: number }>();
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -209,6 +219,15 @@ function cleanPositiveId(value: unknown, field: string): number | undefined {
   return value;
 }
 
+function cleanNullablePositiveId(value: unknown, field: string): number | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError(`${field} must be a positive integer or null`);
+  }
+  return value;
+}
+
 function cleanEpoch(value: unknown, field: string): number | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
@@ -370,6 +389,70 @@ function normalizePairMessageInput(body: unknown): PairMessageInput {
   };
 }
 
+function cleanOperatorId(value: unknown): string {
+  return cleanString(value, "operatorId", { max: 200 }) || "user";
+}
+
+function normalizeInboxThreadStateInput(body: unknown): {
+  operatorId: string;
+  peerId: string;
+  readCursorMessageId?: number | null;
+  archivedAtMessageId?: number | null;
+} {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const input: {
+    operatorId: string;
+    peerId: string;
+    readCursorMessageId?: number | null;
+    archivedAtMessageId?: number | null;
+  } = {
+    operatorId: cleanOperatorId(body.operatorId),
+    peerId: cleanString(body.peerId, "peerId", { required: true, max: 200 })!,
+  };
+  const readCursorMessageId = cleanNullablePositiveId(body.readCursorMessageId, "readCursorMessageId");
+  if (readCursorMessageId !== undefined) input.readCursorMessageId = readCursorMessageId;
+  const archivedAtMessageId = cleanNullablePositiveId(body.archivedAtMessageId, "archivedAtMessageId");
+  if (archivedAtMessageId !== undefined) input.archivedAtMessageId = archivedAtMessageId;
+  return input;
+}
+
+function normalizeInboxDraftInput(body: unknown): {
+  operatorId: string;
+  peerId: string;
+  body: string;
+  subject?: string;
+  channel?: string;
+} {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    operatorId: cleanOperatorId(body.operatorId),
+    peerId: cleanString(body.peerId, "peerId", { required: true, max: 200 })!,
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    subject: cleanString(body.subject, "subject", { max: 200 }),
+    channel: cleanString(body.channel, "channel", { max: 120 }),
+  };
+}
+
+function normalizeActivityInput(body: unknown): ActivityEventInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    operatorId: cleanOperatorId(body.operatorId),
+    clientId: cleanString(body.clientId, "clientId", { max: 240 }),
+    kind: cleanEnum(body.kind, "kind", VALID_ACTIVITY_KINDS, "operator") as ActivityKind,
+    title: cleanString(body.title, "title", { required: true, max: 200 })!,
+    body: cleanString(body.body, "body", { max: 1000 }),
+    meta: cleanString(body.meta, "meta", { max: 500 }),
+    icon: cleanString(body.icon, "icon", { max: 80 }),
+    view: cleanString(body.view, "view", { max: 80 }),
+    peer: cleanString(body.peer, "peer", { max: 200 }),
+    messageId: cleanPositiveId(body.messageId, "messageId"),
+    pairId: cleanString(body.pairId, "pairId", { max: 120 }),
+    taskId: cleanPositiveId(body.taskId, "taskId"),
+    agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    metadata: cleanMeta(body.metadata),
+  };
+}
+
 function pairErrorStatus(code: string): number {
   if (code === "not_found") return 404;
   if (code === "busy") return 409;
@@ -432,14 +515,39 @@ async function postCallback(deliveryId: number, url: string, payload: unknown):
   }
 }
 
+function auditEvent(input: ActivityEventInput): void {
+  try {
+    createActivityEvent({
+      ...input,
+      metadata: { source: "server", ...(input.metadata ?? {}) },
+    });
+  } catch {
+    // Audit trail writes must never block relay behavior.
+  }
+}
+
 // --- Agent routes ---
 
 const postAgent: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
-    const agent = upsertAgent(normalizeAgentInput(parsed.body));
+    const input = normalizeAgentInput(parsed.body);
+    const existing = getAgent(input.id);
+    const agent = upsertAgent(input);
     emitAgentStatus(agent.id);
+    if (!existing) {
+      auditEvent({
+        clientId: "server-agent-" + agent.id + "-registered",
+        kind: "state",
+        title: "Agent registered",
+        body: agent.name,
+        meta: agent.id,
+        icon: "ti-robot",
+        view: "agents",
+        agentId: agent.id,
+      });
+    }
     return json(agent, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -485,6 +593,15 @@ const patchAgentStatus: Handler = async (req, params) => {
     throw e;
   }
   emitAgentStatus(params.id!);
+  auditEvent({
+    clientId: "server-agent-" + params.id! + "-status-" + body.status + "-" + Date.now(),
+    kind: "state",
+    title: "Agent " + body.status,
+    meta: params.id!,
+    icon: body.status === "offline" ? "ti-plug-off" : "ti-activity",
+    view: "agents",
+    agentId: params.id!,
+  });
   return json({ ok: true });
 };
 
@@ -543,6 +660,15 @@ const patchAgentReady: Handler = async (req, params) => {
     throw e;
   }
   emitAgentStatus(params.id!);
+  auditEvent({
+    clientId: "server-agent-" + params.id! + "-ready-" + body.ready + "-" + Date.now(),
+    kind: "state",
+    title: body.ready ? "Agent ready" : "Agent not ready",
+    meta: params.id!,
+    icon: body.ready ? "ti-circle-check" : "ti-loader",
+    view: "agents",
+    agentId: params.id!,
+  });
   return json({ ok: true });
 };
 
@@ -569,7 +695,20 @@ const postMessage: Handler = async (req) => {
       input.idempotencyKey = cleanString(req.headers.get("Idempotency-Key") ?? undefined, "idempotencyKey", { max: 240 });
     }
     const result = sendMessageWithResult(input);
-    if (result.created) emitNewMessage(result.message);
+    if (result.created) {
+      emitNewMessage(result.message);
+      auditEvent({
+        clientId: "server-message-" + result.message.id,
+        kind: result.message.claimable ? "task" : "message",
+        title: result.message.claimable ? "Claimable message sent" : "Message sent",
+        body: result.message.subject || result.message.body,
+        meta: `${result.message.from} -> ${result.message.to}`,
+        icon: result.message.claimable ? "ti-hand-grab" : "ti-send",
+        view: "messages",
+        messageId: result.message.id,
+        agentId: result.message.from,
+      });
+    }
     return json(result.message, result.created ? 201 : 200);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -668,6 +807,17 @@ const postClaimMessage: Handler = async (req, params) => {
   const result = claimMessage(id, body.agentId, guard);
   if (result.ok) {
     emitMessageClaimed(id, body.agentId, getMessage(id)?.claimExpiresAt);
+    auditEvent({
+      clientId: "server-message-" + id + "-claimed-" + body.agentId,
+      kind: "task",
+      title: "Message claimed",
+      body: "Message #" + id,
+      meta: "by " + body.agentId,
+      icon: "ti-user-check",
+      view: "work",
+      messageId: id,
+      agentId: body.agentId,
+    });
     if (result.task) {
       emitTaskChanged(result.task, "task.claimed");
       void dispatchTaskCallbacks(result.task.id, "task.claimed");
@@ -730,6 +880,80 @@ const deleteMessageById: Handler = (_req, params) => {
 
 const getCursorRoute: Handler = () => json({ latestId: getLatestMessageId() });
 
+// --- Inbox operator state ---
+
+const getInboxStateRoute: Handler = (req) => {
+  const url = new URL(req.url);
+  const operatorId = cleanOperatorId(url.searchParams.get("operatorId") ?? undefined);
+  return json(getInboxState(operatorId));
+};
+
+const patchInboxThreadState: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(setInboxThreadState(normalizeInboxThreadStateInput(parsed.body)));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const putInboxDraft: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(setInboxDraft(normalizeInboxDraftInput(parsed.body)));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const deleteInboxDraftRoute: Handler = (req) => {
+  const url = new URL(req.url);
+  try {
+    const operatorId = cleanOperatorId(url.searchParams.get("operatorId") ?? undefined);
+    const peerId = cleanString(url.searchParams.get("peerId") ?? undefined, "peerId", { required: true, max: 200 })!;
+    deleteInboxDraft(operatorId, peerId);
+    return json({ ok: true });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+// --- Shared activity audit trail ---
+
+const getActivityEvents: Handler = (req) => {
+  const url = new URL(req.url);
+  try {
+    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 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");
+    return json(listActivityEvents({
+      operatorId: cleanString(url.searchParams.get("operatorId") ?? undefined, "operatorId", { max: 200 }),
+      limit: limitRaw ?? 200,
+      since: sinceRaw ?? undefined,
+    }));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postActivityEvent: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(createActivityEvent(normalizeActivityInput(parsed.body)), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 // --- Tasks and integrations ---
 
 const postIntegrationEvent: Handler = async (req) => {
@@ -804,6 +1028,17 @@ const postClaimTask: Handler = async (req, params) => {
     return error(result.error!, status);
   }
   emitTaskChanged(result.task!, "task.claimed");
+  auditEvent({
+    clientId: "server-task-" + id + "-claimed-" + agentId,
+    kind: "task",
+    title: "Task claimed",
+    body: result.task!.title,
+    meta: "by " + agentId,
+    icon: "ti-user-check",
+    view: "work",
+    taskId: id,
+    agentId,
+  });
   if (result.task!.messageId) {
     emitMessageClaimed(result.task!.messageId, agentId, getMessage(result.task!.messageId)?.claimExpiresAt);
   }
@@ -846,6 +1081,17 @@ const patchTaskStatus: Handler = async (req, params) => {
     const result = updateTaskStatus(id, normalizeTaskStatusInput(parsed.body));
     if (!result.ok) return error(result.error!, result.error === "task not found" ? 404 : agentSessionStatus(result.error));
     emitTaskChanged(result.task!, "task.status");
+    auditEvent({
+      clientId: "server-task-" + id + "-status-" + result.task!.status + "-" + Date.now(),
+      kind: "task",
+      title: "Task " + result.task!.status,
+      body: result.task!.title,
+      meta: result.task!.claimedBy ? "by " + result.task!.claimedBy : result.task!.target,
+      icon: "ti-arrows-exchange",
+      view: "work",
+      taskId: id,
+      agentId: result.task!.claimedBy,
+    });
     void dispatchTaskCallbacks(id, "task.status");
     return json({ task: result.task, event: result.event });
   } catch (e) {
@@ -863,6 +1109,17 @@ const postPair: Handler = async (req) => {
     const result = createPair(normalizeCreatePairInput(parsed.body));
     if (!result.ok) return pairError(result);
     emitNewMessage(result.invite);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-invited",
+      kind: "pair",
+      title: "Pair invited",
+      body: result.pair.objective,
+      meta: `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-link-plus",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.requesterId,
+    });
     return json({ pair: result.pair, invite: result.invite }, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -894,6 +1151,17 @@ const postAcceptPair: Handler = async (req, params) => {
     const result = acceptPair(params.id!, normalizePairActionInput(parsed.body));
     if (!result.ok) return pairError(result);
     for (const notice of result.notices) emitNewMessage(notice);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-accepted",
+      kind: "pair",
+      title: "Pair accepted",
+      body: result.pair.objective,
+      meta: `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-link",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.targetId,
+    });
     return json(result.pair);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -908,6 +1176,17 @@ const postRejectPair: Handler = async (req, params) => {
     const result = rejectPair(params.id!, normalizePairActionInput(parsed.body));
     if (!result.ok) return pairError(result);
     emitNewMessage(result.notice);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-rejected",
+      kind: "pair",
+      title: "Pair rejected",
+      body: result.pair.objective,
+      meta: `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-x",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.targetId,
+    });
     return json(result.pair);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -922,6 +1201,17 @@ const postHangupPair: Handler = async (req, params) => {
     const result = endPair(params.id!, normalizePairActionInput(parsed.body));
     if (!result.ok) return pairError(result);
     if (result.notice) emitNewMessage(result.notice);
+    auditEvent({
+      clientId: "server-pair-" + result.pair.id + "-ended-" + Date.now(),
+      kind: "pair",
+      title: "Pair ended",
+      body: result.pair.objective,
+      meta: result.pair.endedBy ? "by " + result.pair.endedBy : `${result.pair.requesterId} <-> ${result.pair.targetId}`,
+      icon: "ti-phone-off",
+      view: "pairs",
+      pairId: result.pair.id,
+      agentId: result.pair.endedBy,
+    });
     return json(result.pair);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -936,6 +1226,18 @@ const postPairMessage: Handler = async (req, params) => {
     const result = sendPairMessage(params.id!, normalizePairMessageInput(parsed.body));
     if (!result.ok) return pairError(result);
     emitNewMessage(result.message);
+    auditEvent({
+      clientId: "server-pair-message-" + result.message.id,
+      kind: "pair",
+      title: "Pair message sent",
+      body: result.message.subject || result.message.body,
+      meta: "from " + result.message.from,
+      icon: "ti-messages",
+      view: "pairs",
+      messageId: result.message.id,
+      pairId: result.pair.id,
+      agentId: result.message.from,
+    });
     return json({ pair: result.pair, message: result.message }, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -956,6 +1258,28 @@ const getEvents: Handler = (req) => {
 const getStatsRoute: Handler = () => json(getStats());
 const getHealthRoute: Handler = () => json(getHealth());
 
+const postSystemReap: Handler = () => {
+  const released = releaseExpiredClaims();
+  const reapedAgentIds = reapStaleAgents();
+  for (const id of released.messageIds) emitMessageClaimReleased(id);
+  for (const task of released.tasks) emitTaskChanged(task, "task.updated");
+  for (const id of reapedAgentIds) emitAgentStatus(id);
+  auditEvent({
+    clientId: "server-system-reap-" + Date.now(),
+    kind: "state",
+    title: "Maintenance reaper run",
+    body: `${reapedAgentIds.length} stale agent(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
+    icon: "ti-broom",
+    view: "activity",
+  });
+  return json({
+    ok: true,
+    reapedAgentIds,
+    releasedMessageIds: released.messageIds,
+    releasedTaskIds: released.tasks.map((task) => task.id),
+  });
+};
+
 // --- Router ---
 
 interface Route {
@@ -1001,6 +1325,14 @@ const routes: Route[] = [
   route("PATCH", "/api/messages/:id", patchMessage),
   route("DELETE", "/api/messages/:id", deleteMessageById),
 
+  route("GET", "/api/inbox/state", getInboxStateRoute),
+  route("PATCH", "/api/inbox/threads", patchInboxThreadState),
+  route("PUT", "/api/inbox/drafts", putInboxDraft),
+  route("DELETE", "/api/inbox/drafts", deleteInboxDraftRoute),
+
+  route("GET", "/api/activity", getActivityEvents),
+  route("POST", "/api/activity", postActivityEvent),
+
   route("POST", "/api/integrations/events", postIntegrationEvent),
   route("GET", "/api/tasks", getTasks),
   route("GET", "/api/tasks/:id", getTaskById),
@@ -1020,6 +1352,7 @@ const routes: Route[] = [
   route("GET", "/api/events", getEvents),
   route("GET", "/api/stats", getStatsRoute),
   route("GET", "/api/health", getHealthRoute),
+  route("POST", "/api/system/reap", postSystemReap),
 ];
 
 export function matchRoute(

package/src/security.ts

@@ -55,7 +55,7 @@ export function corsPreflight(req: Request): Response {
 
   const response = new Response(null, {
     headers: {
-      "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
+      "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
       "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Agent-Relay-Token, Idempotency-Key, X-Agent-Relay-Instance-Id, X-Agent-Relay-Epoch",
       "Access-Control-Max-Age": "600",
     },
@@ -97,6 +97,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/events") return "events:read";
   if (pathname.startsWith("/api/integrations/")) return method === "GET" ? "integrations:read" : "integrations:write";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agents:read" : "agents:write";
+  if (pathname.startsWith("/api/activity")) return method === "GET" ? "activity:read" : "activity:write";
+  if (pathname.startsWith("/api/inbox")) return method === "GET" ? "messages:read" : "messages:write";
   if (pathname.startsWith("/api/messages")) return method === "GET" ? "messages:read" : "messages:write";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "tasks:read" : "tasks:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";

package/src/types.ts

@@ -184,6 +184,67 @@ export interface TaskStatusInput {
   metadata?: Record<string, unknown>;
 }
 
+export interface InboxThreadState {
+  operatorId: string;
+  peerId: string;
+  readCursorMessageId?: number;
+  archivedAtMessageId?: number;
+  updatedAt: number;
+}
+
+export interface InboxDraft {
+  operatorId: string;
+  peerId: string;
+  body: string;
+  subject?: string;
+  channel?: string;
+  updatedAt: number;
+}
+
+export interface InboxState {
+  operatorId: string;
+  threads: InboxThreadState[];
+  drafts: InboxDraft[];
+}
+
+export type ActivityKind = "message" | "reply" | "question" | "operator" | "pair" | "task" | "state";
+
+export interface ActivityEvent {
+  id: number;
+  operatorId?: string;
+  clientId?: string;
+  kind: ActivityKind;
+  title: string;
+  body?: string;
+  meta?: string;
+  icon?: string;
+  view?: string;
+  peer?: string;
+  messageId?: number;
+  pairId?: string;
+  taskId?: number;
+  agentId?: string;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+}
+
+export interface ActivityEventInput {
+  operatorId?: string;
+  clientId?: string;
+  kind: ActivityKind;
+  title: string;
+  body?: string;
+  meta?: string;
+  icon?: string;
+  view?: string;
+  peer?: string;
+  messageId?: number;
+  pairId?: string;
+  taskId?: number;
+  agentId?: string;
+  metadata?: Record<string, unknown>;
+}
+
 export interface HealthCheck {
   name: string;
   status: "ok" | "warn" | "error";