@desplega.ai/agent-swarm 2.3.0 → 2.4.1

package/src/http/core.ts

@@ -47,6 +47,14 @@ import { refreshSecretScrubberCache, registerSensitiveKeyName } from "../utils/s
 import { resolveHttpRequestAuth } from "./auth";
 import { generateOpenApiSpec, SCALAR_HTML } from "./openapi";
 import { findRoute, isPublicRoute, route, runtimeInstanceHeader } from "./route-def";
+import {
+  canReadSession,
+  pathSessionDenial,
+  readableByFor,
+  resolveSessionActor,
+  SESSION_READ_DENIED,
+  userAgentIdentityDenial,
+} from "./session-access";
 import {
   agentWithCapacity,
   duplicateGuardedQueryKey,
@@ -503,6 +511,15 @@ export async function handleCore(
     setRequestAuth(req, auth);
   }
 
+  // A user token never gains agent identity from X-Agent-ID, on /mcp, /api/poll
+  // or any worker-header route.
+  const routeDef = findRoute(req.method, pathSegments);
+  const agentIdentityDenial = await userAgentIdentityDenial(req, routeDef, pathSegments);
+  if (agentIdentityDenial) {
+    jsonError(res, agentIdentityDenial, 403);
+    return true;
+  }
+
   if (auth?.kind === "agent") {
     const query = parseQueryParams(req.url || "");
     const duplicate = duplicateGuardedQueryKey(query);
@@ -565,7 +582,7 @@ export async function handleCore(
   if (auth?.kind === "user" && isRbacEnabled()) {
     const grant = await getUserGrant(auth.userId);
     if (!grant.grantsAll) {
-      const def = findRoute(req.method, pathSegments);
+      const def = routeDef;
       const decision = decideAdmission({
         method: req.method ?? "",
         rbac: def?.rbac,
@@ -585,6 +602,16 @@ export async function handleCore(
     }
   }
 
+  // Session access for every route keyed by a task or steering message, before
+  // its handler reads or changes anything (the route's `session` posture).
+  if (routeDef?.session) {
+    const sessionDenial = await pathSessionDenial(req, myAgentId, routeDef, pathSegments);
+    if (sessionDenial) {
+      jsonError(res, sessionDenial, 403);
+      return true;
+    }
+  }
+
   // POST /internal/reload-config — re-read swarm_config into process.env and re-init integrations
   if (req.method === "POST" && req.url === "/internal/reload-config") {
     try {
@@ -662,7 +689,14 @@ export async function handleCore(
     const queryParams = parseQueryParams(req.url || "");
     const taskId = queryParams.get("taskId");
 
+    // A user token naming an agent in X-Agent-ID still reads only its sessions.
+    const sessionActor = await resolveSessionActor(req, myAgentId);
     if (taskId) {
+      if (!(await canReadSession(req, myAgentId, taskId))) {
+        res.writeHead(403, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: SESSION_READ_DENIED }));
+        return true;
+      }
       // Check if specific task is cancelled
       const task = await getTaskById(taskId);
       if (task && task.status === "cancelled") {
@@ -687,7 +721,10 @@ export async function handleCore(
     }
 
     // No taskId - return all recently cancelled tasks for this agent
-    const cancelledTasks = await getRecentlyCancelledTasksForAgent(myAgentId);
+    const cancelledTasks = await getRecentlyCancelledTasksForAgent(
+      myAgentId,
+      readableByFor(sessionActor),
+    );
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ cancelled: cancelledTasks }));
     return true;

package/src/http/events.ts

@@ -13,7 +13,8 @@ import {
   EventStatusSchema,
   SwarmEventSchema,
 } from "../types";
-import { route } from "./route-def";
+import { bodyListTask, bodyTask, route } from "./route-def";
+import { readableByFor, resolveSessionActor } from "./session-access";
 import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
@@ -36,6 +37,7 @@ const createEventRoute = route({
   method: "post",
   path: "/api/events",
   pattern: ["api", "events"],
+  session: bodyTask("taskId"),
   summary: "Store a single event",
   tags: ["Events"],
   body: eventBodySchema,
@@ -53,6 +55,7 @@ const createEventsBatchRoute = route({
   method: "post",
   path: "/api/events/batch",
   pattern: ["api", "events", "batch"],
+  session: bodyListTask("events", "taskId"),
   summary: "Store multiple events in a batch",
   tags: ["Events"],
   body: z.object({
@@ -153,7 +156,7 @@ export async function handleEvents(
   res: ServerResponse,
   pathSegments: string[],
   queryParams: URLSearchParams,
-  _myAgentId: string | undefined,
+  myAgentId: string | undefined,
 ): Promise<boolean> {
   // Match batch BEFORE generic /api/events (POST)
   if (createEventsBatchRoute.match(req.method, pathSegments)) {
@@ -252,6 +255,7 @@ export async function handleEvents(
       limit: parsed.query.limit ?? 100,
       events: eventFilter,
       latestPerDataField: latestPerDataField ? { events: latestEvents, dataFields } : undefined,
+      readableBy: readableByFor(await resolveSessionActor(req, myAgentId)),
     });
     getEventsRoute.respond(
       res,

package/src/http/favorite-owner.ts

@@ -16,7 +16,7 @@ export type FavoriteOwner = {
  */
 export const DASHBOARD_USER_HEADER = "x-swarm-user-id";
 
-function dashboardUserIdHeader(req: IncomingMessage): string | null {
+export function dashboardUserIdHeader(req: IncomingMessage): string | null {
   const raw = req.headers[DASHBOARD_USER_HEADER];
   const value = (Array.isArray(raw) ? raw[0] : raw)?.trim();
   return value ? value : null;

package/src/http/fleet-benchmark.ts

@@ -1,6 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { getSwarmConfigs } from "../be/db";
 import { getLocalFleetStats } from "../be/fleet-benchmark-stats";
 import {
   compareWithFleet,
@@ -12,6 +11,9 @@ import {
   localTasksPerWeek,
 } from "../fleet-benchmark";
 import { isTelemetryEnabled } from "../telemetry";
+import { COMPANY_TEAM_SIZES, COMPANY_USE_CASES } from "../utils/company-profile";
+import { normalizeOrgWebsite } from "../utils/org-website";
+import { globalConfig } from "./global-config";
 import { rejectGuest } from "./request-principal";
 import { route } from "./route-def";
 import { telemetryProxyEndpoint } from "./used-by";
@@ -34,6 +36,14 @@ const FleetStateSchema = z.enum([
 
 const FleetBenchmarkResponseSchema = z.object({
   state: FleetStateSchema,
+  level: z.enum(["basic", "full"]),
+  peerGroup: z
+    .object({
+      teamSize: z.string().nullable(),
+      useCase: z.string().nullable(),
+      orgs: z.number().int(),
+    })
+    .nullable(),
   local: z
     .object({
       tasksPerWeek: z.number(),
@@ -67,7 +77,7 @@ const fleetBenchmark = route({
   pattern: ["api", "fleet-benchmark"],
   summary: "Compare this swarm with similar swarms",
   description:
-    "Places this swarm's tasks per week and task success rate (last 30 days) in the fleet percentiles published by the telemetry proxy, against swarms with the same agent count when enough exist. Needs telemetry on and an organization name; otherwise `state` says what is missing and the proxy is not called. `unavailable` also covers an install whose first event the proxy saw cannot be established locally (until 30 days after the first accepted event). The fleet numbers are cached for a day.",
+    "Compares local task volume and success rate with fleet percentiles over the last 30 days. Comparisons require telemetry, an organization name, and a known proxy ingest date. A website, team size, and use case enable full comparisons with peer filters. The response includes the proxy's peer group when available. With telemetry off, it returns local DB counts without a proxy request. The fleet cache key includes the peer filters.",
   tags: ["Telemetry"],
   responses: {
     200: {
@@ -81,8 +91,12 @@ const fleetBenchmark = route({
 
 // ─── Caches ──────────────────────────────────────────────────────────────────
 
-let fleetCache: { value: FleetBenchmarks | null; until: number } | null = null;
-let localCache: { value: LocalFleetStats | null; until: number } | null = null;
+let fleetCache: { key: string; value: ProxyFleetBenchmarks | null; until: number } | null = null;
+let localCache: {
+  requireIngestAnchor: boolean;
+  value: LocalFleetStats | null;
+  until: number;
+} | null = null;
 
 const ProxyMetricSchema = z.object({
   n: z.number(),
@@ -112,19 +126,34 @@ const ProxyFleetBenchmarksSchema = z.object({
     "2-5": ProxyBlockSchema.optional(),
     "6+": ProxyBlockSchema.optional(),
   }),
+  peer_group: z
+    .object({
+      team_size: z.string().nullable(),
+      use_case: z.string().nullable(),
+      orgs: z.number().int().nonnegative(),
+    })
+    .nullable()
+    .optional(),
 }) satisfies z.ZodType<FleetBenchmarks>;
 
+type ProxyFleetBenchmarks = z.infer<typeof ProxyFleetBenchmarksSchema>;
+
 /** The proxy's fleet percentiles. The request carries no install ID. */
-async function fleetBenchmarks(now: number): Promise<FleetBenchmarks | null> {
-  if (fleetCache && fleetCache.until > now) return fleetCache.value;
-  let value: FleetBenchmarks | null = null;
+async function fleetBenchmarks(
+  now: number,
+  peerGroup: { teamSize: string; useCase: string } | null,
+): Promise<ProxyFleetBenchmarks | null> {
+  const endpoint = new URL(await telemetryProxyEndpoint("/v1/fleet/benchmarks"));
+  endpoint.searchParams.set("window", "30d");
+  if (peerGroup) {
+    endpoint.searchParams.set("team_size", peerGroup.teamSize);
+    endpoint.searchParams.set("use_case", peerGroup.useCase);
+  }
+  const key = endpoint.toString();
+  if (fleetCache?.key === key && fleetCache.until > now) return fleetCache.value;
+  let value: ProxyFleetBenchmarks | null = null;
   try {
-    const response = await fetch(
-      `${await telemetryProxyEndpoint("/v1/fleet/benchmarks")}?window=30d`,
-      {
-        signal: AbortSignal.timeout(TIMEOUT_MS),
-      },
-    );
+    const response = await fetch(key, { signal: AbortSignal.timeout(TIMEOUT_MS) });
     if (response.ok) {
       const parsed = ProxyFleetBenchmarksSchema.safeParse(await response.json());
       if (parsed.success) value = parsed.data;
@@ -132,38 +161,46 @@ async function fleetBenchmarks(now: number): Promise<FleetBenchmarks | null> {
   } catch {
     // Unreachable proxy: the card says the comparison is unavailable.
   }
-  fleetCache = { value, until: now + (value ? FLEET_TTL_MS : FLEET_FAILURE_TTL_MS) };
+  fleetCache = { key, value, until: now + (value ? FLEET_TTL_MS : FLEET_FAILURE_TTL_MS) };
   return value;
 }
 
-async function localStats(now: Date): Promise<LocalFleetStats | null> {
-  if (localCache && localCache.until > now.getTime()) return localCache.value;
-  const value = await getLocalFleetStats(now);
-  localCache = { value, until: now.getTime() + LOCAL_TTL_MS };
+async function localStats(now: Date, requireIngestAnchor = true): Promise<LocalFleetStats | null> {
+  if (localCache?.requireIngestAnchor === requireIngestAnchor && localCache.until > now.getTime())
+    return localCache.value;
+  const value = await getLocalFleetStats(now, { requireIngestAnchor });
+  localCache = { requireIngestAnchor, value, until: now.getTime() + LOCAL_TTL_MS };
   return value;
 }
 
-async function orgName(): Promise<string | undefined> {
-  const stored = (
-    await getSwarmConfigs({ scope: "global", key: "SWARM_ORG_NAME" })
-  )?.[0]?.value?.trim();
-  return stored || process.env.SWARM_ORG_NAME?.trim() || undefined;
-}
-
 export async function buildFleetBenchmarkResponse(
   now = new Date(),
 ): Promise<FleetBenchmarkResponse> {
+  const [name, website, teamSize, useCase] = await Promise.all([
+    globalConfig("SWARM_ORG_NAME"),
+    globalConfig("SWARM_ORG_WEBSITE"),
+    globalConfig("SWARM_ORG_TEAM_SIZE"),
+    globalConfig("SWARM_ORG_USE_CASE"),
+  ]);
+  const team = z.enum(COMPANY_TEAM_SIZES).safeParse(teamSize);
+  const use = z.enum(COMPANY_USE_CASES).safeParse(useCase);
+  const peerGroup =
+    normalizeOrgWebsite(website) && team.success && use.success
+      ? { teamSize: team.data, useCase: use.data }
+      : null;
   const empty = {
+    level: peerGroup ? ("full" as const) : ("basic" as const),
+    peerGroup: null,
     local: null,
     minFinishedTasks: FLEET_MIN_FINISHED_TASKS,
     generatedAt: null,
     comparisons: [],
   };
   // Telemetry off means no call to our proxy at all, not even an anonymous one.
-  if (!isTelemetryEnabled()) return { state: "telemetry_off", ...empty };
-  if (!(await orgName())) return { state: "no_org_name", ...empty };
+  const telemetryEnabled = isTelemetryEnabled();
+  if (telemetryEnabled && !name) return { state: "no_org_name", ...empty };
 
-  const stats = await localStats(now);
+  const stats = await localStats(now, telemetryEnabled);
   // Where the proxy started counting this install is unknown: no comparison.
   if (!stats) return { state: "unavailable", ...empty };
   const finishedTasks = stats.tasksCompleted + stats.tasksFailed;
@@ -174,14 +211,26 @@ export async function buildFleetBenchmarkResponse(
     agents: stats.agents,
     bucket: fleetBucketFor(stats.agents),
   };
+  if (!telemetryEnabled) return { ...empty, state: "telemetry_off", local };
   if (finishedTasks < FLEET_MIN_FINISHED_TASKS)
     return { ...empty, state: "not_enough_tasks", local };
 
-  const fleet = await fleetBenchmarks(now.getTime());
+  const fleet = await fleetBenchmarks(now.getTime(), peerGroup);
+  const responsePeerGroup =
+    peerGroup && fleet?.peer_group
+      ? {
+          teamSize: fleet.peer_group.team_size,
+          useCase: fleet.peer_group.use_case,
+          orgs: fleet.peer_group.orgs,
+        }
+      : null;
   const comparisons = fleet ? compareWithFleet(stats, fleet, now) : [];
-  if (!fleet || comparisons.length === 0) return { ...empty, state: "unavailable", local };
+  if (!fleet || comparisons.length === 0)
+    return { ...empty, state: "unavailable", local, peerGroup: responsePeerGroup };
   return {
+    ...empty,
     state: "ready",
+    peerGroup: responsePeerGroup,
     local,
     minFinishedTasks: FLEET_MIN_FINISHED_TASKS,
     generatedAt: fleet.generatedAt,

package/src/http/fs.ts

@@ -15,6 +15,7 @@ import { getCurrentRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { requestPrincipal } from "./request-principal";
 import { route } from "./route-def";
+import { canReadSession, SESSION_READ_DENIED } from "./session-access";
 import { BODY_TOO_LARGE, enforceContentLengthCap, jsonError } from "./utils";
 
 // Upload wall-clock past which the provider round-trip is worth a log line.
@@ -126,6 +127,7 @@ const listTaskFilesRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files",
   pattern: ["api", "fs", "tasks", null, "files"],
+  session: { taskParam: "taskId" },
   summary: "List task file attachments",
   tags: ["FS"],
   params: taskParams,
@@ -142,6 +144,7 @@ const uploadTaskFileRoute = route({
   method: "post",
   path: "/api/fs/tasks/{taskId}/files",
   pattern: ["api", "fs", "tasks", null, "files"],
+  session: { taskParam: "taskId" },
   summary: "Upload a binary task file attachment",
   description:
     "Accepts a raw binary request body. Pass the display/path name as the `name` query parameter.",
@@ -163,6 +166,7 @@ const getTaskFileRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}",
   pattern: ["api", "fs", "tasks", null, "files", null],
+  session: { taskParam: "taskId" },
   summary: "Get task file attachment metadata",
   tags: ["FS"],
   params: attachmentParams,
@@ -176,6 +180,7 @@ const downloadTaskFileRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}/raw",
   pattern: ["api", "fs", "tasks", null, "files", null, "raw"],
+  session: { taskParam: "taskId" },
   summary: "Download raw task file bytes",
   description: "Streams raw bytes. File content is not secret-scrubbed.",
   tags: ["FS"],
@@ -193,6 +198,7 @@ const signedUrlTaskFileRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}/signed-url",
   pattern: ["api", "fs", "tasks", null, "files", null, "signed-url"],
+  session: { taskParam: "taskId" },
   summary: "Create a provider signed GET URL for a task file",
   tags: ["FS"],
   params: attachmentParams,
@@ -208,6 +214,7 @@ const deleteTaskFileRoute = route({
   method: "delete",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}",
   pattern: ["api", "fs", "tasks", null, "files", null],
+  session: { taskParam: "taskId" },
   summary: "Delete a task file attachment",
   tags: ["FS"],
   params: attachmentParams,
@@ -263,7 +270,13 @@ export async function handleFs(
   if (downloadTaskFileRoute.match(req.method, pathSegments)) {
     const parsed = await downloadTaskFileRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const attachment = await findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
+    const attachment = await findAttachment(
+      req,
+      myAgentId,
+      parsed.params.taskId,
+      parsed.params.attachmentId,
+      res,
+    );
     if (!attachment) return true;
     return sendDownload(res, attachment);
   }
@@ -271,7 +284,13 @@ export async function handleFs(
   if (signedUrlTaskFileRoute.match(req.method, pathSegments)) {
     const parsed = await signedUrlTaskFileRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const attachment = await findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
+    const attachment = await findAttachment(
+      req,
+      myAgentId,
+      parsed.params.taskId,
+      parsed.params.attachmentId,
+      res,
+    );
     if (!attachment) return true;
     return sendSignedUrl(res, attachment, parsed.query.expiresIn);
   }
@@ -279,7 +298,13 @@ export async function handleFs(
   if (getTaskFileRoute.match(req.method, pathSegments)) {
     const parsed = await getTaskFileRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const attachment = await findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
+    const attachment = await findAttachment(
+      req,
+      myAgentId,
+      parsed.params.taskId,
+      parsed.params.attachmentId,
+      res,
+    );
     if (!attachment) return true;
     getTaskFileRoute.respond(res, 200, attachment);
     return true;
@@ -313,6 +338,10 @@ export async function handleFs(
     const parsed = await listTaskFilesRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     if (!(await getTaskById(parsed.params.taskId))) return notFound(res, "Task not found");
+    if (!(await canReadSession(req, myAgentId, parsed.params.taskId))) {
+      jsonError(res, SESSION_READ_DENIED, 403);
+      return true;
+    }
     listTaskFilesRoute.respond(res, 200, {
       attachments: await getTaskAttachments(parsed.params.taskId),
     });
@@ -493,6 +522,8 @@ function backingProviderId(attachment: TaskAttachment): string | null {
 }
 
 async function findAttachment(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
   taskId: string,
   attachmentId: string,
   res: ServerResponse,
@@ -501,6 +532,10 @@ async function findAttachment(
     notFound(res, "Task not found");
     return null;
   }
+  if (!(await canReadSession(req, myAgentId, taskId))) {
+    jsonError(res, SESSION_READ_DENIED, 403);
+    return null;
+  }
   const attachment = (await getTaskAttachments(taskId)).find((item) => item.id === attachmentId);
   if (!attachment) {
     notFound(res, "Attachment not found");

package/src/http/global-config.ts

@@ -0,0 +1,7 @@
+import { getSwarmConfigs } from "../be/db";
+
+/** Stored values, including empty strings, override env values, as on config reload. */
+export async function globalConfig(key: string): Promise<string | undefined> {
+  const stored = (await getSwarmConfigs({ scope: "global", key }))?.[0]?.value;
+  return (stored ?? process.env[key])?.trim() || undefined;
+}

package/src/http/index.ts

@@ -116,6 +116,7 @@ import { handlePagesPublic } from "./pages-public";
 import { handlePoll } from "./poll";
 import { handlePricing } from "./pricing";
 import { handlePromptTemplates } from "./prompt-templates";
+import { handleRanking } from "./ranking";
 import { handleRealtimeAsset, handleRealtimeTicket } from "./realtime";
 import { handleRepos } from "./repos";
 import { handleRooms } from "./rooms";
@@ -403,10 +404,11 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleExtensions(req, res, pathSegments, queryParams, myAgentId),
         () => handleFavorites(req, res, pathSegments, queryParams, myAgentId),
         () => handleUsers(req, res, pathSegments, queryParams),
-        () => handleSessions(req, res, pathSegments, queryParams),
+        () => handleSessions(req, res, pathSegments, queryParams, myAgentId),
         () => handleInboxState(req, res, pathSegments, queryParams),
         () => handleTelemetryUi(req, res, pathSegments, queryParams, myAgentId),
         () => handleUsedBy(req, res, pathSegments, queryParams, myAgentId),
+        () => handleRanking(req, res, pathSegments, queryParams),
         () => handleFleetBenchmark(req, res, pathSegments, queryParams),
         () => handleTaskTemplates(req, res, pathSegments, queryParams),
         () => handleMcp(req, res, transports, transportActivity, mcpSessionAgents),

package/src/http/memory.ts

@@ -44,7 +44,7 @@ import { AgentMemorySchema, AgentMemoryScopeSchema, AgentMemorySourceSchema } fr
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { rejectGuest } from "./request-principal";
-import { route } from "./route-def";
+import { bodyTask, route } from "./route-def";
 import { jsonError, parseQueryParams } from "./utils";
 
 // ─── Response Schemas ────────────────────────────────────────────────────────
@@ -68,6 +68,7 @@ const indexMemory = route({
   method: "post",
   path: "/api/memory/index",
   pattern: ["api", "memory", "index"],
+  session: bodyTask("sourceTaskId"),
   summary: "Ingest content into memory system (async embedding)",
   tags: ["Memory"],
   // The gate only bites when the key that lands on the rows (here, `sourcePath`) sits under a
@@ -687,6 +688,7 @@ const rateMemory = route({
   method: "post",
   path: "/api/memory/rate",
   pattern: ["api", "memory", "rate"],
+  session: { none: "worker-only: it needs X-Agent-ID, which a user token cannot send" },
   summary: "Submit RatingEvents to update memory usefulness posteriors",
   tags: ["Memory"],
   auth: { apiKey: true, agentId: true },