@desplega.ai/agent-swarm 1.169.0 → 1.171.0

package/src/types.ts

@@ -6,6 +6,7 @@ import { normalizeAssetKey } from "./assets/key";
 import { isSafeBundlePath } from "./extensions/bundle-path";
 import { MAX_PROFILE_FILE_LENGTH } from "./utils/constants";
 import { z } from "./utils/zod-openapi";
+
 // ─── Asset namespaces ──────────────────────────────────────────────────────
 
 export const AssetKeySchema = z
@@ -594,6 +595,7 @@ export const AgentTaskSchema = z
       "Origin of the routing reason: declared by the caller or chosen by the engine. Absent for unknown historical provenance or no reason.",
     ),
     routingNote: z.string().max(200).optional(),
+    poolWakeAt: z.string().optional(),
 
     // Task metadata
     taskType: z.string().max(50).optional(), // e.g., "bug", "feature", "chore"
@@ -1158,6 +1160,9 @@ export const AgentSchema = z
     name: z.string().min(1),
     isLead: z.boolean().default(false),
     status: AgentStatusSchema,
+    runtimePoolId: z.string().nullable().optional(),
+    runtimeProvisionAttempts: z.number().int().min(0).optional(),
+    runtimeProvisionRetryAt: z.string().nullable().optional(),
 
     // Profile fields
     description: z.string().optional(),
@@ -1321,7 +1326,7 @@ export type AcpSessionConfigOption = z.infer<typeof AcpSessionConfigOptionSchema
 
 export const AgentAcpStatusSchema = z
   .object({
-    target: z.enum(["opencode", "gemini", "copilot", "custom"]),
+    target: z.enum(["opencode", "gemini", "copilot", "qwen", "kiro", "goose", "custom"]),
     configOptions: z.array(AcpSessionConfigOptionSchema),
     reportedAt: z.number(),
   })
@@ -1959,12 +1964,120 @@ export type ActiveSession = z.infer<typeof ActiveSessionSchema>;
 // Runtime Instance Types (multi-runtime worker tracking)
 // ============================================================================
 
+export const WorkerNudgeSchema = z.object({
+  v: z.literal(1),
+  kind: z.enum(["work", "cancel", "steer", "config"]),
+  taskId: z.string().optional(),
+  at: z.iso.datetime(),
+});
+export type WorkerNudge = z.infer<typeof WorkerNudgeSchema>;
+
 /**
  * Lifecycle of a runtime instance. Zod is the source of truth for the allowed
  * values — the SQL column has no CHECK constraint (migration 132) so adding a
  * state doesn't require a table rebuild.
  */
-export const RuntimeInstanceStatusSchema = z.enum(["active", "offline"]);
+export const RuntimeInstanceStatusSchema = z.enum(["active", "offline", "provisioning"]);
+
+/**
+ * Infrastructure kind a runtime pool provisions on. `k8s` is reserved: write
+ * paths reject it until its adapter exists.
+ */
+export const RuntimeProviderKindSchema = z.enum(["static", "docker", "e2b", "k8s"]);
+export type RuntimeProviderKind = z.infer<typeof RuntimeProviderKindSchema>;
+
+export const DeliveryModeSchema = z.enum(["poll", "push"]);
+export type DeliveryMode = z.infer<typeof DeliveryModeSchema>;
+export const PoolLifecycleSchema = z.enum(["idle", "per-task"]);
+const RuntimeResourcesSchema = z
+  .object({
+    cpu: z.number().positive().optional(),
+    memoryMb: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export const RuntimeControllerCreateSchema = z
+  .object({
+    name: z.string().min(1).max(200),
+    kind: RuntimeProviderKindSchema,
+    placement: z.enum(["builtin", "remote"]).default("remote"),
+    config: z.record(z.string(), z.string()).default({}),
+    secretConfig: z.record(z.string(), z.string().nullable()).optional(),
+  })
+  .strict();
+export const RuntimeControllerUpdateSchema = RuntimeControllerCreateSchema.partial().extend({
+  placement: z.enum(["builtin", "remote"]).optional(),
+  config: z.record(z.string(), z.string()).optional(),
+});
+export const RuntimeControllerSchema = RuntimeControllerCreateSchema.omit({ secretConfig: true })
+  .extend({
+    id: z.string(),
+    secretConfigKeys: z.array(z.string()),
+    secretConfigError: z.boolean().optional(),
+    status: z.enum(["online", "offline", "unknown"]),
+    lastSeenAt: z.string().nullable(),
+    lastError: z.string().nullable(),
+    lastErrorAt: z.string().nullable(),
+    createdBy: z.string().nullable(),
+    updatedBy: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  })
+  .openapi("RuntimeController");
+export type RuntimeController = z.infer<typeof RuntimeControllerSchema>;
+
+export const RuntimePoolCreateSchema = z
+  .object({
+    name: z.string().min(1).max(200),
+    kind: RuntimeProviderKindSchema,
+    placements: z.array(z.string().min(1)).length(1),
+    image: z.string().min(1).nullable().optional(),
+    lifecycle: PoolLifecycleSchema.default("idle"),
+    idleMinutes: z.number().int().positive().nullable().default(null),
+    slotsPerRuntime: z.number().int().min(1).default(1),
+    maxRuntimes: z.number().int().min(0).nullable().default(null),
+    minRuntimes: z.number().int().min(0).default(0),
+    delivery: DeliveryModeSchema.nullable().default(null),
+    env: z.record(z.string(), z.string()).default({}),
+    resources: RuntimeResourcesSchema.nullable().default(null),
+    ttlSec: z.number().int().positive().nullable().default(null),
+    enabled: z.boolean().default(true),
+  })
+  .strict();
+export const RuntimePoolUpdateSchema = RuntimePoolCreateSchema.partial().extend({
+  lifecycle: PoolLifecycleSchema.optional(),
+  idleMinutes: z.number().int().positive().nullable().optional(),
+  slotsPerRuntime: z.number().int().min(1).optional(),
+  maxRuntimes: z.number().int().min(0).nullable().optional(),
+  minRuntimes: z.number().int().min(0).optional(),
+  delivery: DeliveryModeSchema.nullable().optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  resources: RuntimeResourcesSchema.nullable().optional(),
+  ttlSec: z.number().int().positive().nullable().optional(),
+  enabled: z.boolean().optional(),
+});
+export const RuntimePoolSchema = RuntimePoolCreateSchema.extend({
+  id: z.string(),
+  resolvedImage: z.string().nullable(),
+  consecutiveFailures: z.number().int(),
+  circuitOpenUntil: z.string().nullable(),
+  lastError: z.string().nullable(),
+  lastErrorAt: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  updatedBy: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).openapi("RuntimePool");
+export type RuntimePool = z.infer<typeof RuntimePoolSchema>;
+export const RuntimePoolCreateAgentSchema = z
+  .object({
+    name: z.string().min(1),
+    isLead: z.boolean().optional(),
+    harnessProvider: ProviderNameSchema.optional(),
+    maxTasks: z.number().int().min(1).max(100).optional(),
+    templateId: z.string().min(1).optional(),
+  })
+  .strict();
 
 /**
  * One worker process serving a logical agent. The `agents` row (AGENT_ID /
@@ -1979,6 +2092,16 @@ export const RuntimeInstanceSchema = z
     id: z.string(),
     agentId: z.string(),
     status: RuntimeInstanceStatusSchema,
+    poolId: z.string().nullable().optional(),
+    controllerId: z.string().nullable().optional(),
+    externalHandle: z.record(z.string(), z.unknown()).nullable().optional(),
+    provisionAttempts: z.number().int().optional(),
+    provisionError: z.string().nullable().optional(),
+    provisionRequestedAt: z.string().nullable().optional(),
+    draining: z.boolean().optional(),
+    idleSince: z.string().nullable().optional(),
+    leaseExpiresAt: z.string().nullable().optional(),
+    taskId: z.string().nullable().optional(),
     /** Runtime-local concurrent task capacity, self-reported at registration. */
     reportedSlots: z.number().int(),
     /** Process-local credential readiness; null when never reported. */
@@ -2710,8 +2833,20 @@ export const WorkflowRunSchema = z
     startedAt: z.string(),
     lastUpdatedAt: z.string(),
     finishedAt: z.string().optional(),
+    /** The `sub-workflow` step that started this run. Unset on a top-level run. */
+    parentStepId: z.string().optional(),
   })
   .openapi("WorkflowRun");
+
+/** The run and `sub-workflow` step that started a child run. */
+export const WorkflowRunParentSchema = z
+  .object({
+    runId: z.string(),
+    workflowId: z.string(),
+    stepId: z.string(),
+    nodeId: z.string(),
+  })
+  .openapi("WorkflowRunParent");
 export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
 
 /** List row of a run: no `context`, which `GET /api/workflow-runs/{id}` serves. */

package/src/utils/config-secrets.ts

@@ -0,0 +1 @@
+export const MASKED_SECRET_VALUE = "********";

package/src/utils/lead-monitor-channels.ts

@@ -0,0 +1,3 @@
+export function isLeadChannelMonitoringEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.LEAD_MONITOR_CHANNELS === "true";
+}

package/src/utils/org-website.ts

@@ -0,0 +1,104 @@
+/**
+ * The organization's website (`SWARM_ORG_WEBSITE`), shared by the API server
+ * and the dashboard. Pure: no DB, no network.
+ *
+ * Stored as a bare lowercase hostname. It feeds the telemetry `org_website`
+ * context field, the "used by" consent, and the org logo, which the telemetry
+ * proxy serves from logo.dev so the logo.dev key never leaves the proxy.
+ */
+
+const LABEL = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+const BLOCKED_SUFFIXES = [".local", ".internal", ".localhost", ".lan", ".home", ".test"];
+
+/** Default telemetry proxy origin. */
+export const TELEMETRY_PROXY_ORIGIN = "https://proxy.desplega.sh";
+
+/**
+ * Normalize what someone typed as their company website to a bare hostname:
+ * lowercase, no scheme, `www.`, path, port, query or trailing dot. Null when it
+ * is not a public hostname: an IP literal, `localhost`, a single label, a
+ * `.local` / `.internal` style name, or anything over 253 characters.
+ */
+export function normalizeOrgWebsite(raw: string | null | undefined): string | null {
+  let value = raw?.trim().toLowerCase();
+  if (!value) return null;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//.test(value)) value = `https://${value}`;
+  let host: string;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.username || url.password) return null;
+    host = url.hostname;
+  } catch {
+    return null;
+  }
+  host = host.replace(/\.$/, "");
+  if (host.startsWith("www.")) host = host.slice(4);
+  if (!host || host.length > 253) return null;
+  if (host.startsWith("[") || IPV4.test(host)) return null;
+  const labels = host.split(".");
+  if (labels.length < 2) return null;
+  if (!labels.every((label) => label.length <= 63 && LABEL.test(label))) return null;
+  if (/^\d+$/.test(labels.at(-1) ?? "")) return null;
+  if (BLOCKED_SUFFIXES.some((suffix) => host.endsWith(suffix))) return null;
+  return host;
+}
+
+/** The proxy URL that serves the logo for `host`. */
+export function orgLogoUrl(host: string, origin = TELEMETRY_PROXY_ORIGIN): string {
+  return `${origin.replace(/\/+$/, "")}/v1/logo?domain=${encodeURIComponent(host)}`;
+}
+
+/**
+ * Whether `url` has the shape of a logo URL `orgLogoUrl` builds for `origin`:
+ * the proxy origin itself, never just a matching path on another host.
+ */
+export function isFilledOrgLogoUrl(
+  url: string | null | undefined,
+  origin = TELEMETRY_PROXY_ORIGIN,
+): boolean {
+  if (!url) return false;
+  try {
+    const parsed = new URL(url);
+    return (
+      parsed.origin === new URL(origin).origin &&
+      parsed.pathname === "/v1/logo" &&
+      parsed.searchParams.has("domain")
+    );
+  } catch {
+    return false;
+  }
+}
+
+const FREE_MAIL_DOMAINS = new Set([
+  "gmail.com",
+  "googlemail.com",
+  "outlook.com",
+  "hotmail.com",
+  "live.com",
+  "msn.com",
+  "yahoo.com",
+  "icloud.com",
+  "me.com",
+  "mac.com",
+  "aol.com",
+  "proton.me",
+  "protonmail.com",
+  "gmx.com",
+  "gmx.de",
+  "yandex.com",
+  "yandex.ru",
+  "mail.com",
+  "zoho.com",
+  "qq.com",
+  "163.com",
+  "hey.com",
+  "fastmail.com",
+]);
+
+/** The admin's email domain as a website suggestion, or null for free-mail domains. */
+export function websiteSuggestion(orgDomain: string | null | undefined): string | null {
+  const host = normalizeOrgWebsite(orgDomain);
+  return host && !FREE_MAIL_DOMAINS.has(host) ? host : null;
+}

package/src/utils/request-auth-context.ts

@@ -7,8 +7,16 @@ export type HttpRequestAuth = (
   | { kind: "user"; userId: string; user: User }
   /** Password-page viewer with no user identity. Least privilege: every gate denies it. */
   | { kind: "guest" }
-  /** Ephemeral session token minted by the ACP adapter per session (aseph_ prefix). */
-  | { kind: "agent"; agentId: string; taskId: string }
+  | { kind: "controller"; controllerId: string; tokenId: string; expiresAt: string }
+  /** Ephemeral token bound to an ACP task or a worker runtime (aseph_ prefix). */
+  | {
+      kind: "agent";
+      agentId: string;
+      taskId: string | null;
+      runtimeId: string | null;
+      tokenId: string;
+      expiresAt: string;
+    }
 ) & {
   /** Verified page context for agent-scoped operations. This does not identify the viewer. */
   page?: { id: string; executionAgentId: string };

package/src/utils/runtime-pools-flag.ts

@@ -0,0 +1,11 @@
+import { isEnvFlagEnabled } from "./env-flag";
+
+/**
+ * `RUNTIME_POOLS_ENABLED` (default off) gates the whole push-workers feature:
+ * the runtime supervisor, pool routing, worker nudges, the pool/controller
+ * routes and tools, and the dashboard pages. Read it per call so a
+ * `swarm_config` reload takes effect.
+ */
+export function isRuntimePoolsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isEnvFlagEnabled("RUNTIME_POOLS_ENABLED", false, env);
+}

package/src/utils/secret-scrubber.ts

@@ -1031,6 +1031,15 @@ export function registerVolatileSecret(value: string, name: string): void {
   }
 }
 
+/** Remove a short-lived secret and its encoded forms after credential revocation. */
+export function unregisterVolatileSecret(name: string): void {
+  for (const [value, registeredName] of volatileSecrets) {
+    if (registeredName !== name) continue;
+    volatileSecrets.delete(value);
+    volatileGeneration++;
+  }
+}
+
 /**
  * Mark a key name as sensitive at runtime (a swarm_config row with
  * isSecret=1 whose name matches no suffix rule). Its process.env value joins

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

@@ -0,0 +1,20 @@
+const connections = new Map<string, Set<() => void>>();
+
+export function registerSessionTokenConnection(tokenId: string, close: () => void): () => void {
+  let callbacks = connections.get(tokenId);
+  if (!callbacks) {
+    callbacks = new Set();
+    connections.set(tokenId, callbacks);
+  }
+  callbacks.add(close);
+  return () => {
+    callbacks.delete(close);
+    if (callbacks.size === 0) connections.delete(tokenId);
+  };
+}
+
+export function closeSessionTokenConnections(tokenIds: string[]): void {
+  for (const tokenId of tokenIds) {
+    for (const close of connections.get(tokenId) ?? []) close();
+  }
+}

package/templates/skills/apps/content.md

@@ -86,7 +86,7 @@ Use `{ "$state": "/user/<field>" }` on a page for the read-only current-user bin
 
 ### Theming
 
-An optional top-level `"theme"` sets the preset the dashboard applies to the app's rendered canvas — a lowercase slug validated by shape only. The preset catalog ships with the dashboard (`apps/ui/src/lib/themes.ts` + `theme-classics.ts` — update this list and the `app-upsert` tool description when it changes); current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette — hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `"hive"` is an explicit reset to the stock look even inside a themed dashboard.
+An optional top-level `"theme"` sets the preset the dashboard applies to the app's rendered canvas — a lowercase slug validated by shape only. The preset catalog ships with the dashboard (`apps/ui/src/lib/themes.ts` + `theme-classics.ts` — update this list and the `app-upsert` tool description when it changes); current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette — hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `"hive"` is an explicit reset to the stock look even inside a themed dashboard.
 
 Viewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.
 

package/templates/skills/code-quality/content.md

@@ -71,7 +71,15 @@ The Repository Guidelines carry `allowMerge` and `mergeChecks`.
    A regression test must fail on the pre-fix code for the intended reason and pass after the repair. A regression test that never demonstrably failed does not prove the fix.
 6. Apply the "Review Guidance" entries from the Repository Guidelines.
 7. Read the diff for security (injection, secrets in code), logic (null handling, off-by-one, edge cases), performance (N+1, leaks), and code shape (naming, duplication, error handling). Run the test suite and the type check locally when you can.
-8. Post the review with the verdict first. One finding per comment, with file and line, and what to change.
+8. Post the review with the verdict first. One finding per comment, with file and line, and what to change. When a finding is a pattern (a missing guard, a call shape, a test-only export), grep the whole PR diff for the same pattern and list every instance in that finding, so one fix round clears the class.
+
+9. Self-authored PR. GitHub refuses APPROVE and REQUEST_CHANGES when the reviewing account authored the PR. Compare `gh pr view <n> --json author --jq .author.login` with `gh api user --jq .login` before you submit. Same login: post one COMMENT whose first line is the verdict (`APPROVE` or `REQUEST_CHANGES`), then one line saying a formal review is blocked because this account authored the PR.
+10. Optimistic UI mutations (toggles, favorites, pins). Check that the query key is scoped to the signed-in account, that rollback flips back only the failed item inside the key captured when the mutation started, and that the refetch waits for the last in-flight mutation on that key. Ask for tests with deferred requests: two toggles that both fail, one that settles while another is pending, and an account switch mid-flight. Run them against the old head too: they must fail there.
+11. A resolved thread is not a fixed finding. Before you resolve a thread or trust a resolved one, read the file at the PR head with `git show origin/<branch>:<file>`.
+12. A bot acknowledgment carries no change request. Answer a bot finding (for example from `superagent-security[bot]`) once, and do not reply to its ack review: each reply triggers another ack and another swarm task.
+13. Human verdicts live in the reviews endpoint. `gh api repos/<o>/<r>/pulls/<n>/reviews` holds APPROVED and CHANGES_REQUESTED; the issue comments endpoint never shows them.
+14. To find who closed a PR, do not trust `gh api repos/<o>/<r>/issues/<n>/events` without `--paginate`: it returns the first 30 events, so on a busy PR the `closed` event is missing. Use GraphQL `timelineItems(itemTypes:[CLOSED_EVENT])`.
+15. Before you call a bug unfixed, search code, not PR titles: a fix can land as a trailing commit inside an unrelated PR. Use `git log origin/main -S'<symbol>'` and the open PRs' diffs.
 
 ## GitHub review-reply provenance
 

package/templates/skills/db-query-guidance/content.md

@@ -38,6 +38,15 @@ For these four tables:
 If you need a row total or a column type census, ask the lead. Do not derive
 it yourself by scanning the table.
 
+## Columns audits guess wrong
+
+Run `SELECT name FROM pragma_table_info('<table>')` before you guess a column.
+
+- `agent_tasks`: no cost column and no `metadata` column. Cost is `session_costs.totalCostUsd`, joined on `taskId`. Assignee `agentId`, creator `creatorAgentId`, model `model`, `resolvedModel`, `modelSource`. `parentTaskId` is the only SQL child finder, because `key` is unique per task.
+- `scripts`: the owner is `createdByAgentId`; there is no `agentId`. `isScratch = 1` marks inline `script-run` bodies (`scratch-*` names), and they outnumber named scripts many times over. Add `isScratch = 0` to catalog audits. To find a script's callers, group by `isScratch` instead of dropping scratch rows: inline runs are often the negative tests.
+- `script_runs`: `scriptName`, `agentId`, `status`, `startedAt`, `finishedAt`, `error`. There is no duration column: use `(julianday(finishedAt) - julianday(startedAt)) * 86400`.
+- `session_costs`: `taskId`, `agentId`, `totalCostUsd`, `model`, the token columns, `createdAt`.
+
 ## Operator config knobs
 
 All are read dynamically (a `swarm_config` edit or env var change takes

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

@@ -69,7 +69,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 - `agentId` is propagated through the `X-Agent-ID` header, so SDK calls run as you. `taskId` is not ambient: pass it in `args` when the script calls `task_storeProgress`.
 - A script invoked from a workflow node may run under a workflow identity.
 - Return compact structured data. Raw logs, full HTML, big JSON arrays, and file contents stay inside the script.
-- Limits: about 30 s wall clock (up to 5 minutes where the tool exposes it), 1 MB stdout. Never sleep or loop past about 25 s. Chain `wait-for-task` calls instead.
+- Limits: about 30 s wall clock (up to 5 minutes where the tool exposes it), 1 MB stdout. Never sleep or loop past about 25 s. Chain `wait-for-task` calls instead. The cap also applies to a script called through `ctx.step.swarmScript`; the step's `timeoutMs` does not extend it. A long LLM call, such as a 2,000-word draft, goes in a `ctx.step.rawLlm` step inside `launch-script-run`, never in a called script.
 
 ### What `ctx` holds
 

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

@@ -64,7 +64,7 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
 - `agentId` is propagated through the `X-Agent-ID` header, so SDK calls run as you. `taskId` is not ambient: pass it in `args` when the script calls `task_storeProgress`.
 - A script invoked from a workflow node may run under a workflow identity.
 - Return compact structured data. Raw logs, full HTML, big JSON arrays, and file contents stay inside the script.
-- Limits: about 30 s wall clock (up to 5 minutes where the tool exposes it), 1 MB stdout. Never sleep or loop past about 25 s. Chain `wait-for-task` calls instead.
+- Limits: about 30 s wall clock (up to 5 minutes where the tool exposes it), 1 MB stdout. Never sleep or loop past about 25 s. Chain `wait-for-task` calls instead. The cap also applies to a script called through `ctx.step.swarmScript`; the step's `timeoutMs` does not extend it. A long LLM call, such as a 2,000-word draft, goes in a `ctx.step.rawLlm` step inside `launch-script-run`, never in a called script.
 
 ### What `ctx` holds
 

package/templates/skills/work-on-task/SKILL.md

@@ -13,7 +13,7 @@ When the task names a skill (`researching`, `planning`, `implementing`), use it.
 
 Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
 
-Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push.
+Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief's agent-fs output path and the task attachments. Run `agent-fs ls` on that path, download any partial and extend it; never re-run collection steps that already produced artifacts. If your task's `model` differs from the parent's, say so in the output, because the result's provenance changed.
 
 Write times in replies, outputs and defer notes in the requester's timezone when the Requester Profile names one, never raw UTC.
 

package/templates/skills/work-on-task/content.md

@@ -8,7 +8,7 @@ When the task names a skill (`researching`, `planning`, `implementing`), use it.
 
 Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
 
-Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push.
+Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief's agent-fs output path and the task attachments. Run `agent-fs ls` on that path, download any partial and extend it; never re-run collection steps that already produced artifacts. If your task's `model` differs from the parent's, say so in the output, because the result's provenance changed.
 
 Write times in replies, outputs and defer notes in the requester's timezone when the Requester Profile names one, never raw UTC.
 

package/dist/{cli-qd97v6z2.js → cli-1qtgd1h1.js}

@@ -12,6 +12,9 @@ import {
 import {
   sanitizeSurrogates
 } from "./cli-y2apkfe2.js";
+import {
+  parseStreamingJson
+} from "./cli-1m2e086m.js";
 import {
   calculateCost,
   getSystemMessageText,
@@ -19,9 +22,6 @@ import {
   resolveTranscript,
   resolveTranscriptTools
 } from "./cli-g7k7zbcz.js";
-import {
-  parseStreamingJson
-} from "./cli-1m2e086m.js";
 
 // node_modules/@earendil-works/pi-ai/dist/api/openai-responses-shared.js
 function encodeTextSignatureV1(id, phase) {

package/dist/{cli-cmxkbzzs.js → cli-j0w59p15.js}

@@ -39,6 +39,12 @@ import {
 import {
   providerHeadersToRecord
 } from "./cli-7kyk9jr3.js";
+import {
+  getProviderEnvValue
+} from "./cli-btbzvq95.js";
+import {
+  parseStreamingJson
+} from "./cli-1m2e086m.js";
 import {
   calculateCost,
   collapseSystemMessages,
@@ -47,12 +53,6 @@ import {
   getSystemMessageText,
   withoutInitialSystemMessage
 } from "./cli-g7k7zbcz.js";
-import {
-  getProviderEnvValue
-} from "./cli-btbzvq95.js";
-import {
-  parseStreamingJson
-} from "./cli-1m2e086m.js";
 import {
   AssistantMessageEventStream,
   appendAssistantMessageDiagnostic

package/dist/{google-generative-ai-b8zxrpax.js → google-generative-ai-pvhm0dq1.js}

@@ -14,10 +14,10 @@ import {
   toGoogleThinkingLevel,
   usesGoogleThinkingLevel
 } from "./cli-95zs84qw.js";
+import"./cli-zy39d433.js";
 import {
   getPiUserAgent
 } from "./cli-et1bbwqf.js";
-import"./cli-zy39d433.js";
 import"./cli-yatxqynm.js";
 import {
   formatProviderError,

package/dist/{google-vertex-nrdd697t.js → google-vertex-tek9sqe2.js}

@@ -15,10 +15,10 @@ import {
   toGoogleThinkingLevel,
   usesGoogleThinkingLevel
 } from "./cli-95zs84qw.js";
+import"./cli-zy39d433.js";
 import {
   getPiUserAgent
 } from "./cli-et1bbwqf.js";
-import"./cli-zy39d433.js";
 import"./cli-yatxqynm.js";
 import {
   formatProviderError,
@@ -33,6 +33,9 @@ import {
 import {
   providerHeadersToRecord
 } from "./cli-7kyk9jr3.js";
+import {
+  getProviderEnvValue
+} from "./cli-btbzvq95.js";
 import {
   calculateCost,
   clampThinkingLevel,
@@ -41,9 +44,6 @@ import {
   getInitialSystemMessage,
   getSystemMessageText
 } from "./cli-g7k7zbcz.js";
-import {
-  getProviderEnvValue
-} from "./cli-btbzvq95.js";
 import {
   AssistantMessageEventStream
 } from "./cli-wnb9b2g3.js";

package/dist/{mistral-conversations-059y51zt.js → mistral-conversations-rjxa9s1j.js}

@@ -16,6 +16,9 @@ import {
 import {
   headersToRecord
 } from "./cli-7kyk9jr3.js";
+import {
+  parseStreamingJson
+} from "./cli-1m2e086m.js";
 import {
   calculateCost,
   clampThinkingLevel,
@@ -24,9 +27,6 @@ import {
   renderSystemMessageUpdate,
   resolveTranscript
 } from "./cli-g7k7zbcz.js";
-import {
-  parseStreamingJson
-} from "./cli-1m2e086m.js";
 import {
   AssistantMessageEventStream
 } from "./cli-wnb9b2g3.js";

package/dist/{openai-completions-663yncfq.js → openai-completions-44gb0zsk.js}

@@ -5,18 +5,18 @@ import {
 import {
   clampOpenAIPromptCacheKey
 } from "./cli-mrptpp86.js";
-import {
-  shortHash
-} from "./cli-5m9j2spm.js";
 import {
   OpenAI
 } from "./cli-7cxw8b60.js";
-import {
-  getPiUserAgent
-} from "./cli-et1bbwqf.js";
 import {
   retryProviderRequest
 } from "./cli-zy39d433.js";
+import {
+  shortHash
+} from "./cli-5m9j2spm.js";
+import {
+  getPiUserAgent
+} from "./cli-et1bbwqf.js";
 import {
   formatProviderError,
   normalizeProviderError
@@ -40,6 +40,12 @@ import {
 import {
   headersToRecord
 } from "./cli-7kyk9jr3.js";
+import {
+  getProviderEnvValue
+} from "./cli-btbzvq95.js";
+import {
+  parseStreamingJson
+} from "./cli-1m2e086m.js";
 import {
   calculateCost,
   clampThinkingLevel,
@@ -49,12 +55,6 @@ import {
   resolveTranscript,
   resolveTranscriptTools
 } from "./cli-g7k7zbcz.js";
-import {
-  getProviderEnvValue
-} from "./cli-btbzvq95.js";
-import {
-  parseStreamingJson
-} from "./cli-1m2e086m.js";
 import {
   AssistantMessageEventStream
 } from "./cli-wnb9b2g3.js";