@desplega.ai/agent-swarm 1.147.0 → 1.149.0

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",

package/templates/skills/comms/config.json

@@ -0,0 +1,18 @@
+{
+  "category": "skills",
+  "description": "Re-express something so it lands — re-explain your last reply in plain casual language, show the current topic visually (diagram, code-shape sketch, HTML artifact), do both at once, or rewrite artifact text into unambiguous ASD-STE100 English. Use when the user runs /desplega:comms, types /bro, says 'say it simpler', 'bro what', 'I don't follow', 'show me', 'draw this', 'visualize', 'disambiguate this', or 'STE100 rewrite'. Not for creative or marketing copy.",
+  "displayName": "Comms",
+  "kind": "skill",
+  "name": "comms",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "slug": "comms",
+  "systemDefault": true,
+  "tags": [
+    "ai-toolbox",
+    "agents",
+    "workflow"
+  ],
+  "title": "Comms",
+  "version": "1.0.0"
+}

package/templates/skills/comms/content.md

@@ -0,0 +1,74 @@
+# /comms — make it land
+
+Merged from three MIT sources: [bro-skill](https://github.com/luchasarie/bro-skill) (Simpler), the local show-me skill (Visual), and [asd-ste100-skill](https://github.com/desplega-ai/asd-ste100-skill) (Precise).
+
+One skill, three base modes plus a joint one. Pick from the **target** of the request, not from the wording alone.
+
+## Dispatch
+
+| Target of the request | Mode |
+|---|---|
+| Your own previous message — "simpler", "bro what", "didn't get it", "rephrase" | **Simpler** |
+| A concept, flow, architecture, or change — "show me", "draw", "diagram", "what does this look like" | **Visual** |
+| Your previous message AND it describes structure (a flow, a tree, an architecture, a sequence) — or the user asks for both ("simpler, and draw it") | **Joint** |
+| Artifact text a machine or reader must parse without a back-channel — tool description, error message, prompt, doc paragraph — "disambiguate", "rewrite", "STE" | **Precise** |
+
+Dispatch rules:
+
+- If the request names a mode, obey it.
+- If the target is your previous message and it is plain prose, use Simpler. If it describes structure, prefer Joint — a small visual usually lands faster than more words.
+- Never mix registers: no casual flavor in Precise output, no STE flatness in Simpler output. Precise never combines with the other modes.
+- If there is nothing to re-express (no previous message, no artifact, no topic), say so in one line.
+
+## Mode: Simpler
+
+Re-explain YOUR most recent assistant message like you're explaining it to a smart friend over a beer.
+
+1. **Re-explain, don't re-answer.** Never answer a new question, never add new information, never use tools. You are only re-expressing what you already said.
+2. **Simpler, not necessarily shorter.** The goal is "impossible to misunderstand", not "fewer words". Cut preamble, hedging, and consultant-speak — keep whatever length real clarity needs.
+3. **Facts survive verbatim.** Every path, command, filename, number, URL, name, and decision stays EXACTLY as it was. Simplify the explanation around the facts, never the facts themselves.
+4. **Light casual flavor.** Direct and informal ("basically...", "the point is...", "ok so..."). A touch of personality — don't turn it into a meme.
+5. **Same language.** If the original message was in another language, the simpler version stays in that language.
+6. **Flatten structure.** Drop headers and ceremony. Tables become plain sentences. Keep a short list only if the original genuinely had multiple parts.
+
+## Mode: Visual
+
+Help the user understand the current topic visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear:
+
+- **Pseudocode** for logic or an algorithm.
+- **Call tree** for runtime control flow.
+- **Component tree** for UI structure, including the state and module boundaries that matter.
+- **Shallow file tree** for file responsibility or a broad refactor.
+- **Mermaid** for component interaction, control flow, or data flow.
+- **`diff`** when the point is what changes and the surrounding shape already exists — diff the tree or pseudocode itself, not raw code. Match the diff shape to the topic.
+- **Whole code block** when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape.
+- **One focused HTML file** for a visual UI, layout, state comparison, or concept too dense for Mermaid — a diagram, infographic, or short slide deck. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then `Bash(open path/to/comms-{description}.html)`.
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the current question. Use one shape, maybe several — never all. Concrete example shapes: `references/visual-shapes.md`.
+
+**Delivery:** write the visual explanation to `/tmp/YYYY-MM-DD-HHMM-comms-<topic>.md` and open it with `file-review` (via Bash, `run_in_background: true`, `timeout: 600000`) — it rich-renders the markdown and lets the user leave inline comments; process their comments when the window closes. If `file-review` is not on PATH, put the visual in chat instead. Keep `Bash(open ...)` for HTML artifacts. Skip file-review only for a single small visual that reads fine in chat.
+
+## Mode: Joint
+
+Simpler + Visual in one document: Simpler-mode prose with Visual-mode shapes placed right after the sentence each one supports. Follow both rule sets — casual register for the words, smallest-view discipline for the visuals. Deliver via file-review, like Visual mode.
+
+## Mode: Precise
+
+Rewrite the given text under ASD-STE100 structural discipline so no reader — human or agent — can misparse it. Full rule tables, sub-mode detail, and process: `references/ste-rules.md`.
+
+Core rules:
+
+- Active voice. Simple tenses ("we received", not "we have received").
+- One instruction per sentence. ≤20 words for instructions, ≤25 for descriptions.
+- No semicolons. No phrasal verbs ("start", not "spin up"). No noun stacks over 3 words. No dropped words.
+- One name per thing — never rotate synonyms for the same referent.
+- Verb over nominalization ("analyze the log", not "perform an analysis of the log").
+- **Keep every hedge and qualifier.** "May have failed" never becomes "failed". A rewrite that changes confidence is a different claim, not a simplification.
+- Never add a fact the source did not state.
+
+Two sub-modes:
+
+- **Strict** — tool descriptions, error messages, prompts, procedures, safety text: every rule.
+- **STE-flavored** — READMEs, PR text, explanatory prose: structural rules in full, lexical rules advisory.
+
+Output: the rewritten text and nothing else — no preamble, no mode announcement, no change summary. If you deliberately kept a longer phrasing to preserve precision, add one line prefixed `Kept as-is:`. When asked to "show the diff" or "explain the changes", output the before/after rule table from `references/ste-rules.md` instead.

package/templates/skills/comms/files/references/ste-rules.md

@@ -0,0 +1,73 @@
+# Precise mode — ASD-STE100 rules
+
+Condensed from [asd-ste100-skill](https://github.com/desplega-ai/asd-ste100-skill) (MIT), which encodes the rule categories of ASD-STE100 Issue 9 (Jan 2025).
+
+This encodes the standard's rule *categories*, not ASD's ~900-word approved dictionary (free to obtain, not free to redistribute). Structural rules are checkable from the description alone — apply them with confidence. Lexical rules depend on the dictionary — apply them as a direction of travel, and never imply dictionary compliance.
+
+## Structural rules — apply these
+
+| Rule | Do | Don't |
+|---|---|---|
+| Active voice | "The agent deletes the file." | "The file is deleted (by the agent)." — unless the actor is genuinely unknown or irrelevant |
+| No phrasal verbs | "Remove the panel." / "Start the job." | "Take off the panel." / "Spin up the job." |
+| One instruction per sentence | "Open the file. Read line 3." | "Open the file and read line 3, then check if it matches." |
+| Sentence length | ≤20 words for instructions, ≤25 for descriptions | Long compound/subordinate-clause sentences |
+| No semicolons | Split into separate sentences | Any semicolon at all |
+| Noun clusters | ≤3 words stacked as a noun phrase | 4+ word noun stacks ("high pressure fuel pump inlet valve assembly") |
+| No ellipsis | Keep subject, verb, and article explicit | Drop words to save space ("Files not backed up will be lost" → ambiguous which files) |
+| Keep modality | "The request **may have** failed." stays "may have" | Promote a hedge to a fact, or invent a certainty the source did not state |
+| Paragraph limits | One topic per paragraph, ≤6 sentences | Multi-topic paragraphs |
+| Lists for sequences | Numbered/bulleted list for 3+ steps or conditions | A sequence buried in one prose sentence |
+
+## Lexical rules — direction of travel only
+
+| Rule | Do | Don't |
+|---|---|---|
+| One word, one meaning | Pick one verb for one action and reuse it every time | Rotate synonyms ("check"/"verify"/"confirm") for the same action |
+| One part of speech per word | "Apply oil to the valve" (oil = noun) | "Oil the valve" (oil = verb) |
+| Verb, not noun | "Analyze the log." | "Perform an analysis of the log." |
+| Domain terms | Keep needed technical terms; define each once if not common English | Jargon never defined |
+
+## Simple tenses — one exception
+
+STE permits infinitive, imperative, simple present, simple past, simple future, and past participle as adjective. It excludes present perfect: "we received the report", not "we have received the report". Exception: where the compound form carries information the simple form cannot — current relevance ("the job has completed" = output available now), or a hedge like "may have failed" — keep it and flag the departure.
+
+## Scan checklist
+
+Scan for all six before rewriting. Each is mechanical — you can point at the exact word that breaks it.
+
+1. **Synonym rotation** — the same thing has several names ("the user", "the customer", "the client"). Fix: one name, every time.
+2. **Hedge stacking** — qualifiers pile up until nothing is asserted ("it is important to note that this may potentially help to improve"). Fix: state the claim or delete it.
+3. **Nominalization** — an action frozen into a noun ("perform an analysis of"). Fix: use the verb.
+4. **Marketing adjectives** — seamless, robust, powerful, blazing-fast. Fix: delete, or replace with the measurement that earns the claim.
+5. **Run-on sentences** — ideas joined by semicolons or em dashes. Fix: one idea per sentence.
+6. **Soft phrasal verbs** — spin up, reach out, dive into, kick off. Fix: the single plain verb (start, contact, read, begin).
+
+## Process
+
+1. Pick the sub-mode (Strict or STE-flavored). Keep the choice internal unless asked.
+2. Read the input once for meaning before rewriting anything.
+3. Walk it sentence by sentence; flag every violation. In STE-flavored, flag lexical rules but do not enforce them.
+4. Rewrite each flagged sentence, preserving the original meaning exactly. If a rewrite would drop necessary precision (a safety condition, scope qualifier, number), keep the longer phrasing and flag it. Check modality before committing — a shorter sentence that upgrades a hedge to a fact is a different claim. Never add a fact the source did not state.
+5. Output the rewritten text alone. If the input already complies, say so — do not force changes.
+
+## Diff table format (on request)
+
+When asked to "show the diff" / "which rules did it break" / "before/after":
+
+```markdown
+| Rule violated | Original | Simplified |
+|---|---|---|
+| Present perfect tense | "We have received your request." | "We received your request." |
+| Noun cluster (4+ words) | "the agent task queue priority handler" | "the handler that sets task-queue priority" |
+
+Mode: Strict. 7 violations found.
+```
+
+Follow with one line naming anything deliberately not simplified, and why.
+
+## Boundaries
+
+- Not a certified STE authoring tool — a clarity tool inspired by the standard. For aerospace-grade compliance, check word-by-word against the official dictionary from [asd-ste100.org](https://www.asd-ste100.org/STE_downloads.html).
+- Fixes form, not substance: a hollow paragraph rewritten under these rules is a clean hollow paragraph. Say so instead of polishing it.
+- Stop when the sentence is unambiguous, not when it is shortest.

package/templates/skills/comms/files/references/visual-shapes.md

@@ -0,0 +1,112 @@
+# Visual mode — example shapes
+
+Concrete examples for each view the Visual mode can produce. Source: the show-me skill (bundled into this skill).
+
+Logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+Runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+File responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+Component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+`diff` shapes — match the diff to the topic.
+
+Component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+File-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+Call-tree change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+State or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+Whole block when most of it is new or a copyable target shape is needed:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```

package/templates/skills/swarm-scripts/SKILL.md

@@ -37,7 +37,7 @@ The swarm ships named scripts at global scope. Each one replaces a multi-step to
 | `task-context-gathering` | `{ taskId, queries: [...] }` | the task plus a deduplicated multi-query memory recall |
 | `smart-recall` | `{ queries: [...] }` | multi-query memory recall without the task |
 | `memory-dedup-check` | `{ text, threshold? }` | near-duplicates before you store a memory |
-| `delegate` | `{ agentName, task, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
+| `delegate` | `{ agentName, task, routingReason, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
 | `wait-for-task` | `{ taskId }` | waits up to about 25 s for a terminal state, returns `{ done, status, output }`; call again while `done` is false |
 | `get-child-outputs` | `{ parentTaskId }` | every child with status and output |
 | `complete-task` | `{ taskId, output }` | finish a task from inside a script |
@@ -74,6 +74,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 ### What `ctx` holds
 
 - `ctx.swarm.*`: the swarm SDK. `task_get`, `task_send`, `task_storeProgress`, `task_action`, `task_list`, `slack_reply`, `memory_search`, `memory_store`, `kv_get`, `kv_getOrNull`, `kv_set`, `kv_delete`, `kv_incr`, `kv_list`, `swarm_get`, `agent_info`, `db_query`, and more. `kv_getOrNull` returns the entry, `null` on a missing key, and throws on other errors.
+- `ctx.swarm.task_send` requires `routingReason` whenever `agentId` is present. Use `human_pinned` for an explicit/configured choice, `skill` for a role or specialization match, `continuity` for the same worker/session, `reroute_fault` for a fault handoff, or `overflow` for capacity/pool escalation. Omit both `agentId` and routing fields for the pool.
 - `ctx.swarm.config`: `apiKey`, `agentId`, `mcpBaseUrl`, and `ctx.swarm.config.get("KEY")` for user config values. All are `Redacted` wrappers that stringify to `<redacted>`. Never unwrap one into a return value, a log line, or a request body you build by hand.
 - `ctx.api.<slug>` and `ctx.mcp.<slug>`: typed clients for registered connections. They exist only for registered connections. Introspect with `Object.keys(ctx.api ?? {})` and `Object.keys(ctx.mcp ?? {})`.
 - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `Redacted`.
@@ -81,7 +82,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 
 ### Durable workflow scripts
 
-`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
+`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. A configured `ctx.step.agentTask` `agentId` records `human_pinned` unless `routingReason` is supplied. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
 
 ## Inline script pattern
 

package/templates/skills/swarm-scripts/content.md

@@ -32,7 +32,7 @@ The swarm ships named scripts at global scope. Each one replaces a multi-step to
 | `task-context-gathering` | `{ taskId, queries: [...] }` | the task plus a deduplicated multi-query memory recall |
 | `smart-recall` | `{ queries: [...] }` | multi-query memory recall without the task |
 | `memory-dedup-check` | `{ text, threshold? }` | near-duplicates before you store a memory |
-| `delegate` | `{ agentName, task, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
+| `delegate` | `{ agentName, task, routingReason, parentTaskId? }` | a subtask for an agent by name, returns `{ taskId }` |
 | `wait-for-task` | `{ taskId }` | waits up to about 25 s for a terminal state, returns `{ done, status, output }`; call again while `done` is false |
 | `get-child-outputs` | `{ parentTaskId }` | every child with status and output |
 | `complete-task` | `{ taskId, output }` | finish a task from inside a script |
@@ -69,6 +69,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 ### What `ctx` holds
 
 - `ctx.swarm.*`: the swarm SDK. `task_get`, `task_send`, `task_storeProgress`, `task_action`, `task_list`, `slack_reply`, `memory_search`, `memory_store`, `kv_get`, `kv_getOrNull`, `kv_set`, `kv_delete`, `kv_incr`, `kv_list`, `swarm_get`, `agent_info`, `db_query`, and more. `kv_getOrNull` returns the entry, `null` on a missing key, and throws on other errors.
+- `ctx.swarm.task_send` requires `routingReason` whenever `agentId` is present. Use `human_pinned` for an explicit/configured choice, `skill` for a role or specialization match, `continuity` for the same worker/session, `reroute_fault` for a fault handoff, or `overflow` for capacity/pool escalation. Omit both `agentId` and routing fields for the pool.
 - `ctx.swarm.config`: `apiKey`, `agentId`, `mcpBaseUrl`, and `ctx.swarm.config.get("KEY")` for user config values. All are `Redacted` wrappers that stringify to `<redacted>`. Never unwrap one into a return value, a log line, or a request body you build by hand.
 - `ctx.api.<slug>` and `ctx.mcp.<slug>`: typed clients for registered connections. They exist only for registered connections. Introspect with `Object.keys(ctx.api ?? {})` and `Object.keys(ctx.mcp ?? {})`.
 - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `Redacted`.
@@ -76,7 +77,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 
 ### Durable workflow scripts
 
-`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
+`launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, and no `ctx.swarm.config`. A configured `ctx.step.agentTask` `agentId` records `human_pinned` unless `routingReason` is supplied. Call a connection from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
 
 ## Inline script pattern