@desplega.ai/agent-swarm 2.5.1 → 2.5.2

package/src/be/db/session-tree.ts

@@ -6,12 +6,18 @@ import {
 } from "../../assets/key";
 import { isTerminalTaskStatus, TERMINAL_TASK_STATUSES } from "../../types";
 import { getDbClient, literalPrefixPattern } from "../db";
-import { type SessionViewer, sessionViewerCondition } from "./session-visibility";
+import {
+  type SessionViewer,
+  sessionMineCondition,
+  sessionViewerCondition,
+} from "./session-visibility";
 
 export type SessionReadState = "unread" | "read" | "later" | "done";
 export interface SessionFilters {
   /** Restrict roots to these task sources. */
   source?: string[];
+  /** Leave out roots of these task sources (the sessions v2 source filter). */
+  hideSource?: string[];
   /** Match root task text or title with a case-insensitive substring. */
   q?: string;
   /** Match the root requester, excluding NULL requester rows. */
@@ -36,6 +42,8 @@ export interface SessionFilters {
   now?: string;
   /** Exclude ownerless roots for user viewers to match the tree's visibility. */
   tree?: boolean;
+  /** For user viewers: only human-started roots of the viewer and shares (the "Mine" view). */
+  mine?: boolean;
   /** Match exactly this root (one session's summary, e.g. its read state). */
   rootId?: string;
 }
@@ -89,6 +97,9 @@ export function sessionRootFilter(opts: SessionFilters = {}): SqlFragment {
   const sources = opts.source?.filter(Boolean) ?? [];
   if (sources.length)
     add({ sql: `r.source IN (${sources.map(() => "?").join(",")})`, params: sources });
+  const hidden = opts.hideSource?.filter(Boolean) ?? [];
+  if (hidden.length)
+    add({ sql: `r.source NOT IN (${hidden.map(() => "?").join(",")})`, params: hidden });
   if (opts.q?.trim()) {
     const like = `%${opts.q.trim().toLowerCase()}%`;
     add({
@@ -106,6 +117,7 @@ export function sessionRootFilter(opts: SessionFilters = {}): SqlFragment {
   if (opts.viewer) {
     add(sessionViewerCondition(opts.viewer));
     if (opts.tree) conditions.push("r.requestedByUserId IS NOT NULL");
+    if (opts.mine) add(sessionMineCondition(opts.viewer.userId));
   }
   if (opts.keyPrefix) {
     const { lo, hi } = keyPrefixRange(opts.keyPrefix);
@@ -322,25 +334,32 @@ export interface SessionTree {
   later: SessionSectionCounts;
   done: SessionSectionCounts;
   noGroup: SessionSectionCounts;
+  /** Each root source in this view with its session count, hidden sources included, most first. */
+  sources: { source: string; total: number }[];
 }
 
 export async function getSessionTree(
   actor: { kind: "bypass" } | { kind: "user"; userId: string | null },
   now?: string,
+  opts: { mine?: boolean; hideSource?: string[] } = {},
 ): Promise<SessionTree> {
+  // No source filter in SQL: the source counts must include hidden sources,
+  // so the filter menu can offer them back. The loop skips them instead.
   const query = sessionSummaryQuery({
     ...(actor.kind === "user" ? { viewer: { userId: actor.userId, scope: "all" } as const } : {}),
     now,
     tree: true,
+    mine: opts.mine,
   });
   const rows = await getDbClient().query<{
     key: string;
+    source: string;
     lastActivityAt: string;
     latestStatus: string;
     readState: SessionReadState | null;
     needsYou: number;
   }>(
-    `SELECT r."key", a.lastActivityAt, a.latestStatus, a.readState, a.needsYou
+    `SELECT r."key", r.source, a.lastActivityAt, a.latestStatus, a.readState, a.needsYou
     FROM (${query.sql}) a CROSS JOIN agent_tasks r ON r.id = a.root_id`,
     query.params,
   );
@@ -351,7 +370,10 @@ export async function getSessionTree(
     later: counts(),
     done: counts(),
     noGroup: counts(),
+    sources: [],
   };
+  const hidden = new Set(opts.hideSource);
+  const sources = new Map<string, number>();
   const groups = new Map<string, SessionTreeGroup>();
   const add = (section: SessionSectionCounts, row: (typeof rows)[number]) => {
     section.total++;
@@ -360,6 +382,8 @@ export async function getSessionTree(
     if (row.needsYou) section.needsYou++;
   };
   for (const row of rows) {
+    sources.set(row.source, (sources.get(row.source) ?? 0) + 1);
+    if (hidden.has(row.source)) continue;
     const key = sessionGroupKey(row.key);
     const noGroup =
       key === "shared/" || (actor.kind === "user" && key === `personal/${actor.userId}/`);
@@ -380,5 +404,68 @@ export async function getSessionTree(
     }
   }
   result.groups = [...groups.values()].sort((a, b) => a.key.localeCompare(b.key));
+  result.sources = [...sources]
+    .map(([source, total]) => ({ source, total }))
+    .sort((a, b) => b.total - a.total || a.source.localeCompare(b.source));
   return result;
 }
+
+/** Triage actions on a whole list: the bulk bar's "Select all N". */
+export type SessionListTriage = "done" | "inbox" | "read" | "unread";
+
+/** The read cursor of "unread". The dashboard and the my-swarm app write the same value. */
+const UNREAD_CURSOR = "1970-01-01T00:00:00.000Z";
+
+/**
+ * Apply one triage action to every session a sidebar list shows `userId`
+ * (the same filters as `GET /api/sessions?scope=tree`), in one statement.
+ * The rows match what the dashboard writes for one session: Done, back to
+ * the Inbox, read up to the newest activity, or unread. Returns the number
+ * of sessions written.
+ */
+export async function triageSessionList(
+  userId: string,
+  filters: Pick<SessionFilters, "triage" | "noGroup" | "groupKey" | "mine" | "hideSource" | "now">,
+  action: SessionListTriage,
+): Promise<number> {
+  const now = filters.now ?? new Date().toISOString();
+  const query = sessionSummaryQuery({
+    ...filters,
+    now,
+    viewer: { userId, scope: "all" },
+    tree: true,
+  });
+  const status = action === "done" ? "done" : "open";
+  // `read` moves the cursor to each session's newest activity, `unread` to the epoch.
+  const lastReadAt =
+    action === "read" ? "a.lastActivityAt" : action === "unread" ? `'${UNREAD_CURSOR}'` : "NULL";
+  const setsLastRead = action === "read" || action === "unread";
+  // The conflict rules copy `upsertInboxState` in src/be/db.ts (sticky readAt,
+  // lastReadAt only when the action sets it, snooze and dismiss cleared). Keep
+  // the two in step. `WHERE true` is required: SQLite cannot parse
+  // INSERT ... SELECT ... ON CONFLICT when the SELECT has no WHERE clause.
+  const result = await getDbClient().run(
+    `INSERT INTO inbox_item_state
+      (userId, itemType, itemId, status, snoozeUntil, dismissedAt, doneAt, readAt, lastReadAt, createdAt, lastUpdatedAt)
+    SELECT ?, 'to_read', a.root_id, ?, NULL, NULL, ?, ?, ${lastReadAt}, ?, ?
+    FROM (${query.sql}) a WHERE true
+    ON CONFLICT(userId, itemType, itemId) DO UPDATE SET
+      status = excluded.status,
+      snoozeUntil = NULL,
+      dismissedAt = NULL,
+      doneAt = excluded.doneAt,
+      readAt = COALESCE(inbox_item_state.readAt, excluded.readAt),
+      lastReadAt = ${setsLastRead ? "excluded.lastReadAt" : "inbox_item_state.lastReadAt"},
+      lastUpdatedAt = excluded.lastUpdatedAt`,
+    [
+      userId,
+      status,
+      action === "done" ? now : null,
+      action === "read" ? now : null,
+      now,
+      now,
+      ...query.params,
+    ],
+  );
+  return result.changes;
+}

package/src/be/db/session-visibility.ts

@@ -27,3 +27,34 @@ export function sessionViewerCondition(viewer: SessionViewer): {
     params: [viewer.userId, viewer.userId],
   };
 }
+
+/**
+ * Root sources that a machine starts: a workflow run, a schedule, or the
+ * swarm itself (heartbeat, follow-ups, budget and approval notices). A
+ * workflow root carries the user whose trigger fired it, so the requester
+ * alone does not tell a person's session from fan-out. `kapso-inbound` is the
+ * exception: a WhatsApp message a person sent, written with `system`.
+ */
+export const MACHINE_SESSION_SOURCES = ["workflow", "schedule", "system"] as const;
+const HUMAN_SYSTEM_TASK_TYPES = ["kapso-inbound"] as const;
+
+/**
+ * The sessions v2 "Mine" view (alias `r`): roots this user started from a
+ * human channel (every source outside {@link MACHINE_SESSION_SOURCES}), plus
+ * sessions shared with this user or everyone. A list filter only: it narrows
+ * what a list shows and never changes who can open a session.
+ */
+export function sessionMineCondition(userId: string | null): {
+  sql: string;
+  params: (string | null)[];
+} {
+  const machine = MACHINE_SESSION_SOURCES.map(() => "?").join(",");
+  const humanSystem = HUMAN_SYSTEM_TASK_TYPES.map(() => "?").join(",");
+  return {
+    sql: `((r.requestedByUserId = ? AND (r.source NOT IN (${machine})
+        OR (r.source = 'system' AND r.taskType IN (${humanSystem}))))
+      OR EXISTS (SELECT 1 FROM session_shares s
+        WHERE s.rootTaskId = r.id AND s.revokedAt IS NULL AND (s.userId IS NULL OR s.userId = ?)))`,
+    params: [userId, ...MACHINE_SESSION_SOURCES, ...HUMAN_SYSTEM_TASK_TYPES, userId],
+  };
+}

package/src/be/db/tasks/read.ts

@@ -1715,6 +1715,18 @@ export async function getLatestLeadTaskInThread(
   return row ? rowToAgentTask(row) : null;
 }
 
+/**
+ * `source` filter of the contextKey lookups below. `'chat'` also matches a
+ * defer-task wake-up of a chat task: it keeps the chat contextKey with
+ * `source = 'schedule'` (src/scheduler/schedule-task.ts) and continues the
+ * same ask, so `/cancel`, steering and routing treat it as the chat task.
+ * Binds `source` three times.
+ */
+function contextKeySourceSql(alias = ""): string {
+  return `(? IS NULL OR ${alias}source = ?
+          OR (? = 'chat' AND ${alias}source = 'schedule' AND ${alias}taskType = 'deferred'))`;
+}
+
 /**
  * ContextKey twins of the Slack thread lookups above, for channels that key a
  * conversation by `contextKey` only (Chat SDK). `source` narrows to the
@@ -1731,7 +1743,7 @@ export async function getAgentWorkingOnContextKey(
   const taskRow = await getDbClient().get<AgentTaskRow>(
     `SELECT agentId FROM agent_tasks
        WHERE contextKey = ?
-       AND (? IS NULL OR source = ?)
+       AND ${contextKeySourceSql()}
        AND (? IS NULL
             OR status NOT IN (${TERMINAL_TASK_STATUSES.map(() => "?").join(", ")})
             OR finishedAt >= ?)
@@ -1741,6 +1753,7 @@ export async function getAgentWorkingOnContextKey(
       contextKey,
       source ?? null,
       source ?? null,
+      source ?? null,
       endedSince ?? null,
       ...TERMINAL_TASK_STATUSES,
       endedSince ?? null,
@@ -1760,11 +1773,11 @@ export async function getLatestActiveTaskByContextKey(
   const row = await getDbClient().get<AgentTaskRow>(
     `SELECT * FROM agent_tasks
        WHERE contextKey = ?
-       AND (? IS NULL OR source = ?)
+       AND ${contextKeySourceSql()}
        AND status IN ('in_progress', 'pending')
        ORDER BY createdAt DESC, rowid DESC
        LIMIT 1`,
-    [contextKey, source ?? null, source ?? null],
+    [contextKey, source ?? null, source ?? null, source ?? null],
   );
 
   return row ? rowToAgentTask(row) : null;
@@ -1780,11 +1793,11 @@ export async function getLatestLeadTaskByContextKey(
        FROM agent_tasks t
        JOIN agents a ON a.id = t.agentId
        WHERE t.contextKey = ?
-         AND (? IS NULL OR t.source = ?)
+         AND ${contextKeySourceSql("t.")}
          AND a.isLead = 1
        ORDER BY t.createdAt DESC, t.rowid DESC
        LIMIT 1`,
-    [contextKey, source ?? null, source ?? null],
+    [contextKey, source ?? null, source ?? null, source ?? null],
   );
 
   return row ? rowToAgentTask(row) : null;

package/src/be/db.ts

@@ -12629,6 +12629,8 @@ export async function upsertInboxState(opts: {
 
   // SQLite upsert via UNIQUE(userId, itemType, itemId). readAt is sticky: the
   // first non-null value written wins on every subsequent conflict.
+  // `triageSessionList` in src/be/db/session-tree.ts copies these conflict
+  // rules for whole-list triage. Keep the two in step.
   const row = await getDbClient().get<InboxItemStateRow>(
     `INSERT INTO inbox_item_state (userId, itemType, itemId, status, snoozeUntil, dismissedAt, doneAt, readAt, lastReadAt, createdAt, lastUpdatedAt)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)

package/src/be/migrations/233_script_run_session_tokens.sql

@@ -0,0 +1,8 @@
+-- Mark the ephemeral session token a script run uses for its ctx.swarm SDK
+-- calls, so it stands in for the executing agent instead of the operator key.
+-- It shares the all-null binding shape of an agent (worker) token, so this
+-- flag is what keeps the two lifecycles apart: worker-token queries
+-- (AGENT_TOKEN_BINDING) filter on scriptRun = 0, so minting or revoking an
+-- agent's worker token never touches a script run's in-flight token, and a
+-- script run's token never counts as the agent's worker token.
+ALTER TABLE session_tokens ADD COLUMN scriptRun INTEGER NOT NULL DEFAULT 0;

package/src/be/migrations/235_chat_relay_defer.sql

@@ -0,0 +1,86 @@
+-- Chat relay and defer-task (see 217_chat_sdk_state.sql for the obligation table).
+--
+-- 1. A deferred task posts nothing. `defer-task` completes the task with a
+--    "deferred until ..." placeholder, which the terminal trigger enqueues like
+--    any answer. `completeTask` writes `deferredAt` after the status, in the same
+--    transaction, so this trigger drops the obligation before it commits.
+-- 2. The wake-up task (`source='schedule'`, `taskType='deferred'`) keeps the
+--    chat contextKey of the task it continues (src/scheduler/schedule-task.ts),
+--    and relays like a chat task: it carries the real answer. The scheduler
+--    grants the key only to the deferring agent continuing a task that itself
+--    answered in chat; the triggers also require that the wake-up runs as the
+--    same agent on the same thread as its parent.
+
+CREATE TRIGGER drop_chat_relay_on_defer
+AFTER UPDATE OF deferredAt ON agent_tasks
+WHEN NEW.deferredAt IS NOT NULL AND OLD.deferredAt IS NULL
+BEGIN
+  DELETE FROM chat_relay_obligations
+  WHERE task_id = NEW.id AND delivered_at IS NULL;
+END;
+
+-- Placeholders already queued by earlier deferrals.
+DELETE FROM chat_relay_obligations
+WHERE delivered_at IS NULL
+  AND given_up_at IS NULL
+  AND task_id IN (SELECT id FROM agent_tasks WHERE deferredAt IS NOT NULL);
+
+DROP TRIGGER IF EXISTS enqueue_chat_relay_after_terminal_update;
+DROP TRIGGER IF EXISTS enqueue_chat_relay_after_terminal_insert;
+
+CREATE TRIGGER enqueue_chat_relay_after_terminal_update
+AFTER UPDATE OF status ON agent_tasks
+WHEN OLD.status NOT IN ('completed', 'failed', 'cancelled', 'superseded')
+  AND NEW.status IN ('completed', 'failed', 'cancelled')
+  AND NEW.contextKey GLOB 'task:chat-sdk:*'
+  AND (
+    NEW.source = 'chat'
+    OR (NEW.source = 'system' AND NEW.taskType = 'follow-up')
+    OR (
+      NEW.source = 'schedule'
+      AND NEW.taskType = 'deferred'
+      AND EXISTS (
+        SELECT 1 FROM agent_tasks parent
+        WHERE parent.id = NEW.parentTaskId
+          AND parent.agentId = NEW.agentId
+          AND parent.contextKey = NEW.contextKey
+      )
+    )
+    OR (
+      NEW.source = 'system'
+      AND NEW.taskType = 'resume'
+      AND EXISTS (SELECT 1 FROM agents WHERE agents.id = NEW.agentId AND agents.isLead = 1)
+    )
+  )
+BEGIN
+  INSERT OR IGNORE INTO chat_relay_obligations (task_id)
+  VALUES (NEW.id);
+END;
+
+CREATE TRIGGER enqueue_chat_relay_after_terminal_insert
+AFTER INSERT ON agent_tasks
+WHEN NEW.status IN ('completed', 'failed', 'cancelled')
+  AND NEW.contextKey GLOB 'task:chat-sdk:*'
+  AND (
+    NEW.source = 'chat'
+    OR (NEW.source = 'system' AND NEW.taskType = 'follow-up')
+    OR (
+      NEW.source = 'schedule'
+      AND NEW.taskType = 'deferred'
+      AND EXISTS (
+        SELECT 1 FROM agent_tasks parent
+        WHERE parent.id = NEW.parentTaskId
+          AND parent.agentId = NEW.agentId
+          AND parent.contextKey = NEW.contextKey
+      )
+    )
+    OR (
+      NEW.source = 'system'
+      AND NEW.taskType = 'resume'
+      AND EXISTS (SELECT 1 FROM agents WHERE agents.id = NEW.agentId AND agents.isLead = 1)
+    )
+  )
+BEGIN
+  INSERT OR IGNORE INTO chat_relay_obligations (task_id)
+  VALUES (NEW.id);
+END;

package/src/be/migrations/237_session_inbox_cleanup.sql

@@ -0,0 +1,75 @@
+-- Sessions v2: a one-time Inbox cleanup. Until now a session with no triage
+-- row stayed in the Inbox forever, so long-time users opened an Inbox with
+-- thousands of old sessions.
+--
+-- For every user who sees a session in the sessions v2 tree (the owner, a
+-- direct share, or a share with everyone), the session moves to Done when it
+-- reads as "read" for that user, its chain had no activity in the last 7
+-- days, its latest task is finished (completed, failed, cancelled, or
+-- superseded), and no approval in it waits for an answer. A stuck running
+-- session or a pending approval stays in the Inbox. "Read" is the rule of
+-- `sessionReadStateSql` in src/be/db/session-tree.ts: no triage row (quiet
+-- for 7 days is read), or an open row whose read cursor covers the newest
+-- activity. Snoozed, done,
+-- dismissed, and unread sessions keep their state. New activity brings a
+-- Done session back to the Inbox as unread, as for a session marked Done by
+-- hand. Ownerless roots are not in the tree and get no rows.
+
+CREATE TEMP TABLE _quiet_sessions AS
+WITH RECURSIVE chain(root_id, id, lastUpdatedAt, status) AS (
+  SELECT id, id, lastUpdatedAt, status FROM agent_tasks
+  WHERE parentTaskId IS NULL AND requestedByUserId IS NOT NULL
+  UNION ALL
+  SELECT c.root_id, t.id, t.lastUpdatedAt, t.status
+  FROM chain c JOIN agent_tasks t ON t.parentTaskId = c.id
+), activity AS (
+  -- SQLite takes the bare status from the row with MAX(lastUpdatedAt), as
+  -- the session list does. Keep MAX the only MIN/MAX aggregate here.
+  SELECT root_id, MAX(lastUpdatedAt) AS lastActivityAt, status AS latestStatus,
+    SUM(EXISTS (SELECT 1 FROM approval_requests ar
+      WHERE ar.sourceTaskId = chain.id AND ar.status = 'pending')) AS pendingApproval
+  FROM chain GROUP BY root_id
+), quiet AS (
+  SELECT root_id, lastActivityAt FROM activity
+  WHERE lastActivityAt <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days')
+    AND latestStatus IN ('completed', 'failed', 'cancelled', 'superseded')
+    AND pendingApproval = 0
+), viewers AS (
+  SELECT r.requestedByUserId AS userId, q.root_id AS rootId, q.lastActivityAt
+  FROM quiet q JOIN agent_tasks r ON r.id = q.root_id
+  UNION
+  SELECT s.userId, q.root_id, q.lastActivityAt
+  FROM quiet q JOIN session_shares s ON s.rootTaskId = q.root_id
+  WHERE s.revokedAt IS NULL AND s.userId IS NOT NULL
+  UNION
+  SELECT u.id, q.root_id, q.lastActivityAt
+  FROM quiet q JOIN session_shares s ON s.rootTaskId = q.root_id CROSS JOIN users u
+  WHERE s.revokedAt IS NULL AND s.userId IS NULL
+)
+SELECT v.userId, v.rootId, v.lastActivityAt
+FROM viewers v JOIN users u ON u.id = v.userId;
+
+-- Open rows that read as read: their cursor covers the newest activity.
+UPDATE inbox_item_state
+SET status = 'done',
+  doneAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+  lastUpdatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+WHERE itemType = 'to_read'
+  AND status = 'open'
+  AND EXISTS (
+    SELECT 1 FROM _quiet_sessions q
+    WHERE q.userId = inbox_item_state.userId
+      AND q.rootId = inbox_item_state.itemId
+      AND q.lastActivityAt <= COALESCE(inbox_item_state.lastReadAt, inbox_item_state.lastUpdatedAt)
+  );
+
+-- No row yet: quiet for 7 days already reads as read.
+INSERT OR IGNORE INTO inbox_item_state
+  (userId, itemType, itemId, status, doneAt, createdAt, lastUpdatedAt)
+SELECT q.userId, 'to_read', q.rootId, 'done',
+  strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+  strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+  strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+FROM _quiet_sessions q;
+
+DROP TABLE _quiet_sessions;

package/src/be/rbac-roles.ts

@@ -1,5 +1,6 @@
 import type { PermissionVerb } from "../rbac";
 import { PermissionVerbSchema } from "../rbac";
+import { invalidateTelemetryUserRole } from "../telemetry-identity";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { getDb, getDbClient } from "./db";
 
@@ -39,8 +40,19 @@ export const BUILTIN_ROLES = [
       "session.presence",
     ],
   },
+  {
+    id: "rbac-role-viewer",
+    name: "viewer",
+    description: "Read-only: no task, approval or script writes.",
+    isBuiltin: true,
+    grantsAll: false,
+    verbs: ["favorite.write.own", "session.presence"],
+  },
 ] satisfies (BuiltinRoleDefinition & { isBuiltin: true })[];
 
+/** A person holds exactly one of these; other roles are extras on top. */
+export const PRIMARY_ROLE_NAMES: readonly string[] = ["admin", "requester", "viewer"];
+
 export type EffectiveGrant = {
   grantsAll: boolean;
   verbs: ReadonlySet<PermissionVerb>;
@@ -80,6 +92,8 @@ type RoleIdentityRow = {
   name: string;
 };
 
+type GrantRoleRow = RoleIdentityRow & { grantsAll: number };
+
 type UserRoleRow = {
   id: string;
   name: string;
@@ -233,6 +247,130 @@ export async function listUserRoles(userId: string): Promise<UserRole[]> {
   return rows.map(roleRowToUserRole);
 }
 
+export type RbacRoleCatalogEntry = UserRole & { primary: boolean; verbs: string[] };
+
+/** Every role with its verbs, for the role picker. */
+export async function listRbacRoles(): Promise<RbacRoleCatalogEntry[]> {
+  const client = getDbClient();
+  const roles = await client.query<UserRoleRow>(
+    "SELECT id, name, description, isBuiltin, grantsAll, createdAt FROM roles ORDER BY name",
+  );
+  const perms = await client.query<{ roleId: string; verb: string }>(
+    "SELECT roleId, verb FROM role_permissions ORDER BY verb",
+  );
+  return roles.map((row) => ({
+    ...roleRowToUserRole(row),
+    primary: PRIMARY_ROLE_NAMES.includes(row.name),
+    verbs: perms.filter((p) => p.roleId === row.id).map((p) => p.verb),
+  }));
+}
+
+export class InvalidRoleSetError extends Error {}
+
+export class LastAdminError extends Error {
+  constructor() {
+    super("last_admin");
+  }
+}
+
+/**
+ * Throw LastAdminError when removing this user would leave the swarm without
+ * an active grant-all user. Joins the caller's transaction.
+ */
+export async function assertNotLastAdmin(userId: string): Promise<void> {
+  const client = getDbClient();
+  const self = await client.get<{ n: number }>(
+    `SELECT COUNT(*) AS n
+     FROM users u
+     JOIN principal_roles pr ON pr.principalType = 'user' AND pr.principalId = u.id
+     JOIN roles r ON r.id = pr.roleId AND r.grantsAll = 1
+     WHERE u.status = 'active' AND u.id = ?`,
+    [userId],
+  );
+  if ((self?.n ?? 0) === 0) return;
+  const others = await client.get<{ n: number }>(
+    `SELECT COUNT(DISTINCT u.id) AS n
+     FROM users u
+     JOIN principal_roles pr ON pr.principalType = 'user' AND pr.principalId = u.id
+     JOIN roles r ON r.id = pr.roleId AND r.grantsAll = 1
+     WHERE u.status = 'active' AND u.id <> ?`,
+    [userId],
+  );
+  if ((others?.n ?? 0) === 0) throw new LastAdminError();
+}
+
+/**
+ * Replace a user's RBAC roles. The set holds exactly one primary role
+ * (admin, requester or viewer) plus any extra roles. Refuses to leave the
+ * swarm without an active grant-all user.
+ */
+export async function setUserRoles(
+  userId: string,
+  roleNames: string[],
+  actorUserId: string | null,
+): Promise<{ before: string[]; after: string[] }> {
+  const names = [...new Set(roleNames)];
+  if (names.filter((name) => PRIMARY_ROLE_NAMES.includes(name)).length !== 1) {
+    throw new InvalidRoleSetError(
+      `Pick exactly one primary role: ${PRIMARY_ROLE_NAMES.join(", ")}`,
+    );
+  }
+  return getDbClient().transaction(async (tx) => {
+    const wanted: GrantRoleRow[] = [];
+    for (const name of names) {
+      const row = await tx.get<GrantRoleRow>(
+        "SELECT id, name, grantsAll FROM roles WHERE name = ?",
+        [name],
+      );
+      if (!row) throw new InvalidRoleSetError(`Unknown role: ${name}`);
+      wanted.push(row);
+    }
+    const current = await tx.query<GrantRoleRow>(
+      `SELECT r.id, r.name, r.grantsAll
+       FROM principal_roles pr JOIN roles r ON r.id = pr.roleId
+       WHERE pr.principalType = 'user' AND pr.principalId = ?
+       ORDER BY r.name`,
+      [userId],
+    );
+    const wantsAll = wanted.some((r) => r.grantsAll === 1);
+    if (current.some((r) => r.grantsAll === 1) && !wantsAll) {
+      const user = await tx.get<{ status: string }>("SELECT status FROM users WHERE id = ?", [
+        userId,
+      ]);
+      if (user?.status === "active") {
+        const others = await tx.get<{ n: number }>(
+          `SELECT COUNT(DISTINCT u.id) AS n
+           FROM users u
+           JOIN principal_roles pr ON pr.principalType = 'user' AND pr.principalId = u.id
+           JOIN roles r ON r.id = pr.roleId AND r.grantsAll = 1
+           WHERE u.status = 'active' AND u.id <> ?`,
+          [userId],
+        );
+        if ((others?.n ?? 0) === 0) throw new LastAdminError();
+      }
+    }
+    const wantedIds = new Set(wanted.map((r) => r.id));
+    for (const row of current) {
+      if (!wantedIds.has(row.id)) {
+        await tx.run(
+          `DELETE FROM principal_roles
+           WHERE principalType = 'user' AND principalId = ? AND roleId = ?`,
+          [userId, row.id],
+        );
+      }
+    }
+    for (const row of wanted) {
+      await tx.run(
+        `INSERT OR IGNORE INTO principal_roles (principalType, principalId, roleId, created_by)
+         VALUES ('user', ?, ?, ?)`,
+        [userId, row.id, actorUserId],
+      );
+    }
+    getDbClient().afterCommit(() => invalidateTelemetryUserRole(userId));
+    return { before: current.map((r) => r.name), after: wanted.map((r) => r.name).sort() };
+  });
+}
+
 export function ensureRbacSeedsSynced(opts?: { quiet?: boolean }): RbacSeedSyncStats {
   const db = getDb();
   const desiredVerbsByRoleId = validatedBuiltinVerbSets();

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

@@ -0,0 +1,64 @@
+import { type RunScriptInput, type RunScriptOutput, runScript } from "../../scripts-runtime/loader";
+import { getAgentById } from "../db";
+import { mintScriptRunToken, revokeSessionToken } from "../users";
+
+/**
+ * Backstop lifetime of a script run's api credential. The run revokes its
+ * token the moment it ends (see `runScriptWithRunCredential`); this bounds a
+ * token whose run died without releasing. Comfortably above the 5m maximum
+ * script wall clock.
+ */
+const SCRIPT_RUN_TOKEN_TTL_MS = 15 * 60 * 1000;
+
+export type ScriptApiCredential = {
+  /**
+   * The bearer the script's `ctx.swarm` SDK calls present to the api, or
+   * `undefined` to let `runScript` fall back to the swarm API key.
+   */
+  apiKey: string | undefined;
+  /** Revoke the per-run token, if one was minted. Safe to call more than once. */
+  release: () => Promise<void>;
+};
+
+/**
+ * Resolve the api credential a script run acts as. When the run has a real
+ * executing agent, mint a short-lived token bound to it so `ctx.swarm` calls
+ * are scoped to that agent at the api, instead of carrying the swarm API key
+ * (the operator). System runs with no real agent (scheduler and workflow runs
+ * pass sentinel ids like "schedule"/"workflow") keep the operator key, their
+ * existing behavior. The caller must `release()` when the run ends.
+ */
+export async function acquireScriptApiCredential(agentId: string): Promise<ScriptApiCredential> {
+  if (!(await getAgentById(agentId))) {
+    return { apiKey: undefined, release: async () => {} };
+  }
+  const token = await mintScriptRunToken(agentId, SCRIPT_RUN_TOKEN_TTL_MS);
+  let released = false;
+  return {
+    apiKey: token.plaintext,
+    release: async () => {
+      if (released) return;
+      released = true;
+      await revokeSessionToken(token.tokenId);
+    },
+  };
+}
+
+/**
+ * Run a script with a per-run credential bound to its executing agent, and
+ * revoke that credential when the run ends: on success, a thrown error, a
+ * timeout or an abort. Every api-side script-run caller goes through here.
+ * The mint and revoke stay on the api side because `src/scripts-runtime/` is
+ * a no-DB zone (`scripts/check-db-boundary.sh`); `runScript` only receives the
+ * bearer.
+ */
+export async function runScriptWithRunCredential(
+  input: Omit<RunScriptInput, "apiKey">,
+): Promise<RunScriptOutput> {
+  const credential = await acquireScriptApiCredential(input.agentId);
+  try {
+    return await runScript({ ...input, apiKey: credential.apiKey });
+  } finally {
+    await credential.release();
+  }
+}