@desplega.ai/agent-swarm 2.5.1 → 2.5.3

package/src/be/db.ts

@@ -208,6 +208,7 @@ import {
   sessionPageFields,
   sessionSummaryQuery,
 } from "./db/session-tree";
+import { searchSkillRowsRanked } from "./db/skill-search";
 import { classifyTaskHumanFree, reclassifyTaskHumanFree } from "./db/tasks/human-free";
 import {
   type AgentTaskRow,
@@ -7842,6 +7843,8 @@ type WorkflowRunRow = {
   finishedAt: string | null;
   /** The `sub-workflow` step that started this run (migration 203). */
   parentStepId?: string | null;
+  /** That step's attempt (`retryCount`) when it started this run (migration 240). */
+  parentStepAttempt?: number | null;
 };
 
 /**
@@ -7862,6 +7865,7 @@ function rowToWorkflowRun(row: WorkflowRunRow, view: WorkflowPayloadView = "repl
     lastUpdatedAt: normalizeDateRequired(row.lastUpdatedAt),
     finishedAt: normalizeDate(row.finishedAt) ?? undefined,
     parentStepId: row.parentStepId ?? undefined,
+    parentStepAttempt: row.parentStepId ? (row.parentStepAttempt ?? 0) : undefined,
   };
   return defineWorkflowPayload(run, "context", row.context, row.context_replay, view, {
     runId: row.id,
@@ -7876,10 +7880,12 @@ export async function createWorkflowRun(data: {
   triggerData?: unknown;
   createdBy?: string;
   parentStepId?: string;
+  /** The parent step's `retryCount` when it started this run (migration 240). */
+  parentStepAttempt?: number;
 }): Promise<WorkflowRun> {
   const now = new Date().toISOString();
   const row = await getDbClient().get<WorkflowRunRow>(
-    `INSERT INTO workflow_runs (id, workflowId, triggerType, startedAt, triggerData, created_by, parentStepId) VALUES (?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+    `INSERT INTO workflow_runs (id, workflowId, triggerType, startedAt, triggerData, created_by, parentStepId, parentStepAttempt) VALUES (?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
     [
       data.id,
       data.workflowId,
@@ -7888,6 +7894,7 @@ export async function createWorkflowRun(data: {
       data.triggerData ? scrubJsonValue(data.triggerData) : null,
       data.createdBy ?? null,
       data.parentStepId ?? null,
+      data.parentStepAttempt ?? 0,
     ],
   );
   if (!row) throw new Error("Failed to create workflow run");
@@ -7992,9 +7999,10 @@ export type WorkflowRunListOptions = {
 };
 
 // Everything but `context`. `triggerData` stays: it is small, and stored
-// scripts read it off list rows (dedupe by trigger, failure reports).
+// scripts read it off list rows (dedupe by trigger, failure reports). The
+// parent link and attempt stay so a list row identifies a child's invocation.
 const WORKFLOW_RUN_SUMMARY_COLUMNS =
-  "id, workflowId, status, triggerType, triggerData, error, created_by, startedAt, lastUpdatedAt, finishedAt";
+  "id, workflowId, status, triggerType, triggerData, error, created_by, startedAt, lastUpdatedAt, finishedAt, parentStepId, parentStepAttempt";
 
 export type WorkflowRunPage = {
   runs: WorkflowRun[];
@@ -10989,11 +10997,23 @@ export async function listSkills(filters?: SkillFilters): Promise<Skill[]> {
   return rows.map(rowToSkill);
 }
 
+/**
+ * Ranked skill search (see searchSkillRowsRanked). Falls back to the unranked
+ * substring match when the ranked query finds nothing, e.g. a partial word or
+ * a query of only stopwords. The fallback also ranks an exact name first.
+ */
 export async function searchSkills(
   query: string,
   limit = 20,
   includeContent = true,
 ): Promise<Skill[]> {
+  const ranked = await searchSkillRowsRanked<SkillRow>(
+    query,
+    limit,
+    includeContent === false ? SKILL_SLIM_COLUMNS : "skills.*",
+  );
+  if (ranked.length > 0) return ranked.map(rowToSkill);
+
   const tokens = query.split(/\s+/).filter(Boolean);
   const columns = includeContent === false ? SKILL_SLIM_COLUMNS : "*";
   const searchClauses = tokens.map(() => "(name LIKE ? OR description LIKE ? OR content LIKE ?)");
@@ -11002,8 +11022,8 @@ export async function searchSkills(
     return [term, term, term];
   });
   const rows = await getDbClient().query<SkillRow>(
-    `SELECT ${columns} FROM skills WHERE ${[...searchClauses, "isEnabled = 1"].join(" AND ")} ORDER BY name ASC LIMIT ?`,
-    [...params, limit],
+    `SELECT ${columns} FROM skills WHERE ${[...searchClauses, "isEnabled = 1"].join(" AND ")} ORDER BY lower(name) = lower(?) DESC, name ASC LIMIT ?`,
+    [...params, query.trim(), limit],
   );
   return rows.map(rowToSkill);
 }
@@ -12629,6 +12649,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/migrations/239_skills_fts.sql

@@ -0,0 +1,40 @@
+-- Full-text index for ranked skill search (searchSkills / skill-search tool).
+-- Same shape as memory_fts: an id column FTS5 does not index, the searchable
+-- text columns, and the porter tokenizer. Column order matters: searchSkills
+-- passes bm25() weights positionally (skill_id, name, description, content).
+CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5(
+  skill_id UNINDEXED,
+  name,
+  description,
+  content,
+  tokenize='porter unicode61'
+);
+
+INSERT INTO skills_fts(skill_id, name, description, content)
+  SELECT id, name, description, content FROM skills
+  WHERE id NOT IN (SELECT skill_id FROM skills_fts WHERE skill_id IS NOT NULL);
+
+-- Triggers keep the index in sync on every write path, including FK cascade
+-- deletes. A later migration that rebuilds `skills` (CREATE new + DROP +
+-- RENAME) drops these triggers with the old table and must recreate them;
+-- src/tests/skill-search.test.ts asserts they exist on the migrated schema.
+CREATE TRIGGER IF NOT EXISTS skills_fts_insert
+AFTER INSERT ON skills
+BEGIN
+  INSERT INTO skills_fts(skill_id, name, description, content)
+    VALUES (NEW.id, NEW.name, NEW.description, NEW.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_fts_update
+AFTER UPDATE OF id, name, description, content ON skills
+BEGIN
+  DELETE FROM skills_fts WHERE skill_id = OLD.id;
+  INSERT INTO skills_fts(skill_id, name, description, content)
+    VALUES (NEW.id, NEW.name, NEW.description, NEW.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_fts_delete
+AFTER DELETE ON skills
+BEGIN
+  DELETE FROM skills_fts WHERE skill_id = OLD.id;
+END;

package/src/be/migrations/240_workflow_run_parent_step_attempt.sql

@@ -0,0 +1,37 @@
+-- Key a child workflow run by its parent step AND that step's attempt.
+--
+-- The retry poller re-executes a failed step under the same step id, with
+-- `retryCount` bumped. Keyed by step id alone, the retried `sub-workflow`
+-- step reconnected to the failed child of the previous attempt and failed
+-- again without starting a new one.
+
+ALTER TABLE workflow_runs ADD COLUMN parentStepAttempt INTEGER NOT NULL DEFAULT 0;
+
+-- Before this migration a step had at most one child, created on whichever
+-- attempt first got that far (a retry after a synchronous failure, such as a
+-- disabled child workflow, creates it on attempt 1 or later), and every later
+-- attempt reconnected to it. Hand that child to the attempt that settles or
+-- re-executes it now, or recovery would look up the step's current attempt,
+-- find no child and fail the parent as "deleted":
+-- - a step queued for a retry (`failed` with `nextRetryAt`) starts its next
+--   attempt at `retryCount`, which must start a new child, so the existing
+--   child belongs to the previous attempt;
+-- - any other step (running, waiting, terminal) owns it at `retryCount`.
+-- A child whose step is gone keeps attempt 0.
+UPDATE workflow_runs
+   SET parentStepAttempt = (
+     SELECT CASE
+              WHEN s.status = 'failed' AND s.nextRetryAt IS NOT NULL
+                THEN MAX(s.retryCount - 1, 0)
+              ELSE s.retryCount
+            END
+       FROM workflow_run_steps s
+      WHERE s.id = workflow_runs.parentStepId
+   )
+ WHERE parentStepId IS NOT NULL
+   AND EXISTS (SELECT 1 FROM workflow_run_steps s WHERE s.id = workflow_runs.parentStepId);
+
+DROP INDEX IF EXISTS idx_workflow_runs_parentStepId;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_workflow_runs_parentStep_attempt
+  ON workflow_runs(parentStepId, parentStepAttempt) WHERE parentStepId IS NOT NULL;

package/src/be/migrations/241_skills_meta_fts.sql

@@ -0,0 +1,39 @@
+-- Name + description index for ranked skill search. skills_fts (239) scores
+-- the whole row, and FTS5 bm25 length-normalizes over every column, so a
+-- long SKILL.md body buries a name or description hit. This index holds only
+-- the short fields; searchSkillRowsRanked adds its score to skills_fts's.
+-- Column order matters: bm25() weights are positional (skill_id, name,
+-- description).
+CREATE VIRTUAL TABLE IF NOT EXISTS skills_meta_fts USING fts5(
+  skill_id UNINDEXED,
+  name,
+  description,
+  tokenize='porter unicode61'
+);
+
+INSERT INTO skills_meta_fts(skill_id, name, description)
+  SELECT id, name, description FROM skills
+  WHERE id NOT IN (SELECT skill_id FROM skills_meta_fts WHERE skill_id IS NOT NULL);
+
+-- Same sync rules as skills_fts: a later migration that rebuilds `skills`
+-- must recreate these triggers; src/tests/skill-search.test.ts asserts them.
+CREATE TRIGGER IF NOT EXISTS skills_meta_fts_insert
+AFTER INSERT ON skills
+BEGIN
+  INSERT INTO skills_meta_fts(skill_id, name, description)
+    VALUES (NEW.id, NEW.name, NEW.description);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_meta_fts_update
+AFTER UPDATE OF id, name, description ON skills
+BEGIN
+  DELETE FROM skills_meta_fts WHERE skill_id = OLD.id;
+  INSERT INTO skills_meta_fts(skill_id, name, description)
+    VALUES (NEW.id, NEW.name, NEW.description);
+END;
+
+CREATE TRIGGER IF NOT EXISTS skills_meta_fts_delete
+AFTER DELETE ON skills
+BEGIN
+  DELETE FROM skills_meta_fts WHERE skill_id = OLD.id;
+END;

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();
+  }
+}

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/swarm-config-guard.ts

@@ -628,6 +628,29 @@ export function validateConfigValue(key: string, value: unknown): string | null
   return validator ? validator(value) : null;
 }
 
+/**
+ * Every check `PUT /api/config` runs before a write: scope and scopeId shape,
+ * reserved and internal keys, the per-key value validator and the env-export
+ * rule. Shared with HITL `config` questions so the two writers cannot drift.
+ */
+export function validateConfigEntry(entry: {
+  scope: "global" | "agent" | "repo";
+  scopeId?: string | null;
+  key: string;
+  value: unknown;
+  exportToEnv?: boolean;
+}): string | null {
+  if (entry.scope === "global" && entry.scopeId) return "Global scope must not have scopeId";
+  if ((entry.scope === "agent" || entry.scope === "repo") && !entry.scopeId) {
+    return "Agent/repo scope requires scopeId";
+  }
+  if (isReservedConfigKey(entry.key)) return reservedKeyError(entry.key).message;
+  if (isInternalConfigKey(entry.key)) return internalConfigKeyError(entry.key).message;
+  return (
+    validateConfigValue(entry.key, entry.value) ?? validateExportToEnv(entry.key, entry.exportToEnv)
+  );
+}
+
 /**
  * Rejects `exportToEnv: true` for keys only the API server reads. Omitting the
  * flag is fine: the write path stores false for those keys.