@desplega.ai/agent-swarm 1.147.0 → 1.149.0

package/src/integrations/kapso/inbound.ts

@@ -154,6 +154,7 @@ export async function routeKapsoInbound(payload: KapsoWebhookPayload): Promise<K
 
   const task = await createTaskWithSiblingAwareness(await buildTaskDescription(payload), {
     agentId: mapping.agentId ?? null,
+    routingReason: mapping.agentId ? "human_pinned" : undefined,
     source: "system",
     taskType: "kapso-inbound",
     tags: ["kapso-whatsapp", "inbound"],

package/src/jira/sync.ts

@@ -582,6 +582,7 @@ async function createInitialJiraTask(input: {
 
   const task = await createTaskWithSiblingAwareness(result.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "jira",
     taskType: "jira-issue",
     requestedByUserId: input.requestedByUserId,
@@ -627,6 +628,7 @@ async function createCommentMentionTask(input: {
 
   const task = await createTaskWithSiblingAwareness(result.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "jira",
     taskType: "jira-issue",
     requestedByUserId: input.requestedByUserId,

package/src/linear/sync.ts

@@ -614,6 +614,7 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
 
   const task = await createTaskWithSiblingAwareness(templateResult.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "linear",
     taskType: "linear-issue",
     requestedByUserId,
@@ -897,6 +898,7 @@ export async function handleAgentSessionPrompted(event: Record<string, unknown>)
 
   const task = await createTaskWithSiblingAwareness(followupResult.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "linear",
     taskType: "linear-issue",
     requestedByUserId: promptedRequestedByUserId,

package/src/prompts/session-templates.ts

@@ -90,14 +90,15 @@ registerTemplate({
 Your output is delegation and review. Workers implement, research, analyze, and write. Data gathering, even a quick query, goes to a worker. You answer simple factual questions yourself.
 
 \`get-swarm\` is the roster. Route by capability and load.
-Delegate with \`send-task\`. Read a child's result with \`get-task-details\`.
+\`send-task\`: include \`routingReason\` with \`agentId\`. Read results via \`get-task-details\`.
 A task states the goal, the repo URL when there is one, and the constraints. Workers know git, the skills, and \`store-progress\`.
 Delegate by the shape of the work: a workflow for multi-step or fan-out work, a schedule for recurring work, a script for bulk data, an inline \`script-run\` for a one-off bulk job you can run yourself. The \`workflow-iterate\`, \`scheduling\`, and \`swarm-scripts\` skills build them.
 Research or exploration: tell the worker to use the \`researching\` skill. A large feature: a task for the \`planning\` skill first, then a task for the \`implementing\` skill with \`parentTaskId\`. A small fix: direct implementation.
 A follow-up that continues earlier work carries \`parentTaskId\`. The worker receives the prior context.
-A task whose result depends on the workers' output: wait for the children with the \`wait-for-task\` script, then merge and complete the task yourself. A turn that ends with children still running leaves the task unfinished.
 
-A worker's completion or failure arrives as a follow-up task. Review the output and complete the follow-up. The worker's result is the answer. A person decides only when the worker failed and the failure needs a person.
+Worker completion/failure triggers a follow-up by default. For longer work, \`defer-task\` with a wake-up or complete this task. Review the worker's answer and complete the follow-up. Escalate only failures needing a person.
+
+Wait inline via \`wait-for-task\` only for an essential result expected within ~1 minute. Set \`send-task.followUpConfig.disabled=true\`; cap all waits at ~1 minute total. If still running, \`defer-task\` with a wake-up.
 
 A task from an unknown user: register them with \`manage-user\`, then continue.
 Your heartbeat runbook is the \`heartbeatMd\` profile field. Edit it with \`update-profile\`. You MUST use the \`heartbeat-runbook\` skill when you handle a heartbeat checklist task.
@@ -229,16 +230,20 @@ registerTemplate({
   defaultBody: `
 ## How you write
 
-These rules cover everything a person reads from you: Slack, PR and issue comments, tickets, email, pages, task output.
+For human-facing replies and artifacts: lead with the result. Use plain words, active voice, one idea per sentence, and sentence case headings.
+State blockers and reasons. Preserve meaningful uncertainty.
+Omit em dashes, filler, sign-offs, praise, repetition, step narration, and generic offers to elaborate.
+
+Simple replies: one to three sentences. Routine replies: under 120 words, using short paragraphs or up to three bullets.
+Use more detail for requested depth or essential evidence, caveats, or instructions.
+Include context only when it changes understanding or action. Link extensive supporting material when useful, but make the reply self-contained.
+Do not shorten investigation, required artifacts, or schema-defined output to meet reply limits.
 
-Lead with the result. Context comes after.
-One idea per sentence. Active voice with a named actor.
-Sentence case headings. Plain words: use, help, many, if.
-Keep a hedge only when you are unsure. "May have failed" stays "may have failed".
-When something is broken, blocked, or a bad idea, say so and say why.
-Reply in the requester's language, at the depth they asked for. A one-line question gets the answer first.
-A Requester Profile section, when present, wins on tone, depth, and format. Correctness wins over style.
-Em dashes, filler, sign-offs, and praise of the question are out.
+Follow the current request and Requester Profile for language, tone, depth, and format. Correctness wins over style.
+Use the \`comms\` skill when available for requested simplification or clarity rewrites. Ordinary replies need no skill invocation.
+Use Visual mode only for explicit visual requests with delivery tools available in the active channel.
+Requests to show data are not visual requests. New facts, diagnosis, and actions still require work.
+Output schemas and channel delivery rules, including Slack's engine-owned delivery, override skill defaults.
 `,
   variables: [],
   category: "system",
@@ -316,6 +321,15 @@ registerTemplate({
 // lists are rendered at the call site and interpolated into the static text)
 // ============================================================================
 
+registerTemplate({
+  eventType: "system.agent.tool_preload",
+  header: "",
+  defaultBody:
+    "This session preloads selected swarm tools. If a tool definition is already available in context, call it directly. Use your harness tool search only for tools whose definitions are not yet available.",
+  variables: [],
+  category: "system",
+});
+
 registerTemplate({
   eventType: "system.agent.tools_skills",
   header: "",
@@ -386,8 +400,8 @@ This swarm runs in **scripts-only mode**. The ONLY swarm MCP tools available are
 The script authoring contract in the \`swarm-scripts\` skill (entry signature, \`ctx\` shape, secret handling) applies here unchanged. The full SDK is \`ctx.swarm.*\`: task lifecycle (\`task_get\`, \`task_send\`, \`task_storeProgress\`, \`task_action\`, \`task_list\`), Slack (\`slack_reply\`, \`slack_post\`, \`slack_read\`), memory, kv, swarm info (\`swarm_get\`, \`agent_info\`), and more. Responses are usually wrapped; prefer \`res?.data ?? res\`.
 
 **Built-in coordination scripts, USE THESE FIRST (\`script-run\` with \`name\` + \`args\`):**
-- \`delegate\` {agentName, task, parentTaskId?} → subtask for an agent by name; returns {taskId}
-- \`wait-for-task\` {taskId} → waits up to ~25s for a terminal state; returns {done, status, output}; while done=false call it again
+- \`delegate\` {agentName, task, routingReason, parentTaskId?} → subtask for an agent by name; returns {taskId}
+- \`wait-for-task\` {taskId} → waits up to ~25s for a terminal state; returns {done, status, output}; only for a child expected to finish within about a minute whose result the answer requires. Bound all calls to about a minute total; if still done=false, use \`defer-task\` with a wake-up to collect the result.
 - \`get-child-outputs\` {parentTaskId} → all children with status+output
 - \`complete-task\` {taskId, output} → THE way to finish your assigned task
 - \`report-progress\` {taskId, note} → progress update
@@ -397,7 +411,7 @@ Rules of the road:
 - Prefer a built-in script over inline source; write inline TypeScript only for logic no built-in covers. Check \`script-search\` first, and \`script-query-types\` for the live \`swarm-sdk.d.ts\` before authoring anything non-trivial.
 - \`taskId\` is NOT ambient inside scripts; pass it explicitly via \`args\`.
 - Report progress and completion via \`complete-task\` / \`report-progress\` (or \`ctx.swarm.task_storeProgress\` inline). This is how you update, complete, or fail your task; there is no other way.
-- Scripts are killed after ~30s and stdout is capped at 1 MB. Never sleep/loop longer than ~25s inside one script; chain \`wait-for-task\` calls instead.
+- Scripts are killed after ~30s and stdout is capped at 1 MB. Never sleep/loop longer than ~25s inside one script. Default to the child's automatic follow-up; chained \`wait-for-task\` calls are only for the inline exception above and must stay within about a minute total.
 - Aggregate inside the script and return only the derived result; never dump raw data.
 - Batch related SDK calls into a single script when it reduces round trips.
 `,

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

@@ -0,0 +1,123 @@
+import { getDbClient, getScheduledTaskById, getUserById, updateScheduledTask } from "@/be/db";
+import type { AgentTask } from "@/types";
+import { workflowEventBus } from "@/workflows/event-bus";
+import { createStandaloneScheduleTask } from "./schedule-task";
+
+export type TaskWakeEvent = "task.completed" | "task.failed" | "settled";
+
+type TaskWait = {
+  scheduleId: string;
+  taskId: string;
+  eventName: TaskWakeEvent;
+  status: "pending" | "fired";
+};
+
+/** Undefined means a normal schedule; an empty result means another caller won. */
+export async function dispatchDeferredTaskWait(
+  scheduleId: string,
+  reason: "ceiling" | "task.completed" | "task.failed",
+  extraTags: string[] = [],
+): Promise<{ task?: AgentTask } | undefined> {
+  const client = getDbClient();
+  // Keep ordinary schedule dispatch off the write-lock path.
+  if (
+    !(await client.get<TaskWait>("SELECT * FROM deferred_task_waits WHERE scheduleId = ?", [
+      scheduleId,
+    ]))
+  )
+    return undefined;
+  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 {};
+    let schedule = await getScheduledTaskById(scheduleId);
+    if (!schedule?.enabled) return {};
+    const now = new Date().toISOString();
+    const claimed = await client.run(
+      "UPDATE deferred_task_waits SET status = 'fired', firedBy = ?, resolvedAt = ?, updated_at = ? WHERE scheduleId = ? AND status = 'pending'",
+      [reason, now, now, scheduleId],
+    );
+    if (!claimed.changes) return {};
+    if (schedule.createdBy && !(await getUserById(schedule.createdBy))) {
+      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}.`,
+      },
+      extraTags,
+    );
+    await client.run("UPDATE deferred_task_waits SET childTaskId = ? WHERE scheduleId = ?", [
+      task.id,
+      scheduleId,
+    ]);
+    await updateScheduledTask(scheduleId, {
+      enabled: false,
+      nextRunAt: null,
+      lastRunAt: now,
+      lastUpdatedAt: now,
+      consecutiveErrors: 0,
+      lastErrorAt: null,
+      lastErrorMessage: null,
+    });
+    return { task };
+  });
+}
+
+/** 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
+     JOIN scheduled_tasks s ON s.id = w.scheduleId
+     WHERE w.status = 'pending' AND s.enabled = 1 AND t.status IN ('completed', 'failed')
+       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 ? [taskId] : [],
+  );
+  for (const row of rows) {
+    try {
+      await dispatchDeferredTaskWait(row.scheduleId, `task.${row.taskStatus}`);
+    } catch (err) {
+      // A broken wait must not stop other event wakes or the ceiling poller.
+      console.error(`[Scheduler] Deferred task wake failed for ${row.scheduleId}:`, err);
+    }
+  }
+}
+
+function onTaskTerminal(payload: unknown): void {
+  if (
+    !payload ||
+    typeof payload !== "object" ||
+    !("taskId" in payload) ||
+    typeof payload.taskId !== "string"
+  )
+    return;
+  void reconcileDeferredTaskWaits(payload.taskId).catch((err) => {
+    console.error("[Scheduler] Deferred task event wake failed:", err);
+  });
+}
+
+/** Two 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);
+  await reconcileDeferredTaskWaits();
+}
+
+export function stopDeferredTaskWaits(): void {
+  workflowEventBus.off("task.completed", onTaskTerminal);
+  workflowEventBus.off("task.failed", onTaskTerminal);
+}

package/src/scheduler/schedule-task.ts

@@ -0,0 +1,42 @@
+import { getDbClient } from "@/be/db";
+import { scheduleContextKey } from "@/tasks/context-key";
+import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
+import type { AgentTask, ScheduledTask } from "@/types";
+
+export async function createStandaloneScheduleTask(
+  schedule: ScheduledTask,
+  extraTags: string[] = [],
+): Promise<AgentTask> {
+  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,
+  });
+  // 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 = ?",
+      [task.id, new Date().toISOString(), schedule.parentTaskId],
+    );
+  }
+  return task;
+}

package/src/scheduler/scheduler.ts

@@ -1,5 +1,6 @@
 import { ensure } from "@desplega.ai/business-use";
 import { CronExpressionParser } from "cron-parser";
+import { notifyAutomationPreflightFailure } from "@/automation-preflight-alert";
 import {
   getAutomationSetupStates,
   isNeedsSetupFailure,
@@ -24,8 +25,6 @@ import {
 import { buildScriptCredentialBindings } from "@/be/script-credential-broker";
 import { getScript } from "@/be/scripts/db";
 import { runScript } from "@/scripts-runtime/loader";
-import { scheduleContextKey } from "@/tasks/context-key";
-import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
 import { telemetry } from "@/telemetry";
 import type { AgentTask, ScheduledTask } from "@/types";
 import { getExecutorRegistry as getWorkflowExecutorRegistry } from "@/workflows";
@@ -33,6 +32,16 @@ import { startWorkflowExecution } from "@/workflows/engine";
 import type { ExecutorRegistry } from "@/workflows/executors/registry";
 import { handleScheduleTrigger } from "@/workflows/triggers";
 
+import {
+  dispatchDeferredTaskWait,
+  initDeferredTaskWaits,
+  reconcileDeferredTaskWaits,
+  stopDeferredTaskWaits,
+} from "./deferred-task-waits";
+import { createStandaloneScheduleTask } from "./schedule-task";
+
+export { createStandaloneScheduleTask } from "./schedule-task";
+
 let schedulerInterval: ReturnType<typeof setInterval> | null = null;
 let isProcessing = false;
 let executorRegistry: ExecutorRegistry | null = null;
@@ -53,33 +62,6 @@ function resolveExecutorRegistry(): ExecutorRegistry | null {
   }
 }
 
-export async function createStandaloneScheduleTask(
-  schedule: ScheduledTask,
-  extraTags: string[] = [],
-): Promise<AgentTask> {
-  if (!schedule.taskTemplate) {
-    throw new Error(`Schedule "${schedule.name}" has no taskTemplate (targetType=agent-task)`);
-  }
-  return 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,
-    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,
-  });
-}
-
 /**
  * Execute a schedule's `targetType='script'` target directly via the
  * scripts-runtime — no agent/LLM in the loop. Reuses the same `runScript()`
@@ -151,12 +133,16 @@ export async function dispatchScheduleTarget(
   schedule: ScheduledTask,
   extraTags: string[] = [],
 ): Promise<DispatchScheduleResult> {
+  const deferred = await dispatchDeferredTaskWait(schedule.id, "ceiling", extraTags);
+  if (deferred) return { triggeredWorkflows: false, ...deferred };
+
   const preflight = preflightAutomation(
     schedulePreflightInput(schedule),
     await getAutomationSetupStates(),
   );
   if (preflight.state === "needs_setup") {
-    await recordSchedulePreflightFailure(schedule.id, preflight.failureReason!);
+    const recorded = await recordSchedulePreflightFailure(schedule.id, preflight.failureReason!);
+    if (recorded) await notifyAutomationPreflightFailure(preflight);
     throw new AutomationNeedsSetupError(preflight.failureReason!);
   }
   // Params are safe and integrations are ready. Only now render values into
@@ -489,7 +475,10 @@ export function startScheduler(
   console.log(`[Scheduler] Starting with ${intervalMs}ms polling interval`);
 
   // Recover missed schedules from downtime, then run normal processing
-  void recoverMissedSchedules().then(() => processSchedules());
+  void initDeferredTaskWaits()
+    .then(() => recoverMissedSchedules())
+    .then(() => processSchedules())
+    .catch((err) => console.error("[Scheduler] Recovery failed:", err));
 
   schedulerInterval = setInterval(async () => {
     await processSchedules();
@@ -523,6 +512,7 @@ async function processSchedules(): Promise<void> {
   isProcessing = true;
 
   try {
+    await reconcileDeferredTaskWaits();
     const dueSchedules = await getDueScheduledTasks();
 
     for (const schedule of dueSchedules) {
@@ -541,6 +531,7 @@ async function processSchedules(): Promise<void> {
  * Stop the scheduler polling loop.
  */
 export function stopScheduler(): void {
+  stopDeferredTaskWaits();
   if (schedulerInterval) {
     clearInterval(schedulerInterval);
     schedulerInterval = null;

package/src/script-workflows/workflow-ctx.ts

@@ -32,6 +32,8 @@ type AgentTaskConfig = {
   template?: string;
   task?: string;
   agentId?: string;
+  routingReason?: "skill" | "continuity" | "overflow" | "human_pinned" | "reroute_fault";
+  routingNote?: string;
   tags?: string[];
   priority?: number;
   offerMode?: boolean;

package/src/scripts-runtime/types/stdlib.d.ts

@@ -28,6 +28,41 @@ declare module "swarm-sdk" {
   export type ScriptFsMode = "none" | "workspace-rw";
   export type ScriptApiRawOptions = { raw: true };
   export type ScriptApiDefaultOptions = { raw?: false };
+  export type RoutingReason =
+    | "skill"
+    | "continuity"
+    | "overflow"
+    | "human_pinned"
+    | "reroute_fault";
+  export type TaskSendArgs = Record<string, unknown> & {
+    task: string;
+    routingNote?: string;
+  } & (
+      | { agentId: string; routingReason: RoutingReason }
+      | { agentId?: never; routingReason?: never }
+    );
+  export type AgentTaskStepConfig = {
+    template?: string;
+    task?: string;
+    agentId?: string;
+    routingReason?: RoutingReason;
+    routingNote?: string;
+    tags?: string[];
+    priority?: number;
+    offerMode?: boolean;
+    dir?: string;
+    vcsRepo?: string;
+    model?: string;
+    parentTaskId?: string;
+    requestedByUserId?: string;
+    outputSchema?: Record<string, unknown>;
+    /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
+    waitForCompletion?: boolean;
+    /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
+    timeoutMs?: number;
+    /** Throw when the task ends failed/cancelled/superseded (default), or resolve with {taskId,status,error} when false. */
+    failOnTaskFailure?: boolean;
+  };
 
   export interface ScriptApiRawResult {
     ok: boolean;
@@ -147,6 +182,7 @@ declare module "swarm-sdk" {
       taskId: string;
       delayMs?: number;
       runAt?: string;
+      wakeOn?: { event: "task.completed" | "task.failed" | "settled"; taskId: string };
       summary: string;
       note: string;
       checks?: string[];
@@ -373,7 +409,7 @@ declare module "swarm-sdk" {
     }): Promise<unknown>;
 
     // --- write: tasks ---
-    task_send(args: Record<string, unknown>): Promise<unknown>;
+    task_send(args: TaskSendArgs): Promise<unknown>;
     task_cancel(args: { taskId: string }): Promise<unknown>;
     task_steer(args: {
       taskId: string;
@@ -579,29 +615,7 @@ declare module "swarm-sdk" {
       label: string,
       config: { prompt: string; model?: string; schema?: Record<string, unknown> },
     ): Promise<unknown>;
-    agentTask(
-      label: string,
-      config: {
-        template?: string;
-        task?: string;
-        agentId?: string;
-        tags?: string[];
-        priority?: number;
-        offerMode?: boolean;
-        dir?: string;
-        vcsRepo?: string;
-        model?: string;
-        parentTaskId?: string;
-        requestedByUserId?: string;
-        outputSchema?: Record<string, unknown>;
-        /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
-        waitForCompletion?: boolean;
-        /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
-        timeoutMs?: number;
-        /** Throw when the task ends failed/cancelled/superseded (default), or resolve with {taskId,status,error} when false. */
-        failOnTaskFailure?: boolean;
-      },
-    ): Promise<unknown>;
+    agentTask(label: string, config: AgentTaskStepConfig): Promise<unknown>;
     swarmScript(
       label: string,
       config: {

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -10,6 +10,41 @@ declare module "swarm-sdk" {
   export type ScriptFsMode = "none" | "workspace-rw";
   export type ScriptApiRawOptions = { raw: true };
   export type ScriptApiDefaultOptions = { raw?: false };
+  export type RoutingReason =
+    | "skill"
+    | "continuity"
+    | "overflow"
+    | "human_pinned"
+    | "reroute_fault";
+  export type TaskSendArgs = Record<string, unknown> & {
+    task: string;
+    routingNote?: string;
+  } & (
+      | { agentId: string; routingReason: RoutingReason }
+      | { agentId?: never; routingReason?: never }
+    );
+  export type AgentTaskStepConfig = {
+    template?: string;
+    task?: string;
+    agentId?: string;
+    routingReason?: RoutingReason;
+    routingNote?: string;
+    tags?: string[];
+    priority?: number;
+    offerMode?: boolean;
+    dir?: string;
+    vcsRepo?: string;
+    model?: string;
+    parentTaskId?: string;
+    requestedByUserId?: string;
+    outputSchema?: Record<string, unknown>;
+    /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
+    waitForCompletion?: boolean;
+    /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
+    timeoutMs?: number;
+    /** Throw when the task ends failed/cancelled/superseded (default), or resolve with {taskId,status,error} when false. */
+    failOnTaskFailure?: boolean;
+  };
 
   export interface ScriptApiRawResult {
     ok: boolean;
@@ -129,6 +164,7 @@ declare module "swarm-sdk" {
       taskId: string;
       delayMs?: number;
       runAt?: string;
+      wakeOn?: { event: "task.completed" | "task.failed" | "settled"; taskId: string };
       summary: string;
       note: string;
       checks?: string[];
@@ -355,7 +391,7 @@ declare module "swarm-sdk" {
     }): Promise<unknown>;
 
     // --- write: tasks ---
-    task_send(args: Record<string, unknown>): Promise<unknown>;
+    task_send(args: TaskSendArgs): Promise<unknown>;
     task_cancel(args: { taskId: string }): Promise<unknown>;
     task_steer(args: {
       taskId: string;
@@ -561,29 +597,7 @@ declare module "swarm-sdk" {
       label: string,
       config: { prompt: string; model?: string; schema?: Record<string, unknown> },
     ): Promise<unknown>;
-    agentTask(
-      label: string,
-      config: {
-        template?: string;
-        task?: string;
-        agentId?: string;
-        tags?: string[];
-        priority?: number;
-        offerMode?: boolean;
-        dir?: string;
-        vcsRepo?: string;
-        model?: string;
-        parentTaskId?: string;
-        requestedByUserId?: string;
-        outputSchema?: Record<string, unknown>;
-        /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
-        waitForCompletion?: boolean;
-        /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
-        timeoutMs?: number;
-        /** Throw when the task ends failed/cancelled/superseded (default), or resolve with {taskId,status,error} when false. */
-        failOnTaskFailure?: boolean;
-      },
-    ): Promise<unknown>;
+    agentTask(label: string, config: AgentTaskStepConfig): Promise<unknown>;
     swarmScript(
       label: string,
       config: {

package/src/server.ts

@@ -7,6 +7,7 @@ import { seedPricingFromModelsDev } from "./be/seed-pricing";
 import { isSteeringEnabled } from "./be/steering";
 import { registerGithubTaskReactions } from "./github/task-reactions";
 import { loadGlobalConfigsIntoEnv } from "./http/core";
+import { resolveTemplate } from "./prompts/resolver";
 import { isRbacEnabled } from "./rbac";
 import { registerAcceptSteerTool } from "./tools/accept-steer";
 import { registerAppDiffTool } from "./tools/app-diff";
@@ -163,6 +164,7 @@ import { registerUnregisterServiceTool } from "./tools/unregister-service";
 // Profiles capability
 import { registerUpdateProfileTool } from "./tools/update-profile";
 import { registerUpdateServiceStatusTool } from "./tools/update-service-status";
+import { setPreloadedTools } from "./tools/utils";
 import {
   registerReplyWhatsappMessageTool,
   registerSendWhatsappMessageTool,
@@ -274,7 +276,9 @@ export function isScriptsOnlyMcp(): boolean {
   return resolveScriptsOnlyMode({ env: process.env.SCRIPTS_ONLY_MCP });
 }
 
-export async function createServer(opts: { scriptsOnly?: boolean; fullSurface?: boolean } = {}) {
+export async function createServer(
+  opts: { scriptsOnly?: boolean; fullSurface?: boolean; preloadedTools?: readonly string[] } = {},
+) {
   // Reload env
   await loadGlobalConfigsIntoEnv(true);
 
@@ -316,12 +320,17 @@ export async function createServer(opts: { scriptsOnly?: boolean; fullSurface?:
       description: pkg.description,
     },
     {
+      ...(opts.preloadedTools?.length
+        ? { instructions: resolveTemplate("system.agent.tool_preload", {}).text }
+        : {}),
       capabilities: {
         logging: {},
       },
     },
   );
 
+  if (opts.preloadedTools?.length) setPreloadedTools(server, opts.preloadedTools);
+
   // Scripts-only surface (experimental code-mode): register just the script
   // catalog tools and stop. script-connections / script-apis stay out — they
   // are lead-only security admin and excluded from the scripts SDK too.

package/src/slack/actions.ts

@@ -84,6 +84,7 @@ export function registerActionHandlers(app: App): void {
     });
     const followUpTask = await createTaskWithSiblingAwareness(followUpText, {
       agentId: lead?.id,
+      routingReason: lead ? "skill" : undefined,
       source: "slack",
       parentTaskId: taskId,
       slackChannelId: originalTask.slackChannelId,

package/src/slack/assistant.ts

@@ -166,6 +166,7 @@ export function createAssistant(): Assistant {
             renderedMessageText,
             {
               agentId: workingAgent.id,
+              routingReason: "continuity",
               source: "slack",
               slackChannelId: channelId,
               slackThreadTs: threadTs,
@@ -247,6 +248,7 @@ export function createAssistant(): Assistant {
           renderedMessageText + channelContext,
           {
             agentId: lead.id,
+            routingReason: "skill",
             source: "slack",
             slackChannelId: channelId,
             slackThreadTs: threadTs,