@desplega.ai/agent-swarm 1.148.0 → 1.149.0

package/src/tools/defer-task.ts

@@ -4,12 +4,14 @@ import * as z from "zod";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import {
   completeTask,
+  createLogEntry,
   createScheduledTask,
   getAgentById,
   getDbClient,
   getTaskById,
   updateAgentStatusFromCapacity,
 } from "@/be/db";
+import { reconcileDeferredTaskWaits } from "@/scheduler/deferred-task-waits";
 import { runTaskTerminalEffects } from "@/tasks/task-terminal-effects";
 import { getTaskOutputValidationError } from "@/tasks/terminal-result-guard";
 import { assertOwnsTask, ownerCtx } from "@/tools/task-tool-ctx";
@@ -32,7 +34,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
       title: "Defer Task",
       annotations: { destructiveHint: false, idempotentHint: false },
       description:
-        "Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output. A one-off schedule wakes you up later with a child task that carries this task as its parent. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check.",
+        "Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output unless the task has an outputSchema. For a task with an outputSchema, provide output as a JSON string matching that schema; it is stored verbatim as terminal output, while deferral details remain visible in the task log. A one-off schedule wakes you up later with a child task that carries this task as its parent. Optionally provide wakeOn to wake early when another task completes or fails; delayMs or runAt remains required as the ceiling. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check.",
       inputSchema: z.object({
         taskId: z.string().describe("The ID of the task you are working on."),
         delayMs: z
@@ -46,12 +48,28 @@ export const registerDeferTaskTool = (server: McpServer) => {
           .datetime()
           .optional()
           .describe("Wake up at this ISO datetime (e.g. '2026-03-06T15:00:00Z'). Must be future."),
+        wakeOn: z
+          .object({
+            event: z.enum(["task.completed", "task.failed", "settled"]),
+            taskId: z.string().min(1),
+          })
+          .strict()
+          .optional()
+          .describe(
+            "Wake early on this task event. settled covers completed or failed. Already-terminal tasks are rejected; a delayMs/runAt ceiling is still required.",
+          ),
         summary: z
           .string()
           .min(1)
           .max(4000)
           .describe(
-            "What you did so far and where things stand. This becomes the task's output; the lead and your wake-up run both read it.",
+            "What you did so far and where things stand. Stored in the task log for tasks with an outputSchema; otherwise becomes the task's output.",
+          ),
+        output: z
+          .string()
+          .optional()
+          .describe(
+            "Required when the task has an outputSchema: a JSON string matching that schema, stored verbatim as terminal output. Ignored for tasks without an outputSchema.",
           ),
         note: z
           .string()
@@ -71,7 +89,11 @@ export const registerDeferTaskTool = (server: McpServer) => {
         nextRunAt: z.string().optional(),
       }),
     },
-    async ({ taskId, delayMs, runAt, summary, note, checks }, requestInfo, _meta) => {
+    async (
+      { taskId, delayMs, runAt, wakeOn, summary, output, note, checks },
+      requestInfo,
+      _meta,
+    ) => {
       if (!requestInfo.agentId) {
         return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
@@ -122,26 +144,37 @@ export const registerDeferTaskTool = (server: McpServer) => {
       }
       const nextRunAt = delayMs ? new Date(Date.now() + delayMs).toISOString() : runAt!;
 
+      const wakeDescription = wakeOn
+        ? `on ${wakeOn.event} for task ${wakeOn.taskId}, or by ${nextRunAt}`
+        : `at ${nextRunAt}`;
       const checksBlock = renderChecks(checks);
       const taskTemplate = `Resume task ${taskId}: ${note}${checksBlock}`;
       const createdBy =
         (await resolveTaskAuditUserId(requestInfo.sourceTaskId, requestInfo.agentId)) ?? undefined;
 
-      // The deferral note is written as the task's FINAL output — a task with
-      // an outputSchema must satisfy it on completion (store-progress enforces
-      // the same rule). Validate before creating anything: the real schedule
-      // id isn't known yet, but it never changes whether this prose is valid
-      // JSON against the schema, so a placeholder stands in for it here.
-      const previewOutput = `${summary}\n\nDeferred until ${nextRunAt} (schedule pending). Pending: ${note}${checksBlock}`;
-      const outputValidationError = getTaskOutputValidationError(task.outputSchema, previewOutput);
-      if (outputValidationError) {
-        return toolErr(
-          `Task ${taskId} has an outputSchema; its terminal output must satisfy it, but a deferral note cannot. ${outputValidationError}`,
-        );
+      // Validate before creating the schedule or changing the task.
+      if (task.outputSchema) {
+        if (!output) {
+          return toolErr(
+            `Task ${taskId} has an outputSchema. Call defer-task with output: a JSON string matching that schema. Summary and note are stored separately in the task log.`,
+          );
+        }
+        const outputValidationError = getTaskOutputValidationError(task.outputSchema, output);
+        if (outputValidationError) return toolErr(outputValidationError);
       }
 
       try {
         const committed = await getDbClient().transaction(async () => {
+          if (wakeOn) {
+            if (wakeOn.taskId === taskId)
+              throw new DeferAbortedError("Cannot wake on the task being deferred.");
+            const watched = await getTaskById(wakeOn.taskId);
+            if (!watched) throw new DeferAbortedError(`Watched task ${wakeOn.taskId} not found.`);
+            if (isTerminalTaskStatus(watched.status))
+              throw new DeferAbortedError(
+                `Watched task ${wakeOn.taskId} is already ${watched.status}; read its result instead of deferring.`,
+              );
+          }
           const schedule = await createScheduledTask({
             // Unique name (`getScheduledTaskByName` is a unique lookup). The UUID
             // prevents concurrent deferrals of the same task from colliding.
@@ -165,12 +198,22 @@ export const registerDeferTaskTool = (server: McpServer) => {
             createdBy,
           });
 
-          const output = `${summary}\n\nDeferred until ${nextRunAt} (schedule ${schedule.id}). Pending: ${note}${checksBlock}`;
+          if (wakeOn) {
+            await getDbClient().run(
+              "INSERT INTO deferred_task_waits (scheduleId, taskId, eventName, created_by, updated_by) VALUES (?, ?, ?, ?, ?)",
+              [schedule.id, wakeOn.taskId, wakeOn.event, createdBy ?? null, createdBy ?? null],
+            );
+            getDbClient().afterCommit(() => {
+              void reconcileDeferredTaskWaits(wakeOn.taskId).catch((err) => {
+                console.error("[defer-task] Event wake reconciliation failed:", err);
+              });
+            });
+          }
+
+          const deferralDetails = `${summary}\n\nDeferred until ${nextRunAt} (schedule ${schedule.id}). Pending: ${note}${checksBlock}`;
 
-          // Deliberately NOT running `getTaskOutputValidationError` again here:
-          // already validated above against a placeholder id; re-run would be
-          // redundant since the id never affects JSON-shape validity.
-          const completed = await completeTask(taskId, output);
+          const terminalOutput = task.outputSchema ? output! : deferralDetails;
+          const completed = await completeTask(taskId, terminalOutput);
           if (!completed) {
             // Another writer terminally completed/failed/cancelled this task
             // between our early check and this transaction's write. Abort:
@@ -182,6 +225,15 @@ export const registerDeferTaskTool = (server: McpServer) => {
             );
           }
 
+          if (task.outputSchema) {
+            await createLogEntry({
+              eventType: "task_progress",
+              taskId,
+              agentId: requestInfo.agentId,
+              newValue: deferralDetails,
+            });
+          }
+
           // afterCommit: the transaction can still roll back; business-use must
           // not be told the task completed for a write that never landed.
           getDbClient().afterCommit(() => {
@@ -207,7 +259,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
             await updateAgentStatusFromCapacity(task.agentId);
           }
 
-          return { scheduleId: schedule.id, output, completed };
+          return { scheduleId: schedule.id, output: terminalOutput, completed };
         });
 
         await runTaskTerminalEffects({
@@ -218,7 +270,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
         });
 
         return toolOk(
-          `Task ${taskId} completed and deferred. Wake-up at ${nextRunAt} (schedule ${committed.scheduleId}). This task is final; the wake-up task continues the work.`,
+          `Task ${taskId} completed and deferred. Wake-up ${wakeDescription} (schedule ${committed.scheduleId}). This task is final; the wake-up task continues the work.`,
           {
             data: {
               yourAgentId: requestInfo.agentId,

package/src/tools/send-task.ts

@@ -31,6 +31,7 @@ import {
   FollowUpConfigSchema,
   ModelTierSchema,
   ReasoningEffortSchema,
+  RoutingReasonSchema,
   splitLegacyModelAlias,
 } from "@/types";
 import { findJsonSchemaShapeErrors } from "@/workflows/json-schema-validator";
@@ -61,6 +62,14 @@ export const sendTaskInputSchema = z
       .string()
       .optional()
       .describe("The agent to assign/offer task to. Omit to create unassigned task for pool."),
+    routingReason: RoutingReasonSchema.optional().describe(
+      "Why this agent was selected. Required when agentId is supplied; omit for pool routing.",
+    ),
+    routingNote: z
+      .string()
+      .max(200)
+      .optional()
+      .describe("Optional routing context (maximum 200 characters)."),
     task: z.string().min(1).describe("The task description to send."),
     key: AssetKeySchema.optional().describe(
       "Logical namespace key. Child tasks inherit their parent namespace when provided.",
@@ -174,6 +183,13 @@ export const sendTaskInputSchema = z
         path: [hasChannel ? "slackThreadTs" : "slackChannelId"],
       });
     }
+    if (data.agentId !== undefined && data.routingReason === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "routingReason is required when agentId is supplied.",
+        path: ["routingReason"],
+      });
+    }
     checkOutputSchemaShape(data.outputSchema, ctx);
   });
 
@@ -222,6 +238,8 @@ export async function sendTaskHandler(
   ctx: ToolCtx,
   {
     agentId,
+    routingReason,
+    routingNote,
     task,
     key,
     offerMode,
@@ -247,6 +265,10 @@ export async function sendTaskHandler(
     outputSchema,
   }: SendTaskArgs,
 ): Promise<SwarmToolResult> {
+  // Defense in depth for direct TypeScript callers that bypass MCP schema parsing.
+  if (agentId !== undefined && routingReason === undefined) {
+    return toolErr("routingReason is required when agentId is supplied.");
+  }
   if (ctx.kind === "owner" && !ctx.agentId) {
     return toolErr('Agent ID not found. The MCP client should define the "X-Agent-ID" header.', {
       data: { yourAgentId: ctx.agentId },
@@ -339,6 +361,9 @@ export async function sendTaskHandler(
       effectiveAgentId = effectiveParentTask.agentId;
     }
   }
+  const effectiveRoutingReason =
+    agentId !== undefined ? routingReason : effectiveAgentId ? "continuity" : undefined;
+  const effectiveRoutingNote = effectiveRoutingReason ? routingNote : undefined;
 
   // The three dedup guards are pure reads, so they run twice: once here as a
   // fast path (keeping this tool's existing early-exit responses), and once
@@ -470,6 +495,8 @@ export async function sendTaskHandler(
         overrideSlackContext,
         followUpConfig,
         outputSchema,
+        routingReason: effectiveRoutingReason,
+        routingNote: effectiveRoutingNote,
         routingAffinity:
           effectiveLeadOnly || requiredCapabilities?.length
             ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }
@@ -537,6 +564,8 @@ export async function sendTaskHandler(
         overrideSlackContext,
         followUpConfig,
         outputSchema,
+        routingReason: effectiveRoutingReason,
+        routingNote: effectiveRoutingNote,
         routingAffinity:
           effectiveLeadOnly || requiredCapabilities?.length
             ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }
@@ -578,6 +607,8 @@ export async function sendTaskHandler(
       overrideSlackContext,
       followUpConfig,
       outputSchema,
+      routingReason: effectiveRoutingReason,
+      routingNote: effectiveRoutingNote,
       routingAffinity:
         effectiveLeadOnly || requiredCapabilities?.length
           ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }

package/src/tools/skills/skill-publish.ts

@@ -71,6 +71,7 @@ To reject: close this task with a rejection reason.`;
 
       const task = await createTaskExtended(taskDescription, {
         agentId: leadAgent.id,
+        routingReason: "skill",
         creatorAgentId: requestInfo.agentId,
         source: "mcp",
         taskType: "skill-approval",

package/src/tools/store-progress.ts

@@ -29,6 +29,17 @@ import { scrubSecrets } from "@/utils/secret-scrubber";
 // echoed the schema example, producing noise rows keyed `mcp-<taskId>-<ts>`
 // that double-counted alongside the harness's authoritative entry.
 
+// Deliberately narrow and phrase-based (not a bare "wait"/"block" substring
+// match) to under-fire rather than over-fire: measured against 196 real
+// progress rows across all statuses, this matched 0 — see PR body for the
+// full false-positive measurement methodology.
+const BLOCKED_WAITING_PATTERN =
+  /\b(waiting (for|on)|blocked (on|until|by)|still waiting|awaiting)\b/i;
+
+// Below this, two check-ins are close enough together that "blocked" reads as
+// noise and calling defer-task buys nothing over checking in again shortly.
+const BLOCKED_WAITING_MIN_ELAPSED_MS = 3 * 60 * 1000;
+
 export const storeProgressOutputSchema = swarmToolOutputSchema({
   // Bounded confirmation only. The handler keeps the full task row internally
   // for completion memory, raters, and follow-up creation, but never echoes it
@@ -56,6 +67,12 @@ export const storeProgressOutputSchema = swarmToolOutputSchema({
     .describe(
       "True when force: true replaced output and/or failureReason on an already-terminal task without replaying completion side effects.",
     ),
+  blockedWaitingElapsedMs: z
+    .number()
+    .optional()
+    .describe(
+      "Present only when this progress text reads as blocked-waiting: milliseconds since the task's prior update. Drives the store-progress nudge toward defer-task.",
+    ),
 });
 
 export const registerStoreProgressTool = (server: McpServer) => {
@@ -251,6 +268,27 @@ export const registerStoreProgressTool = (server: McpServer) => {
 
         let updatedTask = existingTask;
         const isTerminal = isTerminalTaskStatus(existingTask.status);
+        // This call's own status can finish the task even though existingTask
+        // (its state before this call) is not yet terminal — gate on both so a
+        // completing call carrying blocked-waiting-shaped text (e.g. "awaiting
+        // review") never nudges toward defer-task.
+        const goingTerminal = status !== undefined && isTerminalTaskStatus(status);
+
+        // Computed against the task's state as of BEFORE this call's update,
+        // so "elapsed" reads as time since the prior check-in, not zero.
+        let blockedWaitingElapsedMs: number | undefined;
+        if (progress && !isTerminal && !goingTerminal && BLOCKED_WAITING_PATTERN.test(progress)) {
+          const referenceIso = existingTask.lastUpdatedAt ?? existingTask.createdAt;
+          if (referenceIso) {
+            const elapsed = Date.now() - new Date(referenceIso).getTime();
+            // Below the floor, a sub-minute check-in reads as "blocked" purely
+            // from noise, and defer-task buys nothing over just checking in
+            // again shortly — so treat it as not blocked-waiting yet.
+            if (elapsed >= BLOCKED_WAITING_MIN_ELAPSED_MS) {
+              blockedWaitingElapsedMs = elapsed;
+            }
+          }
+        }
 
         // Attachments — pointer-based, append-only. Insert each row inside
         // this transaction; the helper dedups by sha256 (when present) or by
@@ -422,6 +460,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
             ? `Task "${taskId}" marked as ${status}.`
             : `Progress stored for task "${taskId}".`,
           task: updatedTask,
+          blockedWaitingElapsedMs,
         };
       });
 
@@ -463,6 +502,10 @@ export const registerStoreProgressTool = (server: McpServer) => {
         ...("wasForcedOverwrite" in result && result.wasForcedOverwrite
           ? { wasForcedOverwrite: true }
           : {}),
+        ...("blockedWaitingElapsedMs" in result &&
+        typeof result.blockedWaitingElapsedMs === "number"
+          ? { blockedWaitingElapsedMs: result.blockedWaitingElapsedMs }
+          : {}),
       };
       return success ? toolOk(message, { data }) : toolErr(message, { data });
     },

package/src/tools/templates.ts

@@ -197,6 +197,7 @@ Use the crashed agent's identity above as context for who was on it and what kin
 
 Dispatch via \`send-task\` with ALL of:
 - an explicit \`agentId\` (the chosen worker) — REQUIRED. If you omit it, \`send-task\` auto-routes to the original task's agent, which is the dead worker, and the work re-strands.
+- \`routingReason: "reroute_fault"\`
 - \`taskType: "resume"\`
 - the tag \`resume-generation:{{generation_next}}\`
 - \`parentTaskId: {{original_task_id}}\`
@@ -251,7 +252,7 @@ Required capabilities: {{required_capabilities}}{{artifacts_block}}
 
 This task has been sitting unassigned because no currently-registered agent matches its required role/capabilities. Pick an agent to take this work over and RE-DELEGATE it — do NOT execute it yourself.
 
-Dispatch via \`send-task\` with an explicit \`agentId\` (REQUIRED — omitting it re-pools the work under the same affinity tag and it will starve again) and \`parentTaskId: {{original_task_id}}\`.
+Dispatch via \`send-task\` with an explicit \`agentId\` (REQUIRED — omitting it re-pools the work under the same affinity tag and it will starve again), \`routingReason: "overflow"\`, and \`parentTaskId: {{original_task_id}}\`.
 
 This work will NOT fall back to the unassigned pool — you are the only re-delegation path.`,
   variables: [

package/src/tools/utils.ts

@@ -246,6 +246,23 @@ const slackReadNudge = (r: SwarmToolResult): string | undefined => {
     : undefined;
 };
 
+// Sole caller (storeProgressBlockedWaitingNudge) only reaches this once ms is
+// past BLOCKED_WAITING_MIN_ELAPSED_MS (3 minutes), so there's no sub-minute case.
+function formatIdleDuration(ms: number): string {
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const remMinutes = minutes % 60;
+  return remMinutes > 0 ? `${hours}h${remMinutes}m` : `${hours}h`;
+}
+
+const storeProgressBlockedWaitingNudge = (r: SwarmToolResult): string | undefined => {
+  if (!r.ok) return undefined;
+  const ms = (r.data as { blockedWaitingElapsedMs?: unknown } | undefined)?.blockedWaitingElapsedMs;
+  if (typeof ms !== "number") return undefined;
+  return `That reads as blocked-waiting, ${formatIdleDuration(ms)} since your last update — call defer-task so a wake-up task resumes you instead of polling manually.`;
+};
+
 const workflowLongScriptTimeoutNudge = (r: SwarmToolResult): string | undefined => {
   if (!r.ok) return undefined;
   const hint = (r.data as { longScriptTimeoutHint?: unknown } | undefined)?.longScriptTimeoutHint;
@@ -260,6 +277,7 @@ const workflowLongScriptTimeoutNudge = (r: SwarmToolResult): string | undefined
 export const NUDGES: Record<string, (result: SwarmToolResult) => string | undefined> = {
   "defer-task": (r) =>
     r.ok ? "Stop working on this task now; the wake-up task will carry your note." : undefined,
+  "store-progress": storeProgressBlockedWaitingNudge,
   "script-run": scriptRunNudge,
   "script-upsert": scriptAuthoringNudge,
   "launch-script-run": scriptAuthoringNudge,
@@ -745,6 +763,13 @@ type ToolConfig<
   _meta?: Record<string, unknown>;
 };
 
+const preloadedToolsByServer = new WeakMap<McpServer, ReadonlySet<string>>();
+
+/** Configure before registration. The set belongs to one MCP session, never the fleet. */
+export function setPreloadedTools(server: McpServer, names: readonly string[]): void {
+  preloadedToolsByServer.set(server, new Set(names));
+}
+
 /**
  * Creates a tool registration helper that automatically extracts request info
  * and passes it as the second parameter to the callback.
@@ -770,10 +795,13 @@ export const createToolRegistrar = (server: McpServer) => {
     config: ToolConfig<InputArgs, OutputArgs>,
     cb: ToolCallbackWithInfo<InputArgs>,
   ) => {
+    const toolConfig = preloadedToolsByServer.get(server)?.has(name)
+      ? { ...config, _meta: { ...config._meta, "anthropic/alwaysLoad": true } }
+      : config;
     // When inputSchema is undefined, the MCP SDK calls handler(extra) with a single arg.
     // When inputSchema is defined, it calls handler(args, extra) with two args.
     if (config.inputSchema === undefined) {
-      return server.registerTool(name, config, (async (meta: Meta) => {
+      return server.registerTool(name, toolConfig, (async (meta: Meta) => {
         const requestInfo = getRequestInfo(meta);
         return withSpan(
           "mcp.tool",
@@ -793,7 +821,10 @@ export const createToolRegistrar = (server: McpServer) => {
       }) as Parameters<typeof server.registerTool>[2]);
     }
 
-    return server.registerTool(name, config, (async (args: InferInput<InputArgs>, meta: Meta) => {
+    return server.registerTool(name, toolConfig, (async (
+      args: InferInput<InputArgs>,
+      meta: Meta,
+    ) => {
       const requestInfo = getRequestInfo(meta);
       return withSpan(
         // Span name carries the tool: a static `mcp.tool` is unreadable in a

package/src/types.ts

@@ -340,6 +340,15 @@ export const AgentTaskSourceSchema = z.enum([
 ]);
 export type AgentTaskSource = z.infer<typeof AgentTaskSourceSchema>;
 
+export const RoutingReasonSchema = z.enum([
+  "skill",
+  "continuity",
+  "overflow",
+  "human_pinned",
+  "reroute_fault",
+]);
+export type RoutingReason = z.infer<typeof RoutingReasonSchema>;
+
 // ---------------------------------------------------------------------------
 // Harness Provider
 // ---------------------------------------------------------------------------
@@ -504,6 +513,8 @@ export const AgentTaskSchema = z
     title: z.string().optional(), // Human-facing display title override (e.g. session rename); falls back to `task` when unset
     status: AgentTaskStatusSchema,
     source: AgentTaskSourceSchema.default("mcp"),
+    routingReason: RoutingReasonSchema.optional(),
+    routingNote: z.string().max(200).optional(),
 
     // Task metadata
     taskType: z.string().max(50).optional(), // e.g., "bug", "feature", "chore"
@@ -664,6 +675,8 @@ export const CreateTaskOptionsSchema = z.object({
   agentId: z.string().nullable().optional(),
   creatorAgentId: z.string().optional(),
   source: AgentTaskSourceSchema.optional(),
+  routingReason: RoutingReasonSchema.optional(),
+  routingNote: z.string().max(200).optional(),
   taskType: z.string().max(50).optional(),
   tags: z.array(z.string()).optional(),
   priority: z.number().int().min(0).max(100).optional(),
@@ -1936,7 +1949,7 @@ export const WorkflowNodeSchema = z
     config: z
       .record(z.string(), z.unknown())
       .describe(
-        "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. " +
+        "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, routingReason?, routingNote?, tags?, priority?, dir?, vcsRepo?, model? }; configured agentId defaults routingReason to human_pinned. " +
           "For script: { runtime, script, args?, timeout? }. " +
           "For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode?, timeoutMs? (1000-300000) }. " +
           "Agent-task templates and ordinary config values support {{interpolation}} from the node's inputs context, including trigger and declared upstream aliases. " +

package/src/utils/acp-session-token.ts

@@ -5,6 +5,9 @@
  * key for a short-lived aseph_ bearer before handing credentials to the
  * ACP target process.
  */
+import { scrubSecrets } from "./secret-scrubber";
+
+const REVOKE_TIMEOUT_MS = 5000;
 
 /** Wall-clock TTL for a session token: 24 hours. Long enough for any realistic
  * ACP session; the token is actively revoked when the session finishes anyway. */
@@ -38,7 +41,8 @@ export async function mintAcpSessionToken(
 
 /**
  * Ask the swarm API to revoke a previously-minted `aseph_` token. Best-effort:
- * errors are logged but never propagated to the caller.
+ * the request is bounded, and errors are logged but never propagated to the
+ * caller. ACP completion does not wait for this cleanup.
  */
 export async function revokeAcpSessionToken(
   apiUrl: string,
@@ -46,11 +50,17 @@ export async function revokeAcpSessionToken(
   tokenId: string,
 ): Promise<void> {
   try {
-    await fetch(`${apiUrl.replace(/\/+$/, "")}/api/sessions/tokens/${tokenId}`, {
+    const res = await fetch(`${apiUrl.replace(/\/+$/, "")}/api/sessions/tokens/${tokenId}`, {
       method: "DELETE",
       headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(REVOKE_TIMEOUT_MS),
     });
-  } catch {
-    // best-effort — token will expire on its own
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  } catch (error) {
+    console.warn(
+      scrubSecrets(
+        `[acp] Session token revoke failed: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
   }
 }

package/src/utils/secret-scrubber.ts

@@ -104,6 +104,8 @@ const TOKEN_REGEXES: ReadonlyArray<{ name: string; re: RegExp }> = [
   { name: "github_pat", re: /github_pat_[A-Za-z0-9_]{20,}/g },
   // GitHub classic/OAuth tokens (ghp_, gho_, ghu_, ghs_, ghr_)
   { name: "github_token", re: new RegExp(String.raw`${TB}gh[pousr]_[A-Za-z0-9]{20,}\b`, "g") },
+  // ACP ephemeral session tokens (base62 payload)
+  { name: "acp_session_token", re: new RegExp(String.raw`${TB}aseph_[A-Za-z0-9]{20,}\b`, "g") },
   // GitLab personal access tokens
   { name: "gitlab_pat", re: new RegExp(String.raw`${TB}glpat-[A-Za-z0-9_-]{20,}\b`, "g") },
   // Anthropic API keys (must match before the generic sk- rule below)

package/src/utils/task-tool-manifest.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { ALL_TOOLS } from "../tools/tool-config";
+
+const toolNames = z
+  .array(z.string().refine((name) => ALL_TOOLS.has(name), "Unknown swarm tool"))
+  .max(16);
+
+/** Exact task-type and schedule keys; a schedule entry overrides its task type. */
+export const taskToolManifestSchema = z.strictObject({
+  taskTypes: z.record(z.string().min(1).max(50), toolNames).optional(),
+  schedules: z.record(z.uuid(), toolNames).optional(),
+});
+
+export function parseTaskToolManifest(value: string) {
+  return taskToolManifestSchema.parse(JSON.parse(value));
+}
+
+export function selectTaskTools(
+  manifest: z.infer<typeof taskToolManifestSchema>,
+  task: { taskType?: string; scheduleId?: string; slackChannelId?: string },
+): string[] {
+  const fromSchedule =
+    task.scheduleId && Object.hasOwn(manifest.schedules ?? {}, task.scheduleId)
+      ? manifest.schedules?.[task.scheduleId]
+      : undefined;
+  const fromType =
+    task.taskType && Object.hasOwn(manifest.taskTypes ?? {}, task.taskType)
+      ? manifest.taskTypes?.[task.taskType]
+      : undefined;
+  return [...new Set(fromSchedule ?? fromType ?? [])].filter(
+    (name) => !name.startsWith("slack-") || Boolean(task.slackChannelId),
+  );
+}

package/src/workflows/engine.ts

@@ -1,3 +1,4 @@
+import { notifyAutomationPreflightFailure } from "../automation-preflight-alert";
 import {
   getAutomationSetupStates,
   preflightAutomation,
@@ -91,13 +92,15 @@ export async function startWorkflowExecution(
     await getAutomationSetupStates(),
   );
   if (preflight.state === "needs_setup") {
-    return await recordWorkflowPreflightFailure({
+    const { runId, recorded } = await recordWorkflowPreflightFailure({
       workflowId: workflow.id,
       triggerType: options.triggerType ?? "manual",
       triggerData,
       failureReason: preflight.failureReason!,
       createdBy: options.requestedByUserId,
     });
+    if (recorded) await notifyAutomationPreflightFailure(preflight);
+    return runId;
   }
 
   // Templates can consume install params outside the graph definition (most

package/src/workflows/executors/agent-task.ts

@@ -6,6 +6,7 @@ import {
   FollowUpConfigSchema,
   ModelTierSchema,
   ReasoningEffortSchema,
+  RoutingReasonSchema,
   splitLegacyModelAlias,
 } from "../../types";
 import type { ExecutorResult } from "./base";
@@ -13,11 +14,13 @@ import { BaseExecutor } from "./base";
 
 // ─── Config / Output Schemas ────────────────────────────────
 
-const AgentTaskConfigSchema = z.object({
+export const AgentTaskConfigSchema = z.object({
   template: z.string(),
   // Plain string, NOT .uuid(): agents may join with custom IDs (AGENT_ID env /
   // join-swarm agentId), so a UUID filter would reject legitimate agents.
   agentId: z.string().optional(),
+  routingReason: RoutingReasonSchema.optional(),
+  routingNote: z.string().max(200).optional(),
   tags: z.array(z.string()).optional(),
   priority: z.number().int().min(0).max(100).optional(),
   offerMode: z.boolean().optional(),
@@ -98,6 +101,9 @@ export class AgentTaskExecutor extends BaseExecutor<
       {
         key: effectiveKey,
         agentId: config.agentId ?? null,
+        // A configured workflow target is an author pin, including existing definitions.
+        routingReason: config.routingReason ?? (config.agentId ? "human_pinned" : undefined),
+        routingNote: config.routingNote,
         source: "workflow",
         tags: config.tags,
         priority: config.priority,

package/templates/ai-toolbox.manifest.json

@@ -1,5 +1,5 @@
 {
-  "commit": "a4e5e77923eaabc644f8290396ef341d041cdce1",
+  "commit": "9748aabf7252c258378302240d73f7516d113777",
   "excludedSkills": [
     "feedback"
   ],
@@ -11,6 +11,10 @@
     "templates/skills/brainstorming/files/template.md": "ae0aabc02a307db0550f9026aca33fb471608c31f7a0b65ecc781073f17cc953",
     "templates/skills/code-reviewing/config.json": "dde1298b15d55428b898a0421033d1aa140ef152d335d49345059e29deab96f2",
     "templates/skills/code-reviewing/content.md": "85e9aa3b276384ab3f3bc570aece2e8c103a8614c19129378cf4dfec3457a18b",
+    "templates/skills/comms/config.json": "5561ee129f68a03e89b21458afebcd79afd2a8c177c0ba5dad00ffa21ee57bc3",
+    "templates/skills/comms/content.md": "bd1d33b4af13eb36dfd87552bb35ecd200ac0a0dd40d409b50dff448708ce5ea",
+    "templates/skills/comms/files/references/ste-rules.md": "6ee2ed5d6b49d2e421b6c9d22310a5b589fa1abe81de06213e4b89fbc1271e74",
+    "templates/skills/comms/files/references/visual-shapes.md": "5e07e9250ad4cdc877af2281525185f0de89c01f90a077463a2c77c8a7b998e8",
     "templates/skills/delegate-work/config.json": "5b1542eb0be359bb8a17117fcf87917e0607d1b939ae3266ddffacdc14efb281",
     "templates/skills/delegate-work/content.md": "c9562bd17846d3595d40172ecfdc6f85bb99eaf23597eb9d5aa9635d5c14d079",
     "templates/skills/delegate-work/files/scripts/codex-exec.sh": "c2222986c46ac608403f28f201230cb34c7d7ac41a2262dc2c8dbd99c8645dbb",
@@ -74,6 +78,7 @@
     "ask-user",
     "brainstorming",
     "code-reviewing",
+    "comms",
     "delegate-work",
     "design-docs",
     "engineering-standards",