@desplega.ai/agent-swarm 1.169.0 → 1.171.0

package/src/http/core.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
 import { initAgentMail, resetAgentMail } from "../agentmail";
 import {
   initAzureDevOps,
@@ -17,17 +18,20 @@ import {
   updateAgentStatus,
 } from "../be/db";
 import {
+  getRuntimeInstanceById,
   markRuntimeInstanceOffline,
+  markRuntimeTerminated,
   reconcileAgentStatusFromRuntimes,
   touchRuntimeInstance,
 } from "../be/multi-runtime";
 import { enqueueAdmissionRow } from "../be/rbac-audit";
 import { getUserGrant } from "../be/rbac-roles";
+import { syncTelemetryEnabled } from "../be/telemetry-enable";
 import { initGitHub, resetGitHub } from "../github";
 import { initGitLab, isGitLabEnabled, resetGitLab } from "../gitlab";
 import { initJira, resetJira } from "../jira";
 import { initLinear, resetLinear } from "../linear";
-import { decideAdmission, isRbacEnabled } from "../rbac";
+import { can, decideAdmission, isRbacEnabled } from "../rbac";
 import { startSlackApp, stopSlackApp } from "../slack";
 import type { AgentStatus } from "../types";
 import { isMultiRuntimeEnabled } from "../utils/multi-runtime";
@@ -40,7 +44,13 @@ 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 { agentWithCapacity, getPathSegments, jsonError, parseQueryParams } from "./utils";
+import {
+  agentWithCapacity,
+  duplicateGuardedQueryKey,
+  getPathSegments,
+  jsonError,
+  parseQueryParams,
+} from "./utils";
 
 /**
  * Load global swarm_config entries into process.env.
@@ -159,6 +169,12 @@ async function reloadGlobalConfigsAndIntegrationsInner(): Promise<ReloadConfigRe
 
   const updated = await loadGlobalConfigsIntoEnv(true);
 
+  // ANONYMIZED_TELEMETRY may have just flipped on: mint the install ID now
+  // instead of dropping every event until a restart.
+  await syncTelemetryEnabled("settings").catch((err) => {
+    console.error("[config-reload] telemetry re-init failed (non-fatal):", err);
+  });
+
   // Retire the old transport before any other integration can fail during
   // reload. HTTP/invalid selection must never leave the previous socket live.
   await stopSlackApp();
@@ -380,17 +396,18 @@ const closeRoute = route({
   method: "post",
   path: "/close",
   pattern: ["close"],
-  summary: "Mark an agent or runtime offline on shutdown",
+  summary: "End a session or terminate an agent runtime",
   description:
-    `Retires the calling process. ${RUNTIME_HEADER_DOC} With multi-runtime mode on, the header ` +
-    "is required and only that runtime is retired; the agent goes offline once no live runtime " +
-    "remains. With the flag off, the agent is marked offline as before.",
+    `Closes the calling session. ${RUNTIME_HEADER_DOC} Pooled runtimes remain active unless ` +
+    "runtimeShutdown is true. With multi-runtime mode on, the header is required and static " +
+    "runtimes retire independently. With the flag off, static agents are marked offline.",
   tags: ["Core"],
   auth: { apiKey: true, agentId: true },
   headers: runtimeInstanceHeader("retire a runtime"),
+  body: z.object({ runtimeShutdown: z.boolean().optional() }).optional(),
   rbac: { ungated: "self-scoped: an agent retires its own runtime" },
   responses: {
-    204: { description: "Runtime (and agent, when last) marked offline" },
+    204: { description: "Session closed or runtime retired" },
     400: {
       description: "Missing X-Agent-ID, or missing X-Runtime-Instance-ID in multi-runtime mode",
     },
@@ -409,6 +426,14 @@ export async function handleCore(
   // request pipeline does afterwards, including audit columns in the DB layer.
   beginRequestAuthScope();
 
+  // Controller credentials authorize only their separate WebSocket transport.
+  let auth = await resolveHttpRequestAuth(req, apiKey);
+  if (auth?.kind === "controller") {
+    setRequestAuth(req, auth);
+    jsonError(res, "Controller tokens can only connect to the controller socket", 403);
+    return true;
+  }
+
   // Handle preflight
   if (req.method === "OPTIONS") {
     res.writeHead(204);
@@ -455,14 +480,12 @@ export async function handleCore(
   // either the global swarm key or an active user-bound `aswt_` token.
   const pathSegments = getPathSegments(req.url || "");
   const isUserMcpRoute = req.url === "/mcp-user";
-  let auth = null as Awaited<ReturnType<typeof resolveHttpRequestAuth>>;
   // `/mcp-user` runs its own `aswt_`-token auth in `handleMcpUser`; the swarm
   // API key must not gate it.
   if (isUserMcpRoute || isPublicRoute(req.method, pathSegments)) {
+    auth = null;
     setRequestAuth(req, null);
   } else {
-    auth = await resolveHttpRequestAuth(req, apiKey);
-
     if (!auth) {
       setRequestAuth(req, null);
       res.writeHead(401, { "Content-Type": "application/json" });
@@ -472,6 +495,65 @@ export async function handleCore(
     setRequestAuth(req, auth);
   }
 
+  if (auth?.kind === "agent") {
+    const query = parseQueryParams(req.url || "");
+    const duplicate = duplicateGuardedQueryKey(query);
+    if (duplicate) {
+      jsonError(res, `Duplicate query parameter: ${duplicate}`, 400);
+      return true;
+    }
+    if (req.headers["x-page-id"] !== undefined) {
+      jsonError(res, "Agent tokens cannot send X-Page-Id", 403);
+      return true;
+    }
+    const header = req.headers["x-agent-id"];
+    const agentId = Array.isArray(header) ? header[0] : header;
+    if (agentId !== undefined && agentId !== auth.agentId) {
+      jsonError(res, "X-Agent-ID does not match token", 403);
+      return true;
+    }
+    req.headers["x-agent-id"] = auth.agentId;
+    myAgentId = auth.agentId;
+    if (auth.runtimeId) {
+      const header = req.headers["x-runtime-instance-id"];
+      const runtimeId = Array.isArray(header) ? header[0] : header;
+      if (runtimeId !== undefined && runtimeId !== auth.runtimeId) {
+        jsonError(res, "X-Runtime-Instance-ID does not match token", 403);
+        return true;
+      }
+      req.headers["x-runtime-instance-id"] = auth.runtimeId;
+      const sourceHeader = req.headers["x-source-task-id"];
+      const taskId = Array.isArray(sourceHeader) ? sourceHeader[0] : sourceHeader;
+      if (taskId !== undefined && (await getTaskById(taskId))?.agentId !== auth.agentId) {
+        jsonError(res, "X-Source-Task-Id does not belong to token agent", 403);
+        return true;
+      }
+    }
+    const targetAgentId = pathSegments[2];
+    if (
+      pathSegments[0] === "api" &&
+      pathSegments[1] === "agents" &&
+      targetAgentId &&
+      targetAgentId !== auth.agentId &&
+      (req.method !== "GET" ||
+        query.get("resolveSecrets") === "true" ||
+        query.get("includeSecrets") === "true")
+    ) {
+      const agent = await getAgentById(auth.agentId);
+      if (
+        !can({
+          principal: { kind: "agent", agentId: auth.agentId, isLead: agent?.isLead ?? false },
+          verb: "agent.act.any",
+          resource: { kind: "agent", agentId: targetAgentId },
+          source: "http",
+        }).allow
+      ) {
+        jsonError(res, "Token cannot access another agent's scope", 403);
+        return true;
+      }
+    }
+  }
+
   if (auth?.kind === "user" && isRbacEnabled()) {
     const grant = await getUserGrant(auth.userId);
     if (!grant.grantsAll) {
@@ -682,6 +764,14 @@ export async function handleCore(
       return true;
     }
 
+    const parsed = await closeRoute.parse(
+      req,
+      res,
+      getPathSegments(req.url || ""),
+      new URLSearchParams(),
+    );
+    if (!parsed) return true;
+
     const found = await getDbClient().transaction(async () => {
       const agent = await getAgentById(myAgentId);
 
@@ -689,10 +779,14 @@ export async function handleCore(
         return false;
       }
 
-      if (multiRuntime && runtimeInstanceId) {
-        // One process exiting retires only its own runtime; the logical state
-        // is then recomputed from whatever is left — offline when nothing is,
-        // otherwise reflecting the surviving runtimes' readiness and work.
+      const runtime = runtimeInstanceId ? await getRuntimeInstanceById(runtimeInstanceId) : null;
+      if (runtime?.agentId === agent.id && runtime.poolId) {
+        // Session hooks do not end the runtime that owns their sessions.
+        if (parsed.body?.runtimeShutdown) {
+          await markRuntimeTerminated(runtime.id, "Runner shutdown");
+        }
+      } else if (multiRuntime && runtimeInstanceId) {
+        // Static runtimes retain independent close behavior.
         await markRuntimeInstanceOffline(runtimeInstanceId, agent.id);
         await reconcileAgentStatusFromRuntimes(agent.id);
       } else {

package/src/http/favorite-owner.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage } from "node:http";
 import { resolveHttpAuditUserId } from "../be/audit-user";
+import { findUserById } from "../be/users";
 import { getRequestAuth } from "../utils/request-auth-context";
 
 export type FavoriteOwner = {
@@ -8,6 +9,19 @@ export type FavoriteOwner = {
   actorId: string;
 };
 
+/**
+ * Header the dashboard sends with the identity picked in its user picker.
+ * The dashboard authenticates with the shared operator key, so without it
+ * every person using the dashboard would share one favorite set.
+ */
+export const DASHBOARD_USER_HEADER = "x-swarm-user-id";
+
+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;
+}
+
 /**
  * Resolve the authenticated principal that owns favorite state.
  *
@@ -16,20 +30,36 @@ export type FavoriteOwner = {
  * clients authenticate with user-bound `aswt_` tokens. Agent traffic must be
  * resolved through its owned task before the transport-level operator auth is
  * allowed to select the dashboard's shared scope.
+ *
+ * An operator-key dashboard request names its picked user in
+ * `X-Swarm-User-Id`; an active user there owns the favorites. The operator key
+ * is fully trusted, so the header needs no further proof. A user token or a
+ * page session never honors the header. `dashboardUser: false` keeps the
+ * shared operator scope for callers whose stored state predates the header.
  */
 export async function resolveHttpFavoriteOwner(
   req: IncomingMessage,
   callerAgentId: string | undefined,
+  opts: { dashboardUser?: boolean } = {},
 ): Promise<FavoriteOwner | null> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "user") {
     return { scope: `user:${auth.userId}`, userId: auth.userId, actorId: auth.userId };
   }
   if (auth?.kind === "operator" && !callerAgentId) {
+    const pickedUserId =
+      opts.dashboardUser === false || auth.page ? null : dashboardUserIdHeader(req);
+    if (pickedUserId) {
+      const user = await findUserById(pickedUserId);
+      if (user?.status === "active") {
+        return { scope: `user:${user.id}`, userId: user.id, actorId: user.id };
+      }
+    }
     return {
       // A deployment has one configured operator key. Keep its dashboard
       // favorites stable across key rotation; the fingerprint remains the
-      // audit actor, not the storage scope.
+      // audit actor, not the storage scope. Tabs with no picked identity
+      // land here.
       scope: "operator",
       userId: null,
       actorId: auth.fingerprint,

package/src/http/fleet-benchmark.ts

@@ -0,0 +1,206 @@
+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,
+  FLEET_MIN_FINISHED_TASKS,
+  type FleetBenchmarks,
+  fleetBucketFor,
+  type LocalFleetStats,
+  localSuccessRate,
+  localTasksPerWeek,
+} from "../fleet-benchmark";
+import { isTelemetryEnabled } from "../telemetry";
+import { rejectGuest } from "./request-principal";
+import { route } from "./route-def";
+import { telemetryProxyEndpoint } from "./used-by";
+
+/** The fleet changes slowly; one proxy call a day per install is plenty. */
+const FLEET_TTL_MS = 24 * 60 * 60 * 1000;
+/** After a failed call, wait before asking the proxy again. */
+const FLEET_FAILURE_TTL_MS = 60 * 60 * 1000;
+/** Local counts scan agent_tasks; the card does not need them fresher. */
+const LOCAL_TTL_MS = 10 * 60 * 1000;
+const TIMEOUT_MS = 10_000;
+
+const FleetStateSchema = z.enum([
+  "ready",
+  "telemetry_off",
+  "no_org_name",
+  "not_enough_tasks",
+  "unavailable",
+]);
+
+const FleetBenchmarkResponseSchema = z.object({
+  state: FleetStateSchema,
+  local: z
+    .object({
+      tasksPerWeek: z.number(),
+      taskSuccessRate: z.number().nullable(),
+      finishedTasks: z.number().int(),
+      agents: z.number().int(),
+      bucket: z.enum(["1", "2-5", "6+"]).nullable(),
+    })
+    .nullable(),
+  minFinishedTasks: z.number().int(),
+  generatedAt: z.string().nullable(),
+  comparisons: z.array(
+    z.object({
+      key: z.enum(["tasksPerWeek", "taskSuccessRate"]),
+      value: z.number(),
+      p50: z.number(),
+      band: z.enum(["top_10", "top_25", "above_median", "below_median", "bottom_25"]),
+      peers: z.enum(["1", "2-5", "6+", "all"]),
+      installs: z.number().int(),
+    }),
+  ),
+});
+
+export type FleetBenchmarkResponse = z.infer<typeof FleetBenchmarkResponseSchema>;
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const fleetBenchmark = route({
+  method: "get",
+  path: "/api/fleet-benchmark",
+  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.",
+  tags: ["Telemetry"],
+  responses: {
+    200: {
+      description: "Benchmark, or the reason it is not shown",
+      schema: FleetBenchmarkResponseSchema,
+    },
+    401: { description: "Unauthorized" },
+    403: { description: "Guest page sessions cannot read the benchmark" },
+  },
+});
+
+// ─── Caches ──────────────────────────────────────────────────────────────────
+
+let fleetCache: { value: FleetBenchmarks | null; until: number } | null = null;
+let localCache: { value: LocalFleetStats | null; until: number } | null = null;
+
+const ProxyMetricSchema = z.object({
+  n: z.number(),
+  p25: z.number().optional(),
+  p50: z.number().optional(),
+  p75: z.number().optional(),
+  p90: z.number().optional(),
+  omitted: z.string().optional(),
+});
+const ProxyBlockSchema = z.object({
+  installs: z.number(),
+  tasksPerWeek: ProxyMetricSchema,
+  taskSuccessRate: ProxyMetricSchema,
+});
+/**
+ * Everything `compareWithFleet` reads from `GET /v1/fleet/benchmarks`. A body
+ * that fails it counts as a failed call, so a malformed 200 is never cached.
+ */
+const ProxyFleetBenchmarksSchema = z.object({
+  window: z.string(),
+  generatedAt: z.string(),
+  minInstallsPerBucket: z.number(),
+  minFinishedTasks: z.number(),
+  overall: ProxyBlockSchema,
+  byAgentCount: z.object({
+    "1": ProxyBlockSchema.optional(),
+    "2-5": ProxyBlockSchema.optional(),
+    "6+": ProxyBlockSchema.optional(),
+  }),
+}) satisfies z.ZodType<FleetBenchmarks>;
+
+/** 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;
+  try {
+    const response = await fetch(
+      `${await telemetryProxyEndpoint("/v1/fleet/benchmarks")}?window=30d`,
+      {
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      },
+    );
+    if (response.ok) {
+      const parsed = ProxyFleetBenchmarksSchema.safeParse(await response.json());
+      if (parsed.success) value = parsed.data;
+    }
+  } catch {
+    // Unreachable proxy: the card says the comparison is unavailable.
+  }
+  fleetCache = { 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 };
+  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 empty = {
+    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 stats = await localStats(now);
+  // Where the proxy started counting this install is unknown: no comparison.
+  if (!stats) return { state: "unavailable", ...empty };
+  const finishedTasks = stats.tasksCompleted + stats.tasksFailed;
+  const local = {
+    tasksPerWeek: localTasksPerWeek(stats, now),
+    taskSuccessRate: localSuccessRate(stats),
+    finishedTasks,
+    agents: stats.agents,
+    bucket: fleetBucketFor(stats.agents),
+  };
+  if (finishedTasks < FLEET_MIN_FINISHED_TASKS)
+    return { ...empty, state: "not_enough_tasks", local };
+
+  const fleet = await fleetBenchmarks(now.getTime());
+  const comparisons = fleet ? compareWithFleet(stats, fleet, now) : [];
+  if (!fleet || comparisons.length === 0) return { ...empty, state: "unavailable", local };
+  return {
+    state: "ready",
+    local,
+    minFinishedTasks: FLEET_MIN_FINISHED_TASKS,
+    generatedAt: fleet.generatedAt,
+    comparisons,
+  };
+}
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleFleetBenchmark(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (!fleetBenchmark.match(req.method, pathSegments)) return false;
+  if (rejectGuest(req, res)) return true;
+  const parsed = await fleetBenchmark.parse(req, res, pathSegments, queryParams);
+  if (!parsed) return true;
+  fleetBenchmark.respond(res, 200, await buildFleetBenchmarkResponse());
+  return true;
+}

package/src/http/index.ts

@@ -25,9 +25,14 @@ import {
   stopAuditGc,
   stopAuditWriter,
 } from "../be/rbac-audit";
+import { startPoolRouting, stopPoolRouting } from "../be/runtime-pools/routing";
+import { seedRuntimePools } from "../be/runtime-pools/seed";
+import { startRuntimeSupervisor, stopRuntimeSupervisor } from "../be/runtime-pools/supervisor";
 import { startScratchScriptGc, stopScratchScriptGc } from "../be/scripts/retention";
 import { loadSecretRegistry } from "../be/secret-registry";
 import { seedLegacyCapabilitiesConfig } from "../be/seed-capabilities";
+import { initApiTelemetry } from "../be/telemetry-enable";
+import { startWorkerNudgeListener } from "../be/worker-nudge-listener";
 import {
   loadEnabledExtensions,
   setExtensionLoopbackBaseUrl,
@@ -53,7 +58,7 @@ import { attachRealtimeTransport } from "../realtime/transport";
 import { startScriptRunSupervisor, stopScriptRunSupervisor } from "../script-workflows/supervisor";
 import { getServerSessionsProcessed } from "../server-runtime-counters";
 import { startSlackApp, stopSlackApp } from "../slack";
-import { initTelemetry, telemetry } from "../telemetry";
+import { telemetry } from "../telemetry";
 import { startTelemetryTicker } from "../telemetry-snapshot";
 import { API_DRAINING_HEADER } from "../utils/api-drain";
 import { getApiKey } from "../utils/api-key";
@@ -80,6 +85,7 @@ import { handleEcosystem } from "./ecosystem";
 import { handleEvents } from "./events";
 import { handleExtensions } from "./extensions";
 import { handleFavorites } from "./favorites";
+import { handleFleetBenchmark } from "./fleet-benchmark";
 import { handleFs } from "./fs";
 import { handleHeartbeat } from "./heartbeat";
 import { handleInboxState } from "./inbox-state";
@@ -113,6 +119,7 @@ import { handleRealtimeAsset, handleRealtimeTicket } from "./realtime";
 import { handleRepos } from "./repos";
 import { handleRooms } from "./rooms";
 import { describeRequestRoute } from "./route-def";
+import { handleRuntimePools } from "./runtime-pools";
 import { handleSchedules } from "./schedules";
 import { handleScriptConnectionProxy } from "./script-connection-proxy";
 import { handleScriptConnections } from "./script-connections";
@@ -126,7 +133,9 @@ import { handleStats } from "./stats";
 import { handleStatus } from "./status";
 import { handleTaskTemplates } from "./task-templates";
 import { handleTasks } from "./tasks";
+import { handleTelemetryUi } from "./telemetry-ui";
 import { handleTrackers } from "./trackers";
+import { handleUsedBy } from "./used-by";
 import { handleUsers } from "./users";
 import {
   getPathSegments,
@@ -329,7 +338,7 @@ const httpServer = createHttpServer(async (req, res) => {
       if (isApiDraining()) res.setHeader(API_DRAINING_HEADER, "1");
 
       const queryParams = parseQueryParams(req.url || "");
-      const myAgentId = req.headers["x-agent-id"] as string | undefined;
+      let myAgentId = req.headers["x-agent-id"] as string | undefined;
 
       // ── Route handlers (order matters — first match wins) ──
       const handlers: (() => Promise<boolean>)[] = [
@@ -389,11 +398,15 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleApiKeys(req, res, pathSegments, queryParams),
         () => handleHeartbeat(req, res, pathSegments),
         () => handleEvents(req, res, pathSegments, queryParams, myAgentId),
+        () => handleRuntimePools(req, res, pathSegments, queryParams, myAgentId),
         () => handleExtensions(req, res, pathSegments, queryParams, myAgentId),
         () => handleFavorites(req, res, pathSegments, queryParams, myAgentId),
         () => handleUsers(req, res, pathSegments, queryParams),
         () => handleSessions(req, res, pathSegments, queryParams),
         () => handleInboxState(req, res, pathSegments, queryParams),
+        () => handleTelemetryUi(req, res, pathSegments, queryParams, myAgentId),
+        () => handleUsedBy(req, res, pathSegments, queryParams, myAgentId),
+        () => handleFleetBenchmark(req, res, pathSegments, queryParams),
         () => handleTaskTemplates(req, res, pathSegments, queryParams),
         () => handleMcp(req, res, transports, transportActivity, mcpSessionAgents),
         () => handleMcpUser(req, res, transportsUser, sessionUsers, transportActivityUser),
@@ -406,6 +419,7 @@ const httpServer = createHttpServer(async (req, res) => {
         // the async listener as an unhandled rejection and the client got a
         // dropped connection instead of a 500.
         if (await handleCore(req, res, myAgentId, apiKey)) return;
+        myAgentId = req.headers["x-agent-id"] as string | undefined;
 
         for (const handler of handlers) {
           if (await handler()) return;
@@ -433,6 +447,9 @@ const httpServer = createHttpServer(async (req, res) => {
 
 // Store references in globalThis for hot reload persistence
 const detachRealtime = attachRealtimeTransport(httpServer);
+const { attachControllerTransport } = await import("./controllers-connect");
+const detachControllers = attachControllerTransport(httpServer);
+const stopWorkerNudges = startWorkerNudgeListener();
 const stopRoomDeletion = realtimeBus.subscribe("room:namespace-deleted", (namespace) => {
   void Promise.resolve(removeNamespaceRooms(String(namespace))).catch((error) =>
     console.error("[rooms] Deletion failed:", scrubSecrets(String(error))),
@@ -440,6 +457,8 @@ const stopRoomDeletion = realtimeBus.subscribe("room:namespace-deleted", (namesp
 });
 globalState.__closeRealtime = () => {
   detachRealtime();
+  detachControllers();
+  stopWorkerNudges();
   stopRoomDeletion();
 };
 globalState.__httpServer = httpServer;
@@ -468,6 +487,8 @@ async function shutdown() {
 
   // Stop heartbeat triage
   stopHeartbeat();
+  stopPoolRouting();
+  await stopRuntimeSupervisor();
 
   // Stop the out-of-band queue alarm before disconnecting its Slack notifier.
   stopQueueStallAlarm();
@@ -599,7 +620,7 @@ warnIfCorsAllowsAnyOrigin();
 try {
   const loaded = await loadSecretRegistry();
   console.log(
-    `[secret-registry] registered config=${loaded.config} oauth=${loaded.oauth} scriptApi=${loaded.scriptApi} failed=${loaded.failed}`,
+    `[secret-registry] registered config=${loaded.config} oauth=${loaded.oauth} scriptApi=${loaded.scriptApi} runtimeController=${loaded.runtimeController} failed=${loaded.failed}`,
   );
 } catch (err) {
   console.error(
@@ -608,6 +629,15 @@ try {
   );
 }
 
+try {
+  await seedRuntimePools();
+} catch (err) {
+  console.error(
+    "[startup] Failed to seed runtime pools:",
+    scrubSecrets(err instanceof Error ? err.message : String(err)),
+  );
+}
+
 // Upgrade seed: explicit CAPABILITIES env values that predate capability
 // gating get the previously always-registered groups backfilled into a
 // global swarm_config row (operator-editable; skipped when a row exists).
@@ -712,9 +742,8 @@ httpServer
     const telemetrySetConfig = async (key: string, value: string) => {
       await upsertSwarmConfig({ scope: "global", key, value });
     };
-    await initTelemetry("api-server", telemetryGetConfig, telemetrySetConfig, {
-      generateIfMissing: true,
-    });
+    // Also keeps the accessors so turning telemetry on at runtime re-inits it.
+    await initApiTelemetry(telemetryGetConfig, telemetrySetConfig);
     telemetry.server("started", { port });
     // Org email domain (hourly + on user changes) and the daily org.snapshot.
     startTelemetryTicker({ getConfig: telemetryGetConfig, setConfig: telemetrySetConfig });
@@ -780,6 +809,9 @@ httpServer
       startHeartbeat(heartbeatMs);
     }
 
+    startPoolRouting();
+    startRuntimeSupervisor();
+
     // Start OAuth token keepalive (proactive refresh to prevent expiry)
     if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
       const { startOAuthKeepalive } = await import("../oauth/keepalive");

package/src/http/mcp.ts

@@ -92,20 +92,15 @@ function forbidden(res: ServerResponse, message: string): true {
 
 /**
  * When a request is authenticated via an aseph_ session token (kind: "agent"),
- * the X-Agent-ID and X-Source-Task-Id headers MUST match the token's bound
- * agentId and taskId. A valid token cannot be used on behalf of a different
- * agent or task.
+ * the X-Source-Task-Id header must match a task-bound token.
+ * Central HTTP authentication enforces the agent and runtime headers.
  */
 function validateAgentTokenIdentity(req: IncomingMessage, res: ServerResponse): true | undefined {
   const auth = getRequestAuth(req);
-  if (!auth || auth.kind !== "agent") return undefined;
+  if (!auth || auth.kind !== "agent" || auth.taskId === null) return undefined;
 
-  const agentId = headerValue(req.headers["x-agent-id"]);
   const taskId = headerValue(req.headers["x-source-task-id"]);
 
-  if (!agentId || agentId !== auth.agentId) {
-    return forbidden(res, "X-Agent-ID does not match session token");
-  }
   if (!taskId || taskId !== auth.taskId) {
     return forbidden(res, "X-Source-Task-Id does not match session token");
   }