@desplega.ai/agent-swarm 2.2.0 → 2.4.0

package/src/http/ranking.ts

@@ -0,0 +1,367 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getDbClient, upsertSwarmConfig } from "../be/db";
+import {
+  buildListing,
+  mintRankingClaim,
+  PUBLIC_RANKING_ENABLED_KEY,
+  RANKING_CATEGORIES,
+  rankingEntryFile,
+  rankingFormSchema,
+  rankingLeaveUrl,
+  rankingPrUrl,
+  readTelemetryRanking,
+  TELEMETRY_RANKING_KEY,
+  type TelemetryRanking,
+} from "../ranking/telemetry-ranking";
+import { isTelemetryEnabled, telemetry } from "../telemetry";
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import {
+  ORG_IDENTITY_KEYS,
+  type OrgIdentityStatus,
+  orgIdentityStatus,
+} from "../utils/org-identity";
+import { ensureConfigAdmin } from "./config";
+import { scheduleIntegrationsReload } from "./core";
+import { route } from "./route-def";
+import { globalConfig, telemetryProxyEndpoint } from "./used-by";
+
+// ─── Schemas ─────────────────────────────────────────────────────────────────
+
+const ListingSchema = z.object({
+  v: z.literal(1),
+  claim: z.string(),
+  name: z.string(),
+  domain: z.string(),
+  category: z.enum(RANKING_CATEGORIES),
+  subcategory: z.string().nullable(),
+  description: z.string().nullable(),
+  sourceCodeUrl: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+const RankingStateSchema = z.object({
+  eligible: z.boolean(),
+  missing: z.array(z.enum(ORG_IDENTITY_KEYS)),
+  telemetryOn: z.boolean(),
+  enabled: z.boolean(),
+  /** The org identity the listing would copy. */
+  name: z.string().nullable(),
+  domain: z.string().nullable(),
+  listing: ListingSchema.nullable(),
+  /** False when the stored listing was built for another website: a new PR is needed. */
+  listingMatchesDomain: z.boolean(),
+  fileJson: z.string().nullable(),
+  prUrl: z.string().nullable(),
+  verifyUrl: z.string().nullable(),
+});
+export type RankingState = z.infer<typeof RankingStateSchema>;
+
+const OptInResponseSchema = z.object({
+  domain: z.string(),
+  claim: z.string(),
+  listing: ListingSchema,
+  fileJson: z.string(),
+  prUrl: z.string(),
+  verifyUrl: z.string(),
+});
+
+const OptOutResponseSchema = z.object({
+  enabled: z.literal(false),
+  leaveUrl: z.string().nullable(),
+});
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const getRanking = route({
+  method: "get",
+  path: "/api/ranking",
+  pattern: ["api", "ranking"],
+  summary: "Public ranking state",
+  description:
+    "Whether this install can join the public agent-swarm.dev ranking (telemetry on, organization name and website set), whether it is opted in, and its stored listing. The listing carries the private ranking claim, so only a config admin can read it.",
+  tags: ["Telemetry"],
+  responses: {
+    200: { description: "Ranking state", schema: RankingStateSchema },
+    401: { description: "Unauthorized" },
+    403: { description: "Only a config admin can read the ranking state" },
+  },
+  rbac: { permission: "config.write.any" },
+});
+
+const optIn = route({
+  method: "post",
+  path: "/api/ranking/opt-in",
+  pattern: ["api", "ranking", "opt-in"],
+  summary: "Opt this install into the public ranking",
+  description:
+    "Builds the telemetry_ranking listing from the organization name and website plus the chosen category, stores it, turns PUBLIC_RANKING_ENABLED on and sends ranking.opted_in. The install is ranked only after a ranking PR with the returned file is merged into desplega-ai/agent-swarm.",
+  tags: ["Telemetry"],
+  body: rankingFormSchema,
+  responses: {
+    200: { description: "Opted in", schema: OptInResponseSchema },
+    400: { description: "A listing field is invalid" },
+    401: { description: "Unauthorized" },
+    403: { description: "Only a config admin can opt in" },
+    409: {
+      description:
+        "telemetry_off: telemetry is off or the install has no ID. org_identity_missing: the organization name or website is not set (`missing` lists which).",
+    },
+  },
+  rbac: { permission: "config.write.any" },
+});
+
+const optOut = route({
+  method: "post",
+  path: "/api/ranking/opt-out",
+  pattern: ["api", "ranking", "opt-out"],
+  summary: "Leave the public ranking",
+  description:
+    "Turns PUBLIC_RANKING_ENABLED off and sends ranking.opted_out, so workers stop sending ranking.usage. Returns the GitHub page that deletes the ranking entry.",
+  tags: ["Telemetry"],
+  responses: {
+    200: { description: "Opted out", schema: OptOutResponseSchema },
+    401: { description: "Unauthorized" },
+    403: { description: "Only a config admin can opt out" },
+  },
+  rbac: { permission: "config.write.any" },
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const RANKING_CONFIG_KEYS = new Set<string>([...ORG_IDENTITY_KEYS, PUBLIC_RANKING_ENABLED_KEY]);
+
+/**
+ * The org identity from global config. `changed` carries a value just written
+ * or deleted, since `globalConfig` falls back to `process.env`, which the
+ * debounced reload has not updated yet.
+ */
+async function currentIdentity(changed?: {
+  key: string;
+  value: string | null;
+}): Promise<OrgIdentityStatus> {
+  const read = async (key: string) =>
+    changed?.key === key ? changed.value : await globalConfig(key);
+  return orgIdentityStatus({
+    SWARM_ORG_NAME: await read("SWARM_ORG_NAME"),
+    SWARM_ORG_WEBSITE: await read("SWARM_ORG_WEBSITE"),
+  });
+}
+
+async function storedListing(): Promise<TelemetryRanking | null> {
+  return readTelemetryRanking(await globalConfig(TELEMETRY_RANKING_KEY));
+}
+
+async function rankingEnabled(): Promise<boolean> {
+  const raw = await globalConfig(PUBLIC_RANKING_ENABLED_KEY);
+  return isEnvFlagEnabled(PUBLIC_RANKING_ENABLED_KEY, false, {
+    [PUBLIC_RANKING_ENABLED_KEY]: raw,
+  });
+}
+
+async function telemetryReady(): Promise<boolean> {
+  return isTelemetryEnabled() && Boolean(await globalConfig("telemetry_installation_id"));
+}
+
+async function verifyUrl(listing: Pick<TelemetryRanking, "domain" | "claim">): Promise<string> {
+  const params = new URLSearchParams({ domain: listing.domain, claim: listing.claim });
+  return `${await telemetryProxyEndpoint("/v1/ranking/verify")}?${params.toString()}`;
+}
+
+async function setEnabled(enabled: boolean): Promise<void> {
+  await upsertSwarmConfig({
+    scope: "global",
+    key: PUBLIC_RANKING_ENABLED_KEY,
+    value: String(enabled),
+  });
+}
+
+function emitOptedIn(listing: TelemetryRanking): void {
+  telemetry.ranking(
+    "opted_in",
+    { listing: JSON.stringify(listing) },
+    { orgName: listing.name, orgWebsite: listing.domain },
+  );
+}
+
+function emitOptedOut(domain: string): void {
+  telemetry.ranking("opted_out", { domain });
+}
+
+export async function buildRankingState(): Promise<RankingState> {
+  const [identity, listing, enabled, telemetryOn] = await Promise.all([
+    currentIdentity(),
+    storedListing(),
+    rankingEnabled(),
+    telemetryReady(),
+  ]);
+  const listingMatchesDomain = Boolean(listing && listing.domain === identity.website);
+  const current = listingMatchesDomain ? listing : null;
+  return {
+    eligible: telemetryOn && identity.ok,
+    missing: identity.missing,
+    telemetryOn,
+    enabled: enabled && listingMatchesDomain,
+    name: identity.name,
+    domain: identity.website,
+    listing,
+    listingMatchesDomain,
+    fileJson: current ? rankingEntryFile(current) : null,
+    prUrl: current ? rankingPrUrl(current) : null,
+    verifyUrl: current ? await verifyUrl(current) : null,
+  };
+}
+
+/**
+ * Keep the listing in step with the org identity after a global config write.
+ * A renamed org rebuilds the listing with the same claim and re-sends it; a
+ * cleared or placeholder name, a changed or cleared website, or the setting
+ * turned off by hand opts the install out.
+ */
+export async function syncRankingAfterConfigChange(
+  key: string,
+  value: string | null,
+): Promise<void> {
+  if (!RANKING_CONFIG_KEYS.has(key)) return;
+  const listing = await storedListing();
+  if (!listing) return;
+  if (key === PUBLIC_RANKING_ENABLED_KEY) {
+    if (!isEnvFlagEnabled(key, false, { [key]: value ?? undefined })) {
+      emitOptedOut(listing.domain);
+    }
+    return;
+  }
+  if (!(await rankingEnabled())) return;
+
+  const identity = await currentIdentity({ key, value });
+  let rebuilt: TelemetryRanking | null = null;
+  if (identity.ok && identity.website === listing.domain) {
+    if (identity.name === listing.name) return;
+    try {
+      rebuilt = buildListing(identity, listing, listing.claim);
+    } catch {
+      // A name the listing cannot carry (over 60 characters) leaves the ranking.
+    }
+  }
+  if (!rebuilt) {
+    await setEnabled(false);
+    emitOptedOut(listing.domain);
+    return;
+  }
+  await upsertSwarmConfig({
+    scope: "global",
+    key: TELEMETRY_RANKING_KEY,
+    value: JSON.stringify(rebuilt),
+  });
+  emitOptedIn(rebuilt);
+}
+
+function conflict(res: ServerResponse, body: Record<string, unknown>): void {
+  res.writeHead(409, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleRanking(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (getRanking.match(req.method, pathSegments)) {
+    const parsed = await getRanking.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    // The state carries the claim and the PR that proves ownership of the listing.
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+    getRanking.respond(res, 200, await buildRankingState());
+    return true;
+  }
+
+  if (optIn.match(req.method, pathSegments)) {
+    const parsed = await optIn.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+
+    if (!(await telemetryReady())) {
+      conflict(res, {
+        error: "telemetry_off",
+        message: "Turn telemetry on first: the ranking counts tokens from telemetry.",
+      });
+      return true;
+    }
+    const identity = await currentIdentity();
+    if (!identity.ok || !identity.website) {
+      conflict(res, {
+        error: "org_identity_missing",
+        message: "Set the organization name and website first",
+        missing: identity.missing,
+      });
+      return true;
+    }
+
+    const website = identity.website;
+    const db = getDbClient();
+    // Read the stored claim under the write lock: two concurrent first opt-ins
+    // must return the same claim, or the one merged into community/ranking is lost.
+    const built = await db.transaction(async () => {
+      const stored = await storedListing();
+      const claim = stored?.domain === website ? stored.claim : mintRankingClaim();
+      let listing: TelemetryRanking;
+      try {
+        listing = buildListing(identity, parsed.body, claim);
+      } catch (error) {
+        return { ok: false as const, error };
+      }
+      await upsertSwarmConfig({
+        scope: "global",
+        key: TELEMETRY_RANKING_KEY,
+        value: JSON.stringify(listing),
+      });
+      await setEnabled(true);
+      db.afterCommit(() => emitOptedIn(listing));
+      return { ok: true as const, listing };
+    });
+    if (!built.ok) {
+      const issue = built.error instanceof z.ZodError ? built.error.issues[0] : undefined;
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: issue
+            ? `Invalid ${issue.path.join(".") || "listing"}: ${issue.message}`
+            : "Invalid listing",
+        }),
+      );
+      return true;
+    }
+    const { listing } = built;
+    scheduleIntegrationsReload();
+
+    optIn.respond(res, 200, {
+      domain: listing.domain,
+      claim: listing.claim,
+      listing,
+      fileJson: rankingEntryFile(listing),
+      prUrl: rankingPrUrl(listing),
+      verifyUrl: await verifyUrl(listing),
+    });
+    return true;
+  }
+
+  if (optOut.match(req.method, pathSegments)) {
+    const parsed = await optOut.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+    const listing = await storedListing();
+    await setEnabled(false);
+    if (listing) emitOptedOut(listing.domain);
+    scheduleIntegrationsReload();
+    optOut.respond(res, 200, {
+      enabled: false,
+      leaveUrl: listing ? rankingLeaveUrl(listing.domain) : null,
+    });
+    return true;
+  }
+
+  return false;
+}

package/src/http/realtime.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { getCombConfig } from "../comb/config";
+import { findUserById } from "../be/users";
 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 { dashboardUserIdHeader } from "./favorite-owner";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
@@ -14,14 +15,16 @@ const realtimeTicketRoute = route({
   pattern: ["api", "realtime", "ticket"],
   summary: "Issue a one-shot dashboard realtime ticket",
   tags: ["Rooms"],
-  rbac: { permission: "comb.presence" },
+  description:
+    "The ticket authorizes one dashboard socket for presence rooms: Comb drives (`comb.presence`) and sessions (`session.presence`). An operator-key tab's picked user (`X-Swarm-User-Id`) rides on the ticket so session presence can check that user's access.",
+  // Comb presence came first; a role granting only `comb.presence` keeps its ticket.
+  rbac: { permission: "session.presence", alsoAdmits: ["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" },
+    403: { description: "Presence is not allowed" },
   },
 });
 
@@ -37,7 +40,7 @@ route({
   },
 });
 
-/** `POST /api/realtime/ticket`: a one-shot ticket for a dashboard realtime socket (Comb presence). */
+/** `POST /api/realtime/ticket`: a one-shot ticket for a dashboard realtime socket (presence rooms). */
 export async function handleRealtimeTicket(
   req: IncomingMessage,
   res: ServerResponse,
@@ -45,34 +48,36 @@ export async function handleRealtimeTicket(
   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;
-  }
+  // Session presence needs the ticket with Comb off too; each room still
+  // checks its own verb and access when the socket joins it.
   const parsed = await realtimeTicketRoute.parse(req, res, pathSegments, queryParams);
   if (!parsed) return true;
   const auth = getRequestAuth(req);
   if (!auth || auth.kind === "agent" || auth.kind === "guest" || auth.kind === "controller") {
-    jsonError(res, "Comb presence requires dashboard authentication", 403);
+    jsonError(res, "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);
+  const allowed = (verb: "comb.presence" | "session.presence") =>
+    can({ principal, verb, resource: { kind: "none" }, source: "http" }).allow;
+  if (!allowed("comb.presence") && !allowed("session.presence")) {
+    jsonError(res, "Presence requires the comb.presence or session.presence permission", 403);
     return true;
   }
-  realtimeTicketRoute.respond(res, 200, issueRealtimeTicket(auth));
+  let dashboardUserId: string | undefined;
+  if (auth.kind === "operator" && !auth.page) {
+    const picked = dashboardUserIdHeader(req);
+    const user = picked ? await findUserById(picked) : null;
+    if (user?.status === "active") dashboardUserId = user.id;
+  }
+  realtimeTicketRoute.respond(
+    res,
+    200,
+    issueRealtimeTicket(dashboardUserId ? { ...auth, dashboardUserId } : auth),
+  );
   return true;
 }
 

package/src/http/route-def.ts

@@ -76,7 +76,20 @@ export interface RouteDef<
   auth?: {
     apiKey?: boolean; // default true
     agentId?: boolean; // requires X-Agent-ID
+    /**
+     * Why a user token may name an agent in X-Agent-ID here. Everywhere else
+     * `handleCore` refuses that pair. The user still needs `agent.act.any`.
+     */
+    userNamesAgent?: string;
   };
+  /**
+   * Session posture: how a user caller's session access gates this route.
+   * Required on every route keyed by a task, steering message or attachment,
+   * on every write whose body names a task, and on every active-session write
+   * (`session-route-posture.test.ts`).
+   * `handleCore` enforces the path forms; `parse()` enforces `bodyTaskIds`.
+   */
+  session?: SessionPosture;
   /**
    * RBAC posture (DES-445). Required on every non-GET route — enforced by
    * `bun run check:rbac-coverage` (CI). Either name the `PermissionVerb` the
@@ -84,7 +97,56 @@ export interface RouteDef<
    * Declarative in slice 1: the handler still calls `can()` itself; the role
    * engine (increment 3) may enforce the declared verb centrally.
    */
-  rbac?: { permission: PermissionVerb } | { ungated: string };
+  rbac?:
+    | { permission: PermissionVerb; alsoAdmits?: readonly PermissionVerb[] }
+    | { ungated: string };
+}
+
+/**
+ * - `taskParam` / `steeringParam`: the path param naming a task, or a steering
+ *   message whose task counts. A GET needs read access, any other method write.
+ * - `activeSessionParam`: the path param naming an active-session row; its task
+ *   counts the same way. A row with no task admits no user.
+ * - `bodyTaskIds`: the task ids a write's body names; each needs write access.
+ * - `agentWide`: why the route changes sessions across a whole agent. It
+ *   refuses every user actor; agents and the operator key keep access.
+ * - `none`: why the session does not gate this route.
+ */
+export type SessionPosture =
+  | { taskParam: string }
+  | { steeringParam: string }
+  | { activeSessionParam: string }
+  | { agentWide: string }
+  | { bodyTaskIds: (body: unknown) => readonly unknown[] }
+  | { none: string };
+
+/** A `bodyTaskIds` posture reading one top-level body key. */
+export function bodyTask(key: string): SessionPosture {
+  return { bodyTaskIds: (body) => [(body as Record<string, unknown> | null | undefined)?.[key]] };
+}
+
+/** A `bodyTaskIds` posture reading `key` off every item of the body's `listKey` array. */
+export function bodyListTask(listKey: string, key: string): SessionPosture {
+  return {
+    bodyTaskIds: (body) => {
+      const items = (body as Record<string, unknown> | null | undefined)?.[listKey];
+      return Array.isArray(items)
+        ? items.map((item) => (item as Record<string, unknown> | null)?.[key])
+        : [];
+    },
+  };
+}
+
+/** The raw `{name}` path params of `def` read off the request's segments. */
+export function routePathParams(def: RouteDef, pathSegments: string[]): Record<string, string> {
+  const params: Record<string, string> = {};
+  const paramNames = def.path.match(/\{(\w+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+  for (let i = 0; i < def.pattern.length; i++) {
+    if (def.pattern[i] === null && paramNames.length > 0) {
+      params[paramNames.shift()!] = pathSegments[i] ?? "";
+    }
+  }
+  return params;
 }
 
 interface ParsedRequest<TParams, TQuery, TBody> {
@@ -367,21 +429,25 @@ export function route<
 
     async parse(req, res, pathSegments, queryParams) {
       try {
-        // Extract path params from dynamic segments
-        const rawParams: Record<string, string> = {};
-        if (def.params) {
-          const paramNames = def.path.match(/\{(\w+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
-          for (let i = 0; i < def.pattern.length; i++) {
-            if (def.pattern[i] === null && paramNames.length > 0) {
-              rawParams[paramNames.shift()!] = pathSegments[i] ?? "";
-            }
+        const rawBody = def.body ? await parseBody(req, def.maxBodyBytes) : undefined;
+        // Session access first, so a malformed body cannot tell a reader
+        // anything about a session they cannot write in.
+        if (def.session && "bodyTaskIds" in def.session) {
+          // Lazy: session-access reaches the DB layer, which imports route files.
+          const { bodySessionDenial } = await import("./session-access");
+          const denial = await bodySessionDenial(req, def.session.bodyTaskIds(rawBody));
+          if (denial) {
+            jsonError(res, denial, 403);
+            return null;
           }
         }
 
         // Parse + validate each part
-        const params = def.params ? def.params.parse(rawParams) : undefined;
+        const params = def.params
+          ? def.params.parse(routePathParams(def, pathSegments))
+          : undefined;
         const query = def.query ? def.query.parse(Object.fromEntries(queryParams)) : undefined;
-        const body = def.body ? def.body.parse(await parseBody(req, def.maxBodyBytes)) : undefined;
+        const body = def.body ? def.body.parse(rawBody) : undefined;
 
         return { params, query, body } as ParsedRequest<
           z.infer<TParams>,

package/src/http/script-runs.ts

@@ -47,7 +47,7 @@ import {
   RawLlmConfigSchema,
   RawLlmOutputSchema,
 } from "../workflows/executors/raw-llm";
-import { route } from "./route-def";
+import { bodyTask, route } from "./route-def";
 import { json, jsonError } from "./utils";
 
 const DEFAULT_SCRIPT_RUN_CONCURRENCY_CAP = 10;
@@ -282,6 +282,7 @@ const agentTaskRoute = route({
   method: "post",
   path: "/api/internal/script-runs/{runId}/agent-task",
   pattern: ["api", "internal", "script-runs", null, "agent-task"],
+  session: bodyTask("parentTaskId"),
   operationId: "script_runs_internal_agent_task",
   summary: "Create or wait for a script workflow agent task step",
   tags: ["Script Runs"],

package/src/http/scripts.ts

@@ -225,6 +225,10 @@ const upsertRoute = route({
   method: "post",
   path: "/api/scripts/upsert",
   pattern: ["api", "scripts", "upsert"],
+  auth: {
+    userNamesAgent:
+      "dashboard script playground: a user runs or saves a script in a chosen agent's scope",
+  },
   operationId: "scripts_upsert",
   summary: "Create or update a reusable script",
   description: "Explicit script upserts run a TypeScript typecheck before writing.",
@@ -253,6 +257,10 @@ const runRoute = route({
   method: "post",
   path: "/api/scripts/run",
   pattern: ["api", "scripts", "run"],
+  auth: {
+    userNamesAgent:
+      "dashboard script playground: a user runs or saves a script in a chosen agent's scope",
+  },
   operationId: "scripts_run",
   summary: "Run a reusable or inline script",
   description: