agent-relay-server 0.4.15 → 0.4.17

package/src/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages } from "./db";
+import { initDb, reapStaleAgents, pruneOfflineAgents, pruneOldMessages, releaseExpiredClaims } from "./db";
 import { matchRoute } from "./routes";
-import { emitAgentStatus, emitAgentRemoved } from "./sse";
+import { emitAgentStatus, emitAgentRemoved, emitMessageClaimReleased, emitTaskChanged } from "./sse";
 import { resolve, sep } from "path";
 import {
   REAP_INTERVAL_MS,
@@ -14,8 +14,10 @@ import {
   applyCors,
   assertSafeNetworkConfig,
   corsPreflight,
+  forbidden,
   getIntegrationAuth,
   isAuthorized,
+  isScopedRequestAuthorized,
   isOriginAllowed,
   unauthorized,
 } from "./security";
@@ -38,6 +40,13 @@ function startServer(): void {
   initDb(DB_PATH);
 
   setInterval(() => {
+    const released = releaseExpiredClaims();
+    if (released.messageIds.length > 0 || released.tasks.length > 0) {
+      console.log(`released ${released.messageIds.length} expired message claim(s), ${released.tasks.length} expired task claim(s)`);
+      for (const id of released.messageIds) emitMessageClaimReleased(id);
+      for (const task of released.tasks) emitTaskChanged(task, "task.updated");
+    }
+
     const reaped = reapStaleAgents(STALE_TTL_MS);
     if (reaped.length > 0) {
       console.log(`reaped ${reaped.length} stale agent(s)`);
@@ -87,9 +96,10 @@ export function createFetchHandler(
     if (matched) {
       const integrationAuth = getIntegrationAuth(req);
       if (!isAuthorized(req)) {
-        if (!integrationAuth || !url.pathname.startsWith("/api/integrations/")) {
+        if (!integrationAuth) {
           return unauthorized(req);
         }
+        if (!isScopedRequestAuthorized(req)) return forbidden(req);
       }
       const response = await matched.handler(req, matched.params);
       applyCors(req, response);

package/src/routes.ts

@@ -5,10 +5,12 @@ import {
   findAgentsByCapability,
   setStatus,
   setLabel,
+  setTags,
   markReady,
   heartbeat,
   deleteAgent,
   sendMessage,
+  sendMessageWithResult,
   getMessage,
   getThread,
   claimMessage,
@@ -17,18 +19,29 @@ import {
   markRead,
   deleteMessage,
   getStats,
+  getHealth,
   getLatestMessageId,
   ingestIntegrationEvent,
   listTasks,
   getTask,
   listTaskEvents,
   claimTask,
+  renewTaskClaim,
   updateTaskStatus,
+  renewMessageClaim,
+  createPair,
+  getPair,
+  listPairs,
+  acceptPair,
+  rejectPair,
+  endPair,
+  sendPairMessage,
   createCallbackDelivery,
   finishCallbackDelivery,
+  validateAgentSession,
   ValidationError,
 } from "./db";
-import type { IntegrationEventInput, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
+import type { 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,
@@ -129,6 +142,7 @@ function parseQueryInt(
 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 integrationRateBuckets = new Map<string, { windowStart: number; count: number }>();
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -195,6 +209,33 @@ function cleanPositiveId(value: unknown, field: string): number | undefined {
   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) {
+    throw new ValidationError(`${field} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function normalizeAgentSessionGuard(req: Request, body: unknown): AgentSessionGuard | undefined {
+  const record = isRecord(body) ? body : {};
+  const headerInstance = req.headers.get("x-agent-relay-instance-id") ?? undefined;
+  const headerEpoch = req.headers.get("x-agent-relay-epoch") ?? undefined;
+  const instanceId = cleanString(headerInstance ?? record.instanceId, "instanceId", { max: 200 });
+  const rawEpoch = headerEpoch === undefined ? record.epoch : Number(headerEpoch);
+  const epoch = cleanEpoch(rawEpoch, "epoch");
+
+  if (!instanceId && epoch === undefined) return undefined;
+  if (!instanceId) throw new ValidationError("instanceId required when epoch is provided");
+  return { instanceId, epoch };
+}
+
+function agentSessionStatus(errorMessage: string | undefined): number {
+  if (errorMessage === "agent not found") return 404;
+  if (errorMessage === "stale agent instance") return 409;
+  return 400;
+}
+
 function normalizeAgentInput(body: unknown): RegisterAgentInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
   const status = cleanString(body.status, "status", { max: 20 });
@@ -222,6 +263,8 @@ function normalizeAgentInput(body: unknown): RegisterAgentInput {
   if (machine) input.machine = machine;
   const rig = cleanString(body.rig, "rig", { max: 120 });
   if (rig) input.rig = rig;
+  const instanceId = cleanString(body.instanceId, "instanceId", { max: 200 });
+  if (instanceId) input.instanceId = instanceId;
   const meta = cleanMeta(body.meta);
   if (meta) input.meta = meta;
 
@@ -245,6 +288,7 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
     type: type as SendMessageInput["type"] | undefined,
     replyTo: cleanPositiveId(body.replyTo, "replyTo"),
     claimable: body.claimable as boolean | undefined,
+    idempotencyKey: cleanString(body.idempotencyKey, "idempotencyKey", { max: 240 }),
   };
 
   const channel = cleanString(body.channel, "channel", { max: 120 });
@@ -282,12 +326,66 @@ function normalizeTaskStatusInput(body: unknown): TaskStatusInput {
   return {
     status: status as TaskStatus,
     agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    instanceId: cleanString(body.instanceId, "instanceId", { max: 200 }),
+    epoch: cleanEpoch(body.epoch, "epoch"),
     result: cleanString(body.result, "result", { max: MAX_BODY_BYTES }),
     body: cleanString(body.body, "body", { max: MAX_BODY_BYTES }),
     metadata: cleanMeta(body.metadata),
   };
 }
 
+function cleanTtlMs(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError("ttlMs must be a positive integer");
+  }
+  return value;
+}
+
+function normalizeCreatePairInput(body: unknown): CreatePairInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    from: cleanString(body.from, "from", { required: true, max: 200 })!,
+    target: cleanString(body.target, "target", { required: true, max: 200 })!,
+    objective: cleanString(body.objective, "objective", { max: 2000 }),
+    ttlMs: cleanTtlMs(body.ttlMs),
+    meta: cleanMeta(body.meta),
+  };
+}
+
+function normalizePairActionInput(body: unknown): PairActionInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    agentId: cleanString(body.agentId, "agentId", { required: true, max: 200 })!,
+    reason: cleanString(body.reason, "reason", { max: 1000 }),
+  };
+}
+
+function normalizePairMessageInput(body: unknown): PairMessageInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    from: cleanString(body.from, "from", { required: true, max: 200 })!,
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    subject: cleanString(body.subject, "subject", { max: 200 }),
+  };
+}
+
+function pairErrorStatus(code: string): number {
+  if (code === "not_found") return 404;
+  if (code === "busy") return 409;
+  if (code === "ambiguous") return 409;
+  if (code === "forbidden") return 403;
+  return 400;
+}
+
+function pairError(result: { error: string; code: string; matches?: unknown[]; busy?: unknown[] }): Response {
+  return json({
+    error: result.error,
+    ...(result.matches ? { matches: result.matches } : {}),
+    ...(result.busy ? { busy: result.busy } : {}),
+  }, pairErrorStatus(result.code));
+}
+
 function checkIntegrationRateLimit(name: string): boolean {
   const now = Date.now();
   const windowMs = 60_000;
@@ -377,13 +475,31 @@ const patchAgentStatus: Handler = async (req, params) => {
   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(", ")}`);
-  if (!setStatus(params.id!, body.status as any)) return error("agent not found", 404);
+  try {
+    const guard = normalizeAgentSessionGuard(req, body);
+    const session = validateAgentSession(params.id!, guard);
+    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    if (!setStatus(params.id!, body.status as any, guard)) return error("agent not found", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
   emitAgentStatus(params.id!);
   return json({ ok: true });
 };
 
-const postHeartbeat: Handler = (_req, params) => {
-  return heartbeat(params.id!) ? json({ ok: true }) : error("agent not found", 404);
+const postHeartbeat: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const guard = normalizeAgentSessionGuard(req, parsed.body);
+    const session = validateAgentSession(params.id!, guard);
+    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    return heartbeat(params.id!, guard) ? json({ ok: true }) : error("agent not found", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
 };
 
 const patchAgentLabel: Handler = async (req, params) => {
@@ -396,12 +512,36 @@ const patchAgentLabel: Handler = async (req, params) => {
   return json({ ok: true });
 };
 
+const patchAgentTags: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const tags = isRecord(parsed.body) ? cleanStringArray(parsed.body.tags, "tags") : undefined;
+    if (!tags) return error("tags field required");
+    const agent = setTags(params.id!, tags);
+    if (!agent) return error("agent not found", 404);
+    emitAgentStatus(params.id!);
+    return json(agent);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 const patchAgentReady: Handler = async (req, params) => {
   const parsed = await parseBody<{ ready: boolean }>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
   if (body === null || typeof body.ready !== "boolean") return error("ready field required (boolean)");
-  if (!markReady(params.id!, body.ready)) return error("agent not found", 404);
+  try {
+    const guard = normalizeAgentSessionGuard(req, body);
+    const session = validateAgentSession(params.id!, guard);
+    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    if (!markReady(params.id!, body.ready, guard)) return error("agent not found", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
   emitAgentStatus(params.id!);
   return json({ ok: true });
 };
@@ -424,9 +564,13 @@ const postMessage: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
-    const msg = sendMessage(normalizeMessageInput(parsed.body));
-    emitNewMessage(msg);
-    return json(msg, 201);
+    const input = normalizeMessageInput(parsed.body);
+    if (!input.idempotencyKey) {
+      input.idempotencyKey = cleanString(req.headers.get("Idempotency-Key") ?? undefined, "idempotencyKey", { max: 240 });
+    }
+    const result = sendMessageWithResult(input);
+    if (result.created) emitNewMessage(result.message);
+    return json(result.message, result.created ? 201 : 200);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -514,9 +658,16 @@ const postClaimMessage: Handler = async (req, params) => {
   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);
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = claimMessage(id, body.agentId, guard);
   if (result.ok) {
-    emitMessageClaimed(id, body.agentId);
+    emitMessageClaimed(id, body.agentId, getMessage(id)?.claimExpiresAt);
     if (result.task) {
       emitTaskChanged(result.task, "task.claimed");
       void dispatchTaskCallbacks(result.task.id, "task.claimed");
@@ -531,6 +682,34 @@ const postClaimMessage: Handler = async (req, params) => {
   return error(result.error!, status);
 };
 
+const postRenewMessageClaim: 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 agentId = parsed.body?.agentId;
+  if (!agentId) return error("agentId required");
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, parsed.body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = renewMessageClaim(id, agentId, guard);
+  if (!result.ok) {
+    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);
+  }
+  emitMessageClaimed(id, agentId, getMessage(id)?.claimExpiresAt);
+  if (result.task) emitTaskChanged(result.task, "task.updated");
+  return json({ ok: true, claimExpiresAt: getMessage(id)?.claimExpiresAt });
+};
+
 const patchMessage: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid message id");
@@ -612,16 +791,52 @@ const postClaimTask: Handler = async (req, params) => {
   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);
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, parsed.body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = claimTask(id, agentId, guard);
   if (!result.ok) {
-    const status = result.error === "task not found" ? 404 : result.error?.includes("race") ? 409 : 400;
+    const status = result.error === "task not found" ? 404 : result.error?.includes("race") || result.error === "stale agent instance" ? 409 : 400;
     return error(result.error!, status);
   }
   emitTaskChanged(result.task!, "task.claimed");
+  if (result.task!.messageId) {
+    emitMessageClaimed(result.task!.messageId, agentId, getMessage(result.task!.messageId)?.claimExpiresAt);
+  }
   void dispatchTaskCallbacks(id, "task.claimed");
   return json(result.task);
 };
 
+const postRenewTaskClaim: 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");
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, parsed.body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = renewTaskClaim(id, agentId, guard);
+  if (!result.ok) {
+    const status = result.error === "task not found" ? 404 : 409;
+    return error(result.error!, status);
+  }
+  emitTaskChanged(result.task!, "task.updated");
+  if (result.task!.messageId) {
+    emitMessageClaimed(result.task!.messageId, agentId, getMessage(result.task!.messageId)?.claimExpiresAt);
+  }
+  return json(result.task);
+};
+
 const patchTaskStatus: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
@@ -629,7 +844,7 @@ const patchTaskStatus: Handler = async (req, params) => {
   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);
+    if (!result.ok) return error(result.error!, result.error === "task not found" ? 404 : agentSessionStatus(result.error));
     emitTaskChanged(result.task!, "task.status");
     void dispatchTaskCallbacks(id, "task.status");
     return json({ task: result.task, event: result.event });
@@ -639,6 +854,95 @@ const patchTaskStatus: Handler = async (req, params) => {
   }
 };
 
+// --- Pair sessions ---
+
+const postPair: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = createPair(normalizeCreatePairInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    emitNewMessage(result.invite);
+    return json({ pair: result.pair, invite: result.invite }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getPairs: Handler = (req) => {
+  const url = new URL(req.url);
+  const status = url.searchParams.get("status") ?? undefined;
+  if (status && !VALID_PAIR_STATUSES.includes(status as any)) {
+    return error(`status must be one of: ${VALID_PAIR_STATUSES.join(", ")}`);
+  }
+  return json(listPairs({
+    agentId: url.searchParams.get("agent") ?? undefined,
+    status: status as PairStatus | undefined,
+  }));
+};
+
+const getPairById: Handler = (_req, params) => {
+  const pair = getPair(params.id!);
+  return pair ? json(pair) : error("pair not found", 404);
+};
+
+const postAcceptPair: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = acceptPair(params.id!, normalizePairActionInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    for (const notice of result.notices) emitNewMessage(notice);
+    return json(result.pair);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postRejectPair: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = rejectPair(params.id!, normalizePairActionInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    emitNewMessage(result.notice);
+    return json(result.pair);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postHangupPair: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = endPair(params.id!, normalizePairActionInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    if (result.notice) emitNewMessage(result.notice);
+    return json(result.pair);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postPairMessage: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = sendPairMessage(params.id!, normalizePairMessageInput(parsed.body));
+    if (!result.ok) return pairError(result);
+    emitNewMessage(result.message);
+    return json({ pair: result.pair, message: result.message }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 // --- SSE ---
 
 const getEvents: Handler = (req) => {
@@ -650,6 +954,7 @@ const getEvents: Handler = (req) => {
 // --- Stats ---
 
 const getStatsRoute: Handler = () => json(getStats());
+const getHealthRoute: Handler = () => json(getHealth());
 
 // --- Router ---
 
@@ -681,6 +986,7 @@ const routes: Route[] = [
   route("PATCH", "/api/agents/:id/status", patchAgentStatus),
   route("PATCH", "/api/agents/:id/ready", patchAgentReady),
   route("PATCH", "/api/agents/:id/label", patchAgentLabel),
+  route("PATCH", "/api/agents/:id/tags", patchAgentTags),
   route("POST", "/api/agents/:id/heartbeat", postHeartbeat),
   route("DELETE", "/api/agents/:id", deleteAgentById),
 
@@ -691,6 +997,7 @@ const routes: Route[] = [
   route("GET", "/api/messages/:id", getMessageById),
   route("GET", "/api/messages/:id/thread", getMessageThread),
   route("POST", "/api/messages/:id/claim", postClaimMessage),
+  route("POST", "/api/messages/:id/claim/renew", postRenewMessageClaim),
   route("PATCH", "/api/messages/:id", patchMessage),
   route("DELETE", "/api/messages/:id", deleteMessageById),
 
@@ -699,10 +1006,20 @@ const routes: Route[] = [
   route("GET", "/api/tasks/:id", getTaskById),
   route("GET", "/api/tasks/:id/events", getTaskEvents),
   route("POST", "/api/tasks/:id/claim", postClaimTask),
+  route("POST", "/api/tasks/:id/claim/renew", postRenewTaskClaim),
   route("PATCH", "/api/tasks/:id/status", patchTaskStatus),
 
+  route("POST", "/api/pairs", postPair),
+  route("GET", "/api/pairs", getPairs),
+  route("GET", "/api/pairs/:id", getPairById),
+  route("POST", "/api/pairs/:id/accept", postAcceptPair),
+  route("POST", "/api/pairs/:id/reject", postRejectPair),
+  route("POST", "/api/pairs/:id/hangup", postHangupPair),
+  route("POST", "/api/pairs/:id/messages", postPairMessage),
+
   route("GET", "/api/events", getEvents),
   route("GET", "/api/stats", getStatsRoute),
+  route("GET", "/api/health", getHealthRoute),
 ];
 
 export function matchRoute(

package/src/security.ts

@@ -45,7 +45,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-Headers": "Content-Type, Authorization, X-Agent-Relay-Token",
+      "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",
     },
   });
@@ -80,6 +80,36 @@ export function isIntegrationAllowed(
   return true;
 }
 
+export function requiredScopeFor(method: string, pathname: string): string | null {
+  if (pathname === "/api/stats") return "stats:read";
+  if (pathname === "/api/health") return "health:read";
+  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/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";
+  if (pathname.startsWith("/api/system/")) return "system:write";
+  return null;
+}
+
+export function isScopedRequestAuthorized(req: Request): boolean {
+  const auth = getIntegrationAuth(req);
+  if (!auth) return false;
+  const pathname = new URL(req.url).pathname;
+  if (pathname.startsWith("/api/integrations/") && req.method !== "GET") {
+    return hasIntegrationScope(auth, "integrations:write") ||
+      hasIntegrationScope(auth, "tasks:create") ||
+      hasIntegrationScope(auth, "events:create");
+  }
+  const scope = requiredScopeFor(req.method, pathname);
+  return scope ? hasIntegrationScope(auth, scope) : false;
+}
+
+export function forbidden(req: Request): Response {
+  return applyCors(req, Response.json({ error: "forbidden" }, { status: 403 }));
+}
+
 export function unauthorized(req: Request): Response {
   const response = Response.json({ error: "unauthorized" }, { status: 401 });
   response.headers.set("WWW-Authenticate", "Bearer");

package/src/sse.ts

@@ -97,9 +97,15 @@ export function emitAgentRemoved(agentId: string) {
   }
 }
 
-export function emitMessageClaimed(messageId: number, claimedBy: string) {
+export function emitMessageClaimed(messageId: number, claimedBy: string, claimExpiresAt?: number) {
   for (const conn of connections.values()) {
-    send(conn, "message.claimed", { messageId, claimedBy });
+    send(conn, "message.claimed", { messageId, claimedBy, claimExpiresAt });
+  }
+}
+
+export function emitMessageClaimReleased(messageId: number) {
+  for (const conn of connections.values()) {
+    send(conn, "message.claim_released", { messageId });
   }
 }