@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/utils/template.ts

@@ -19,9 +19,16 @@ export interface DeepInterpolateOptions {
   preserveRawTokens?: boolean;
 }
 
+const INTERPOLATION_TOKEN_RE = /\{\{([^}]+)\}\}/g;
+
+/** Return the normalized paths referenced by every {{path}} token in a string. */
+export function findInterpolationTokens(template: string): string[] {
+  return Array.from(template.matchAll(INTERPOLATION_TOKEN_RE), (match) => match[1]!.trim());
+}
+
 export function interpolate(template: string, ctx: Record<string, unknown>): InterpolateResult {
   const unresolved: string[] = [];
-  const result = template.replace(/\{\{([^}]+)\}\}/g, (_match, path: string) => {
+  const result = template.replace(INTERPOLATION_TOKEN_RE, (_match, path: string) => {
     const keys = path.trim().split(".");
     let value: unknown = ctx;
     for (const key of keys) {

package/src/utils/zod-openapi.ts

@@ -0,0 +1,11 @@
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import * as z from "zod";
+
+// Patches the zod prototype with `.openapi()` BEFORE any schema module that
+// names components evaluates. Files that call `.openapi("Name")` on their
+// schemas (src/types.ts and friends) must import z from HERE, not from "zod",
+// so the extension is guaranteed to have run — importing from "zod" directly
+// works only if some other module happened to load this one first.
+extendZodWithOpenApi(z);
+
+export { z };

package/src/workflows/engine.ts

@@ -499,10 +499,20 @@ async function executeStep(
   }
 
   // 4. Deep-interpolate config using local context (not global ctx)
-  const { value: interpolatedValue, unresolved } = interpolateNodeConfig(node, interpolationCtx);
+  const {
+    value: interpolatedValue,
+    unresolved,
+    scriptBodyUnresolved,
+  } = interpolateNodeConfig(node, interpolationCtx);
   const interpolatedConfig = interpolatedValue as Record<string, unknown>;
   const executionCtx: Record<string, unknown> = { ...ctx, ...interpolationCtx };
 
+  if (scriptBodyUnresolved && scriptBodyUnresolved.length > 0) {
+    const errorMsg = scriptBodyInterpolationError(node.id, scriptBodyUnresolved);
+    checkpointStepFailure(runId, stepId, errorMsg, 0);
+    return { outcome: "failed", successors: [] };
+  }
+
   if (unresolved.length > 0) {
     console.warn(
       `[workflow] Step ${node.id}: unresolved interpolation tokens: ${unresolved.join(", ")}`,
@@ -797,7 +807,7 @@ function buildScriptBodyCtx(
 export function interpolateNodeConfig(
   node: Pick<WorkflowNode, "type" | "config" | "inputs">,
   interpolationCtx: Record<string, unknown>,
-): { value: unknown; unresolved: string[] } {
+): { value: unknown; unresolved: string[]; scriptBodyUnresolved?: string[] } {
   if (node.type === "foreach" && Object.hasOwn(node.config, "over")) {
     const { over, body, ...configWithoutOverAndBody } = node.config;
     const configResult = deepInterpolate(configWithoutOverAndBody, interpolationCtx);
@@ -829,15 +839,19 @@ export function interpolateNodeConfig(
     // (`{{someNode.stdout}}`) are LLM- or script-generated text with the same
     // problem. Dynamic per-run values must flow through `args` instead, which
     // are passed as separate argv elements (data), not spliced into source text.
-    // Excluded tokens resolve to "" and are reported in `unresolved`.
+    // Preserve the original source when a body token cannot be resolved. The
+    // caller fails the node before execution and reports the token explicitly;
+    // returning partially blanked source here would recreate the silent-green
+    // failure this guard is intended to prevent.
     const scriptResult = deepInterpolate(script, buildScriptBodyCtx(node, interpolationCtx));
 
     return {
       value: {
         ...(restResult.value as Record<string, unknown>),
-        script: scriptResult.value,
+        script: scriptResult.unresolved.length > 0 ? script : scriptResult.value,
       },
       unresolved: [...restResult.unresolved, ...scriptResult.unresolved],
+      scriptBodyUnresolved: scriptResult.unresolved,
     };
   }
 
@@ -858,6 +872,15 @@ export function interpolateNodeConfig(
   };
 }
 
+export function scriptBodyInterpolationError(nodeId: string, tokens: string[]): string {
+  const renderedTokens = [...new Set(tokens)].map((token) => `{{${token}}}`).join(", ");
+  return (
+    `Script body interpolation failed for node "${nodeId}": unresolved or disallowed token(s): ${renderedTokens}. ` +
+    "Executable source may interpolate only input, workflow, swarm, or run values. " +
+    "Pass dynamic trigger or upstream values through config.args and read them from argv."
+  );
+}
+
 // ─── Helpers ───────────────────────────────────────────────
 
 function timeoutPromise(ms: number): Promise<never> {

package/src/workflows/executors/swarm-script.ts

@@ -12,6 +12,7 @@ import {
 } from "../../scripts-runtime/executors/types";
 import { runScript } from "../../scripts-runtime/loader";
 import type { ExecutorMeta } from "../../types";
+import { findInterpolationTokens } from "../../utils/template";
 import { BaseExecutor, type ExecutorResult } from "./base";
 
 export const SWARM_SCRIPT_DEFAULT_TIMEOUT_MS = DEFAULT_SCRIPT_RESOURCES.wallClockMs;
@@ -47,6 +48,19 @@ export const SwarmScriptOutputSchema = z.object({
 type SwarmScriptConfig = z.infer<typeof SwarmScriptConfigSchema>;
 type SwarmScriptOutput = z.infer<typeof SwarmScriptOutputSchema>;
 
+const WORKFLOW_INTERPOLATION_ROOTS = new Set(["trigger", "input", "workflow", "swarm", "run"]);
+
+function findWorkflowSourceTokens(
+  source: string,
+  inputCtx: Readonly<Record<string, unknown>> | undefined,
+): string[] {
+  const roots = new Set([...WORKFLOW_INTERPOLATION_ROOTS, ...Object.keys(inputCtx ?? {})]);
+  return findInterpolationTokens(source).filter((token) => {
+    const root = token.split(".")[0];
+    return root !== undefined && roots.has(root);
+  });
+}
+
 export class SwarmScriptExecutor extends BaseExecutor<
   typeof SwarmScriptConfigSchema,
   typeof SwarmScriptOutputSchema
@@ -76,6 +90,20 @@ export class SwarmScriptExecutor extends BaseExecutor<
       return { status: "failed", error: resolved.error };
     }
 
+    // Catalog source is never workflow-interpolated. Only reject tokens whose
+    // root is a source available to this node (builtins or declared aliases);
+    // other mustache syntax is literal script data.
+    const sourceTokens = findWorkflowSourceTokens(resolved.source, meta.inputCtx);
+    if (sourceTokens.length > 0) {
+      const renderedTokens = [...new Set(sourceTokens)].map((token) => `{{${token}}}`).join(", ");
+      return {
+        status: "failed",
+        error:
+          `swarm-script body interpolation failed for node "${meta.nodeId}": unresolved token(s): ${renderedTokens}. ` +
+          "Named script source is not workflow-interpolated; pass dynamic values through config.args and read them from args.",
+      };
+    }
+
     const credentials = await buildScriptCredentialBindingsWithFailures({
       agentId: agentId ?? undefined,
     });

package/src/workflows/retry-poller.ts

@@ -8,7 +8,12 @@ import {
 import type { RetryPolicy } from "../types";
 import { checkpointStep, checkpointStepFailure, checkpointStepWaiting } from "./checkpoint";
 import { getSuccessors } from "./definition";
-import { buildNodeInterpolationCtx, interpolateNodeConfig, walkGraph } from "./engine";
+import {
+  buildNodeInterpolationCtx,
+  interpolateNodeConfig,
+  scriptBodyInterpolationError,
+  walkGraph,
+} from "./engine";
 import type { AsyncExecutorResult } from "./executors/base";
 import type { ExecutorRegistry } from "./executors/registry";
 import { runStepValidation } from "./validation";
@@ -71,7 +76,19 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
           // foreach with `over: "{{items}}"` burns all its retries on schema
           // rejections without ever re-dispatching.
           const inputCtx = buildNodeInterpolationCtx(node, ctx);
-          const { value: interpolatedValue } = interpolateNodeConfig(node, inputCtx);
+          const { value: interpolatedValue, scriptBodyUnresolved } = interpolateNodeConfig(
+            node,
+            inputCtx,
+          );
+          if (scriptBodyUnresolved && scriptBodyUnresolved.length > 0) {
+            checkpointStepFailure(
+              run.id,
+              step.id,
+              scriptBodyInterpolationError(node.id, scriptBodyUnresolved),
+              step.retryCount,
+            );
+            continue;
+          }
           const interpolatedConfig = interpolatedValue as Record<string, unknown>;
 
           // Get executor and re-run

package/templates/skills/apps/content.md

@@ -21,6 +21,10 @@ For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch`
 
 `app-patch` can also change `name`; omit `description` to preserve it or pass `description: null` to clear it.
 
+### Reading an app's callable surface
+
+One `app-get` returns everything needed to drive an app you did not write: `definition.queries` are runnable with `app-query` (supply every `$param` the query references), and `definition.actions` are invocable with `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read a query's `$param` placeholders and an action's kind/args from the definition before calling — do not guess parameter names.
+
 ## Safe schema evolution and rollback
 
 Prefer **hiding** a column over deleting it. A hidden column's values stay on every existing row, so an unhide or rollback can make it visible again. Hiding is metadata-only: hidden columns cannot be used in queries, page bindings, `app.mutate` values, or new row writes, and `required` is ignored while hidden. Row GETs still expose the historical value for backward compatibility.
@@ -43,6 +47,10 @@ Schema-changing writes can carry this sibling `migration` object:
 
 Use `set` to backfill a changed column, `from` with optional `map`/`else` to derive it from one existing (including hidden) column, `coerce` for a kind change, and `purge` only for explicit destruction. Non-purge directives target a column changed in that same write. The server fails loudly before writing when a lossy change needs a directive: inspect every returned `issues[]` item, including its per-value row counts, then choose an explicit policy and retry. Never guess a migration just to get a 200.
 
+**Source lifecycle** rides the same engine with the same all-or-nothing guarantees. Free: adding a source, adding a NEW column with a `source` binding, binding an existing column that holds zero values, changing a binding's `field`/`transform`, and changing a source's `args`/`config`/`connection`/`scriptId` (window changes churn staleness on the next pass — expect `stale` flips when narrowing). Rejected with a path-bearing issue: changing `joinKey` (immutable — remove the source and add it again), changing `connector` while the source owns rows (row count in the message), and binding an existing column that already holds values (purge it — or add a fresh column — and bind that instead; a sync pass would otherwise overwrite the data). Removing a source **detaches** its rows: values survive as ordinary columns, the `source`/`syncedAt`/`stale` envelope is stripped, and the report counts them in `detachedRows`. A patch removing a source must drop its column bindings in the same call — a dangling `source.of` is rejected before anything is written.
+
+Sync never adopts rows it does not own: a pulled record whose join key matches an unowned row creates a second, source-owned row. Adding a source over a join-key column that already holds values therefore duplicates those records on the first pass — and remove-source → re-add duplicates for the same reason, because detached rows keep their values. To convert a hand-maintained model into a synced one, purge the old rows first or use a fresh join-key column.
+
 For example, split a legacy `flag` into `priority` and `status` without losing data in one patch: add the two columns, map both from `flag`, update every affected query/page binding, then hide `flag`.
 
 ```json
@@ -66,7 +74,7 @@ For example, split a legacy `flag` into `priority` and `status` without losing d
 }
 ```
 
-Every schema migration returns `{ scanned, backfilled, coerced, mapped, elsed, purgedValues, idxRebuilt, orphanFields }`. Read `orphanFields`: it reports extra row fields that predate or no longer appear in the definition; they are preserved until an explicit purge. `schemaVersion` is server-managed: never set it in an input patch or try to use it as application data.
+Every schema migration returns `{ scanned, backfilled, coerced, mapped, elsed, purgedValues, idxRebuilt, detachedRows, orphanFields }`. Read `orphanFields`: it reports extra row fields that predate or no longer appear in the definition; they are preserved until an explicit purge. `schemaVersion` is server-managed: never set it in an input patch or try to use it as application data.
 
 Every successful definition write snapshots the previous definition. Use `app-history` to select a version, `app-diff({ appId, from: <version> })` to inspect it against CURRENT, then `app-rollback({ appId, version: <version>, migration? })` to restore it. Rollback is a forward migration over live rows, not row-level time travel: it creates a new pre-rollback snapshot and may reject a lossy restore with the same migration directives and counts. A rejected rollback changes nothing.
 
@@ -171,7 +179,87 @@ Each column is `{ "kind": ..., "required"?: boolean, "default"?: ..., "index"?:
 | `date` | ISO-8601 string; never indexed. |
 | `enum` | String from the non-empty unique `enum` list; always indexed, without `index: true`. |
 
-`default` must match the column kind (and be one of the enum values). `required: true` rejects missing/null values unless a default supplies the value. `id`, `createdAt`, `updatedAt`, `createdBy`, and `updatedBy` are system columns and reserved names. Rows always expose `id`/`createdAt`/`updatedAt`; `createdBy`/`updatedBy` record the acting principal (`user:<id>`, `agent:<id>`, or `operator`) and are system-managed on every row write.
+`default` must match the column kind (and be one of the enum values). `required: true` rejects missing/null values unless a default supplies the value. `id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` — and the sync envelope `source`, `syncedAt`, `stale` — are system columns and reserved names. An app created before the sync envelope that declared ordinary columns with these names surfaces `definitionError` after upgrade until they are renamed: patch in a fresh column with a `{from}` migration directive, then purge the old one. Rows always expose `id`/`createdAt`/`updatedAt`; `createdBy`/`updatedBy` record the acting principal (`user:<id>`, `agent:<id>`, `operator`, or `sync:<source>` for engine writes) and are system-managed on every row write.
+
+### Sources and sync
+
+A model may declare up to 4 named `sources` — one-way inbound projections of an external system into its rows. The `script` connector is THE way to bring external data in (GitHub, Linear, any API): a saved script owns the fetch, its auth placeholders, and its paging. `swarm-tasks` is the one native connector, projecting this swarm's own task pool (`config`: `status`/`tags` comma-lists, `agentId`, `assetKey` namespace prefix, `limit` up to 200 — default 100, `includeHeartbeat`). Synced rows are readable by EVERY principal with `app.use` on the app; an unscoped `swarm-tasks` source publishes task prompts (truncated, secret-scrubbed) to all of them, so scope it with `config.assetKey`/`config.agentId` unless that exposure is intended. A user-invoked sync only ever pulls the invoking user's own requested tasks. Script sources run with their run-as identity's credentials — an agent-owned script runs as its owner and only the owner may wire it; an owner-less catalog (global) script runs as the LEAD, so only the lead or the operator can wire or alter such a source (stored references stay valid with their args and connection pinned).
+
+```json
+{
+  "models": {
+    "issue": {
+      "columns": {
+        "issueKey": { "kind": "string" },
+        "title": { "kind": "string", "source": { "of": "gh", "field": "title" } },
+        "openedAt": { "kind": "date", "source": { "of": "gh", "field": "created_at", "transform": "date-parse" } },
+        "note": { "kind": "string" }
+      },
+      "sources": {
+        "gh": { "connector": "script", "scriptId": "<script-uuid>", "joinKey": "issueKey", "args": { "repo": "owner/name" }, "connection": "github" }
+      }
+    }
+  }
+}
+```
+
+- **Join key**: each source names a `joinKey` — an owned, non-hidden `string` column carrying the external identity. It must not be `required`, must not declare a `default`, and cannot itself be source-bound. A row belongs to at most ONE source (`row.source`).
+- **Column bindings**: `{ "of": "<sourceName>", "field": "user.login", "transform"? }` projects a (dotted-path) field of the pulled record into the column on every pass. Transforms and their required column kinds: `slug`/`lower`/`upper` → `string`, `cents` → `number` (×100, rounded), `date-parse` → `date` (ISO). A failed transform nulls that one column and warns; it never fails the pass.
+- **Read-only contract**: source-bound columns and the join key reject every direct write (row create/patch/bulk) with a path-bearing issue — mutate them via the source or a sync refresh. Owned columns on the same model stay writable. Every `required` owned column on a sourced model must declare a `default`, because sync-created rows cannot supply it.
+- **Provenance**: synced rows carry `source` (owner), `syncedAt` (last confirmed presence — sortable), and `stale` (true when a complete pull no longer returned the record; clears on reappearance). `syncedAt` advances on every confirmed row WITHOUT touching `updatedAt`; `updatedAt` moves only when projected data actually changed.
+- **`connection`** (optional, script sources): names a connections-system slug the source depends on. It buys write-time validation plus a preflight before every pull; it does not by itself gate egress. Credentials resolve for the sync run-as identity — the script's owner when it has one, else the lead agent — so global connections always work and agent-scoped ones need matching script ownership. The slug is injected into the script's args as `connection`, letting one generic script serve N connections.
+
+**The canonical sync-script contract** (every sync script, always):
+
+```ts
+export default async function run(args, ctx) {
+  // args = { ...source.args, app: { id }, model: "<model>", source: "<sourceName>", connection?: "<slug>" }
+  const records = [{ key: "42", fields: { title: "…", created_at: "…" } }];
+  return { records, complete: true }; // or return the bare array — a bare array IS a complete snapshot
+}
+```
+
+Return `Array<{ key, fields }>` or `{ records, complete? }`. `key` is the external identity the engine joins on `joinKey` (numbers are coerced to strings); `fields` is the bag bindings project from. Return `complete: false` whenever the pull window may have missed records — a paged fetch, a hit `limit`, or client-side filtering of a full page. An incomplete pull skips the stale sweep, so rows outside a narrow window are not falsely marked stale; compute `complete` BEFORE any client-side filtering. Hard cap 500 records per pull (over-cap pulls truncate and count as incomplete). An invalid return shape, thrown error, or non-zero exit fails the pass with zero row churn.
+
+The seeded catalog script `github-issues-pull` is the worked example (placeholder auth via `[REDACTED:GITHUB_TOKEN]`, PR filtering, `complete` computed before filtering). For scheduled refreshes, point a `targetType: "script"` schedule at the seeded `app-sync-run` with `scriptArgs: { "appId": "<id>", "model"?, "source"? }`.
+
+**Three refresh doors, one engine**: `POST /api/apps/<id>/sync` (body `{ "model"?, "source"? }`), a `sync` action kind, and the `app-sync` MCP tool (`ctx.swarm.app_sync` from scripts). `{model?, source?}` fans out to every matching (model × source) pair; each pass reports `{ pulled, created, updated, refreshed, unchanged, markedStale, warnings }`. A pair already syncing in this API process short-circuits with `alreadyRunning: true` instead of pulling twice. Each pair's last-pass status (`lastFinishedAt`, counts, `error?`) comes back as `syncStatus` — keyed `"<model>:<source>"` — on `GET /api/apps/<id>` and in `app-get` data, so UI and agents can render "last synced / last error" without extra calls.
+
+### Freshness and the refresh button
+
+Freshness renders with the existing column kinds — no special components. Give the table `{ "key": "syncedAt", "kind": "date" }` and `{ "key": "stale", "kind": "badge", "tones": { "true": "warning" } }` columns, declare a `sync` action, and wire a Button to it:
+
+```json
+{
+  "actions": { "refresh": { "kind": "sync" } },
+  "pages": {
+    "main": {
+      "root": "root",
+      "elements": {
+        "root": { "type": "Container", "props": {}, "children": ["refreshBtn", "issuesTable"] },
+        "refreshBtn": {
+          "type": "Button",
+          "props": { "label": "Refresh" },
+          "on": { "press": [{ "action": "app.action", "params": { "name": "refresh" } }] }
+        },
+        "issuesTable": {
+          "type": "Table",
+          "props": {
+            "data": { "$state": "/queries/allIssues/data" },
+            "columns": [
+              { "key": "title", "label": "Issue" },
+              { "key": "syncedAt", "label": "Synced", "kind": "date" },
+              { "key": "stale", "label": "Stale", "kind": "badge", "tones": { "true": "warning" } }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+A `sync` action answers the script-action state shape (`/actions/refresh` → `running` → `ok`/`error`, result under `result.passes`), so the page's queries refetch when it completes. Use `app-query` to READ rows (named queries may filter on `stale`/`source` and sort by `syncedAt`); use `app-sync` to REFRESH sources; never poll a sync door in a loop — schedule it or give people the button.
 
 ### Queries
 
@@ -186,7 +274,7 @@ A named query is:
 }
 ```
 
-`filter` is a strict AND of equality checks. A filter may target a declared model column or a system column (`id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`) — filtering on `id` is the universal way to select one row for a detail view. A literal value must match the column's kind; date filters compare the stored raw ISO string, not parsed instants. Omit `limit` for the default 200 rows, or set an integer from 1 through 1000. `sort.column` is a model column, `createdAt`, or `updatedAt`; `dir` is `asc` or `desc`. Query runtime state is `{ data, loading, error }` under `/queries/<queryName>`.
+`filter` is a strict AND of equality checks. A filter may target a declared model column or a system column (`id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and on synced models `source`, `syncedAt`, `stale`) — filtering on `id` is the universal way to select one row for a detail view, and `{ "stale": true }` selects rows a complete pull stopped confirming. A literal value must match the column's kind; date filters compare the stored raw ISO string, not parsed instants. Omit `limit` for the default 200 rows, or set an integer from 1 through 1000. `sort.column` is a model column, `createdAt`, `updatedAt`, or `syncedAt`; `dir` is `asc` or `desc`. Query runtime state is `{ data, loading, error }` under `/queries/<queryName>`.
 
 A filter value may instead be exactly `{ "$param": "<name>" }`. At execution, the caller supplies that name and the server coerces its value to the filtered column's kind before equality matching:
 
@@ -223,7 +311,8 @@ Actions are optional (maximum 20) and are invoked from the page with the `app.ac
 | Kind | Contract |
 |---|---|
 | `script` | `scriptId` must identify an existing script; optional `args` are defaults. Invocation input overrides same-named defaults, and the runtime also supplies `app: { id }`. |
-| `task` | `prompt` must be non-empty; omit `agentId` to use default (lead) assignment. Only set `agentId` to a real agent UUID. Invocation `input` is included as context for the task prompt. |
+| `task` | `prompt` must be non-empty; omit `agentId` to use default (lead) assignment. Only set `agentId` to a real agent UUID. Invocation `input` is included as context for the task prompt. Spawned tasks carry asset key `shared/app:<appId>/action:<name>/`, so a `swarm-tasks` source with `config.assetKey: "shared/app:<appId>/"` pulls back the tasks this app spawned. |
+| `sync` | Optional `model` and `source` narrow which (model × source) pairs refresh; omitting both syncs every pair the app declares. At least one pair must exist. Answers the script-kind state shape with per-pass results under `result.passes`. |
 
 - Invocation state lands at `/actions/<name>` as `{ status, result?, error?, taskId?, taskStatus? }`, where `status` is `"running"`, `"ok"`, or `"error"`.
 
@@ -480,7 +569,7 @@ An action-chain step is `{ "action": "<type>", "params": {...} }`. Available act
 - arrays and scalar values replace;
 - `null` deletes a key;
 - reusable-element disambiguation: a patch value for `elements.<name>` containing ONLY the `elements` key merges node-by-node; any other key present (`mode`, `root`, `props`, or `export`) makes it a full element replace — restate every field you want kept. In that node-by-node form, `elements.<name>.elements.<id>: null` deletes one node. Literal null nodes are rejected in a full element replace so they cannot be mistaken for deletions.
-- otherwise every supplied `pages.<page>.elements.<id>`, `pages.<page>.params.<param>`, `actions.<name>`, and `models.<name>.columns.<col>` value is atomic and replaces that complete declaration; `null` deletes it.
+- otherwise every supplied `pages.<page>.elements.<id>`, `pages.<page>.params.<param>`, `actions.<name>`, `models.<name>.columns.<col>`, and `models.<name>.sources.<src>` value is atomic and replaces that complete declaration; `null` deletes it (deleting a source detaches its rows — see the source lifecycle above).
 
 `pages.<page>: null` deletes a page, except the current `defaultPage` cannot be deleted. `root`, `title`, and top-level `defaultPage` use ordinary merge semantics. A top-level `page` patch is rejected with guidance to patch `pages.<name>` instead.
 

package/templates/skills/asset-namespaces/content.md

@@ -1,6 +1,6 @@
 # Asset Namespaces
 
-Use an asset `key` as directory-like grouping metadata across tasks, workflows, schedules, pages, and mapped provider files. Keep identity separate: entity IDs remain authoritative, task `contextKey` remains routing context, and many assets may intentionally share one key.
+Use an asset `key` as directory-like grouping metadata across tasks, workflows, schedules, pages, apps, scripts, and mapped provider files. Keep identity separate: entity IDs remain authoritative, task `contextKey` remains routing context, and many assets may intentionally share one key.
 
 ## Choose a namespace
 
@@ -29,7 +29,7 @@ Use entity list tools with `key` for an exact namespace or `keyPrefix` for a sub
 ```js
 const result = await window.swarmSdk.assets.list({
   keyPrefix: "shared/releases/",
-  types: "task,workflow,schedule,page,file",
+  types: "task,workflow,schedule,page,app,script,file",
   limit: 100,
 });
 ```

package/templates/skills/scheduled-task-resilience/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: scheduled-task-resilience
+description: Guardrails for polling, scheduled jobs, and long-running external operations. Use whenever a task waits on CI, builds, deploys, browser jobs, or another asynchronous API so work survives heartbeat checks without duplicate delivery.
+---
+
+# Scheduled Task Resilience
+
+Use these rules whenever a scheduled or regular task polls or waits on a long-running operation. They prevent heartbeat collisions, lost work, duplicate delivery, and sessions that fail after holding an external job open too long.
+
+## Rule 1 — Never use `ScheduleWakeup` with `delaySeconds >= 300`
+
+The runtime heartbeat staleness threshold may sit near the same window as the model prompt-cache TTL. Sleeping for five minutes or longer can therefore look like a dead worker and cause the heartbeat sweep to fail the task mid-poll.
+
+Instead:
+
+- For waits under four minutes, run **one** bounded sleep of at most 240 seconds followed by a **single** status check, as one shell call, then return control to the agent turn.
+- **Never batch sleeps into a single shell invocation.** A loop of five 240-second sleeps blocks the session for twenty minutes with no opportunity to record progress — the same staleness failure `ScheduleWakeup` causes, just spelled differently.
+- Between cycles, record progress as described in Rule 3, then start the next cycle in the next turn.
+- For genuinely long waits such as CI builds, releases, or deploys, prefer a durable workflow or a follow-up task over `ScheduleWakeup`.
+
+Aggregate **every** check run before you decide the poll is over. Reading a single row such as `.[0].state` reports one check and can look terminal while another required check is still pending or failing.
+
+```bash
+# ONE cycle per agent turn. Resolve PR_NUMBER from the current task or repository context.
+sleep 240
+if out=$(gh pr checks "$PR_NUMBER" --json name,state,bucket \
+      --jq 'if   any(.[]; .bucket == "pending") then "PENDING"
+            elif any(.[]; .bucket == "fail" or .bucket == "cancel") then "FAILING"
+            else "PASSED" end' 2>&1); then
+  echo "$out"
+else
+  case "$out" in
+    *"no checks reported"*) echo "PENDING" ;;  # no check contexts yet — not a failure
+    *) echo "$out" >&2; exit 1 ;;              # real gh error: auth, network, bad PR
+  esac
+fi
+```
+
+⚠️ Do not substitute the exit code for the aggregate here. Plain `gh pr checks <pr>` exits `8` while any check is pending and `1` on failure, but **`--json` suppresses that — it exits `0` even mid-run** (verified on gh 2.97.0). A cycle that adds `--json` and then reads `$?` reports success on a still-pending PR, which is the exact bug the aggregate exists to prevent.
+
+⚠️ Treat `no checks reported` as `PENDING`, not as a failure. Right after a PR is opened or a new commit is pushed, GitHub can briefly report zero check contexts. In that window `gh pr checks` exits `1` and prints `no checks reported on the '<branch>' branch` **before** the `--json` exporter runs, so the aggregate never executes at all (verified on gh 2.97.0). A cycle that treats any non-zero exit as failure will stop polling — or report CI as broken — before the workflows have even appeared. That is why the sample branches on the error text instead of on the exit status alone.
+
+Handle each aggregate distinctly: `PASSED` means polling is done. For `PENDING`, call `store-progress`, then run one more cycle in the next turn; cap the number of cycles and hand off to a follow-up task once the total wait approaches the heartbeat staleness threshold. For `FAILING`, stop polling immediately, inspect the failed checks with `gh pr checks <pr> --json name,state,bucket` and the run logs, then report or fix the failure — never sleep again on a failing aggregate.
+
+## Rule 2 — Tag retry tasks with `reboot-retry`
+
+Any task automatically retried after a session loss must include `reboot-retry` in its tags. If you recreate a lost task manually, add the same tag so the deployment's boot-sweep logic can identify it correctly.
+
+Resolve the original task from the current task's parent or retry metadata. Do not copy a task ID from another incident or deployment.
+
+## Rule 3 — Long polls must store progress every two to three minutes
+
+Workers that poll silently can look stale to the heartbeat sweep.
+
+After every poll cycle — that is, after each shell call that sleeps and checks once — call `store-progress` with a concrete progress message such as `polling CI status (attempt 3/10)`. Even when the remote state has not changed, the progress update records that the worker is still active. This is only possible because each cycle returns control to the agent turn, which is why Rule 1 forbids batching sleeps.
+
+Resolve the active task ID from the current task context. Never embed an agent ID, task ID, organization ID, or other deployment-specific identifier in a reusable polling script.
+
+## Rule 4 — Diagnose repeated scheduled-task failures before retrying
+
+Two immediate failures with the same heartbeat-staleness reason usually indicate an infrastructure or lifecycle problem, not a transient job failure. Do not create a third identical attempt.
+
+- A worker should use the swarm's escalation channel or task handoff mechanism to report repeated heartbeat termination.
+- A lead should resolve the configured operator escalation destination from deployment or task metadata rather than hardcoding a Slack channel.
+- Include the affected task IDs in the incident report by reading them from the failed task records at runtime.
+
+## Rule 5 — Check for duplicate delivery before posting
+
+Concurrent sessions can pick up equivalent scheduled work. Before sending scheduled output to Slack, email, a blog, or another external destination:
+
+1. Query recent tasks using the current schedule ID or schedule tag.
+2. Search the destination history for an equivalent delivery in the relevant time window.
+3. If a recent completion already delivered the result, stop and record the duplicate detection with `store-progress`.
+
+Derive the schedule ID, destination, and time window from the current task and schedule records. Do not reuse identifiers or recipient addresses copied from another task.
+
+## Rule 6 — After the deliverable ships, complete and exit
+
+Do not call `ScheduleWakeup` merely to watch CI, a merge, or another downstream state after the requested deliverable already exists. A suspended post-shipping session can still be reaped and mark successful work as failed.
+
+Choose one path:
+
+1. **Workflow-driven task:** call `store-progress` with `status: "completed"` and the deliverable details, then exit. Let the workflow's next node handle downstream state.
+2. **Human-requested task needing later confirmation:** report the deliverable URL and current downstream status, complete the task, and let the lead or automation create a follow-up if the downstream check fails.
+3. **Rare in-process wait:** use the single-cycle sleep-then-check pattern from Rule 1, storing progress between cycles. Do not suspend the session with `ScheduleWakeup`, and do not batch sleeps into one shell call.
+
+The key distinction is whether work remains. `ScheduleWakeup` is only for a brief wait in the middle of active work; it is not a post-delivery monitoring mechanism.
+
+## Rule 7 — Use fire-then-follow-up for slow external jobs
+
+A worker session is not a durable job runner. Polling an external asynchronous API for tens of minutes can outlive the worker heartbeat even when the external job continues successfully.
+
+For browser automation, large data pulls, media processing, or any other external job expected to exceed roughly 20 minutes:
+
+1. Start the external actions.
+2. Store the returned action or task IDs, destination IDs, and a one-line resume recipe with `store-progress`.
+3. Persist the same recovery state in agent-fs, a durable workflow step, or another deployment-approved store.
+4. Complete the fire step and run collection, filtering, deduplication, and delivery in a fresh follow-up task.
+
+Resolve every identifier from the external API response and current task metadata. Never bake a prior run's IDs into the skill or follow-up template.
+
+When historical incident detail is useful, search the deployment's memory registry for heartbeat-reaper and long-running external-poll records instead of depending on copied task IDs or worker names.

package/templates/skills/scheduled-task-resilience/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "scheduled-task-resilience",
+  "displayName": "Scheduled Task Resilience",
+  "slug": "scheduled-task-resilience",
+  "title": "Scheduled Task Resilience",
+  "description": "Guardrails for polling, scheduled jobs, and long-running external operations. Use whenever a task waits on CI, builds, deploys, browser jobs, or another asynchronous API so work survives heartbeat checks without duplicate delivery.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["scheduling", "polling", "resilience"]
+}

package/templates/skills/scheduled-task-resilience/content.md

@@ -0,0 +1,97 @@
+# Scheduled Task Resilience
+
+Use these rules whenever a scheduled or regular task polls or waits on a long-running operation. They prevent heartbeat collisions, lost work, duplicate delivery, and sessions that fail after holding an external job open too long.
+
+## Rule 1 — Never use `ScheduleWakeup` with `delaySeconds >= 300`
+
+The runtime heartbeat staleness threshold may sit near the same window as the model prompt-cache TTL. Sleeping for five minutes or longer can therefore look like a dead worker and cause the heartbeat sweep to fail the task mid-poll.
+
+Instead:
+
+- For waits under four minutes, run **one** bounded sleep of at most 240 seconds followed by a **single** status check, as one shell call, then return control to the agent turn.
+- **Never batch sleeps into a single shell invocation.** A loop of five 240-second sleeps blocks the session for twenty minutes with no opportunity to record progress — the same staleness failure `ScheduleWakeup` causes, just spelled differently.
+- Between cycles, record progress as described in Rule 3, then start the next cycle in the next turn.
+- For genuinely long waits such as CI builds, releases, or deploys, prefer a durable workflow or a follow-up task over `ScheduleWakeup`.
+
+Aggregate **every** check run before you decide the poll is over. Reading a single row such as `.[0].state` reports one check and can look terminal while another required check is still pending or failing.
+
+```bash
+# ONE cycle per agent turn. Resolve PR_NUMBER from the current task or repository context.
+sleep 240
+if out=$(gh pr checks "$PR_NUMBER" --json name,state,bucket \
+      --jq 'if   any(.[]; .bucket == "pending") then "PENDING"
+            elif any(.[]; .bucket == "fail" or .bucket == "cancel") then "FAILING"
+            else "PASSED" end' 2>&1); then
+  echo "$out"
+else
+  case "$out" in
+    *"no checks reported"*) echo "PENDING" ;;  # no check contexts yet — not a failure
+    *) echo "$out" >&2; exit 1 ;;              # real gh error: auth, network, bad PR
+  esac
+fi
+```
+
+⚠️ Do not substitute the exit code for the aggregate here. Plain `gh pr checks <pr>` exits `8` while any check is pending and `1` on failure, but **`--json` suppresses that — it exits `0` even mid-run** (verified on gh 2.97.0). A cycle that adds `--json` and then reads `$?` reports success on a still-pending PR, which is the exact bug the aggregate exists to prevent.
+
+⚠️ Treat `no checks reported` as `PENDING`, not as a failure. Right after a PR is opened or a new commit is pushed, GitHub can briefly report zero check contexts. In that window `gh pr checks` exits `1` and prints `no checks reported on the '<branch>' branch` **before** the `--json` exporter runs, so the aggregate never executes at all (verified on gh 2.97.0). A cycle that treats any non-zero exit as failure will stop polling — or report CI as broken — before the workflows have even appeared. That is why the sample branches on the error text instead of on the exit status alone.
+
+Handle each aggregate distinctly: `PASSED` means polling is done. For `PENDING`, call `store-progress`, then run one more cycle in the next turn; cap the number of cycles and hand off to a follow-up task once the total wait approaches the heartbeat staleness threshold. For `FAILING`, stop polling immediately, inspect the failed checks with `gh pr checks <pr> --json name,state,bucket` and the run logs, then report or fix the failure — never sleep again on a failing aggregate.
+
+## Rule 2 — Tag retry tasks with `reboot-retry`
+
+Any task automatically retried after a session loss must include `reboot-retry` in its tags. If you recreate a lost task manually, add the same tag so the deployment's boot-sweep logic can identify it correctly.
+
+Resolve the original task from the current task's parent or retry metadata. Do not copy a task ID from another incident or deployment.
+
+## Rule 3 — Long polls must store progress every two to three minutes
+
+Workers that poll silently can look stale to the heartbeat sweep.
+
+After every poll cycle — that is, after each shell call that sleeps and checks once — call `store-progress` with a concrete progress message such as `polling CI status (attempt 3/10)`. Even when the remote state has not changed, the progress update records that the worker is still active. This is only possible because each cycle returns control to the agent turn, which is why Rule 1 forbids batching sleeps.
+
+Resolve the active task ID from the current task context. Never embed an agent ID, task ID, organization ID, or other deployment-specific identifier in a reusable polling script.
+
+## Rule 4 — Diagnose repeated scheduled-task failures before retrying
+
+Two immediate failures with the same heartbeat-staleness reason usually indicate an infrastructure or lifecycle problem, not a transient job failure. Do not create a third identical attempt.
+
+- A worker should use the swarm's escalation channel or task handoff mechanism to report repeated heartbeat termination.
+- A lead should resolve the configured operator escalation destination from deployment or task metadata rather than hardcoding a Slack channel.
+- Include the affected task IDs in the incident report by reading them from the failed task records at runtime.
+
+## Rule 5 — Check for duplicate delivery before posting
+
+Concurrent sessions can pick up equivalent scheduled work. Before sending scheduled output to Slack, email, a blog, or another external destination:
+
+1. Query recent tasks using the current schedule ID or schedule tag.
+2. Search the destination history for an equivalent delivery in the relevant time window.
+3. If a recent completion already delivered the result, stop and record the duplicate detection with `store-progress`.
+
+Derive the schedule ID, destination, and time window from the current task and schedule records. Do not reuse identifiers or recipient addresses copied from another task.
+
+## Rule 6 — After the deliverable ships, complete and exit
+
+Do not call `ScheduleWakeup` merely to watch CI, a merge, or another downstream state after the requested deliverable already exists. A suspended post-shipping session can still be reaped and mark successful work as failed.
+
+Choose one path:
+
+1. **Workflow-driven task:** call `store-progress` with `status: "completed"` and the deliverable details, then exit. Let the workflow's next node handle downstream state.
+2. **Human-requested task needing later confirmation:** report the deliverable URL and current downstream status, complete the task, and let the lead or automation create a follow-up if the downstream check fails.
+3. **Rare in-process wait:** use the single-cycle sleep-then-check pattern from Rule 1, storing progress between cycles. Do not suspend the session with `ScheduleWakeup`, and do not batch sleeps into one shell call.
+
+The key distinction is whether work remains. `ScheduleWakeup` is only for a brief wait in the middle of active work; it is not a post-delivery monitoring mechanism.
+
+## Rule 7 — Use fire-then-follow-up for slow external jobs
+
+A worker session is not a durable job runner. Polling an external asynchronous API for tens of minutes can outlive the worker heartbeat even when the external job continues successfully.
+
+For browser automation, large data pulls, media processing, or any other external job expected to exceed roughly 20 minutes:
+
+1. Start the external actions.
+2. Store the returned action or task IDs, destination IDs, and a one-line resume recipe with `store-progress`.
+3. Persist the same recovery state in agent-fs, a durable workflow step, or another deployment-approved store.
+4. Complete the fire step and run collection, filtering, deduplication, and delivery in a fresh follow-up task.
+
+Resolve every identifier from the external API response and current task metadata. Never bake a prior run's IDs into the skill or follow-up template.
+
+When historical incident detail is useful, search the deployment's memory registry for heartbeat-reaper and long-running external-poll records instead of depending on copied task IDs or worker names.