@desplega.ai/agent-swarm 1.158.0 → 1.159.0

package/src/workflows/executors/system-one-providers.ts

@@ -0,0 +1,301 @@
+import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../../utils/openrouter-base-url";
+import type { ExecutorDependencies } from "./base";
+import { resolveWorkflowLlmConfig } from "./workflow-llm";
+
+/**
+ * Hosts that serve typed decisions (Jev, laya). A `system-one-decision` node names one by id
+ * (`config.provider`); the endpoint, header shape, and key name live here, never
+ * in a workflow definition. Every host takes the same `{ state, model, questions }`
+ * request and returns the same `{ model, answers, usage }` body, so the answer
+ * contract in `system-one-decision.ts` is shared. Adding a host is one entry in `SYSTEM_ONE_PROVIDERS`.
+ *
+ * Do not add a chat-completions route. OpenRouter's `typesafe/jev-router` is a
+ * router that forwards a chat request to another model, and `~typesafe/jev-latest`
+ * refuses chat/completions ("is a decisions model"). Only the decisions endpoint
+ * runs Jev itself.
+ */
+
+export interface SystemOneProviderContext {
+  db: ExecutorDependencies["db"];
+  env: NodeJS.ProcessEnv;
+}
+
+/**
+ * A host with no fixed address: the base URL is a global config value, and the
+ * route lives under it. The workflow still carries no URL.
+ */
+export interface SystemOneConfiguredEndpoint {
+  /** Global config key holding the server's base URL, e.g. `LAYA_URL`. */
+  readonly configKey: string;
+  /** Route under the base URL, starting with `/`. */
+  readonly path: string;
+}
+
+export interface SystemOneProvider {
+  /** Name used in messages, e.g. "TypeSafe". */
+  readonly label: string;
+  /** The single credential this host needs: a global secret name. */
+  readonly keyName: string;
+  /** A fixed URL, or the global config key that names the server. */
+  readonly endpoint: string | SystemOneConfiguredEndpoint;
+  /**
+   * Model used when the node sets none. Absent means no `model` is sent and the
+   * host picks, for a host that ignores a model id it does not know.
+   */
+  readonly defaultModel?: string;
+  /**
+   * The field of a `choice` or `score` answer that is the answer's confidence: what
+   * the output reports and what a `humanReview` band is tested against.
+   */
+  readonly confidenceField: "confidence" | "answer_confidence";
+  /** A deployment setting that makes this host unusable, or null. */
+  readonly deploymentProblem?: (env: NodeJS.ProcessEnv) => string | null;
+  /** The credential value, or null/blank when absent. May throw; callers never relay the cause. */
+  readonly readKey: (ctx: SystemOneProviderContext) => Promise<string | null | undefined>;
+}
+
+const TYPESAFE_KEY = "TYPESAFE_API_KEY";
+const OPENROUTER_KEY = "OPENROUTER_API_KEY";
+const LAYA_KEY = "LAYA_API_KEY";
+const LAYA_URL_KEY = "LAYA_URL";
+
+/** Filter by key and scope in SQL so no other config row is read or decrypted. */
+async function readGlobalConfig(
+  db: ExecutorDependencies["db"],
+  key: string,
+): Promise<string | undefined> {
+  const rows = await db.getSwarmConfigs({ scope: "global", key });
+  return rows.find((row) => row.scope === "global" && row.key === key)?.value;
+}
+
+export const SYSTEM_ONE_PROVIDERS = {
+  typesafe: {
+    label: "TypeSafe",
+    keyName: TYPESAFE_KEY,
+    endpoint: "https://api.typesafe.ai/v1/systemone",
+    defaultModel: "jev-latest",
+    confidenceField: "confidence",
+    readKey: ({ db }) => readGlobalConfig(db, TYPESAFE_KEY),
+  },
+  openrouter: {
+    label: "OpenRouter",
+    keyName: OPENROUTER_KEY,
+    endpoint: "https://openrouter.ai/api/alpha/decisions",
+    defaultModel: "~typesafe/jev-latest",
+    confidenceField: "confidence",
+    deploymentProblem(env) {
+      // A gateway URL means OPENROUTER_API_KEY may be a gateway token, and the
+      // decisions API is a sibling of /v1 that a chat gateway need not forward.
+      // Refuse rather than send a credential to a host it was not issued for.
+      return getOpenRouterBaseUrl(env) === DEFAULT_OPENROUTER_BASE_URL
+        ? null
+        : 'OPENROUTER_BASE_URL points at a gateway. SystemOne provider "openrouter" calls openrouter.ai directly and is not supported through a gateway; unset OPENROUTER_BASE_URL or use provider "typesafe".';
+    },
+    async readKey({ env }) {
+      try {
+        // Same resolver raw-llm uses. requireKind stops it falling through to OPENAI_API_KEY.
+        return (await resolveWorkflowLlmConfig(undefined, env, { requireKind: "openrouter" }))
+          .apiKey;
+      } catch {
+        return null;
+      }
+    },
+  },
+  laya: {
+    label: "laya",
+    keyName: LAYA_KEY,
+    endpoint: { configKey: LAYA_URL_KEY, path: "/v1/systemone" },
+    // No default model. laya answers an id it does not know (`jev-latest` included) by
+    // routing on the text instead, with HTTP 200, so a default would be sent as if it meant something.
+    // `confidence` on a choice or score is entropy-based (0.47 top probability reads
+    // ~0.15). `answer_confidence` is the top probability, the number a `noul` band
+    // already uses, so one band means the same thing on every question type.
+    confidenceField: "answer_confidence",
+    readKey: ({ db }) => readGlobalConfig(db, LAYA_KEY),
+  },
+} as const satisfies Record<string, SystemOneProvider>;
+
+export type SystemOneProviderId = keyof typeof SYSTEM_ONE_PROVIDERS;
+
+export const SYSTEM_ONE_PROVIDER_IDS = Object.keys(SYSTEM_ONE_PROVIDERS) as [
+  SystemOneProviderId,
+  ...SystemOneProviderId[],
+];
+
+export const SYSTEM_ONE_DEFAULT_PROVIDER: SystemOneProviderId = "typesafe";
+
+export function isSystemOneProviderId(value: unknown): value is SystemOneProviderId {
+  return typeof value === "string" && Object.hasOwn(SYSTEM_ONE_PROVIDERS, value);
+}
+
+/** Provider a raw node config selects. Undefined when the field is present but not a known id. */
+export function systemOneProviderOf(
+  config: Record<string, unknown>,
+): SystemOneProviderId | undefined {
+  if (config.provider === undefined) return SYSTEM_ONE_DEFAULT_PROVIDER;
+  return isSystemOneProviderId(config.provider) ? config.provider : undefined;
+}
+
+// ─── Messages ───────────────────────────────────────────────
+//
+// Every message names the exact credential and where to set it. They are shared by
+// the save-time warning, the run-start stop, and the step itself, so an author
+// sees the same sentence wherever the problem surfaces.
+
+const SET_IT = (keyName: string) =>
+  `Set ${keyName} as a global secret on the Secrets page (Settings > Secrets).`;
+
+const SET_URL = (configKey: string) =>
+  `Set ${configKey} as a global config value (set-config with scope global).`;
+
+export function systemOneKeyMissingMessage(id: SystemOneProviderId): string {
+  const { label, keyName } = SYSTEM_ONE_PROVIDERS[id];
+  return `${keyName} is not configured. SystemOne provider "${id}" needs a working ${label} API key. ${SET_IT(keyName)}`;
+}
+
+export function systemOneKeyUnreadableMessage(id: SystemOneProviderId): string {
+  // The underlying error can name a config row id; keep the message generic.
+  return `Could not read ${SYSTEM_ONE_PROVIDERS[id].keyName} from swarm config`;
+}
+
+export function systemOneKeyMalformedMessage(id: SystemOneProviderId): string {
+  return `${SYSTEM_ONE_PROVIDERS[id].keyName} is not a valid bearer token value. ${SET_IT(SYSTEM_ONE_PROVIDERS[id].keyName)}`;
+}
+
+/** A 401 or 403 from the host: the key exists but the host does not accept it. */
+export function systemOneKeyRejectedMessage(
+  id: SystemOneProviderId,
+  status: number,
+  code?: string,
+): string {
+  const { label, keyName } = SYSTEM_ONE_PROVIDERS[id];
+  const detail = code ? ` (${code})` : "";
+  return (
+    `${keyName} was rejected by ${label} (HTTP ${status}${detail}). ` +
+    `The key is invalid, revoked, or lacks access to the model. Replace it on the Secrets page (Settings > Secrets). No decision was made.`
+  );
+}
+
+function urlKeyOf(provider: SystemOneProvider): string | null {
+  return typeof provider.endpoint === "string" ? null : provider.endpoint.configKey;
+}
+
+export function systemOneUrlMissingMessage(id: SystemOneProviderId): string {
+  const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[id];
+  const configKey = urlKeyOf(provider) ?? "";
+  return `${configKey} is not configured. SystemOne provider "${id}" needs the URL of a ${provider.label} server. ${SET_URL(configKey)}`;
+}
+
+export function systemOneUrlUnreadableMessage(id: SystemOneProviderId): string {
+  return `Could not read ${urlKeyOf(SYSTEM_ONE_PROVIDERS[id]) ?? ""} from swarm config`;
+}
+
+export function systemOneUrlInvalidMessage(id: SystemOneProviderId): string {
+  const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[id];
+  const configKey = urlKeyOf(provider) ?? "";
+  // The value is not echoed: a URL can carry a credential.
+  return `${configKey} is not a usable ${provider.label} server URL. It must be an https URL (http only for localhost) with no credentials, query, or fragment. ${SET_URL(configKey)}`;
+}
+
+// ─── Credential and endpoint ────────────────────────────────
+
+/** A bearer token is one visible token; anything else would break or split the header. */
+function hasWhitespaceOrControl(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/**
+ * The full request URL for a configured server, or null when the value is not
+ * usable. The credential is sent to this URL, so it must be https (http only for
+ * loopback, for local development) and carry no userinfo, query, or fragment.
+ */
+export function systemOneEndpointFromBase(base: string, path: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(base.trim());
+  } catch {
+    return null;
+  }
+  const secure = url.protocol === "https:";
+  const loopback = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+  if (!secure && !loopback) return null;
+  if (url.username || url.password || url.search || url.hash) return null;
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}${path}`;
+}
+
+export type SystemOneTarget =
+  | { ok: true; apiKey: string; endpoint: string }
+  | { ok: false; error: string };
+
+export interface SystemOneTargetOverrides {
+  /** Replaces the credential lookup. */
+  apiKey?: (id: SystemOneProviderId) => Promise<string | null | undefined>;
+  /** Replaces the lookup of a configured server's base URL. */
+  serverUrl?: (id: SystemOneProviderId) => Promise<string | null | undefined>;
+}
+
+/**
+ * Resolve where a provider is reached and the credential it needs, or the message
+ * to show when it cannot be used. When both a server URL and a key are missing,
+ * both are named in one message. The overrides replace the lookups (tests inject
+ * fakes); the deployment check and the blank / malformed / URL checks still apply.
+ */
+export async function resolveSystemOneTarget(
+  id: SystemOneProviderId,
+  ctx: SystemOneProviderContext,
+  overrides: SystemOneTargetOverrides = {},
+): Promise<SystemOneTarget> {
+  const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[id];
+  const deploymentProblem = provider.deploymentProblem?.(ctx.env);
+  if (deploymentProblem) return { ok: false, error: deploymentProblem };
+
+  const errors: string[] = [];
+
+  let endpoint: string | undefined;
+  if (typeof provider.endpoint === "string") {
+    endpoint = provider.endpoint;
+  } else {
+    const { configKey, path } = provider.endpoint;
+    let base: string | null | undefined;
+    let readable = true;
+    try {
+      base = await (overrides.serverUrl
+        ? overrides.serverUrl(id)
+        : readGlobalConfig(ctx.db, configKey));
+    } catch {
+      readable = false;
+      errors.push(systemOneUrlUnreadableMessage(id));
+    }
+    if (readable) {
+      if (!base || base.trim() === "") {
+        errors.push(systemOneUrlMissingMessage(id));
+      } else {
+        const resolved = systemOneEndpointFromBase(base, path);
+        if (resolved) endpoint = resolved;
+        else errors.push(systemOneUrlInvalidMessage(id));
+      }
+    }
+  }
+
+  let apiKey: string | null | undefined;
+  let keyProblem: string | undefined;
+  try {
+    apiKey = await (overrides.apiKey ? overrides.apiKey(id) : provider.readKey(ctx));
+  } catch {
+    keyProblem = systemOneKeyUnreadableMessage(id);
+  }
+  if (!keyProblem) {
+    if (!apiKey || apiKey.trim() === "") keyProblem = systemOneKeyMissingMessage(id);
+    else if (hasWhitespaceOrControl(apiKey)) keyProblem = systemOneKeyMalformedMessage(id);
+  }
+  if (keyProblem) errors.push(keyProblem);
+
+  if (errors.length > 0 || !endpoint || !apiKey) return { ok: false, error: errors.join(" ") };
+  return { ok: true, apiKey, endpoint };
+}

package/src/workflows/executors/workflow-llm.ts

@@ -7,16 +7,28 @@ export interface WorkflowLlmConfig {
   model: string;
 }
 
-/** Resolve an OpenAI-compatible credential and endpoint for workflow LLM nodes. */
+/**
+ * Resolve an OpenAI-compatible credential and endpoint for workflow LLM nodes.
+ *
+ * `requireKind` is for callers that must talk to one specific provider: the
+ * resolver picks by precedence (OpenRouter, then Anthropic, then OpenAI), so a
+ * caller that needs the OpenRouter key would otherwise be handed an OpenAI key
+ * whenever the OpenRouter one is absent.
+ */
 export async function resolveWorkflowLlmConfig(
   requestedModel?: string,
   env: NodeJS.ProcessEnv = process.env,
+  options: { requireKind?: "openrouter" | "openai" } = {},
 ): Promise<WorkflowLlmConfig> {
   const credential = await resolveCredential({ env });
   if (!credential) {
     throw new Error("No workflow LLM credential found. Set OPENROUTER_API_KEY or OPENAI_API_KEY.");
   }
 
+  if (options.requireKind && credential.kind !== options.requireKind) {
+    throw new Error(`No ${options.requireKind} credential found for this workflow LLM call.`);
+  }
+
   if (credential.kind !== "openrouter" && credential.kind !== "openai") {
     throw new Error(
       `Workflow LLM nodes do not support the resolved ${credential.kind} credential yet. Set OPENROUTER_API_KEY or OPENAI_API_KEY.`,

package/src/workflows/readiness.ts

@@ -0,0 +1,86 @@
+import type { WorkflowDefinition } from "../types";
+import type { ExecutorReadinessNode } from "./executors/base";
+import type { ExecutorRegistry } from "./executors/registry";
+
+export interface WorkflowReadinessProblem {
+  /** Executor type that reported the problem. */
+  type: string;
+  nodeIds: string[];
+  message: string;
+}
+
+/**
+ * Ask every executor type a definition uses whether it can run right now, e.g.
+ * whether the credential a `system-one-decision` node needs is configured. Types are checked in
+ * first-use order, one call per type. Unregistered types are skipped (definition
+ * validation reports them). A check that throws is reported as a problem rather
+ * than propagated, so a broken check can never crash a save or start a run blind.
+ */
+export async function findWorkflowReadinessProblems(
+  definition: Pick<WorkflowDefinition, "nodes">,
+  registry: ExecutorRegistry,
+): Promise<WorkflowReadinessProblem[]> {
+  const nodesByType = new Map<string, ExecutorReadinessNode[]>();
+  for (const node of definition.nodes) {
+    if (!registry.has(node.type)) continue;
+    const group = nodesByType.get(node.type) ?? [];
+    group.push({ id: node.id, config: node.config });
+    nodesByType.set(node.type, group);
+  }
+
+  const problems: WorkflowReadinessProblem[] = [];
+  for (const [type, nodes] of nodesByType) {
+    try {
+      for (const problem of await registry.get(type).checkReadiness(nodes)) {
+        problems.push({ type, ...problem });
+      }
+    } catch {
+      problems.push({
+        type,
+        nodeIds: nodes.map((node) => node.id),
+        message: `Could not check whether "${type}" nodes are ready to run`,
+      });
+    }
+  }
+  return problems;
+}
+
+function describeNodes(problem: WorkflowReadinessProblem): string {
+  const noun = problem.nodeIds.length === 1 ? "node" : "nodes";
+  return `${problem.type} ${noun} ${problem.nodeIds.map((id) => `"${id}"`).join(", ")}`;
+}
+
+/**
+ * Message an author gets when a save succeeded but a node cannot run yet.
+ * The executor's own message comes first so it reads the same as at run start.
+ */
+export function formatReadinessWarning(problem: WorkflowReadinessProblem): string {
+  return `${problem.message} Affects ${describeNodes(problem)}. Runs of this workflow fail before any node executes until this is fixed.`;
+}
+
+/** The problems as one sentence list; callers prefix what was stopped. */
+export function formatReadinessProblems(problems: readonly WorkflowReadinessProblem[]): string {
+  return problems
+    .map((problem) => `${problem.message} Needed by ${describeNodes(problem)}.`)
+    .join(" ");
+}
+
+/** Error recorded on a run that was stopped before any node executed. */
+export function formatReadinessRunError(problems: readonly WorkflowReadinessProblem[]): string {
+  return `Run not started, no node executed: ${formatReadinessProblems(problems)}`;
+}
+
+/** Warnings for a definition that was just saved. Empty when every executor is ready. */
+export async function workflowSaveWarnings(
+  definition: Pick<WorkflowDefinition, "nodes">,
+  registry: ExecutorRegistry,
+): Promise<string[]> {
+  return (await findWorkflowReadinessProblems(definition, registry)).map(formatReadinessWarning);
+}
+
+/** Append save-time warnings to a tool message so the author sees them in the summary. */
+export function withSaveWarnings(text: string, warnings: readonly string[]): string {
+  return warnings.length === 0
+    ? text
+    : `${text} ${warnings.map((warning) => `Warning: ${warning}`).join(" ")}`;
+}

package/src/workflows/recovery.ts

@@ -13,6 +13,7 @@ import {
   updateWorkflowRun,
 } from "../be/db";
 import type { WorkflowRunStep } from "../types";
+import { shapeApprovalResolution } from "./approval-resolution";
 import { loadCompletedStepRouting } from "./completed-step-routing";
 import { FAILED_TASK_OUTPUT_PREFIX } from "./constants";
 import { findReadyNodes, isWorkflowRunActive, walkGraph } from "./engine";
@@ -279,18 +280,17 @@ async function recoverApprovalWaitingRuns(registry: ExecutorRegistry): Promise<n
           return null;
         }
 
-        const nextPort =
-          approvalStatus === "timeout"
-            ? "timeout"
-            : approvalStatus === "rejected"
-              ? "rejected"
-              : "approved";
-
-        const stepOutput = {
-          requestId: stuck.approvalId,
-          status: approvalStatus,
-          responses: approval?.responses ?? null,
-        };
+        const { output: stepOutput, nextPort } = shapeApprovalResolution(
+          registry,
+          workflow.definition,
+          stuck.nodeId,
+          (await getWorkflowRunStep(stuck.stepId))?.output,
+          {
+            requestId: stuck.approvalId,
+            status: approvalStatus,
+            responses: (approval?.responses ?? null) as Record<string, unknown> | null,
+          },
+        );
 
         // Use port-based routing to determine correct successors. Claimed: the
         // live approval.resolved bus event may have routed this step between

package/src/workflows/resume.ts

@@ -22,6 +22,7 @@ import {
   type ApprovalSlackClient,
   postApprovalCancellationUpdates,
 } from "./approval-notifications";
+import { shapeApprovalResolution } from "./approval-resolution";
 import { loadCompletedStepRouting } from "./completed-step-routing";
 import { FAILED_TASK_OUTPUT_PREFIX } from "./constants";
 import { getNextTargets } from "./definition";
@@ -32,6 +33,7 @@ import type { ExecutorRegistry } from "./executors/registry";
 import { computeNextPort } from "./executors/wait";
 import { resolveForeachParent } from "./foreach-join";
 import { getSecretInputKeys } from "./input";
+import { findWorkflowReadinessProblems, formatReadinessProblems } from "./readiness";
 import {
   checkpointPortStepAndResolveSuccessors,
   completeTaskStepAndResolveSuccessors,
@@ -325,6 +327,18 @@ export async function retryFailedRun(runId: string, registry: ExecutorRegistry):
   if (!failedStep) throw new Error("No failed step found");
 
   const completedNodeIds = new Set(await getCompletedStepNodeIds(runId));
+
+  // A retry re-executes the failed node and everything after it. Refuse before the
+  // run is reset when a node still to run cannot run (say, a system-one-decision node with no API
+  // key), so the retry does not repeat side effects only to fail again downstream.
+  const notReady = await findWorkflowReadinessProblems(
+    { nodes: workflow.definition.nodes.filter((node) => !completedNodeIds.has(node.id)) },
+    registry,
+  );
+  if (notReady.length > 0) {
+    throw new Error(`Retry not started, run left failed: ${formatReadinessProblems(notReady)}`);
+  }
+
   const { activeEdges } = await loadCompletedStepRouting(
     workflow.definition,
     runId,
@@ -519,15 +533,15 @@ async function resumeFromApprovalResolution(
     return;
   }
 
-  // Determine output port based on approval status
-  const nextPort =
-    event.status === "timeout" ? "timeout" : event.status === "rejected" ? "rejected" : "approved";
-
-  const stepOutput = {
-    requestId: event.requestId,
-    status: event.status,
-    responses: event.responses,
-  };
+  // Output and port for the approval status. A step parked by an executor other
+  // than human-in-the-loop shapes its own (see shapeApprovalResolution).
+  const { output: stepOutput, nextPort } = shapeApprovalResolution(
+    registry,
+    workflow.definition,
+    step.nodeId,
+    step.output,
+    { requestId: event.requestId, status: event.status, responses: event.responses },
+  );
 
   // Use port-based routing to determine the correct successors.
   // findReadyNodes without activeEdges would return ALL structural successors

package/templates/schedules/daily-blocker-digest/content.md

@@ -29,12 +29,11 @@ You are Lead. Produce one concise daily digest of blockers, stale claims, open P
 
 Run these read-only global scripts first. Use their outputs as evidence, then apply judgment:
 
-1. `script-run` global script `Heartbeat Audit` with args `{ "heartbeatMarkdown": "<current /workspace/HEARTBEAT.md text>" }`
-2. `script-run` global script `schedule-health` with args `{ "days": 7, "publishPage": true }`
-3. `script-run` global script `task-failure-audit` with args `{ "days": 7, "groupBy": "reason", "publishPage": true }`
-4. Read `GET /status`. If the `embeddings` milestone is `unverified`, append this line to the digest: "Memory search is off: set OPENAI_API_KEY on the API server to enable it."
+1. `script-run` global script `schedule-health` with args `{ "days": 7, "publishPage": true }`
+2. `script-run` global script `task-failure-audit` with args `{ "days": 7, "groupBy": "reason", "publishPage": true }`
+3. Read `GET /status`. If the `embeddings` milestone is `unverified`, append this line to the digest: "Memory search is off: set OPENAI_API_KEY on the API server to enable it."
 
-Do not script-ify judgment or notification copy. Use the script outputs to identify stale blocker claims, schedule risks, provider failure clusters, and digest-run health.
+Do not script-ify judgment or notification copy. Use the script outputs to identify schedule risks and provider failure clusters.
 
 ## Phase 1: Gather Blockers
 

package/templates/skills/agent-browser/SKILL.md

@@ -64,21 +64,22 @@ ffmpeg -y -i in.mp4 -filter:v "setpts=PTS/1.5,fps=30" -an \
 
 Speed-up is a post-process step: `record start` has no speed or human flag. Keep `fps=30` to preserve a steady 30 fps output rather than uneven frame drops at an inferred rate. `-an` disables audio because agent-browser recordings carry no audio track. The worker ships only `ffmpeg`, not `ffprobe`; inspect duration with `ffmpeg -i out-1.5x.mp4 2>&1 | grep Duration`.
 
-Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path and signed-URL steps as screenshots below, and link it in the PR body.
+Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path as screenshots below, and link it in the PR body.
 
 ## Step 3: share the screenshot through agent-fs
 
-Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention and share the signed URL. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention. Use `share-create` when a person needs to open the file, and `signed-url` for raw embeds such as an image in GitHub PR markdown. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
 
 ```bash
 agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
   --file /tmp/<name>.png -m "<what it shows>"
 agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
-agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # 24h default, --expires-in up to 7d
+agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json
+agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # raw URL for embeds; 24h default, --expires-in up to 7d
 ```
 
-- Embed the URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
-- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the signed URL in the progress text.
+- Embed the signed URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
+- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 
 The `artifacts` skill holds the full agent-fs recipe and the naming conventions.

package/templates/skills/agent-browser/content.md

@@ -59,21 +59,22 @@ ffmpeg -y -i in.mp4 -filter:v "setpts=PTS/1.5,fps=30" -an \
 
 Speed-up is a post-process step: `record start` has no speed or human flag. Keep `fps=30` to preserve a steady 30 fps output rather than uneven frame drops at an inferred rate. `-an` disables audio because agent-browser recordings carry no audio track. The worker ships only `ffmpeg`, not `ffprobe`; inspect duration with `ffmpeg -i out-1.5x.mp4 2>&1 | grep Duration`.
 
-Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path and signed-URL steps as screenshots below, and link it in the PR body.
+Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path as screenshots below, and link it in the PR body.
 
 ## Step 3: share the screenshot through agent-fs
 
-Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention and share the signed URL. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention. Use `share-create` when a person needs to open the file, and `signed-url` for raw embeds such as an image in GitHub PR markdown. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
 
 ```bash
 agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
   --file /tmp/<name>.png -m "<what it shows>"
 agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
-agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # 24h default, --expires-in up to 7d
+agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json
+agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # raw URL for embeds; 24h default, --expires-in up to 7d
 ```
 
-- Embed the URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
-- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the signed URL in the progress text.
+- Embed the signed URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
+- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 
 The `artifacts` skill holds the full agent-fs recipe and the naming conventions.

package/templates/skills/heartbeat-runbook/config.json

@@ -4,7 +4,7 @@
   "displayName": "Heartbeat Runbook",
   "slug": "heartbeat-runbook",
   "title": "Heartbeat Runbook",
-  "description": "Heartbeat, HEARTBEAT.md, standing orders, heartbeat-checklist task, boot-triage task: how the lead keeps its heartbeat runbook short and handles a checklist or boot-triage task. Covers the tracked-item cap, lift triggers, the `Heartbeat Audit` and `boot-triage` scripts, and reboot-interrupted work. Lead only.",
+  "description": "Heartbeat, HEARTBEAT.md, standing orders, heartbeat-checklist task, boot-triage task: how the lead keeps its heartbeat runbook short and handles a checklist or boot-triage task. Covers the tracked-item cap, lift triggers, the `schedule-health`, `task-failure-audit` and `boot-triage` scripts, and reboot-interrupted work. Lead only.",
   "version": "1.0.0",
   "category": "skills",
   "placeholders": [],

package/templates/skills/heartbeat-runbook/content.md

@@ -29,8 +29,8 @@ Two kinds of sections:
 
 1. Read the latest runbook. The snapshot in the task may be stale.
 2. Prune first. Check every tracked item against its lift trigger. Remove resolved, stale, and past-date items.
-3. Run the seeded audit: `script-run` with name `Heartbeat Audit` and `args: { heartbeatMarkdown: <the runbook text> }`. It reports resolved stale PRs, pool-target risk schedules, schedule and provider failure clusters, and whether the daily blocker digest ran today.
-4. Read the system status and the audit result for stalled tasks, idle workers next to open work, and anomalies.
+3. Run the seeded scripts: `script-run` with name `schedule-health`, then `task-failure-audit`, both with `args: { days: 1, publishPage: false }`. They report failing schedules and failure clusters. Check any other standing order in the runbook yourself.
+4. Read the system status and the script results for stalled tasks, idle workers next to open work, and anomalies.
 5. Reboot-interrupted failures: a failure reason "worker session not found" or "worker session heartbeat is stale" means a server restart cut the task off. For each one: `get-task-details` on the task, confirm a retry task tagged `reboot-retry` exists and moves, recreate the task when no retry exists and the work is still needed. These are never "expected cleanup".
 6. Act with your tools: create tasks, cancel stuck ones, post to Slack under the `slack-interaction` skill rules.
 7. Update the runbook after pruning.

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

@@ -43,7 +43,7 @@ The swarm ships named scripts at global scope. Each one replaces a multi-step to
 | `complete-task` | `{ taskId, output }` | finish a task from inside a script |
 | `report-progress` | `{ taskId, note }` | a progress note from inside a script |
 | `swarm-overview` | `{}` | agents and task counts |
-| `Heartbeat Audit`, `boot-triage` | see `heartbeat-runbook` | the lead's heartbeat data gathering |
+| `schedule-health`, `task-failure-audit`, `boot-triage` | see `heartbeat-runbook` | the lead's heartbeat data gathering |
 
 ## Authoring contract
 

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

@@ -38,7 +38,7 @@ The swarm ships named scripts at global scope. Each one replaces a multi-step to
 | `complete-task` | `{ taskId, output }` | finish a task from inside a script |
 | `report-progress` | `{ taskId, note }` | a progress note from inside a script |
 | `swarm-overview` | `{}` | agents and task counts |
-| `Heartbeat Audit`, `boot-triage` | see `heartbeat-runbook` | the lead's heartbeat data gathering |
+| `schedule-health`, `task-failure-audit`, `boot-triage` | see `heartbeat-runbook` | the lead's heartbeat data gathering |
 
 ## Authoring contract