@desplega.ai/agent-swarm 1.149.1 → 1.151.0

package/src/rbac/elevated-agents.ts

@@ -0,0 +1,24 @@
+/**
+ * Agents that act with lead privileges without carrying the `isLead` flag.
+ *
+ * Extension system agents (`ext:<name>`) run operator-enabled code inside the
+ * API process. Their `ctx.swarm` calls must pass lead-only checks such as
+ * posting to Slack, but the agent row keeps `isLead: false` so lead selection
+ * (Slack routing, follow-ups, heartbeat triage) never picks them.
+ *
+ * The registry is process-local and mirrors the loaded-extension set: the
+ * extension dispatcher grants on load and revokes on dispose.
+ */
+const leadEquivalentAgentIds = new Set<string>();
+
+export function grantLeadEquivalence(agentId: string): void {
+  leadEquivalentAgentIds.add(agentId);
+}
+
+export function revokeLeadEquivalence(agentId: string): void {
+  leadEquivalentAgentIds.delete(agentId);
+}
+
+export function hasLeadEquivalence(agentId: string | null | undefined): boolean {
+  return !!agentId && leadEquivalentAgentIds.has(agentId);
+}

package/src/rbac/legacy-policy.ts

@@ -10,6 +10,8 @@
  * Compile-time exhaustiveness: `LEGACY_POLICY` must cover every
  * `PermissionVerb` (enforced via `satisfies`).
  */
+
+import { hasLeadEquivalence } from "./elevated-agents";
 import type { PermissionVerb } from "./permissions";
 import type { RbacPrincipal, RbacResource } from "./types";
 
@@ -24,10 +26,33 @@ export type LegacyRule = {
 
 // ── Named rules (research §3 Rule column) ────────────────────────────────────
 
+/** Lead agents, plus extension system agents registered as lead-equivalent. */
+function actsAsLead(principal: RbacPrincipal): boolean {
+  return principal.kind === "agent" && (principal.isLead || hasLeadEquivalence(principal.agentId));
+}
+
 const leadOnly: LegacyRule = {
   name: "lead-only",
   denyReason: "requires lead agent",
-  evaluate: (principal) => principal.kind === "agent" && principal.isLead,
+  evaluate: (principal) => actsAsLead(principal),
+};
+
+/**
+ * Human principals: the shared API key (operator) and dashboard session users.
+ * Dashboard users carry no admin flag today, so they are treated like the
+ * operator, matching the config routes (`src/http/config.ts`).
+ */
+const operatorOrUser: LegacyRule = {
+  name: "operator-or-user",
+  denyReason: "requires operator or user authentication",
+  evaluate: (principal) => principal.kind === "operator" || principal.kind === "user",
+};
+
+const leadOrOperatorOrUser: LegacyRule = {
+  name: "lead-or-operator-or-user",
+  denyReason: "requires lead agent, operator, or user authentication",
+  evaluate: (principal) =>
+    principal.kind === "operator" || principal.kind === "user" || actsAsLead(principal),
 };
 
 const leadOrTaskCreator: LegacyRule = {
@@ -35,7 +60,7 @@ const leadOrTaskCreator: LegacyRule = {
   denyReason: "requires lead agent or task creator",
   evaluate: (principal, resource) => {
     if (principal.kind !== "agent") return false;
-    if (principal.isLead) return true;
+    if (actsAsLead(principal)) return true;
     return (
       resource?.kind === "task" &&
       resource.creatorAgentId != null &&
@@ -49,7 +74,7 @@ const leadOrResourceOwner: LegacyRule = {
   denyReason: "requires lead agent or resource owner",
   evaluate: (principal, resource) => {
     if (principal.kind !== "agent") return false;
-    if (principal.isLead) return true;
+    if (actsAsLead(principal)) return true;
     return (
       resource?.kind === "owned" &&
       resource.ownerAgentId != null &&
@@ -63,7 +88,7 @@ const leadOrOwnNamespace: LegacyRule = {
   denyReason: "requires lead agent or your own task:agent: namespace",
   evaluate: (principal, resource) => {
     if (principal.kind !== "agent") return false;
-    if (principal.isLead) return true;
+    if (actsAsLead(principal)) return true;
     // A blank agent id can never own a namespace — the pre-migration guards
     // used truthiness (`if (info.agentId && ...)`), so `X-Agent-ID: ""` plus
     // the literal namespace `task:agent:` must stay denied.
@@ -105,7 +130,7 @@ const memoryOwnerOrLeadSwarm: LegacyRule = {
   evaluate: (principal, resource) => {
     if (principal.kind !== "agent" || resource?.kind !== "owned") return false;
     if (resource.ownerAgentId != null && resource.ownerAgentId === principal.agentId) return true;
-    return principal.isLead && resource.scope === "swarm";
+    return actsAsLead(principal) && resource.scope === "swarm";
   },
 };
 
@@ -121,7 +146,7 @@ const taskFsMutate: LegacyRule = {
   denyReason: "requires operator, user, lead agent, task assignee, or task creator",
   evaluate: (principal, resource) => {
     if (principal.kind === "operator" || principal.kind === "user") return true;
-    if (principal.isLead) return true;
+    if (actsAsLead(principal)) return true;
     if (resource?.kind !== "task") return false;
     return (
       (resource.agentId != null && resource.agentId === principal.agentId) ||
@@ -132,6 +157,8 @@ const taskFsMutate: LegacyRule = {
 
 /** All named (non-composite) rule kinds, keyed by identifier. */
 export const LEGACY_RULES = {
+  "operator-or-user": operatorOrUser,
+  "lead-or-operator-or-user": leadOrOperatorOrUser,
   "lead-only": leadOnly,
   "lead-or-task-creator": leadOrTaskCreator,
   "lead-or-resource-owner": leadOrResourceOwner,
@@ -203,4 +230,6 @@ export const LEGACY_POLICY = {
   "script.api.update": leadOnly,
   "script.api.rotate": leadOnly,
   "script.api.delete": leadOnly,
+  "extension.write": leadOrOperatorOrUser,
+  "extension.activate": operatorOrUser,
 } as const satisfies Record<PermissionVerb, LegacyRule>;

package/src/rbac/permissions.ts

@@ -257,6 +257,14 @@ export const PERMISSIONS = {
     description: "Delete an external script API endpoint.",
     namespace: "script",
   },
+  "extension.write": {
+    description: "Install, update, or uninstall a swarm extension.",
+    namespace: "extension",
+  },
+  "extension.activate": {
+    description: "Enable, disable, or activate a version of a swarm extension.",
+    namespace: "extension",
+  },
 } as const satisfies Record<string, { description: string; namespace: string }>;
 
 export type PermissionVerb = keyof typeof PERMISSIONS;

package/src/scheduler/deferred-task-waits.ts

@@ -1,21 +1,94 @@
 import { getDbClient, getScheduledTaskById, getUserById, updateScheduledTask } from "@/be/db";
-import type { AgentTask } from "@/types";
+import type { PreparedTaskCreate } from "@/tasks/sibling-awareness";
+import type { AgentTask, ScheduledTask } from "@/types";
 import { workflowEventBus } from "@/workflows/event-bus";
-import { createStandaloneScheduleTask } from "./schedule-task";
+import { createStandaloneScheduleTask, prepareStandaloneScheduleTask } from "./schedule-task";
 
 export type TaskWakeEvent = "task.completed" | "task.failed" | "settled";
 
 type TaskWait = {
   scheduleId: string;
-  taskId: string;
   eventName: TaskWakeEvent;
+  mode: "all" | "any";
   status: "pending" | "fired";
 };
 
+type WaitMember = { taskId: string; taskStatus: string | null; deferred: number };
+
+type WakeReason = "ceiling" | "task.completed" | "task.failed" | "task.cancelled";
+
+/**
+ * Read the wait row and its member set and decide whether the wait is ready.
+ * Returns the wake-up cause text, or undefined when the wait is absent, already
+ * fired, not addressed by `reason`, or its member set has not matched yet.
+ * Pure reads: callers run it once outside the transaction (to build the task
+ * through the extension pre-hooks) and once more under the write lock, where
+ * the answer is authoritative. An event only identifies a candidate wait; it
+ * never proves the set is ready.
+ */
+async function resolveWaitCause(
+  scheduleId: string,
+  reason: WakeReason,
+): Promise<{ wait: TaskWait; cause: string } | undefined> {
+  const client = getDbClient();
+  const wait = await client.get<TaskWait>(
+    "SELECT * FROM deferred_task_waits WHERE scheduleId = ?",
+    [scheduleId],
+  );
+  if (!wait || wait.status !== "pending") return undefined;
+  if (reason !== "ceiling" && wait.eventName !== "settled" && wait.eventName !== reason)
+    return undefined;
+  if (reason === "ceiling") return { wait, cause: "ceiling expired" };
+  const members = await client.query<WaitMember>(
+    `SELECT m.taskId, t.status AS taskStatus, EXISTS (
+       SELECT 1 FROM scheduled_tasks d
+       WHERE d.parentTaskId = t.id AND d.taskType = 'deferred' AND d.enabled = 1
+     ) AS deferred
+     FROM deferred_task_wait_members m LEFT JOIN agent_tasks t ON t.id = m.taskId
+     WHERE m.scheduleId = ?`,
+    [scheduleId],
+  );
+  const matched = members.filter(
+    (member) =>
+      !member.deferred &&
+      (member.taskStatus === "completed" ||
+        member.taskStatus === "failed" ||
+        member.taskStatus === "cancelled") &&
+      (wait.eventName === "settled" || wait.eventName === `task.${member.taskStatus}`),
+  );
+  if (!matched.length || (wait.mode === "all" && matched.length !== members.length))
+    return undefined;
+  const cause =
+    members.length === 1
+      ? `task.${matched[0]!.taskStatus} for task ${matched[0]!.taskId}`
+      : `${wait.mode} tasks matched ${wait.eventName}: ${matched.map((member) => `${member.taskId} (${member.taskStatus})`).join(", ")}`;
+  return { wait, cause };
+}
+
+function wakeSchedule(schedule: ScheduledTask, cause: string): ScheduledTask {
+  return { ...schedule, taskTemplate: `${schedule.taskTemplate}\n\nWake-up cause: ${cause}.` };
+}
+
+async function prepareDeferredWakeTask(
+  scheduleId: string,
+  reason: WakeReason,
+  extraTags: string[],
+): Promise<PreparedTaskCreate | undefined> {
+  const resolved = await resolveWaitCause(scheduleId, reason);
+  if (!resolved) return undefined;
+  let schedule = await getScheduledTaskById(scheduleId);
+  if (!schedule?.enabled) return undefined;
+  if (schedule.createdBy && !(await getUserById(schedule.createdBy))) {
+    schedule = { ...schedule, createdBy: undefined };
+  }
+  if (!schedule.taskTemplate) throw new Error(`Schedule "${schedule.name}" has no taskTemplate`);
+  return await prepareStandaloneScheduleTask(wakeSchedule(schedule, resolved.cause), extraTags);
+}
+
 /** Undefined means a normal schedule; an empty result means another caller won. */
 export async function dispatchDeferredTaskWait(
   scheduleId: string,
-  reason: "ceiling" | "task.completed" | "task.failed",
+  reason: WakeReason,
   extraTags: string[] = [],
 ): Promise<{ task?: AgentTask } | undefined> {
   const client = getDbClient();
@@ -26,14 +99,15 @@ export async function dispatchDeferredTaskWait(
     ]))
   )
     return undefined;
+  // Extension pre-hooks must run outside the transaction, so build the wake-up task
+  // first; the transaction below re-reads the wait and its member set before claiming.
+  // The prepared description carries the cause seen here; for an `any` wait a member
+  // that settles between this read and the claim is missing from that text only.
+  const preparedForWait = await prepareDeferredWakeTask(scheduleId, reason, extraTags);
+  if (!preparedForWait) return {};
   return client.transaction(async () => {
-    const wait = await client.get<TaskWait>(
-      "SELECT * FROM deferred_task_waits WHERE scheduleId = ?",
-      [scheduleId],
-    );
-    if (!wait || wait.status !== "pending") return {};
-    if (reason !== "ceiling" && wait.eventName !== "settled" && wait.eventName !== reason)
-      return {};
+    const resolved = await resolveWaitCause(scheduleId, reason);
+    if (!resolved) return {};
     let schedule = await getScheduledTaskById(scheduleId);
     if (!schedule?.enabled) return {};
     const now = new Date().toISOString();
@@ -46,13 +120,10 @@ export async function dispatchDeferredTaskWait(
       schedule = { ...schedule, createdBy: undefined };
     }
     if (!schedule.taskTemplate) throw new Error(`Schedule "${schedule.name}" has no taskTemplate`);
-    const cause = reason === "ceiling" ? "ceiling expired" : `${reason} for task ${wait.taskId}`;
     const task = await createStandaloneScheduleTask(
-      {
-        ...schedule,
-        taskTemplate: `${schedule.taskTemplate}\n\nWake-up cause: ${cause}.`,
-      },
+      wakeSchedule(schedule, resolved.cause),
       extraTags,
+      preparedForWait,
     );
     await client.run("UPDATE deferred_task_waits SET childTaskId = ? WHERE scheduleId = ?", [
       task.id,
@@ -73,17 +144,50 @@ export async function dispatchDeferredTaskWait(
 
 /** Reconcile durable producer state, including terminal transitions missed by this process. */
 export async function reconcileDeferredTaskWaits(taskId?: string): Promise<void> {
-  const rows = await getDbClient().query<TaskWait & { taskStatus: "completed" | "failed" }>(
-    `SELECT w.*, t.status AS taskStatus FROM deferred_task_waits w
-     JOIN agent_tasks t ON t.id = w.taskId
+  const client = getDbClient();
+  const replacements = await client.query<{ taskId: string; resumeTaskId: string }>(
+    `SELECT DISTINCT m.taskId, (
+       SELECT r.id FROM agent_tasks r
+       WHERE r.parentTaskId = t.id AND r.taskType = 'resume'
+       ORDER BY r.createdAt, r.id LIMIT 1
+     ) AS resumeTaskId
+     FROM deferred_task_wait_members m
+     JOIN deferred_task_waits w ON w.scheduleId = m.scheduleId
+     JOIN agent_tasks t ON t.id = m.taskId
+     WHERE w.status = 'pending' AND t.status = 'superseded'
+       AND resumeTaskId IS NOT NULL`,
+  );
+  if (replacements.length) {
+    await client.transaction(async () => {
+      for (const replacement of replacements) {
+        // Collapse members that now watch the same child. Fired waits and their
+        // original ceilings stay untouched. No resume child (including skipped
+        // recovery) means hold to the ceiling, never wake on supersession.
+        await client.run(
+          `UPDATE OR REPLACE deferred_task_wait_members SET taskId = ?, updated_at = ?
+           WHERE taskId = ? AND scheduleId IN (
+             SELECT scheduleId FROM deferred_task_waits WHERE status = 'pending'
+           )`,
+          [replacement.resumeTaskId, new Date().toISOString(), replacement.taskId],
+        );
+      }
+    });
+    // Catch up through a chain missed while stopped, and check the replacements
+    // even when the triggering event named their superseded parent.
+    return reconcileDeferredTaskWaits();
+  }
+  const rows = await client.query<TaskWait & { taskStatus: "completed" | "failed" | "cancelled" }>(
+    `SELECT DISTINCT w.*, t.status AS taskStatus FROM deferred_task_waits w
+     JOIN deferred_task_wait_members m ON m.scheduleId = w.scheduleId
+     JOIN agent_tasks t ON t.id = m.taskId
      JOIN scheduled_tasks s ON s.id = w.scheduleId
-     WHERE w.status = 'pending' AND s.enabled = 1 AND t.status IN ('completed', 'failed')
+     WHERE w.status = 'pending' AND s.enabled = 1 AND t.status IN ('completed', 'failed', 'cancelled')
        AND NOT EXISTS (
          SELECT 1 FROM scheduled_tasks d
          WHERE d.parentTaskId = t.id AND d.taskType = 'deferred' AND d.enabled = 1
        )
        AND (w.eventName = 'settled' OR w.eventName = 'task.' || t.status)
-       ${taskId ? "AND w.taskId = ?" : ""}`,
+       ${taskId ? "AND m.taskId = ?" : ""}`,
     taskId ? [taskId] : [],
   );
   for (const row of rows) {
@@ -96,7 +200,7 @@ export async function reconcileDeferredTaskWaits(taskId?: string): Promise<void>
   }
 }
 
-function onTaskTerminal(payload: unknown): void {
+function onTaskEvent(payload: unknown): void {
   if (
     !payload ||
     typeof payload !== "object" ||
@@ -109,15 +213,22 @@ function onTaskTerminal(payload: unknown): void {
   });
 }
 
-/** Two fixed listeners read durable waits, so boot needs no per-wait in-memory registry. */
+/** Fixed listeners read durable waits, so boot needs no per-wait in-memory registry. */
 export async function initDeferredTaskWaits(): Promise<void> {
   stopDeferredTaskWaits();
-  workflowEventBus.on("task.completed", onTaskTerminal);
-  workflowEventBus.on("task.failed", onTaskTerminal);
+  workflowEventBus.on("task.completed", onTaskEvent);
+  workflowEventBus.on("task.failed", onTaskEvent);
+  workflowEventBus.on("task.cancelled", onTaskEvent);
+  workflowEventBus.on("task.superseded", onTaskEvent);
+  // The resume may be committed after its parent's supersede event.
+  workflowEventBus.on("task.created", onTaskEvent);
   await reconcileDeferredTaskWaits();
 }
 
 export function stopDeferredTaskWaits(): void {
-  workflowEventBus.off("task.completed", onTaskTerminal);
-  workflowEventBus.off("task.failed", onTaskTerminal);
+  workflowEventBus.off("task.completed", onTaskEvent);
+  workflowEventBus.off("task.failed", onTaskEvent);
+  workflowEventBus.off("task.cancelled", onTaskEvent);
+  workflowEventBus.off("task.superseded", onTaskEvent);
+  workflowEventBus.off("task.created", onTaskEvent);
 }

package/src/scheduler/schedule-task.ts

@@ -1,40 +1,70 @@
-import { getDbClient } from "@/be/db";
+import { createTaskExtended, getDbClient } from "@/be/db";
 import { scheduleContextKey } from "@/tasks/context-key";
-import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
+import {
+  type PreparedTaskCreate,
+  prepareTaskWithSiblingAwareness,
+} from "@/tasks/sibling-awareness";
 import type { AgentTask, ScheduledTask } from "@/types";
 
-export async function createStandaloneScheduleTask(
+/**
+ * Run the `pre.task.create` extension hooks for a schedule firing. Call this OUTSIDE
+ * the transaction that creates the task: the dispatcher skips hooks while a
+ * transaction is open. Throws `TaskCreationBlockedError` when a hook blocks.
+ */
+export async function prepareStandaloneScheduleTask(
   schedule: ScheduledTask,
   extraTags: string[] = [],
-): Promise<AgentTask> {
+): Promise<PreparedTaskCreate> {
   if (!schedule.taskTemplate) {
     throw new Error(`Schedule "${schedule.name}" has no taskTemplate (targetType=agent-task)`);
   }
-  const task = await createTaskWithSiblingAwareness(schedule.taskTemplate, {
-    key: schedule.key,
-    creatorAgentId: schedule.createdByAgentId,
-    taskType: schedule.taskType,
-    tags: [...schedule.tags, "scheduled", `schedule:${schedule.name}`, ...extraTags],
-    priority: schedule.priority,
-    agentId: schedule.targetAgentId,
-    routingReason: schedule.targetAgentId ? "human_pinned" : undefined,
-    model: schedule.model,
-    modelTier: schedule.modelTier,
-    scheduleId: schedule.id,
-    source: "schedule",
-    requestedByUserId: schedule.createdBy,
-    contextKey: scheduleContextKey({ scheduleId: schedule.id }),
-    // Set only by `defer-task`. An explicit parent wins over the sibling-awareness
-    // auto-wiring (see withSiblingAwareness in src/tasks/sibling-awareness.ts), so
-    // the wake-up run continues the deferred task rather than a random sibling.
-    parentTaskId: schedule.parentTaskId,
-  });
+  return await prepareTaskWithSiblingAwareness(
+    schedule.taskTemplate,
+    {
+      key: schedule.key,
+      creatorAgentId: schedule.createdByAgentId,
+      taskType: schedule.taskType,
+      tags: [...schedule.tags, "scheduled", `schedule:${schedule.name}`, ...extraTags],
+      priority: schedule.priority,
+      agentId: schedule.targetAgentId,
+      routingReason: schedule.targetAgentId ? "human_pinned" : undefined,
+      routingSource: schedule.targetAgentId ? "engine_default" : undefined,
+      model: schedule.model,
+      modelTier: schedule.modelTier,
+      scheduleId: schedule.id,
+      source: "schedule",
+      requestedByUserId: schedule.createdBy,
+      contextKey: scheduleContextKey({ scheduleId: schedule.id }),
+      // Set only by `defer-task`. An explicit parent wins over the sibling-awareness
+      // auto-wiring (see withSiblingAwareness in src/tasks/sibling-awareness.ts), so
+      // the wake-up run continues the deferred task rather than a random sibling.
+      parentTaskId: schedule.parentTaskId,
+    },
+    { origin: "schedule" },
+  );
+}
+
+/**
+ * Insert the schedule's task. Pass the result of `prepareStandaloneScheduleTask`
+ * when calling from inside a transaction; without it the hooks run here.
+ */
+export async function createStandaloneScheduleTask(
+  schedule: ScheduledTask,
+  extraTags: string[] = [],
+  prepared?: PreparedTaskCreate,
+): Promise<AgentTask> {
+  const { description, options } =
+    prepared ?? (await prepareStandaloneScheduleTask(schedule, extraTags));
+  const task = await createTaskExtended(description, options);
   // Both timer and event dispatch wrap this helper in a transaction. Transfer
   // pending watchers before the resume task becomes visible or its schedule is
   // disabled; their own schedules retain the original ceilings.
   if (schedule.taskType === "deferred" && schedule.parentTaskId) {
     await getDbClient().run(
-      "UPDATE deferred_task_waits SET taskId = ?, updated_at = ? WHERE status = 'pending' AND taskId = ?",
+      `UPDATE deferred_task_wait_members SET taskId = ?, updated_at = ?
+       WHERE taskId = ? AND scheduleId IN (
+         SELECT scheduleId FROM deferred_task_waits WHERE status = 'pending'
+       )`,
       [task.id, new Date().toISOString(), schedule.parentTaskId],
     );
   }