agent-relay-server 0.4.23 → 0.4.24

package/src/db.ts

@@ -3,6 +3,8 @@ import { randomUUID } from "node:crypto";
 import { VERSION } from "./config.ts";
 import type {
   AgentCard,
+  ActivityEvent,
+  ActivityEventInput,
   AgentSessionGuard,
   CreatePairInput,
   HealthCheck,
@@ -168,6 +170,27 @@ export function initDb(path: string = "agent-relay.db"): Database {
       PRIMARY KEY (operator_id, peer_id)
     );
     CREATE INDEX IF NOT EXISTS idx_inbox_drafts_operator ON inbox_drafts(operator_id);
+
+    CREATE TABLE IF NOT EXISTS activity_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      operator_id TEXT,
+      client_id TEXT UNIQUE,
+      kind TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      meta_text TEXT,
+      icon TEXT,
+      view TEXT,
+      peer_id TEXT,
+      message_id INTEGER,
+      pair_id TEXT,
+      task_id INTEGER,
+      agent_id TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_activity_operator ON activity_events(operator_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_activity_created ON activity_events(created_at);
   `);
 
   // Migrations
@@ -438,6 +461,27 @@ function rowToInboxDraft(row: any): InboxDraft {
   };
 }
 
+function rowToActivityEvent(row: any): ActivityEvent {
+  return {
+    id: row.id,
+    operatorId: row.operator_id ?? undefined,
+    clientId: row.client_id ?? undefined,
+    kind: row.kind,
+    title: row.title,
+    body: row.body ?? undefined,
+    meta: row.meta_text ?? undefined,
+    icon: row.icon ?? undefined,
+    view: row.view ?? undefined,
+    peer: row.peer_id ?? undefined,
+    messageId: row.message_id ?? undefined,
+    pairId: row.pair_id ?? undefined,
+    taskId: row.task_id ?? undefined,
+    agentId: row.agent_id ?? undefined,
+    metadata: parseJson(row.metadata, {}),
+    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`;
@@ -1576,6 +1620,60 @@ export function deleteInboxDraft(operatorId: string, peerId: string): boolean {
   return db.prepare("DELETE FROM inbox_drafts WHERE operator_id = ? AND peer_id = ?").run(operatorId, peerId).changes > 0;
 }
 
+export function listActivityEvents(input: {
+  operatorId?: string;
+  limit?: number;
+  since?: number;
+} = {}): ActivityEvent[] {
+  const conditions: string[] = [];
+  const params: any[] = [];
+  if (input.operatorId) {
+    conditions.push("operator_id = ?");
+    params.push(input.operatorId);
+  }
+  if (input.since !== undefined) {
+    conditions.push("created_at >= ?");
+    params.push(input.since);
+  }
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  params.push(input.limit ?? 200);
+  return (db.prepare(
+    `SELECT * FROM activity_events ${where} ORDER BY created_at DESC, id DESC LIMIT ?`,
+  ).all(...params) as any[]).map(rowToActivityEvent);
+}
+
+export function createActivityEvent(input: ActivityEventInput): ActivityEvent {
+  if (input.clientId) {
+    const existing = db.prepare("SELECT * FROM activity_events WHERE client_id = ?").get(input.clientId) as any | undefined;
+    if (existing) return rowToActivityEvent(existing);
+  }
+  const now = Date.now();
+  const result = db.prepare(`
+    INSERT INTO activity_events (
+      operator_id, client_id, kind, title, body, meta_text, icon, view, peer_id,
+      message_id, pair_id, task_id, agent_id, metadata, created_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    input.operatorId ?? null,
+    input.clientId ?? null,
+    input.kind,
+    input.title,
+    input.body ?? null,
+    input.meta ?? null,
+    input.icon ?? null,
+    input.view ?? null,
+    input.peer ?? null,
+    input.messageId ?? null,
+    input.pairId ?? null,
+    input.taskId ?? null,
+    input.agentId ?? null,
+    JSON.stringify(input.metadata ?? {}),
+    now,
+  );
+  return rowToActivityEvent(db.prepare("SELECT * FROM activity_events WHERE id = ?").get(Number(result.lastInsertRowid)));
+}
+
 export function deleteMessage(id: number): boolean {
   return db.transaction(() => {
     // Break reply_to references from children so the FK doesn't block delete.

package/src/routes.ts

@@ -40,12 +40,16 @@ import {
   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,
@@ -58,6 +62,7 @@ import {
   emitAgentStatus,
   emitAgentRemoved,
   emitMessageClaimed,
+  emitMessageClaimReleased,
   emitMessageDeleted,
   emitTaskChanged,
 } from "./sse";
@@ -147,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> {
@@ -427,6 +433,26 @@ function normalizeInboxDraftInput(body: unknown): {
   };
 }
 
+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;
@@ -489,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);
@@ -542,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 });
 };
 
@@ -600,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 });
 };
 
@@ -626,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);
@@ -725,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");
@@ -830,6 +923,37 @@ const deleteInboxDraftRoute: Handler = (req) => {
   }
 };
 
+// --- 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) => {
@@ -904,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);
   }
@@ -946,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) {
@@ -963,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);
@@ -994,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);
@@ -1008,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);
@@ -1022,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);
@@ -1036,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);
@@ -1056,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 {
@@ -1106,6 +1330,9 @@ const routes: Route[] = [
   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),
@@ -1125,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

@@ -97,6 +97,7 @@ 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";

package/src/types.ts

@@ -207,6 +207,44 @@ export interface InboxState {
   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";