@desplega.ai/agent-swarm 2.6.0 → 2.7.0

package/src/heartbeat/script-runner-probe.ts

@@ -0,0 +1,47 @@
+import { runScriptWithRunCredential } from "../be/scripts/run-credential";
+import { scrubSecrets } from "../utils/secret-scrubber";
+
+const PROBE_TIMEOUT_MS = 10_000;
+
+/** Exercise the same executor and per-run credential as the gate, with a deadline even if the runner stalls. */
+export async function probeScriptRunner(
+  agentId: string,
+  runner: typeof runScriptWithRunCredential = runScriptWithRunCredential,
+): Promise<{ quiet: false; reason: string } | null> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new Error("timeout after 10000ms"));
+      }, PROBE_TIMEOUT_MS);
+    });
+    const output = await Promise.race([
+      runner({
+        source: "export default async function () { return true; }",
+        agentId,
+        fsMode: "none",
+        timeoutMs: PROBE_TIMEOUT_MS,
+        signal: controller.signal,
+      }),
+      deadline,
+    ]);
+    if (output.exitCode !== 0 || output.error || output.runtimeError) {
+      throw new Error(
+        output.runtimeError?.message ??
+          output.error ??
+          `script exited with code ${output.exitCode}`,
+      );
+    }
+    return null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      quiet: false,
+      reason: `script-runner-unhealthy: ${scrubSecrets(message)}`.slice(0, 300),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/http/api-keys.ts

@@ -243,14 +243,28 @@ const getAvailable = route({
   pattern: ["api", "keys", "available"],
   summary: "Get available (non-rate-limited) key indices for a credential type",
   tags: ["API Keys"],
-  query: z.object({
-    keyType: z.string(),
-    totalKeys: z.coerce.number().int().min(1),
-    scope: z.string().optional(),
-    scopeId: z.string().optional(),
-    /** Model family the caller is about to run. Filters out keys with an active weekly window block for that family. */
-    model: z.enum(["fable", "opus", "sonnet", "haiku"]).optional(),
-  }),
+  query: z
+    .object({
+      keyType: z.string(),
+      totalKeys: z.coerce.number().int().min(1),
+      scope: z.string().optional(),
+      scopeId: z.string().optional(),
+      /** Model family the caller is about to run. Filters out keys with an active weekly window block for that family. */
+      model: z.enum(["fable", "opus", "sonnet", "haiku"]).optional(),
+      /**
+       * Comma-separated key suffixes of the caller's pool, in pool order. When set,
+       * key status is matched by suffix across all scopes (not by stored index or
+       * `scope`), and returned indices are positions in this list.
+       */
+      keySuffixes: z
+        .string()
+        .transform((value) => value.split(","))
+        .optional(),
+    })
+    .refine((query) => !query.keySuffixes || query.keySuffixes.length === query.totalKeys, {
+      message: "keySuffixes must list exactly totalKeys suffixes",
+      path: ["keySuffixes"],
+    }),
   responses: {
     200: {
       description: "List of available key indices",
@@ -690,7 +704,7 @@ export async function handleApiKeys(
     const parsed = await getAvailable.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
-    const { keyType, totalKeys, scope, scopeId, model } = parsed.query;
+    const { keyType, totalKeys, scope, scopeId, model, keySuffixes } = parsed.query;
     try {
       const result = await getAvailableKeyIndices(
         keyType,
@@ -698,6 +712,7 @@ export async function handleApiKeys(
         scope,
         scopeId ?? null,
         model,
+        keySuffixes,
       );
       getAvailable.respond(res, 200, {
         success: true,

package/src/http/idempotency-key.ts

@@ -8,7 +8,7 @@ import { getRequestAuth } from "../utils/request-auth-context";
 import { jsonError } from "./utils";
 
 /** Visible ASCII, at most 255 characters: room for a UUID, a ULID or a client's own scheme. */
-const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{1,255}$/;
+export const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{1,255}$/;
 
 /** Set on a response answered from an earlier accepted request. */
 export const IDEMPOTENT_REPLAYED_HEADER = "Idempotent-Replayed";

package/src/http/index.ts

@@ -517,7 +517,7 @@ async function shutdown() {
   await stopChatSdk();
 
   // Stop OAuth keepalive
-  if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
+  if (!isEnvFlagEnabled("OAUTH_KEEPALIVE_DISABLE", false)) {
     const { stopOAuthKeepalive } = await import("../oauth/keepalive");
     await stopOAuthKeepalive();
   }
@@ -847,7 +847,7 @@ httpServer
     startRuntimeSupervisor();
 
     // Start OAuth token keepalive (proactive refresh to prevent expiry)
-    if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
+    if (!isEnvFlagEnabled("OAUTH_KEEPALIVE_DISABLE", false)) {
       const { startOAuthKeepalive } = await import("../oauth/keepalive");
       startOAuthKeepalive();
     }
@@ -855,7 +855,7 @@ httpServer
     // Start generic OAuth token refresh sweep (all oauth_apps providers,
     // 15-min tick, first run ~1 min after boot). Complements the tracker-only
     // keepalive above — see src/be/oauth-refresh-sweep.ts.
-    if (process.env.OAUTH_REFRESH_SWEEP_DISABLE !== "true") {
+    if (!isEnvFlagEnabled("OAUTH_REFRESH_SWEEP_DISABLE", false)) {
       const { startOAuthRefreshSweep } = await import("../be/oauth-refresh-sweep");
       startOAuthRefreshSweep();
     }

package/src/http/pages-public.ts

@@ -308,13 +308,45 @@ function getAppBaseUrl(): string {
   return getAppUrl(LOCAL_PAGE_APP_URL);
 }
 
+// CSP host-source without a path: optional http(s) scheme, a host that may
+// start with a `*.` wildcard label, and an optional port (digits or `*`).
+// Bare `*`, keywords (`'none'`, `'self'`) and anything carrying `;` or a path
+// are rejected so a bad env value cannot widen or break the policy.
+const FRAME_ANCESTOR_SOURCE_RE =
+  /^(?:https?:\/\/)?(?:\*\.)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::(?:\d{1,5}|\*))?$/i;
+
+let cachedFrameAncestors: { raw: string; origins: string[] } | null = null;
+
+/**
+ * Parse `PAGES_FRAME_ANCESTORS`: extra origins allowed to iframe PUBLIC pages
+ * (for example a marketing site embedding a chart). Comma or space separated.
+ * Invalid entries are dropped with one warning per distinct env value; the
+ * parse is cached on the raw string so a config reload picks up changes
+ * without re-warning on every request.
+ */
+export function getPageFrameAncestors(): string[] {
+  const raw = process.env.PAGES_FRAME_ANCESTORS ?? "";
+  if (cachedFrameAncestors?.raw === raw) return cachedFrameAncestors.origins;
+  const origins: string[] = [];
+  for (const entry of raw.split(/[\s,]+/)) {
+    const value = entry.replace(/\/+$/, "");
+    if (!value) continue;
+    if (FRAME_ANCESTOR_SOURCE_RE.test(value)) origins.push(value);
+    else console.warn(`[pages] ignoring invalid PAGES_FRAME_ANCESTORS entry: ${entry}`);
+  }
+  cachedFrameAncestors = { raw, origins };
+  return origins;
+}
+
 /**
  * Build the `Content-Security-Policy` for the served HTML. Allows inline
  * scripts (required for `BROWSER_SDK_JS`) but locks down everything else to
  * `'self'`. The SPA iframes the page in step-6 with `sandbox="allow-scripts
- * allow-forms"`; the CSP is a defence-in-depth layer.
+ * allow-forms"`; the CSP is a defence-in-depth layer. `PAGES_FRAME_ANCESTORS`
+ * applies only to public pages: authed and password pages stay embeddable by
+ * the app origins alone.
  */
-function buildCsp(): string {
+function buildCsp(page: Page): string {
   // `frame-ancestors` lists every origin allowed to iframe `/p/:id`. We must
   // include the SPA origin(s). Configured app URLs may be comma-separated so
   // portless dev (`https://ui.swarm.localhost`), a Vite port (`http://localhost:5274`),
@@ -333,7 +365,8 @@ function buildCsp(): string {
           "https://*.localhost",
           "http://*.localhost",
         ];
-  const ancestors = Array.from(new Set([...configured, ...devFallbacks]));
+  const embedders = page.authMode === "public" ? getPageFrameAncestors() : [];
+  const ancestors = Array.from(new Set([...configured, ...devFallbacks, ...embedders]));
   // Allow Tailwind Play CDN (`cdn.tailwindcss.com`) for scripts, Google
   // Fonts (`fonts.googleapis.com` stylesheets + `fonts.gstatic.com` font
   // files) for the swarm default typography, and same-origin /@swarm/api/*
@@ -609,7 +642,7 @@ export async function handlePagesPublic(
       const headers: Record<string, string | string[]> = {
         "Content-Type": "text/html; charset=utf-8",
         "Cache-Control": "no-store",
-        "Content-Security-Policy": buildCsp(),
+        "Content-Security-Policy": buildCsp(page),
         "X-Content-Type-Options": "nosniff",
       };
       if (inlineSetCookie.length > 0) headers["Set-Cookie"] = inlineSetCookie;
@@ -642,7 +675,7 @@ export async function handlePagesPublic(
   const headers: Record<string, string | string[]> = {
     "Content-Type": "text/html; charset=utf-8",
     "Cache-Control": "no-store",
-    "Content-Security-Policy": buildCsp(),
+    "Content-Security-Policy": buildCsp(page),
     // Defence-in-depth: prevent MIME sniffing and clickjacking outside the SPA.
     "X-Content-Type-Options": "nosniff",
   };

package/src/http/scripts.ts

@@ -40,12 +40,14 @@ import {
   typecheckScript,
 } from "../be/scripts/typecheck";
 import { can } from "../rbac";
+import { isExecutorAllowedByDeployment } from "../scripts-runtime/executors/registry";
 import { extractScriptSignature, type ScriptSignature } from "../scripts-runtime/extract-signature";
 import { checkQuickJSCompat, quickJSCompatWarnings } from "../scripts-runtime/quickjs-compat";
 import {
   ScriptApiAuthModeSchema,
   ScriptApiRecordSchema,
   type ScriptDetail,
+  ScriptExecutorNameSchema,
   ScriptFsModeSchema,
   type ScriptListItem,
   type ScriptRecord,
@@ -67,6 +69,7 @@ const upsertBodySchema = z.object({
   intent: z.string().default(""),
   scope: ScriptScopeSchema.default("agent"),
   fsMode: ScriptFsModeSchema.default("none"),
+  executor: ScriptExecutorNameSchema.nullable().optional(),
 });
 
 const runBodySchema = z
@@ -77,6 +80,7 @@ const runBodySchema = z
     intent: z.string().default(""),
     scope: ScriptScopeSchema.optional(),
     fsMode: ScriptFsModeSchema.default("none"),
+    executor: ScriptExecutorNameSchema.nullable().optional(),
     idempotencyKey: z.string().max(200).optional(),
   })
   .refine((body) => Boolean(body.name) !== Boolean(body.source), {
@@ -671,6 +675,15 @@ export async function handleScripts(
       }
     }
 
+    if (parsed.body.executor && !isExecutorAllowedByDeployment(parsed.body.executor)) {
+      jsonError(
+        res,
+        'Executor "native" is not permitted when deployment SCRIPT_EXECUTOR="quickjs"',
+        400,
+      );
+      return true;
+    }
+
     const secretRefusal = refuseSourceWithSecrets(parsed.body.source);
     if (secretRefusal) {
       json(res, secretRefusal, 400);
@@ -708,6 +721,7 @@ export async function handleScripts(
       signatureJson: signatureJsonFor(parsed.body.source),
       argsJsonSchema,
       fsMode: parsed.body.fsMode,
+      executor: parsed.body.executor,
       agentId: agent.id,
       isScratch: false,
       typeChecked: true,
@@ -758,6 +772,7 @@ export async function handleScripts(
 
     let source = parsed.body.source;
     let fsMode = parsed.body.fsMode;
+    let executor = parsed.body.executor ?? null;
     let namedScript: ScriptRecord | null = null;
     if (parsed.body.name) {
       const script = await resolveScript(parsed.body.name, agent.id, parsed.body.scope);
@@ -768,6 +783,7 @@ export async function handleScripts(
       namedScript = script;
       source = script.source;
       fsMode = script.fsMode;
+      executor = parsed.body.executor !== undefined ? parsed.body.executor : script.executor;
     }
 
     if (fsMode === "workspace-rw") {
@@ -775,6 +791,15 @@ export async function handleScripts(
       return true;
     }
 
+    if (executor && !isExecutorAllowedByDeployment(executor)) {
+      jsonError(
+        res,
+        'Executor "native" is not permitted when deployment SCRIPT_EXECUTOR="quickjs"',
+        400,
+      );
+      return true;
+    }
+
     const startedAt = new Date().toISOString();
     // Touch before executing so an already-stale scratch script isn't reaped
     // by the retention sweep while this run is still in flight.
@@ -786,6 +811,7 @@ export async function handleScripts(
       source: source as string,
       args: parsed.body.args,
       fsMode,
+      executor,
       agentId: agent.id,
       runtimeInstanceId,
       egressSecrets: credentials.egressSecrets,
@@ -954,6 +980,7 @@ export async function handleScripts(
       isScratch: script.isScratch,
       typeChecked: script.typeChecked,
       fsMode: script.fsMode,
+      executor: script.executor,
       createdByAgentId: script.createdByAgentId,
       createdAt: script.createdAt,
       updatedAt: script.updatedAt,

package/src/http/workflows.ts

@@ -307,6 +307,15 @@ const triggerWorkflowRoute = route({
     "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  query: z.object({
+    wait: z
+      .enum(["true", "false"])
+      .optional()
+      .describe(
+        "Default true: respond after the run's instant steps ran, when it finishes or parks at its first async step. " +
+          "false: respond as soon as the run is committed and walk it in the background.",
+      ),
+  }),
   headers: idempotencyKeyHeader("starts one run"),
   responses: {
     201: {
@@ -1002,6 +1011,7 @@ export async function handleWorkflows(
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
         triggerType: "api",
         requestedByUserId: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+        detach: parsed.query.wait === "false",
         // Recorded in the run's own transaction, before the walk starts.
         accept: claim
           ? async (run) => {

package/src/http/x.ts

@@ -20,6 +20,7 @@ import {
   MAX_SCRIPT_WALL_CLOCK_MS,
   MIN_SCRIPT_WALL_CLOCK_MS,
 } from "../scripts-runtime/executors/types";
+import { HOST_VALIDATED_ARGS } from "../scripts-runtime/host-validated-args";
 import type { RunScriptOutput } from "../scripts-runtime/loader";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 import { validateJsonSchema } from "../workflows/json-schema-validator";
@@ -214,6 +215,7 @@ export async function handleX(
   // Scripts predating the schema column, or where extraction failed, have a
   // null schema — we skip and let the in-subprocess Zod check surface as a
   // runtime_error instead.
+  let hostValidatedArgs = false;
   if (script.argsJsonSchema) {
     try {
       const schema = JSON.parse(script.argsJsonSchema) as Record<string, unknown>;
@@ -227,6 +229,7 @@ export async function handleX(
         });
         return true;
       }
+      hostValidatedArgs = true;
     } catch {
       // Malformed stored schema — don't block execution on it.
     }
@@ -245,7 +248,9 @@ export async function handleX(
   const output = await runScriptWithRunCredential({
     source: script.source,
     args: args ?? null,
+    [HOST_VALIDATED_ARGS]: hostValidatedArgs,
     fsMode: "none",
+    executor: script.executor,
     agentId: endpoint.agentId,
     // timeoutMs only raises the wall-clock limit (network-bound scripts can use
     // the full window); the CPU ulimit (`ulimit -t`) is intentionally left at

package/src/prompts/base-prompt.ts

@@ -271,12 +271,22 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
       renderToolsAndSkillsVars({
         skillsSummary: args.skillsSummary,
         mcpServers: args.mcpServers,
+        // pi defers installed MCP servers together with swarm tools.
+        mcpToolsDeferred: provider === "pi" && hasToolSearch,
         nativeSkillDiscovery,
         toolDiscovery: discoveryResult.text,
         hasLocalEnv,
       }),
     );
     prompt += toolsResult.text;
+
+    // Lead docs pointer: only when the lead has the `swarm-docs` skill. The
+    // skill list is unknown on claude-managed (the cloud sandbox owns skill
+    // delivery) and before the first skill load, so render it then.
+    if (role === "lead" && hasSwarmDocsSkill(args.skillsSummary)) {
+      const docsResult = await resolveTemplateAsync("system.agent.lead.docs", {});
+      prompt += docsResult.text;
+    }
   }
 
   // J. Agent notes (CLAUDE.md), only when it differs from the generated
@@ -339,6 +349,11 @@ export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise
   return prompt.replace(/\n{3,}/g, "\n\n").trim();
 };
 
+/** True when the skill list includes `swarm-docs`, or when the list is unknown. */
+function hasSwarmDocsSkill(skills: { name: string }[] | undefined): boolean {
+  return skills === undefined || skills.some((skill) => skill.name === "swarm-docs");
+}
+
 /**
  * Dynamic lines for `system.agent.tools_skills`. The static text lives in the
  * template so operators can override or skip the section; only the lists that
@@ -347,6 +362,7 @@ export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise
 function renderToolsAndSkillsVars(input: {
   skillsSummary?: { name: string; description: string }[];
   mcpServers?: string[];
+  mcpToolsDeferred?: boolean;
   nativeSkillDiscovery: boolean;
   hasLocalEnv: boolean;
   toolDiscovery: string;
@@ -382,7 +398,11 @@ function renderToolsAndSkillsVars(input: {
   const servers = (input.mcpServers ?? []).filter((name) => name.trim().length > 0);
   const mcpLine =
     servers.length > 0
-      ? `Connected MCP servers: ${servers.join(", ")}. Their tools are in your tool list.\n`
+      ? `Connected MCP servers: ${servers.join(", ")}. ${
+          input.mcpToolsDeferred
+            ? "Load their tools with your harness tool search."
+            : "Their tools are in your tool list."
+        }\n`
       : "";
 
   return {

package/src/prompts/session-templates.ts

@@ -15,8 +15,9 @@
  *   G  secrets                 system.agent.secrets
  *
  * Deployment-gated blocks (E outputs, H slack, steering) and the per-agent and
- * per-task sections (tools and skills, agent notes, repository, requester
- * profile) are appended by base-prompt.ts after the composite.
+ * per-task sections (tools and skills, the lead docs pointer, agent notes,
+ * repository, requester profile) are appended by base-prompt.ts after the
+ * composite.
  *
  * Writing rules for every body: sentence case headings, one idea per sentence,
  * active voice, plain words, no em dashes, a prohibition only where no positive
@@ -109,6 +110,19 @@ Your heartbeat runbook is the \`heartbeatMd\` profile field. Edit it with \`upda
   category: "system",
 });
 
+// Lead docs pointer. base-prompt.ts appends it after the tools and skills
+// section when the lead has the `swarm-docs` skill (or when the skill list is
+// unknown). An operator override with an empty body switches it off.
+registerTemplate({
+  eventType: "system.agent.lead.docs",
+  header: "",
+  defaultBody: `
+Load the \`swarm-docs\` skill only when a person asks for something no skill, workflow, schedule or memory of yours covers, or asks where something is documented. Then follow its offer rules.
+`,
+  variables: [],
+  category: "system",
+});
+
 // Remote providers (no MCP, no container): the task arrives in the session
 // prompt and the final message is the output. No tools to name.
 registerTemplate({
@@ -168,7 +182,7 @@ registerTemplate({
 ## Memory
 
 Memories from past sessions are in your task message. Read them before you start. For a wider search, run the \`task-context-gathering\` script with the task ID and two to four queries.
-Store a learning with \`memory-store\` when you solve something that will come back: a fix, a pattern, a gotcha. Completed task outputs are stored for you.
+When you learn something that would change how the next agent works (a fix, a pattern, a gotcha), pass it as \`learning\` on a \`store-progress\` call before the task ends. Completed task outputs are stored for you.
 You MUST use the \`memory\` skill before you store, edit, or delete a memory.
 `,
   variables: [],

package/src/providers/amp-adapter.ts

@@ -45,7 +45,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1792929650-g000512";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1793025586-g9211b5";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/dsh-adapter.ts

@@ -37,7 +37,7 @@ import type {
 } from "./types";
 
 // npm's `latest` is older and lacks the JSON/stdin contract used here.
-export const DSH_PACKAGE = "@deepseek-ai/dsh@0.2.1-rc.3";
+export const DSH_PACKAGE = "@deepseek-ai/dsh@0.2.1-rc.4";
 
 export function checkDshCredentials(env: Record<string, string | undefined>): CredStatus {
   return env.DEEPSEEK_API_KEY?.trim() || env.OPENROUTER_API_KEY?.trim()

package/src/providers/pi-mono-adapter.ts

@@ -382,14 +382,15 @@ type ToolStructuredContent = NonNullable<AgentToolResult["structuredContent"]>;
 export const SWARM_TOOL_NAMESPACE = { name: "agent-swarm" } as const;
 
 /**
- * `PI_TOOL_DEFERRAL`: hide non-core swarm tools behind pi's `tool_search`.
- * Off by default until a pilot measures the prompt-cache cost of mid-session
- * tool-set changes. Read from `process.env` by both the adapter traits (which
- * pick the prompt's tool-discovery line) and `createSession`, so the prompt
- * and the session always agree.
+ * `PI_TOOL_DEFERRAL`: hide non-core swarm tools, and installed MCP server
+ * tools, behind pi's `tool_search`. On by default: the deferred schemas cost
+ * more on every request than the one partial cache miss a load causes.
+ * `false` declares every tool up front. Read from `process.env` by both the
+ * adapter traits (which pick the prompt's tool-discovery line) and
+ * `createSession`, so the prompt and the session always agree.
  */
 export function isPiToolDeferralEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  return parseEnvFlag(env.PI_TOOL_DEFERRAL, false);
+  return parseEnvFlag(env.PI_TOOL_DEFERRAL, true);
 }
 
 /**
@@ -919,6 +920,28 @@ function requestContextTokens(message: unknown): number | undefined {
   return usage.input + cacheRead + cacheWrite;
 }
 
+/**
+ * The session-log line for one LLM call's usage (token counts only, never
+ * content). The dashboard reads it as that call's cache-hit chip.
+ */
+function callUsageLine(message: unknown): string | undefined {
+  const usage = (message as { usage?: Record<string, unknown> } | null)?.usage;
+  if (typeof usage?.input !== "number") return undefined;
+  const count = (value: unknown) =>
+    typeof value === "number" && Number.isFinite(value) ? value : 0;
+  return JSON.stringify({
+    type: "call_usage",
+    harness: "pi",
+    usage: {
+      input: count(usage.input),
+      cacheRead: count(usage.cacheRead),
+      cacheWrite: count(usage.cacheWrite),
+      output: count(usage.output),
+      reasoning: count(usage.reasoning),
+    },
+  });
+}
+
 function describeAssistantTurn(message: unknown): AssistantTurnShape {
   const msg = (message ?? {}) as {
     content?: unknown;
@@ -1116,6 +1139,10 @@ export class PiMonoSession implements ProviderSession {
         if (endMsg.role === "assistant") {
           const turn = describeAssistantTurn(event.message);
           this.lastAssistantTurn = turn;
+          // Ahead of the turn's text and tool lines: the chip rides on the
+          // call's first row.
+          const usageLine = callUsageLine(event.message);
+          if (usageLine) this.emit({ type: "raw_log", content: usageLine });
           if (endMsg.stopReason === "error") {
             // Candidate terminal failure. May still be cleared by a successful
             // retry (auto_retry_end success / a later good message_end).
@@ -1684,12 +1711,15 @@ function escapeValues(values: unknown): Record<string, string> {
 /**
  * Map installed servers (`fetchInstalledMcpServers(..., "claude")` entries)
  * to pi MCP configs. pi speaks stdio and streamable HTTP; `sse` entries map to
- * HTTP, which is how the previous pi client already reached them. Tools stay
- * `direct`, as before: the prompt lists these servers as in the tool list.
+ * HTTP, which is how the previous pi client already reached them. With
+ * `deferred`, their tools load through `tool_search` like non-core swarm
+ * tools; otherwise they are declared up front.
  */
 export function toPiMcpServers(
   installed: Record<string, Record<string, unknown>> | null,
+  options: { deferred?: boolean } = {},
 ): Record<string, McpServerConfig> {
+  const exposure = options.deferred ? "deferred" : "direct";
   const servers: Record<string, McpServerConfig> = {};
   for (const [name, entry] of Object.entries(installed ?? {})) {
     if (typeof entry.command === "string") {
@@ -1698,14 +1728,14 @@ export function toPiMcpServers(
         command: entry.command,
         args: Array.isArray(entry.args) ? entry.args.map(String) : [],
         env: escapeValues(entry.env),
-        exposure: "direct",
+        exposure,
       };
     } else if (typeof entry.url === "string") {
       servers[name] = {
         type: "http",
         url: entry.url,
         headers: escapeValues(entry.headers),
-        exposure: "direct",
+        exposure,
       };
     }
   }
@@ -1860,7 +1890,7 @@ export class PiMonoAdapter implements ProviderAdapter {
       config.apiUrl && config.apiKey && config.agentId
         ? await fetchInstalledMcpServers(config.apiUrl, config.apiKey, config.agentId, "claude")
         : null;
-    const piMcpServers = toPiMcpServers(installedMcpServers);
+    const piMcpServers = toPiMcpServers(installedMcpServers, { deferred: deferTools });
     if (Object.keys(piMcpServers).length > 0) {
       console.log(
         `\x1b[2m[${config.role}]\x1b[0m Registering ${Object.keys(piMcpServers).length} installed MCP server(s) with pi`,

package/src/scheduler/scheduler.ts

@@ -75,7 +75,7 @@ function resolveExecutorRegistry(): ExecutorRegistry | null {
  * scripts-runtime — no agent/LLM in the loop. Reuses the same `runScriptWithRunCredential()`
  * path as the `swarm-script` workflow executor.
  */
-async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
+export async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
   if (!schedule.scriptName) {
     throw new Error(`Schedule "${schedule.name}" has no scriptName (targetType=script)`);
   }
@@ -106,6 +106,7 @@ async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
       source: script.source,
       args,
       fsMode: "none",
+      executor: script.executor,
       agentId,
       egressSecrets: credentials.egressSecrets,
       userConfig: credentials.userConfig,

package/src/scripts-runtime/eval-harness.ts

@@ -1,6 +1,7 @@
 import { buildCtx } from "./ctx";
 import { patchFetchWithEgressSubstitution } from "./egress-secrets";
 import type { SwarmConfigPayload } from "./executors/types";
+import { isHostValidationEquivalent } from "./host-validated-args";
 import { ctxSignatureHintFor } from "./script-error-hints";
 import { SwarmConfig } from "./swarm-config";
 
@@ -131,8 +132,14 @@ try {
     );
   }
 
+  const hostValidatedArgs = process.env.SWARM_SCRIPT_HOST_VALIDATED_ARGS === "1";
   let validatedArgs = parsedArgs;
-  if (mod.argsSchema && typeof mod.argsSchema === "object" && "parse" in mod.argsSchema) {
+  if (
+    mod.argsSchema &&
+    typeof mod.argsSchema === "object" &&
+    "parse" in mod.argsSchema &&
+    !(hostValidatedArgs && isHostValidationEquivalent(mod.argsSchema, parsedArgs))
+  ) {
     try {
       // biome-ignore lint/suspicious/noExplicitAny: argsSchema is a Zod schema at runtime
       validatedArgs = (mod.argsSchema as any).parse(parsedArgs);