@desplega.ai/agent-swarm 2.5.1 → 2.5.2

package/src/be/scripts/run-saved.ts

@@ -1,4 +1,4 @@
-import { type RunScriptOutput, runScript } from "../../scripts-runtime/loader";
+import type { RunScriptOutput } from "../../scripts-runtime/loader";
 import type { ScriptRecord } from "../../types";
 import {
   getScriptApiConnectionDescriptors,
@@ -6,6 +6,7 @@ import {
 } from "../script-connections";
 import { buildScriptCredentialBindingsWithFailures } from "../script-credential-broker";
 import { restoreScratchScriptLastUsedIfUnchanged, touchScratchScriptLastUsed } from "./db";
+import { runScriptWithRunCredential } from "./run-credential";
 
 export function getSavedScriptOwnerAgentId(script: ScriptRecord): string | null {
   return script.scopeId ?? script.createdByAgentId;
@@ -45,7 +46,7 @@ export async function runSavedScriptAsAgent(
         exitCode: 1,
         error: "killed",
       }
-    : await runScript({
+    : await runScriptWithRunCredential({
         source: args.script.source,
         args: args.input,
         fsMode: args.script.fsMode,

package/src/be/users.ts

@@ -615,6 +615,23 @@ export async function mintRuntimeToken(
   return await insertSessionToken(agentId, null, runtimeId, ttlMs);
 }
 
+/**
+ * Mint the short-lived `aseph_` token a script run uses for its `ctx.swarm`
+ * SDK calls, so those calls present the executing agent instead of the swarm
+ * API key (the operator). It resolves as a plain agent principal (`kind:
+ * "agent"`, no task/runtime binding), so the API layer scopes it to that
+ * agent's permissions: a lead keeps lead powers, a worker reads only its own
+ * scope. Marked `scriptRun` so it stays apart from the agent's worker token
+ * (see `AGENT_TOKEN_BINDING`). The run revokes it when it ends; `ttlMs` is the
+ * backstop for a run that dies without revoking.
+ */
+export async function mintScriptRunToken(
+  agentId: string,
+  ttlMs: number,
+): Promise<{ tokenId: string; plaintext: string }> {
+  return await insertSessionToken(agentId, null, null, ttlMs, null, undefined, null, null, true);
+}
+
 export async function insertSessionToken(
   agentId: string,
   taskId: string | null,
@@ -624,6 +641,7 @@ export async function insertSessionToken(
   expiresAtCeiling?: string,
   controllerId: string | null = null,
   parentTokenId: string | null = null,
+  scriptRun = false,
 ): Promise<{ tokenId: string; plaintext: string }> {
   const plaintext = `${SESSION_TOKEN_PREFIX}${base62(randomBytes(24))}`;
   const tokenId = randomUUID().replace(/-/g, "");
@@ -636,8 +654,8 @@ export async function insertSessionToken(
 
   await getDbClient().run(
     `INSERT INTO session_tokens
-     (id, tokenHash, tokenPreview, agentId, taskId, runtimeId, parentRuntimeId, expiresAt, createdAt, controllerId, parentTokenId)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+     (id, tokenHash, tokenPreview, agentId, taskId, runtimeId, parentRuntimeId, expiresAt, createdAt, controllerId, parentTokenId, scriptRun)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     [
       tokenId,
       hash,
@@ -650,6 +668,7 @@ export async function insertSessionToken(
       now.toISOString(),
       controllerId,
       parentTokenId,
+      scriptRun ? 1 : 0,
     ],
   );
 
@@ -713,9 +732,14 @@ export async function revokeRuntimeTokensForRuntime(runtimeId: string): Promise<
 // Agent tokens (long-lived, one agent, no runtime)
 // ---------------------------------------------------------------------------
 
-/** SQL predicate for an agent token: bound to its agent and nothing else. */
+/**
+ * SQL predicate for an agent (worker) token: bound to its agent and nothing
+ * else. `scriptRun = 0` excludes a script run's ephemeral token, which shares
+ * the same all-null binding shape but has its own lifecycle (see migration 233
+ * and `mintScriptRunToken`).
+ */
 const AGENT_TOKEN_BINDING =
-  "taskId IS NULL AND runtimeId IS NULL AND controllerId IS NULL AND parentRuntimeId IS NULL";
+  "taskId IS NULL AND runtimeId IS NULL AND controllerId IS NULL AND parentRuntimeId IS NULL AND scriptRun = 0";
 
 /** Stored expiry of a token that does not expire. `expiresAt` is NOT NULL. */
 export const AGENT_TOKEN_NO_EXPIRY = "9999-12-31T23:59:59.999Z";

package/src/http/all-routes.ts

@@ -70,6 +70,7 @@ import "./trackers/linear";
 import "./ranking";
 import "./used-by";
 import "./fleet-benchmark";
+import "./user-roles";
 import "./users";
 import "./webhooks";
 import "./workflow-events";

package/src/http/approval-requests.ts

@@ -20,8 +20,12 @@ import { findUserById } from "../be/users";
 import { can, type RbacPrincipal } from "../rbac";
 import type { User } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { cancelApprovalRequest } from "../workflows/approval-cancel";
-import { createApprovalFollowUpTask } from "../workflows/approval-notifications";
+import {
+  createApprovalFollowUpTask,
+  dispatchApprovalNotifications,
+} from "../workflows/approval-notifications";
 import { workflowEventBus } from "../workflows/event-bus";
 import { bodyTask, route } from "./route-def";
 import { jsonError } from "./utils";
@@ -288,7 +292,10 @@ const createRoute = route({
           target: z.string(),
         }),
       )
-      .optional(),
+      .optional()
+      .describe(
+        "Where to announce the request. A Slack target (channel or user ID) gets a card with the title, the questions and a link to the dashboard page that answers it. Slack targets need a lead agent caller (403 otherwise). Email is not supported yet and is skipped.",
+      ),
   }),
   responses: {
     201: {
@@ -296,6 +303,7 @@ const createRoute = route({
       schema: z.object({ approvalRequest: ApprovalRequestSchema }),
     },
     400: { description: "Validation error" },
+    403: { description: "Slack notifications require a lead agent" },
   },
   auth: { apiKey: true },
 });
@@ -578,7 +586,7 @@ export async function handleApprovalRequests(
     const parsed = await cancelRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
-    const { principal, resolvedBy } = await approvalCancelPrincipal(req);
+    const { principal, resolvedBy } = await approvalCallerPrincipal(req);
     const result = await cancelApprovalRequest({
       id: parsed.params.id,
       reason: parsed.body.reason,
@@ -619,6 +627,17 @@ export async function handleApprovalRequests(
     const parsed = await createRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
+    // Posting to Slack is lead-only everywhere else (slack-post); a caller that
+    // may not post must not reach an arbitrary channel through this route.
+    if (parsed.body.notifications?.some((notification) => notification.channel === "slack")) {
+      const { principal } = await approvalCallerPrincipal(req);
+      const decision = can({ principal, verb: "integration.slack.post", source: "http" });
+      if (!decision.allow) {
+        jsonError(res, SLACK_NOTIFICATION_REFUSED, 403);
+        return true;
+      }
+    }
+
     const id = crypto.randomUUID();
     // Prefer a trusted authenticated user (never client-controlled); else fall
     // back to the ownership-validated sourceTaskId the request body carries.
@@ -642,6 +661,24 @@ export async function handleApprovalRequests(
       createdBy,
     });
 
+    // Fire-and-forget: Slack must not delay or fail the 201. Workflow HITL
+    // requests are created by the executor directly, so they never post here.
+    const notifications = parsed.body.notifications;
+    if (notifications?.length && request.status === "pending") {
+      dispatchApprovalNotifications({
+        requestId: request.id,
+        title: request.title,
+        questions: parsed.body.questions,
+        timeoutSeconds: parsed.body.timeoutSeconds,
+        notifications,
+      }).catch((err) => {
+        console.error(
+          "[approval-requests] Unexpected error dispatching notifications:",
+          scrubSecrets(err instanceof Error ? err.message : String(err)),
+        );
+      });
+    }
+
     createRoute.respond(res, 201, {
       approvalRequest: await toApprovalRequestResponse(request),
     });
@@ -676,11 +713,14 @@ export async function handleApprovalRequests(
   return false;
 }
 
+const SLACK_NOTIFICATION_REFUSED =
+  "Slack notifications require lead privileges (integration.slack.post). Create the request without them, or ask the lead to post the link.";
+
 /**
- * The caller of the cancel route. The shared API key with an `X-Agent-ID`
- * header identifies that agent, as on the create route.
+ * The caller of the create and cancel routes. The shared API key with an
+ * `X-Agent-ID` header identifies that agent.
  */
-async function approvalCancelPrincipal(
+async function approvalCallerPrincipal(
   req: IncomingMessage,
 ): Promise<{ principal: RbacPrincipal; resolvedBy: string | null }> {
   const auth = getRequestAuth(req);

package/src/http/index.ts

@@ -139,6 +139,7 @@ import { handleTasks } from "./tasks";
 import { handleTelemetryUi } from "./telemetry-ui";
 import { handleTrackers } from "./trackers";
 import { handleUsedBy } from "./used-by";
+import { handleUserRoles } from "./user-roles";
 import { handleUsers } from "./users";
 import {
   getPathSegments,
@@ -404,6 +405,7 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleRuntimePools(req, res, pathSegments, queryParams, myAgentId),
         () => handleExtensions(req, res, pathSegments, queryParams, myAgentId),
         () => handleFavorites(req, res, pathSegments, queryParams, myAgentId),
+        () => handleUserRoles(req, res, pathSegments, queryParams),
         () => handleUsers(req, res, pathSegments, queryParams),
         () => handleSessions(req, res, pathSegments, queryParams, myAgentId),
         () => handleInboxState(req, res, pathSegments, queryParams),

package/src/http/schedules.ts

@@ -19,6 +19,7 @@ import {
 import { explicitModelErrorForAgent } from "../be/model-validation";
 import { mergeScheduleTiming, validateRecurringTiming } from "../be/schedules/validate";
 import { getScript } from "../be/scripts/db";
+import { can } from "../rbac";
 import { calculateNextRun, dispatchScheduleTarget } from "../scheduler/scheduler";
 import {
   AgentTaskSchema,
@@ -30,6 +31,7 @@ import {
   splitLegacyModelAlias,
 } from "../types";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
+import { agentFirstPrincipal } from "./request-principal";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
@@ -219,6 +221,7 @@ const updateSchedule = route({
   responses: {
     200: { description: "Schedule updated", schema: ScheduledTaskSchema.nullable() },
     400: { description: "Validation error" },
+    403: { description: "Deferral owned by another agent" },
     404: { description: "Schedule not found" },
     409: { description: "Duplicate name" },
   },
@@ -237,6 +240,7 @@ const patchSchedule = route({
   responses: {
     200: { description: "Schedule patched", schema: ScheduledTaskSchema.nullable() },
     400: { description: "Validation error" },
+    403: { description: "Deferral owned by another agent" },
     404: { description: "Schedule not found" },
     409: { description: "Duplicate name" },
   },
@@ -559,6 +563,28 @@ export async function handleSchedules(
       jsonError(res, "Schedule not found", 404);
       return true;
     }
+    // A deferral continues its owner's task, in that task's chat thread when
+    // it has one (src/scheduler/schedule-task.ts). An agent may change it only
+    // as its owner or a lead, as in the patch-schedule and update-schedule tools.
+    if (existing.taskType === "deferred") {
+      const principal = await agentFirstPrincipal(req, myAgentId);
+      if (
+        principal.kind === "agent" &&
+        !can({
+          principal,
+          verb: "schedule.deferral.update.any",
+          resource: { kind: "owned", ownerAgentId: existing.createdByAgentId },
+          source: "http",
+        }).allow
+      ) {
+        jsonError(
+          res,
+          `Schedule "${existing.name}" defers another agent's task. Only that agent or a lead can change it.`,
+          403,
+        );
+        return true;
+      }
+    }
     // A move to another agent re-judges the stored model against the new harness.
     const agentChanged =
       parsed.body.targetAgentId !== undefined &&

package/src/http/scripts.ts

@@ -32,6 +32,7 @@ import {
 } from "../be/scripts/db";
 import { searchScripts } from "../be/scripts/embeddings";
 import { extractArgsJsonSchema } from "../be/scripts/extract-schema";
+import { runScriptWithRunCredential } from "../be/scripts/run-credential";
 import { refuseSourceWithSecrets } from "../be/scripts/source-secrets";
 import {
   scriptSdkTypesWithGeneratedApis,
@@ -40,7 +41,6 @@ import {
 } from "../be/scripts/typecheck";
 import { can } from "../rbac";
 import { extractScriptSignature, type ScriptSignature } from "../scripts-runtime/extract-signature";
-import { runScript } from "../scripts-runtime/loader";
 import { checkQuickJSCompat, quickJSCompatWarnings } from "../scripts-runtime/quickjs-compat";
 import {
   ScriptApiAuthModeSchema,
@@ -782,7 +782,7 @@ export async function handleScripts(
       ? await touchScratchScriptLastUsed(namedScript.id)
       : null;
     const credentials = await buildScriptCredentialBindingsWithFailures({ agentId: agent.id });
-    const output = await runScript({
+    const output = await runScriptWithRunCredential({
       source: source as string,
       args: parsed.body.args,
       fsMode,

package/src/http/sessions.ts

@@ -26,7 +26,7 @@ import {
   moveSessionChains,
   type SessionKeyMove,
 } from "../be/db/session-moves";
-import { getSessionReadState, getSessionTree } from "../be/db/session-tree";
+import { getSessionReadState, getSessionTree, triageSessionList } from "../be/db/session-tree";
 import { getUserGrant } from "../be/rbac-roles";
 import {
   getSessionRoot,
@@ -157,6 +157,9 @@ const SessionTreeResponseSchema = z.object({
   later: SessionSectionCountsSchema,
   done: SessionSectionCountsSchema,
   noGroup: SessionSectionCountsSchema,
+  sources: z
+    .array(z.object({ source: z.string(), total: z.number().int() }))
+    .describe("Each root source in this view with its session count, hidden sources included."),
 });
 
 const SessionApprovalSchema = z.object({
@@ -480,6 +483,28 @@ async function handleAgentTokens(
   return true;
 }
 
+const SessionShowSchema = z
+  .enum(["mine", "all"])
+  .optional()
+  .describe(
+    "Sessions v2 view, for a user viewer with tree scope. mine (default): roots the user started from a human channel (not workflow, schedule, or system) plus sessions shared with the user. all: every tree session. Lists only: access is unchanged.",
+  );
+
+const SessionHideSourceSchema = z
+  .string()
+  // The same cap as the `hideSource` body field of `POST /api/session-triage`.
+  .refine((value) => value.split(",").length <= 32, "hideSource takes at most 32 sources.")
+  .optional()
+  .transform((value) =>
+    value
+      ?.split(",")
+      .map((source) => source.trim())
+      .filter(Boolean),
+  )
+  .describe(
+    "Comma-separated root sources to leave out (the sessions v2 source filter), e.g. `slack,chat`.",
+  );
+
 const listSessions = route({
   method: "get",
   path: "/api/sessions",
@@ -539,6 +564,10 @@ const listSessions = route({
       .describe(
         "mine: owned sessions. shared: sessions shared with me. tree: Sessions that GET /api/session-tree counts: mine plus shared with me, no ownerless roots. A bypass actor sees every root with tree scope.",
       ),
+    /** With `scope=tree`: `mine` (default) or `all`. Must match the tree's `show`. */
+    show: SessionShowSchema,
+    /** Root sources to leave out. Must match the tree's `hideSource`. */
+    hideSource: SessionHideSourceSchema,
   }),
   responses: {
     200: {
@@ -561,6 +590,7 @@ const sessionTree = route({
   pattern: ["api", "session-tree"],
   summary: "Get session groups and triage counts",
   tags: ["Sessions"],
+  query: z.object({ show: SessionShowSchema, hideSource: SessionHideSourceSchema }),
   responses: {
     200: { description: "Visible groups and section counts", schema: SessionTreeResponseSchema },
     401: { description: "Unauthorized" },
@@ -568,6 +598,39 @@ const sessionTree = route({
   auth: { apiKey: true },
 });
 
+const triageSessionListRoute = route({
+  method: "post",
+  path: "/api/session-triage",
+  pattern: ["api", "session-triage"],
+  summary: "Triage every session of one sidebar list",
+  description:
+    "The bulk bar's 'Select all N': Done, back to the Inbox, read, or unread for every session that one sessions v2 list shows the caller (the `GET /api/sessions?scope=tree` filters). Needs a picked user.",
+  tags: ["Sessions"],
+  body: z
+    .object({
+      action: z.enum(["done", "inbox", "read", "unread"]),
+      /** The list: one of Inbox, Later, Done, No group, or a group. */
+      triage: z.enum(["inbox", "later", "done"]).optional(),
+      noGroup: z.boolean().optional(),
+      groupKey: SessionKeyFilterSchema.optional(),
+      show: SessionShowSchema,
+      hideSource: z.array(z.string().min(1)).max(32).optional(),
+    })
+    .refine((body) => [body.triage, body.noGroup, body.groupKey].filter(Boolean).length === 1, {
+      message: "Name exactly one list: triage, noGroup, or groupKey",
+    }),
+  responses: {
+    200: {
+      description: "The number of sessions written",
+      schema: z.object({ updated: z.number().int() }),
+    },
+    400: { description: "Validation error, or no picked user" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: { ungated: "per-user inbox UI state, same posture as PATCH /api/inbox-state" },
+});
+
 const SESSION_MOVE_LIMIT = 200;
 const SESSION_MOVE_OWNER_ONLY = "Only the session owner can move this group";
 const SESSION_MOVE_UNAVAILABLE = "Session not found or not accessible";
@@ -877,6 +940,7 @@ export async function handleSessions(
     }
     const filterOpts = {
       source: sources,
+      hideSource: parsed.query.hideSource,
       q: parsed.query.q,
       requestedByUserId: parsed.query.requestedByUserId,
       contextKeyPrefix: parsed.query.contextKeyPrefix,
@@ -888,6 +952,7 @@ export async function handleSessions(
       withUserId: parsed.query.withUserId,
       now: new Date().toISOString(),
       tree: parsed.query.scope === "tree",
+      mine: parsed.query.scope === "tree" && parsed.query.show !== "all",
       ...(actor.kind === "user"
         ? {
             viewer: {
@@ -922,7 +987,33 @@ export async function handleSessions(
   if (sessionTree.match(req.method, pathSegments)) {
     const parsed = await sessionTree.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    sessionTree.respond(res, 200, await getSessionTree(await resolveSessionActor(req, myAgentId)));
+    const actor = await resolveSessionActor(req, myAgentId);
+    sessionTree.respond(
+      res,
+      200,
+      await getSessionTree(actor, undefined, {
+        mine: parsed.query.show !== "all",
+        hideSource: parsed.query.hideSource,
+      }),
+    );
+    return true;
+  }
+
+  if (triageSessionListRoute.match(req.method, pathSegments)) {
+    const parsed = await triageSessionListRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const actor = await resolveSessionActor(req, myAgentId);
+    if (actor.kind !== "user" || !actor.userId) {
+      jsonError(res, "Pick a user to triage sessions", 400);
+      return true;
+    }
+    const { action, show, ...list } = parsed.body;
+    const updated = await triageSessionList(
+      actor.userId,
+      { ...list, mine: show !== "all" },
+      action,
+    );
+    triageSessionListRoute.respond(res, 200, { updated });
     return true;
   }
 

package/src/http/user-roles.ts

@@ -0,0 +1,173 @@
+/**
+ * RBAC role assignment for people.
+ *
+ *   GET /api/rbac/roles
+ *   GET /api/users/:id/roles
+ *   PUT /api/users/:id/roles
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getUserById } from "../be/db";
+import {
+  getUserGrant,
+  InvalidRoleSetError,
+  LastAdminError,
+  listRbacRoles,
+  listUserRoles,
+  PRIMARY_ROLE_NAMES,
+  setUserRoles,
+} from "../be/rbac-roles";
+import { recordIdentityEvent } from "../be/users";
+import { can, isRbacEnabled } from "../rbac";
+import { RbacRoleSchema, UserRbacRolesSchema } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
+import { getOperatorActor } from "./operator-actor";
+import { agentFirstPrincipal, rejectGuest } from "./request-principal";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+const listRolesRoute = route({
+  method: "get",
+  path: "/api/rbac/roles",
+  pattern: ["api", "rbac", "roles"],
+  operationId: "rbac_listRoles",
+  summary: "List RBAC roles with their verbs",
+  tags: ["Users"],
+  responses: {
+    200: { description: "Role catalog", schema: z.object({ roles: z.array(RbacRoleSchema) }) },
+  },
+});
+
+const getUserRolesRoute = route({
+  method: "get",
+  path: "/api/users/{id}/roles",
+  pattern: ["api", "users", null, "roles"],
+  operationId: "users_getRbacRoles",
+  summary: "Get a user's RBAC roles",
+  tags: ["Users"],
+  params: z.object({ id: z.string().min(1) }),
+  responses: {
+    200: { description: "The user's roles", schema: UserRbacRolesSchema },
+    404: { description: "User not found" },
+  },
+});
+
+const setUserRolesRoute = route({
+  method: "put",
+  path: "/api/users/{id}/roles",
+  pattern: ["api", "users", null, "roles"],
+  operationId: "users_setRbacRoles",
+  summary: "Set a user's RBAC roles",
+  description: `Replaces the user's roles. The set holds exactly one of ${PRIMARY_ROLE_NAMES.join(", ")} plus any extra roles. Demoting a user below admin removes the ability to answer approval requests, even when the user is listed as an approver. Fails with 409 when it would leave no active admin.`,
+  tags: ["Users"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z.object({ roles: z.array(z.string().min(1)).min(1) }).strict(),
+  responses: {
+    200: { description: "The user's roles after the change", schema: UserRbacRolesSchema },
+    400: { description: "Invalid role set" },
+    403: { description: "Not allowed to change roles" },
+    404: { description: "User not found" },
+    409: { description: "Would leave no active admin" },
+  },
+  rbac: { permission: "user.role.manage" },
+});
+
+async function composeRoles(userId: string) {
+  const [catalog, held] = await Promise.all([listRbacRoles(), listUserRoles(userId)]);
+  const names = new Set(held.map((role) => role.name));
+  return { userId, roles: catalog.filter((role) => names.has(role.name)) };
+}
+
+/** Operator or user only; agents never change human roles, even with the shared key. */
+async function ensureRoleManager(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (rejectGuest(req, res)) return false;
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "operator" && auth?.kind !== "user") {
+    jsonError(res, "Role changes require operator or user credentials", 403);
+    return false;
+  }
+  const header = req.headers["x-agent-id"];
+  const decision = can({
+    principal: await agentFirstPrincipal(req, Array.isArray(header) ? header[0] : header),
+    verb: "user.role.manage",
+    resource: { kind: "none" },
+    source: "http",
+  });
+  if (!decision.allow) {
+    jsonError(res, decision.reason, 403);
+    return false;
+  }
+  // A custom role holding user.role.manage must not be able to grant admin.
+  if (auth.kind === "user" && isRbacEnabled() && !(await getUserGrant(auth.userId)).grantsAll) {
+    jsonError(res, "Role changes require a grant-all role", 403);
+    return false;
+  }
+  return true;
+}
+
+export async function handleUserRoles(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listRolesRoute.match(req.method, pathSegments)) {
+    if (rejectGuest(req, res)) return true;
+    listRolesRoute.respond(res, 200, { roles: await listRbacRoles() });
+    return true;
+  }
+
+  if (getUserRolesRoute.match(req.method, pathSegments)) {
+    if (rejectGuest(req, res)) return true;
+    const parsed = await getUserRolesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await getUserById(parsed.params.id))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    getUserRolesRoute.respond(res, 200, await composeRoles(parsed.params.id));
+    return true;
+  }
+
+  if (setUserRolesRoute.match(req.method, pathSegments)) {
+    const parsed = await setUserRolesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureRoleManager(req, res))) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    const userId = parsed.params.id;
+    if (!(await getUserById(userId))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    try {
+      const { before, after } = await setUserRoles(
+        userId,
+        parsed.body.roles,
+        actor.kind === "user" ? actor.id : null,
+      );
+      await recordIdentityEvent(
+        userId,
+        "profile_changed",
+        actor,
+        { rbacRoles: before },
+        { rbacRoles: after },
+      );
+    } catch (err) {
+      if (err instanceof LastAdminError) {
+        jsonError(res, "last_admin", 409);
+        return true;
+      }
+      if (err instanceof InvalidRoleSetError) {
+        jsonError(res, err.message, 400);
+        return true;
+      }
+      throw err;
+    }
+    setUserRolesRoute.respond(res, 200, await composeRoles(userId));
+    return true;
+  }
+
+  return false;
+}

package/src/http/users.ts

@@ -45,6 +45,7 @@ import {
   updateUser,
   upsertBudget,
 } from "../be/db";
+import { assertNotLastAdmin, LastAdminError } from "../be/rbac-roles";
 import {
   getUserIdentities,
   type IdentityEvent,
@@ -484,6 +485,7 @@ const mergeUsersRoute = route({
     400: { description: "Validation error (e.g. target == source)" },
     401: { description: "Unauthorized" },
     404: { description: "Target or source user not found" },
+    409: { description: "Source is the last active admin (last_admin)" },
   },
   auth: { apiKey: true },
 });
@@ -1071,6 +1073,9 @@ export async function handleUsers(
           }
         }
 
+        // The source's roles go with it; never leave the swarm without an admin.
+        await assertNotLastAdmin(sourceId);
+
         // Delete source — CASCADE cleans up any leftover external_ids row that
         // we may have missed. Retained user references move to the target.
         await deleteUser(sourceId, targetId);
@@ -1095,6 +1100,10 @@ export async function handleUsers(
       });
       mergeUsersRoute.respond(res, 200, { user: mergedUser });
     } catch (err) {
+      if (err instanceof LastAdminError) {
+        jsonError(res, "last_admin", 409);
+        return true;
+      }
       jsonError(res, err instanceof Error ? err.message : "Failed to merge users", 500);
     }
     return true;