@desplega.ai/agent-swarm 1.113.0 → 1.115.0

package/src/be/db.ts

@@ -62,6 +62,7 @@ import type {
   ProviderName,
   ReasoningEffort,
   RepoGuidelines,
+  RoutingAffinity,
   ScheduledTask,
   ScheduledTaskSummary,
   ScriptRun,
@@ -108,6 +109,7 @@ import {
   type ModelTier,
   parseModelTier,
   ReasoningEffortSchema,
+  RoutingAffinitySchema,
 } from "../types";
 import { deriveProviderFromKeyType } from "../utils/credentials";
 import type { RateLimitWindowTelemetry } from "../utils/error-tracker";
@@ -1028,6 +1030,75 @@ export function updateAgentStatusFromCapacity(agentId: string): void {
   }
 }
 
+// ============================================================================
+// Routing Affinity (interrupted/pooled task role & capability gating)
+// ============================================================================
+
+/**
+ * Kill-switch for the pool eligibility gate (`isAgentEligibleForTask` and its
+ * callers: `claimTask`, `assignUnassignedTaskPending`,
+ * `getUnassignedTaskIdsForAgent`). ON by default. Set to `0` to restore
+ * pre-affinity behavior verbatim — mirrors the `HEARTBEAT_PIN_*_RESUME`
+ * rollback convention. A function (read dynamically), not a module-load-time
+ * const, so it can be toggled mid-test (see `isGracefulResumePinEnabled` in
+ * src/tasks/worker-follow-up.ts for the same pattern).
+ */
+export function isPoolAffinityEnforcementEnabled(): boolean {
+  return process.env.POOL_AFFINITY_ENFORCEMENT !== "0";
+}
+
+/**
+ * Snapshot an agent's role/harness/capabilities into a `RoutingAffinity`
+ * blob, for stamping onto a continuation task (resume, retry) at the moment
+ * of interruption. Returns `null` when the agent row is already gone —
+ * callers fall back to the parent's own (inherited) `routingAffinity` via
+ * `createTaskExtended`'s parentTaskId inheritance block.
+ */
+export function buildRoutingAffinityFromAgent(agentId: string): RoutingAffinity | null {
+  const agent = getAgentById(agentId);
+  if (!agent) return null;
+  return {
+    sourceAgentId: agent.id,
+    role: agent.role,
+    harnessProvider: agent.harnessProvider ?? agent.provider ?? undefined,
+    capabilities: agent.capabilities ?? [],
+  };
+}
+
+/**
+ * The single eligibility gate every pool consumer (poll auto-claim,
+ * `task-action claim`, `autoAssignPoolTasks`) MUST use before handing a task
+ * to an agent. Exact-match on the snapshotted role string (no keyword
+ * taxonomy in v1); `harnessProvider` is informational only and never
+ * enforced (native session resume is deprecated). Missing role data on
+ * either side is treated as INELIGIBLE — never fail-open to "anyone" — so a
+ * capability-only requirement (no `role` set) can only ever be claimed by
+ * its `sourceAgentId`, and otherwise queues until the starvation escalation
+ * hands it to the Lead.
+ */
+export function isAgentEligibleForTask(
+  agent: Pick<Agent, "id" | "role" | "capabilities">,
+  task: Pick<AgentTask, "routingAffinity">,
+): boolean {
+  if (!isPoolAffinityEnforcementEnabled()) return true;
+
+  const affinity = task.routingAffinity;
+  if (!affinity) return true; // Untagged task — unchanged behavior.
+
+  if (affinity.sourceAgentId && affinity.sourceAgentId === agent.id) return true; // Own work.
+
+  if (!agent.role || !affinity.role) return false; // Missing role data — no fail-open.
+  if (agent.role !== affinity.role) return false;
+
+  const requiredCapabilities = affinity.capabilities ?? [];
+  if (requiredCapabilities.length > 0) {
+    const agentCapabilities = new Set(agent.capabilities ?? []);
+    if (!requiredCapabilities.every((cap) => agentCapabilities.has(cap))) return false;
+  }
+
+  return true;
+}
+
 // ============================================================================
 // AgentTask Queries
 // ============================================================================
@@ -1100,6 +1171,7 @@ type AgentTaskRow = {
   harnessVariant: string | null;
   harnessVariantMeta: string | null;
   totalCostUsd?: number | null;
+  routingAffinity: string | null;
 };
 
 function rowToAgentTask(row: AgentTaskRow): AgentTask {
@@ -1124,6 +1196,26 @@ function rowToAgentTask(row: AgentTaskRow): AgentTask {
     }
   }
 
+  let routingAffinity: RoutingAffinity | undefined;
+  if (row.routingAffinity) {
+    try {
+      const parsed = RoutingAffinitySchema.safeParse(JSON.parse(row.routingAffinity));
+      if (parsed.success) {
+        routingAffinity = parsed.data;
+      } else {
+        console.warn(
+          `[db] Ignoring invalid agent_tasks.routingAffinity for task ${row.id}:`,
+          parsed.error.message,
+        );
+      }
+    } catch (error) {
+      console.warn(
+        `[db] Ignoring malformed agent_tasks.routingAffinity for task ${row.id}:`,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
   return {
     id: row.id,
     agentId: row.agentId,
@@ -1194,6 +1286,7 @@ function rowToAgentTask(row: AgentTaskRow): AgentTask {
     harnessVariant: row.harnessVariant ?? undefined,
     harnessVariantMeta: row.harnessVariantMeta ? JSON.parse(row.harnessVariantMeta) : undefined,
     totalCostUsd: row.totalCostUsd ?? undefined,
+    routingAffinity,
   };
 }
 
@@ -1359,6 +1452,29 @@ export function getPendingTaskForAgent(agentId: string): AgentTask | null {
 }
 
 export function assignUnassignedTaskPending(taskId: string, agentId: string): AgentTask | null {
+  // Eligibility pre-check (routing affinity) — defense in depth for the
+  // heartbeat's `autoAssignPoolTasks`, which already filters candidates via
+  // `isAgentEligibleForTask` before calling this, but any other caller gets
+  // the same guard for free.
+  if (isPoolAffinityEnforcementEnabled()) {
+    const task = getTaskById(taskId);
+    const agent = getAgentById(agentId);
+    if (task && agent && !isAgentEligibleForTask(agent, task)) {
+      try {
+        createLogEntry({
+          eventType: "task_claim_rejected_affinity",
+          agentId,
+          taskId,
+          metadata: {
+            agentRole: agent.role ?? null,
+            requiredRole: task.routingAffinity?.role ?? null,
+          },
+        });
+      } catch {}
+      return null;
+    }
+  }
+
   const now = new Date().toISOString();
   const row = getDb()
     .prepare<AgentTaskRow, [string, string, string]>(
@@ -1636,8 +1752,12 @@ export interface TaskFilters {
   source?: AgentTaskSource[];
   /** ISO 8601 timestamp; only return tasks where createdAt >= this. */
   createdAfter?: string;
+  /** ISO 8601 timestamp; only return tasks where createdAt < this. */
+  createdBefore?: string;
   /** Only return tasks requested by this canonical user. NULL rows are excluded. */
   requestedByUserId?: string;
+  /** Sort list rows for either table freshness or timeline paging. */
+  orderBy?: "lastUpdatedAt" | "createdAt";
   limit?: number;
   offset?: number;
   includeHeartbeat?: boolean;
@@ -1721,6 +1841,11 @@ export function getAllTasks(
     params.push(filters.createdAfter);
   }
 
+  if (filters?.createdBefore) {
+    conditions.push("createdAt < ?");
+    params.push(filters.createdBefore);
+  }
+
   if (filters?.requestedByUserId) {
     conditions.push("requestedByUserId = ?");
     params.push(filters.requestedByUserId);
@@ -1739,10 +1864,14 @@ export function getAllTasks(
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const limit = filters?.limit ?? 25;
   const offset = filters?.offset ?? 0;
+  const orderBy =
+    filters?.orderBy === "createdAt"
+      ? "createdAt DESC, rowid DESC"
+      : "lastUpdatedAt DESC, priority DESC";
   const query = `SELECT agent_tasks.*,
     (SELECT SUM(totalCostUsd) FROM session_costs WHERE session_costs.taskId = agent_tasks.id) AS totalCostUsd
     FROM agent_tasks ${whereClause}
-    ORDER BY lastUpdatedAt DESC, priority DESC LIMIT ${limit} OFFSET ${offset}`;
+    ORDER BY ${orderBy} LIMIT ${limit} OFFSET ${offset}`;
 
   const rows = getDb()
     .prepare<AgentTaskRow, (string | AgentTaskStatus)[]>(query)
@@ -1838,6 +1967,16 @@ export function getTasksCount(filters?: Omit<TaskFilters, "limit" | "readyOnly">
     params.push(filters.createdAfter);
   }
 
+  if (filters?.createdBefore) {
+    conditions.push("createdAt < ?");
+    params.push(filters.createdBefore);
+  }
+
+  if (filters?.requestedByUserId) {
+    conditions.push("requestedByUserId = ?");
+    params.push(filters.requestedByUserId);
+  }
+
   // Exclude system/heartbeat tasks by default. The flag is still called
   // `includeHeartbeat` for backward compat with existing API callers, but we
   // also gate boot-triage + heartbeat-checklist behind it since those are
@@ -3243,6 +3382,12 @@ export interface CreateTaskOptions {
   followUpConfig?: FollowUpConfig;
   requestedByUserId?: string;
   contextKey?: string;
+  /**
+   * Routing-affinity snapshot gating pool eligibility (see
+   * `isAgentEligibleForTask`). Inherited from the parent (via `parentTaskId`)
+   * when not explicitly set — same treatment as `vcsRepo`/`contextKey`.
+   */
+  routingAffinity?: RoutingAffinity;
 }
 
 /**
@@ -3414,6 +3559,9 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
       if (parent.followUpConfig && !options.followUpConfig) {
         options.followUpConfig = parent.followUpConfig;
       }
+      if (parent.routingAffinity && !options.routingAffinity) {
+        options.routingAffinity = parent.routingAffinity;
+      }
     }
   }
 
@@ -3448,8 +3596,8 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
         vcsInstallationId, vcsNodeId,
         agentmailInboxId, agentmailMessageId, agentmailThreadId,
         mentionMessageId, mentionChannelId, dir, parentTaskId, model, modelTier, effort, scheduleId,
-        workflowRunId, workflowRunStepId, outputSchema, followUpConfig, requestedByUserId, contextKey, swarmVersion, createdAt, lastUpdatedAt, created_by, updated_by
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+        workflowRunId, workflowRunStepId, outputSchema, followUpConfig, requestedByUserId, contextKey, routingAffinity, swarmVersion, createdAt, lastUpdatedAt, created_by, updated_by
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
     )
     .get(
       id,
@@ -3493,6 +3641,7 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
       options?.followUpConfig ? JSON.stringify(options.followUpConfig) : null,
       options?.requestedByUserId ?? null,
       options?.contextKey ?? null,
+      options?.routingAffinity ? JSON.stringify(options.routingAffinity) : null,
       pkg.version,
       now,
       now,
@@ -3542,6 +3691,28 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
 }
 
 export function claimTask(taskId: string, agentId: string): AgentTask | null {
+  // Eligibility pre-check (routing affinity): static per (agent, task), so
+  // pre-filtering here does NOT reopen the claim race — the atomic UPDATE
+  // below still arbitrates concurrent claims by eligible agents.
+  if (isPoolAffinityEnforcementEnabled()) {
+    const task = getTaskById(taskId);
+    const agent = getAgentById(agentId);
+    if (task && agent && !isAgentEligibleForTask(agent, task)) {
+      try {
+        createLogEntry({
+          eventType: "task_claim_rejected_affinity",
+          agentId,
+          taskId,
+          metadata: {
+            agentRole: agent.role ?? null,
+            requiredRole: task.routingAffinity?.role ?? null,
+          },
+        });
+      } catch {}
+      return null;
+    }
+  }
+
   // Atomic claim: single UPDATE with WHERE guard ensures exactly-once claiming.
   // No pre-read needed — the WHERE clause handles the race condition.
   // Status goes directly to 'in_progress' because the claiming session is
@@ -3806,6 +3977,61 @@ export function getUnassignedTaskIds(limit = 10): string[] {
   return rows.map((r) => r.id);
 }
 
+/**
+ * Batch size and hard cap for the paginated eligibility scans in
+ * `getUnassignedTaskIdsForAgent` (and `autoAssignPoolTasks` in
+ * src/heartbeat/heartbeat.ts, which mirrors this pattern). A fixed single
+ * window used to mean N ineligible affinity-tagged tasks at the head of the
+ * priority order could hide all eligible work behind them forever — see
+ * PR #954 review. Scanning continues page-by-page until `limit` eligible
+ * candidates are found or the pool is exhausted; the cap bounds worst-case
+ * DB load when eligible work is buried deep or genuinely absent.
+ */
+const ELIGIBILITY_SCAN_BATCH_SIZE = Number(process.env.ELIGIBILITY_SCAN_BATCH_SIZE) || 25;
+const ELIGIBILITY_SCAN_CAP = Number(process.env.ELIGIBILITY_SCAN_CAP) || 500;
+
+/**
+ * Same ordering as `getUnassignedTaskIds`, filtered through
+ * `isAgentEligibleForTask` for the requesting agent. Used by the poll
+ * auto-claim path so an ineligible candidate is never even offered to the
+ * budget gate / claim loop. Paginates through the unassigned pool in
+ * `ELIGIBILITY_SCAN_BATCH_SIZE`-row windows (filtering in JS to avoid
+ * JSON-parsing `routingAffinity` in SQL) until `limit` eligible tasks are
+ * found or the pool is exhausted, capped at `ELIGIBILITY_SCAN_CAP` rows
+ * scanned so a pool full of ineligible tasks can't turn every poll into an
+ * unbounded scan.
+ */
+export function getUnassignedTaskIdsForAgent(agentId: string, limit = 10): string[] {
+  const agent = getAgentById(agentId);
+  if (!agent) return [];
+
+  const batchSize = Math.max(limit * 5, ELIGIBILITY_SCAN_BATCH_SIZE);
+  const eligible: string[] = [];
+  let offset = 0;
+
+  while (eligible.length < limit && offset < ELIGIBILITY_SCAN_CAP) {
+    const rows = getDb()
+      .prepare<AgentTaskRow, [number, number]>(
+        "SELECT * FROM agent_tasks WHERE status = 'unassigned' ORDER BY priority DESC, createdAt ASC, rowid ASC LIMIT ? OFFSET ?",
+      )
+      .all(batchSize, offset);
+    if (rows.length === 0) break;
+
+    for (const row of rows) {
+      const task = rowToAgentTask(row);
+      if (isAgentEligibleForTask(agent, task)) {
+        eligible.push(task.id);
+        if (eligible.length >= limit) break;
+      }
+    }
+
+    offset += rows.length;
+    if (rows.length < batchSize) break; // Exhausted the pool.
+  }
+
+  return eligible;
+}
+
 // ============================================================================
 // Dependency Checking
 // ============================================================================
@@ -6936,16 +7162,22 @@ export function getStalledInProgressTasks(thresholdMinutes: number = 30): AgentT
 }
 
 /**
- * Genuine same-agent protected resume PINS (tagged `crash-recovery-pin` or
- * `graceful-shutdown-pin`) that are still `pending` `graceMin` minutes after
- * creation — the heartbeat reaper escalates these to a Lead reroute-decision.
+ * Genuine same-agent protected pins — resumes tagged `crash-recovery-pin` /
+ * `graceful-shutdown-pin`, OR a reboot-retry child tagged `reboot-retry-pin`
+ * (routing-affinity Phase 3) — that are still `pending` `graceMin` minutes
+ * after creation. The heartbeat reaper escalates these to a Lead
+ * reroute-decision.
  *
- * Three scoping clauses, each load-bearing:
- *  - pin tags — restricts to resumes actually pinned to their original agent on
- *    protected paths. Without this, a *pooled* resume that `autoAssignPoolTasks`
- *    flips to `pending` earlier in the SAME sweep (keeping its old `createdAt`)
- *    would be reaped and cancelled before the assigned worker polls; it also
- *    keeps `context_limits` / `manual_supersede` pins from being escalated under
+ * Scoping clauses, each load-bearing:
+ *  - `taskType = 'resume' AND (crash/graceful pin tags)` OR `reboot-retry-pin`
+ *    tag alone — restricts to work actually pinned to its original agent on a
+ *    protected path. A reboot-retry-pin task is a FRESH task (`taskType`
+ *    mirrors the original work, not `'resume'`), so it needs its own
+ *    disjunct rather than reusing the `taskType = 'resume'` gate. Without
+ *    this, a *pooled* resume that `autoAssignPoolTasks` flips to `pending`
+ *    earlier in the SAME sweep (keeping its old `createdAt`) would be reaped
+ *    and cancelled before the assigned worker polls; it also keeps
+ *    `context_limits` / `manual_supersede` pins from being escalated under
  *    the protected-pin label. (Literals must match the pin tag constants in
  *    src/tasks/worker-follow-up.ts.)
  *  - `status = 'pending'` — the "currently unreclaimed" discriminator: when the
@@ -6966,8 +7198,11 @@ export function getStalePinnedResumes(graceMin: number): AgentTask[] {
   return getDb()
     .prepare<AgentTaskRow, [string]>(
       `SELECT * FROM agent_tasks
-       WHERE taskType = 'resume' AND status = 'pending'
-         AND (tags LIKE '%"crash-recovery-pin"%' OR tags LIKE '%"graceful-shutdown-pin"%')
+       WHERE status = 'pending'
+         AND (
+           (taskType = 'resume' AND (tags LIKE '%"crash-recovery-pin"%' OR tags LIKE '%"graceful-shutdown-pin"%'))
+           OR tags LIKE '%"reboot-retry-pin"%'
+         )
          AND createdAt < ?
        ORDER BY createdAt ASC`,
     )
@@ -7037,18 +7272,39 @@ export function getIdleWorkersWithCapacity(): Agent[] {
 }
 
 /**
- * Get unassigned pool tasks ordered by priority (DESC) then creation time (ASC).
- * Used by the heartbeat for auto-assignment.
+ * Get unassigned pool tasks ordered by priority (DESC), creation time (ASC),
+ * then `rowid` (ASC) as a stable tiebreaker. The `rowid` tiebreaker matters
+ * once `offset` is used for pagination (`autoAssignPoolTasks` in
+ * src/heartbeat/heartbeat.ts) — without it, rows sharing a `createdAt` could
+ * be skipped or repeated across pages. Used by the heartbeat for
+ * auto-assignment and status reporting.
  */
-export function getUnassignedPoolTasks(limit: number = 10): AgentTask[] {
+export function getUnassignedPoolTasks(limit: number = 10, offset: number = 0): AgentTask[] {
   return getDb()
-    .prepare<AgentTaskRow, [number]>(
+    .prepare<AgentTaskRow, [number, number]>(
       `SELECT * FROM agent_tasks
        WHERE status = 'unassigned'
-       ORDER BY priority DESC, createdAt ASC
-       LIMIT ?`,
+       ORDER BY priority DESC, createdAt ASC, rowid ASC
+       LIMIT ? OFFSET ?`,
     )
-    .all(limit)
+    .all(limit, offset)
+    .map(rowToAgentTask);
+}
+
+/**
+ * Affinity-tagged pool tasks that have sat `unassigned` past `cutoffIso` —
+ * the starvation-escalation candidate set (routing-affinity Phase 3). Callers
+ * MUST separately confirm zero registered agents satisfy
+ * `isAgentEligibleForTask` before escalating; this only narrows by tag age.
+ */
+export function getStaleUnassignedAffinityTasks(cutoffIso: string): AgentTask[] {
+  return getDb()
+    .prepare<AgentTaskRow, [string]>(
+      `SELECT * FROM agent_tasks
+       WHERE status = 'unassigned' AND routingAffinity IS NOT NULL AND createdAt < ?
+       ORDER BY createdAt ASC`,
+    )
+    .all(cutoffIso)
     .map(rowToAgentTask);
 }
 
@@ -8081,8 +8337,12 @@ export function updatePage(
 }
 
 export function deletePage(id: string): boolean {
-  // ON DELETE CASCADE on page_versions.pageId handles history cleanup.
-  const result = getDb().run("DELETE FROM pages WHERE id = ?", [id]);
+  const result = getDb().transaction(() => {
+    getDb().run("DELETE FROM user_favorites WHERE itemType = 'page' AND itemId = ?", [id]);
+    getDb().run("DELETE FROM kv_entries WHERE namespace = ?", [`task:page:${id}`]);
+    // ON DELETE CASCADE on page_versions.pageId handles history cleanup.
+    return getDb().run("DELETE FROM pages WHERE id = ?", [id]);
+  })();
   return result.changes > 0;
 }
 
@@ -8894,6 +9154,7 @@ export interface ApprovalRequest {
   timeoutSeconds: number | null;
   expiresAt: string | null;
   notificationChannels: unknown[] | null;
+  createdBy?: string;
   createdAt: string;
   updatedAt: string;
 }
@@ -8913,6 +9174,7 @@ interface ApprovalRequestRow {
   timeoutSeconds: number | null;
   expiresAt: string | null;
   notificationChannels: string | null;
+  created_by: string | null;
   createdAt: string;
   updatedAt: string;
 }
@@ -8933,6 +9195,7 @@ function rowToApprovalRequest(row: ApprovalRequestRow): ApprovalRequest {
     timeoutSeconds: row.timeoutSeconds,
     expiresAt: normalizeDate(row.expiresAt),
     notificationChannels: row.notificationChannels ? JSON.parse(row.notificationChannels) : null,
+    createdBy: row.created_by ?? undefined,
     createdAt: normalizeDateRequired(row.createdAt),
     updatedAt: normalizeDateRequired(row.updatedAt),
   };
@@ -8948,6 +9211,7 @@ export function createApprovalRequest(data: {
   sourceTaskId?: string;
   timeoutSeconds?: number;
   notificationChannels?: unknown[];
+  createdBy?: string;
 }): ApprovalRequest {
   const now = new Date().toISOString();
   const expiresAt = data.timeoutSeconds
@@ -8968,12 +9232,13 @@ export function createApprovalRequest(data: {
         number | null,
         string | null,
         string | null,
+        string | null,
         string,
         string,
       ]
     >(
-      `INSERT INTO approval_requests (id, title, questions, workflowRunId, workflowRunStepId, sourceTaskId, approvers, timeoutSeconds, expiresAt, notificationChannels, createdAt, updatedAt)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `INSERT INTO approval_requests (id, title, questions, workflowRunId, workflowRunStepId, sourceTaskId, approvers, timeoutSeconds, expiresAt, notificationChannels, created_by, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        RETURNING *`,
     )
     .get(
@@ -8987,6 +9252,7 @@ export function createApprovalRequest(data: {
       data.timeoutSeconds ?? null,
       expiresAt,
       data.notificationChannels ? JSON.stringify(data.notificationChannels) : null,
+      data.createdBy ?? null,
       now,
       now,
     );
@@ -10288,9 +10554,29 @@ export function updateMcpServer(
   return row ? rowToMcpServer(row) : null;
 }
 
-export function deleteMcpServer(id: string): boolean {
-  const result = getDb().prepare("DELETE FROM mcp_servers WHERE id = ?").run(id);
-  return result.changes > 0;
+export type DeleteMcpServerResult = {
+  deleted: boolean;
+  deletedScriptConnectionCount: number;
+};
+
+export function deleteMcpServer(id: string): DeleteMcpServerResult {
+  const db = getDb();
+  const existing = db
+    .prepare<{ id: string }, [string]>("SELECT id FROM mcp_servers WHERE id = ?")
+    .get(id);
+  if (!existing) return { deleted: false, deletedScriptConnectionCount: 0 };
+
+  const tx = db.transaction(() => {
+    const deletedConnections = db
+      .prepare("DELETE FROM script_connections WHERE mcp_server_id = ?")
+      .run(id);
+    const deletedServer = db.prepare("DELETE FROM mcp_servers WHERE id = ?").run(id);
+    return {
+      deleted: deletedServer.changes > 0,
+      deletedScriptConnectionCount: deletedConnections.changes,
+    };
+  });
+  return tx();
 }
 
 export function getMcpServerById(id: string): McpServer | null {

package/src/be/identity.ts

@@ -0,0 +1,79 @@
+/**
+ * The framework's single identity-resolution primitive.
+ *
+ * Invariant (Rule 33 / provenance-or-silence): the swarm's sole responsibility
+ * for identity is the reverse lookup `(kind, externalId)` (or email) → linked
+ * user → canonical name, via `findUserByExternalId` / `findUserByEmail`. If
+ * the lookup points nowhere, callers render the explicit UNKNOWN sentinel —
+ * NEVER a provider display name, NEVER a guess. Every provider adapter that
+ * renders a human identity into agent-visible text MUST go through
+ * `renderIdentity(resolveIdentity(...))` (or `resolveIdentityByEmail`).
+ *
+ * Pure DB reads — zero provider API calls. `unknown` is a value, not an
+ * error: callers branch on `status`, never throw or fall back to a
+ * provider-supplied label.
+ *
+ * This module is API-side ONLY (see the DB-boundary note in `./users.ts`).
+ */
+
+import { findUserByEmail, findUserByExternalId } from "./users";
+
+export type IdentityResolution =
+  | {
+      status: "resolved";
+      kind: string;
+      externalId: string;
+      userId: string;
+      name: string;
+      email?: string;
+    }
+  | { status: "unknown"; kind: string; externalId: string };
+
+/** Reverse lookup by `(kind, externalId)` — e.g. `resolveIdentity('slack', 'U016H7XKZGS')`. */
+export function resolveIdentity(kind: string, externalId: string): IdentityResolution {
+  const user = findUserByExternalId(kind, externalId);
+  if (!user) {
+    return { status: "unknown", kind, externalId };
+  }
+  return {
+    status: "resolved",
+    kind,
+    externalId,
+    userId: user.id,
+    name: user.name,
+    email: user.email,
+  };
+}
+
+/**
+ * Reverse lookup by email (primary or alias). Email is a `users.email`
+ * attribute, not an external-id kind — rendered with `kind: "email"` so
+ * `renderIdentity` produces a consistent pair form regardless of provider.
+ */
+export function resolveIdentityByEmail(email: string): IdentityResolution {
+  const user = findUserByEmail(email);
+  if (!user) {
+    return { status: "unknown", kind: "email", externalId: email };
+  }
+  return {
+    status: "resolved",
+    kind: "email",
+    externalId: email,
+    userId: user.id,
+    name: user.name,
+    email: user.email,
+  };
+}
+
+/**
+ * Render an `IdentityResolution` into agent-visible text — the only two
+ * shapes an identity may ever take. The sentinel keeps the raw id but never
+ * a name: an unresolved identity must never be confused for a real one.
+ */
+export function renderIdentity(resolution: IdentityResolution): string {
+  const pair = `${resolution.kind}:${resolution.externalId}`;
+  if (resolution.status === "resolved") {
+    return `${resolution.name} (${pair})`;
+  }
+  return `${pair} (unknown user)`;
+}