@desplega.ai/agent-swarm 1.161.0 → 1.162.0

package/src/http/all-routes.ts

@@ -16,6 +16,7 @@ import "./assets";
 import "./budgets";
 import "./codex-oauth-device";
 import "./codex-oauth-keep-warm";
+import "./comb";
 import "./config";
 import "./context";
 import "./core";

package/src/http/assets.ts

@@ -5,7 +5,6 @@ import { auditAssetKeys } from "../be/asset-key-audit";
 import { AssetKeyAuthorizationError, authorizeAssetKeyWrite } from "../be/asset-key-auth";
 import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
-  getAgentById,
   getDb,
   getDbClient,
   getTaskById,
@@ -14,7 +13,7 @@ import {
   upsertAssetKeyMapping,
 } from "../be/db";
 import { getScriptById } from "../be/scripts/db";
-import { can, type RbacPrincipal, type RbacResource } from "../rbac";
+import { can, type RbacResource } from "../rbac";
 import {
   type AssetEntityType,
   AssetEntityTypeSchema,
@@ -23,6 +22,7 @@ import {
   AssetSummarySchema,
 } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
+import { requestPrincipal } from "./request-principal";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
@@ -176,18 +176,6 @@ const moveAssetRoute = route({
   },
 });
 
-async function assetMovePrincipal(
-  req: IncomingMessage,
-  myAgentId: string | undefined,
-): Promise<RbacPrincipal | null> {
-  const auth = getRequestAuth(req);
-  if (auth?.kind === "operator") return { kind: "operator" };
-  if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
-  if (!myAgentId) return null;
-  const agent = await getAgentById(myAgentId);
-  return { kind: "agent", agentId: myAgentId, isLead: agent?.isLead ?? false };
-}
-
 async function canMutateTaskNamespace(
   task: { id: string; agentId: string | null; creatorAgentId?: string },
   myAgentId: string | undefined,
@@ -199,7 +187,7 @@ async function canMutateTaskNamespace(
     agentId: task.agentId,
     creatorAgentId: task.creatorAgentId,
   };
-  const principal = await assetMovePrincipal(req, myAgentId);
+  const principal = await requestPrincipal(req, myAgentId);
   if (!principal) return false;
   return can({ principal, verb: "task.fs.mutate", resource, source: "http" }).allow;
 }
@@ -209,7 +197,7 @@ async function canManageAppNamespace(
   req: IncomingMessage,
   myAgentId: string | undefined,
 ): Promise<boolean> {
-  const principal = await assetMovePrincipal(req, myAgentId);
+  const principal = await requestPrincipal(req, myAgentId);
   return (
     !!principal &&
     can({ principal, verb: "app.manage", resource: { kind: "app", appId: id }, source: "http" })
@@ -222,7 +210,7 @@ async function canManageScriptNamespace(
   req: IncomingMessage,
   myAgentId: string | undefined,
 ): Promise<boolean> {
-  const principal = await assetMovePrincipal(req, myAgentId);
+  const principal = await requestPrincipal(req, myAgentId);
   if (!principal) return false;
   if (principal.kind === "operator") return true;
   if (principal.kind !== "agent") return false;

package/src/http/comb.ts

@@ -0,0 +1,131 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { resolveHttpAuditUserId } from "../be/audit-user";
+import { getCombConfig } from "../comb/config";
+import { REVIEW_BATCH_MAX, ReviewBatchError, sendReviewBatch } from "../comb/review-batch";
+import { can } from "../rbac";
+import { TaskCreationBlockedError } from "../tasks/errors";
+import { scrubSecrets } from "../utils/secret-scrubber";
+import { requestPrincipal } from "./request-principal";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+const skippedSchema = z.object({
+  id: z.string(),
+  reason: z.enum(["not-found", "reply", "resolved", "already-sent"]),
+  /** The task an "already-sent" comment went to, when known. */
+  taskId: z.string().optional(),
+});
+
+const resultSchema = z.object({
+  /** The new task. Null on a 200: the batch only posted missing "sent" replies again. */
+  taskId: z.string().nullable(),
+  sent: z.array(z.string()),
+  skipped: z.array(skippedSchema),
+  /** Comments of an earlier send whose missing "sent" reply this batch posted again. */
+  repaired: z.array(z.object({ id: z.string(), taskId: z.string() })),
+});
+
+const batchErrorSchema = z.object({ error: z.string(), skipped: z.array(skippedSchema) });
+
+/** A drive path: starts with "/", no "." or ".." segment. */
+function isDrivePath(path: string): boolean {
+  return (
+    path.startsWith("/") && !path.split("/").some((segment) => segment === "." || segment === "..")
+  );
+}
+
+const reviewBatchRoute = route({
+  method: "post",
+  path: "/api/comb/review-batches",
+  pattern: ["api", "comb", "review-batches"],
+  summary: "Send agent-fs comments to the swarm as one lead task",
+  description:
+    "Comb's 'Send to swarm'. The server reads each comment again from agent-fs with its bootstrap key, skips replies, resolved comments, and comments already sent, and creates ONE task for the lead. Each sent comment gets a `[comb:sent task=<id>]` reply from the swarm service account. A comment is sent at most once. When an earlier send lost its reply, the batch posts that reply again (`repaired`). Answers 404 while COMB_ENABLED is off.",
+  tags: ["Comb"],
+  body: z.object({
+    orgId: z.string().min(1),
+    driveId: z.string().min(1),
+    // agent-fs comment ids are UUIDs, so a malformed id never costs an agent-fs read.
+    commentIds: z.array(z.uuid()).min(1).max(REVIEW_BATCH_MAX),
+    /** The file or folder the batch was sent from (a Comb path such as "/docs/"). */
+    scopePath: z
+      .string()
+      .min(1)
+      .max(1024)
+      .refine(isDrivePath, "scopePath must start with '/' and have no '.' or '..' segment"),
+  }),
+  responses: {
+    200: {
+      description: "No new task: the batch only posted missing 'sent' replies again",
+      schema: resultSchema,
+    },
+    201: { description: "Task created", schema: resultSchema },
+    400: { description: "Invalid body, or not the swarm drive" },
+    403: { description: "Caller cannot create tasks" },
+    404: { description: "Comb is not enabled" },
+    409: {
+      description: "Nothing to send (every comment was skipped)",
+      schema: batchErrorSchema,
+    },
+    422: { description: "Task creation blocked by an extension" },
+    502: { description: "agent-fs could not read a comment" },
+    503: {
+      description:
+        "agent-fs or the swarm drive is not set up, or an operator disabled a Comb review template",
+      schema: batchErrorSchema,
+    },
+  },
+  rbac: { permission: "task.create.own" },
+});
+
+export async function handleComb(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+  myAgentId?: string,
+): Promise<boolean> {
+  if (!reviewBatchRoute.match(req.method, pathSegments)) return false;
+  // Comb off: the route does not exist. No body parsing, no RBAC answer.
+  if (!getCombConfig().enabled) {
+    jsonError(res, "Comb is not enabled", 404);
+    return true;
+  }
+
+  const parsed = await reviewBatchRoute.parse(req, res, pathSegments, queryParams);
+  if (!parsed) return true;
+  const principal = await requestPrincipal(req, myAgentId);
+  if (
+    !principal ||
+    !can({ principal, verb: "task.create.own", resource: { kind: "none" }, source: "http" }).allow
+  ) {
+    jsonError(res, "Not authorized to create tasks", 403);
+    return true;
+  }
+
+  try {
+    const result = await sendReviewBatch({
+      ...parsed.body,
+      requestedByUserId: await resolveHttpAuditUserId(req, myAgentId),
+    });
+    reviewBatchRoute.respond(res, result.taskId === null ? 200 : 201, result);
+  } catch (error) {
+    if (error instanceof ReviewBatchError) {
+      if (error.status === 409 || error.status === 503) {
+        reviewBatchRoute.respond(res, error.status, {
+          error: error.message,
+          skipped: error.skipped,
+        });
+      } else {
+        jsonError(res, error.message, error.status);
+      }
+    } else if (error instanceof TaskCreationBlockedError) {
+      jsonError(res, error.reason, 422);
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      jsonError(res, scrubSecrets(`Failed to send comments to the swarm: ${message}`), 500);
+    }
+  }
+  return true;
+}

package/src/http/core.ts

@@ -360,7 +360,8 @@ const pingRoute = route({
     `Refreshes the calling agent's status. ${RUNTIME_HEADER_DOC} With multi-runtime mode on, ` +
     "the header must identify a live runtime of this agent; an absent, unknown, offline, or " +
     "foreign identifier makes the call a no-op instead of an error, so workers predating the " +
-    "flag keep running.",
+    "flag keep running. While the API is draining after SIGTERM, every response (this one " +
+    "included) carries `X-Swarm-Draining: 1`: workers hand off in-flight tasks and take no new work.",
   tags: ["Core"],
   auth: { apiKey: true, agentId: true },
   headers: runtimeInstanceHeader("refresh a runtime's liveness"),

package/src/http/fs.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { deleteTaskAttachment, getAgentById, getTaskAttachments, getTaskById } from "../be/db";
+import { deleteTaskAttachment, getTaskAttachments, getTaskById } from "../be/db";
 import {
   ensureAgentFsCredentialsForAgent,
   inviteEmailToSharedOrg,
@@ -8,11 +8,12 @@ import {
 import { MAX_TASK_ATTACHMENT_BYTES, recordTaskAttachmentUpload } from "../be/task-attachment-store";
 import { type FileObject, type FileScope, FilesError, normalizeFilesError } from "../fs/provider";
 import { getFileStorageProvider } from "../fs/registry";
-import { can, type RbacPrincipal, type RbacResource } from "../rbac";
+import { can, type RbacResource } from "../rbac";
 import { type TaskAttachment, TaskAttachmentSchema } from "../types";
 import { attachmentContentDisposition } from "../utils/content-disposition";
-import { getCurrentRequestAuth, getRequestAuth } from "../utils/request-auth-context";
+import { getCurrentRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { requestPrincipal } from "./request-principal";
 import { route } from "./route-def";
 import { BODY_TOO_LARGE, enforceContentLengthCap, jsonError } from "./utils";
 
@@ -522,20 +523,11 @@ async function canMutateTask(
   // Decision order preserved (plan Appendix A row 36): operator/user request
   // auth short-circuits BEFORE agent identity — an operator bearer with a
   // non-owner X-Agent-ID is still allowed. The agent branches only bind when
-  // the request-auth context is unset.
-  const auth = getRequestAuth(req);
-  let principal: RbacPrincipal;
-  if (auth?.kind === "operator") {
-    principal = { kind: "operator" };
-  } else if (auth?.kind === "user") {
-    principal = { kind: "user", userId: auth.userId };
-  } else {
-    // A missing caller identity cannot be lead/assignee/creator — same denial
-    // as before (no separate "agent not found" branch).
-    if (!myAgentId) return false;
-    const agent = await getAgentById(myAgentId);
-    principal = { kind: "agent", agentId: myAgentId, isLead: agent?.isLead ?? false };
-  }
+  // the request-auth context is unset. A missing caller identity cannot be
+  // lead/assignee/creator: same denial as before (no separate "agent not
+  // found" branch).
+  const principal = await requestPrincipal(req, myAgentId);
+  if (!principal) return false;
   return can({ principal, verb: "task.fs.mutate", resource, source: "http" }).allow;
 }
 

package/src/http/index.ts

@@ -9,6 +9,7 @@ import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/se
 import { getEnabledCapabilities, hasCapability } from "@/server";
 import { initAgentMail } from "../agentmail";
 import { initAzureDevOps } from "../azure-devops";
+import { drainApi, isApiDraining } from "../be/api-drain";
 import {
   closeDb,
   emitBuiltInIntegrationConnectedOnce,
@@ -53,6 +54,8 @@ import { startScriptRunSupervisor, stopScriptRunSupervisor } from "../script-wor
 import { getServerSessionsProcessed } from "../server-runtime-counters";
 import { startSlackApp, stopSlackApp } from "../slack";
 import { initTelemetry, telemetry } from "../telemetry";
+import { startTelemetryTicker } from "../telemetry-snapshot";
+import { API_DRAINING_HEADER } from "../utils/api-drain";
 import { getApiKey } from "../utils/api-key";
 import { getMcpBaseUrl } from "../utils/constants";
 import { isEnvFlagEnabled } from "../utils/env-flag";
@@ -67,6 +70,7 @@ import { handleAssets } from "./assets";
 import { handleBudgets } from "./budgets";
 import { handleCodexOAuthDevice } from "./codex-oauth-device";
 import { handleCodexOAuthKeepWarm } from "./codex-oauth-keep-warm";
+import { handleComb } from "./comb";
 import { handleConfig } from "./config";
 import { handleContext } from "./context";
 import { handleCore, loadGlobalConfigsIntoEnv } from "./core";
@@ -104,7 +108,7 @@ import { handlePagesPublic } from "./pages-public";
 import { handlePoll } from "./poll";
 import { handlePricing } from "./pricing";
 import { handlePromptTemplates } from "./prompt-templates";
-import { handleRealtimeAsset } from "./realtime";
+import { handleRealtimeAsset, handleRealtimeTicket } from "./realtime";
 import { handleRepos } from "./repos";
 import { handleRooms } from "./rooms";
 import { describeRequestRoute } from "./route-def";
@@ -318,6 +322,8 @@ const httpServer = createHttpServer(async (req, res) => {
     // nest under it instead of attaching to the root with no parent.
     const handleRequest = async () => {
       setCorsHeaders(req, res);
+      // Tells polling workers to hand off in-flight tasks while this API still serves.
+      if (isApiDraining()) res.setHeader(API_DRAINING_HEADER, "1");
 
       const queryParams = parseQueryParams(req.url || "");
       const myAgentId = req.headers["x-agent-id"] as string | undefined;
@@ -348,8 +354,10 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleApps(req, res, pathSegments, queryParams, myAgentId),
         () => handleConfig(req, res, pathSegments, queryParams),
         () => handleFs(req, res, pathSegments, queryParams, myAgentId),
+        () => handleComb(req, res, pathSegments, queryParams, myAgentId),
         () => handleKv(req, res, pathSegments, queryParams),
         () => handleRooms(req, res, pathSegments, queryParams),
+        () => handleRealtimeTicket(req, res, pathSegments, queryParams),
         () => handleRealtimeAsset(req, res),
         () => handleIntegrations(req, res, pathSegments, queryParams),
         () => handlePromptTemplates(req, res, pathSegments, queryParams),
@@ -469,6 +477,10 @@ async function shutdown() {
   // Stop the out-of-band queue alarm before disconnecting its Slack notifier.
   stopQueueStallAlarm();
 
+  // Dispatch has stopped. Keep serving, bounded, while workers hand off their
+  // in-flight tasks; new work waits for the next API (see src/be/api-drain.ts).
+  await drainApi();
+
   // Stop durable script workflow subprocesses
   await stopScriptRunSupervisor();
 
@@ -684,15 +696,17 @@ httpServer
     // The api-server is the sole authority for the install identity — pass
     // generateIfMissing so it mints a new install ID on first boot. Workers
     // must NOT mint (see src/commands/runner.ts).
-    await initTelemetry(
-      "api-server",
-      async (key) => (await getSwarmConfigs({ scope: "global", key }))?.[0]?.value,
-      async (key, value) => {
-        await upsertSwarmConfig({ scope: "global", key, value });
-      },
-      { generateIfMissing: true },
-    );
+    const telemetryGetConfig = async (key: string) =>
+      (await getSwarmConfigs({ scope: "global", key }))?.[0]?.value;
+    const telemetrySetConfig = async (key: string, value: string) => {
+      await upsertSwarmConfig({ scope: "global", key, value });
+    };
+    await initTelemetry("api-server", telemetryGetConfig, telemetrySetConfig, {
+      generateIfMissing: true,
+    });
     telemetry.server("started", { port });
+    // Org email domain (hourly + on user changes) and the daily org.snapshot.
+    startTelemetryTicker({ getConfig: telemetryGetConfig, setConfig: telemetrySetConfig });
     if (process.env.GITHUB_TOKEN) {
       await emitBuiltInIntegrationConnectedOnce("github");
     }

package/src/http/onboarding.ts

@@ -128,10 +128,27 @@ function memoryErrorStatus(error: unknown): number | undefined {
   return Number.isInteger(status) && status >= 100 && status <= 599 ? status : undefined;
 }
 
+/**
+ * A 404 names the model or deployment only when the provider says so: OpenAI
+ * answers `model_not_found`, Azure `DeploymentNotFound`. A bare 404 (Azure's
+ * `Resource not found`, a proxy page) means the path itself does not exist.
+ */
+function notFoundNamesModel(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const { code, type, error: body } = error as { code?: unknown; type?: unknown; error?: unknown };
+  const bodyMessage =
+    typeof body === "object" && body !== null ? (body as { message?: unknown }).message : undefined;
+  const text = [code, type, bodyMessage]
+    .filter((part): part is string => typeof part === "string")
+    .join(" ")
+    .toLowerCase();
+  return text.includes("model") || text.includes("deployment");
+}
+
 function classifyMemoryError(error: unknown): OnboardingErrorClass {
   const status = memoryErrorStatus(error);
   if (status === 401 || status === 403) return "auth";
-  if (status === 404) return "model";
+  if (status === 404) return notFoundNamesModel(error) ? "model" : "endpoint";
   if (status === 408) return "timeout";
   const text =
     error instanceof Error
@@ -157,7 +174,9 @@ function memoryErrorMessage(errorClass: OnboardingErrorClass, status?: number):
     case "auth":
       return `The endpoint rejected the key${statusSuffix}.`;
     case "model":
-      return `The endpoint could not find the embedding model${statusSuffix}.`;
+      return `The endpoint could not find the embedding model or deployment${statusSuffix}.`;
+    case "endpoint":
+      return `The endpoint path was not found${statusSuffix}. Check the base URL.`;
     case "timeout":
       return "The endpoint timed out.";
     case "network":

package/src/http/poll.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { ensure } from "@desplega.ai/business-use";
 import { z } from "zod";
+import { isApiDraining } from "../be/api-drain";
 import { canClaim } from "../be/budget-admission";
 import {
   type BudgetRefusalContext,
@@ -37,7 +38,7 @@ import { poolTaskRunsOnHarness } from "../be/model-validation";
 import { touchRuntimeInstance } from "../be/multi-runtime";
 import { hasCapability } from "../server";
 import { fetchChannelActivity } from "../slack/channel-activity";
-import { telemetry } from "../telemetry";
+import { emitTaskTelemetry, resolveTriggerSurface } from "../telemetry-trigger";
 import {
   AgentTaskSchema,
   BudgetRefusedTriggerSchema,
@@ -123,6 +124,9 @@ const PollTaskOfferedTriggerSchema = z.object({
 const PollTaskAssignedTriggerSchema = z.object({
   type: z.literal("task_assigned"),
   taskId: z.string(),
+  // Surface that started the whole task chain (root task's source, mapped to
+  // the telemetry catalog). Workers tag their session telemetry with it.
+  triggerSurface: z.string().optional(),
   task: AgentTaskSchema.extend({
     attachments: z.array(PollTriggerAttachmentSchema),
   }),
@@ -172,6 +176,9 @@ const pollTriggers = route({
   path: "/api/poll",
   pattern: ["api", "poll"],
   summary: "Poll for triggers (tasks, mentions)",
+  description:
+    "While the API is draining after SIGTERM it dispatches nothing: the answer is `{ trigger: null }` " +
+    "and carries `X-Swarm-Draining: 1`, the signal for a worker to hand off in-flight tasks.",
   tags: ["Poll"],
   auth: { apiKey: true, agentId: true },
   headers: runtimeInstanceHeader("poll for work").extend({
@@ -369,6 +376,13 @@ export async function handlePoll(
           return { trigger: null };
         }
 
+        // A draining API dispatches nothing: offers, assignments and pool claims
+        // wait for the next API. Workers learn to hand off from the
+        // X-Swarm-Draining header the HTTP pipeline adds (src/be/api-drain.ts).
+        if (isApiDraining()) {
+          return { trigger: null };
+        }
+
         // Check for offered tasks first (highest priority for both workers and leads)
         // Atomically claim the task for review to prevent duplicate processing.
         // Capacity is checked in the same transaction as the claim: with
@@ -470,7 +484,7 @@ export async function handlePoll(
                 conditions: [{ timeout_ms: 300_000 }], // 5 min: polling interval + queue wait
               });
 
-              telemetry.taskEvent("started", {
+              void emitTaskTelemetry("started", {
                 taskId: pendingTask.id,
                 source: pendingTask.source,
                 agentId: myAgentId,
@@ -480,11 +494,18 @@ export async function handlePoll(
             // Resolve requesting user if available (UNKNOWN sentinel handling
             // lives in buildTriggerRequestedBy).
             const assignedRequestedBy = await buildTriggerRequestedBy(pendingTask);
+            // The surface that started the whole chain, so the worker can tag
+            // its session events with it (workers cannot read the task tree).
+            const assignedTriggerSurface = await resolveTriggerSurface(
+              pendingTask.id,
+              pendingTask.source,
+            );
 
             return {
               trigger: {
                 type: "task_assigned",
                 taskId: pendingTask.id,
+                triggerSurface: assignedTriggerSurface,
                 task: {
                   ...pendingTask,
                   ...(await claimModelFields(pendingTask, agent)),
@@ -612,17 +633,22 @@ export async function handlePoll(
                 // Post-commit (see the `started` path above): a rolled-back
                 // claim must not report the task as claimed.
                 getDbClient().afterCommit(() => {
-                  telemetry.taskEvent("claimed", {
+                  void emitTaskTelemetry("claimed", {
                     taskId: claimed.id,
                     source: claimed.source,
                     agentId: myAgentId,
                   });
                 });
                 const claimedRequestedBy = await buildTriggerRequestedBy(claimed);
+                const claimedTriggerSurface = await resolveTriggerSurface(
+                  claimed.id,
+                  claimed.source,
+                );
                 return {
                   trigger: {
                     type: "task_assigned",
                     taskId: claimed.id,
+                    triggerSurface: claimedTriggerSurface,
                     task: {
                       ...claimed,
                       ...(await claimModelFields(claimed, agent)),
@@ -672,6 +698,7 @@ export async function handlePoll(
     // Throttled to avoid Slack API rate limits (~50 calls/min).
     if (
       result.trigger === null &&
+      !isApiDraining() &&
       process.env.LEAD_MONITOR_CHANNELS === "true" &&
       Date.now() - lastChannelActivityCheckAt >= CHANNEL_ACTIVITY_INTERVAL_MS
     ) {

package/src/http/realtime.ts

@@ -1,6 +1,29 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getCombConfig } from "../comb/config";
+import { can } from "../rbac";
 import bundle from "../realtime/browser.generated.txt" with { type: "text" };
+import { issueRealtimeTicket } from "../realtime/tickets";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+const realtimeTicketRoute = route({
+  method: "post",
+  path: "/api/realtime/ticket",
+  pattern: ["api", "realtime", "ticket"],
+  summary: "Issue a one-shot dashboard realtime ticket",
+  tags: ["Rooms"],
+  rbac: { permission: "comb.presence" },
+  responses: {
+    200: {
+      description: "One-shot realtime ticket",
+      schema: z.object({ ticket: z.string(), expiresAt: z.number().int() }),
+    },
+    403: { description: "Comb presence is not allowed" },
+    404: { description: "Comb is not enabled" },
+  },
+});
 
 route({
   method: "get",
@@ -14,6 +37,45 @@ route({
   },
 });
 
+/** `POST /api/realtime/ticket`: a one-shot ticket for a dashboard realtime socket (Comb presence). */
+export async function handleRealtimeTicket(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (!realtimeTicketRoute.match(req.method, pathSegments)) return false;
+  // Comb presence is the only ticket consumer, so the route is off with Comb.
+  if (!getCombConfig().enabled) {
+    jsonError(res, "Comb is not enabled", 404);
+    return true;
+  }
+  const parsed = await realtimeTicketRoute.parse(req, res, pathSegments, queryParams);
+  if (!parsed) return true;
+  const auth = getRequestAuth(req);
+  if (!auth || auth.kind === "agent") {
+    jsonError(res, "Comb presence requires dashboard authentication", 403);
+    return true;
+  }
+  const principal =
+    auth.kind === "operator"
+      ? ({ kind: "operator" } as const)
+      : ({ kind: "user", userId: auth.userId } as const);
+  if (
+    !can({
+      principal,
+      verb: "comb.presence",
+      resource: { kind: "none" },
+      source: "http",
+    }).allow
+  ) {
+    jsonError(res, "Comb presence requires the comb.presence permission", 403);
+    return true;
+  }
+  realtimeTicketRoute.respond(res, 200, issueRealtimeTicket(auth));
+  return true;
+}
+
 export async function handleRealtimeAsset(
   req: IncomingMessage,
   res: ServerResponse,

package/src/http/request-principal.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from "node:http";
+import { getAgentById } from "../be/db";
+import type { RbacPrincipal } from "../rbac";
+import { getRequestAuth } from "../utils/request-auth-context";
+
+/**
+ * The RBAC principal of an HTTP request, for a handler-side `can()` check.
+ * Operator and user request auth win over the X-Agent-ID header (an operator
+ * bearer with any agent id stays the operator). An agent id that is not
+ * registered is a non-lead agent. Null when the request has neither.
+ */
+export async function requestPrincipal(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+): Promise<RbacPrincipal | null> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind === "operator") return { kind: "operator" };
+  if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  if (!myAgentId) return null;
+  const agent = await getAgentById(myAgentId);
+  return { kind: "agent", agentId: myAgentId, isLead: agent?.isLead ?? false };
+}