@desplega.ai/agent-swarm 2.4.3 → 2.4.4

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

@@ -0,0 +1,264 @@
+import { getOpenRouterAttributionHeaders } from "../../utils/openrouter-base-url";
+import {
+  type SystemOneCapability,
+  type SystemOneHostId,
+  systemOneKeyRejectedMessage,
+} from "./system-one-providers";
+import { cloudflareErrorCode, isRecord } from "./system-one-wire";
+
+/**
+ * One POST to a System One host, shared by every capability (`system-one-decision`,
+ * `system-one-extraction`): one time budget, transient retries with backoff,
+ * `Retry-After`, redirect refusal, a response size cap, and the same error
+ * sentences. The credential goes only into the `authorization` header.
+ */
+
+export const SYSTEM_ONE_DEFAULT_TIMEOUT_MS = 30_000;
+export const SYSTEM_ONE_MIN_TIMEOUT_MS = 1_000;
+export const SYSTEM_ONE_MAX_TIMEOUT_MS = 300_000;
+export const SYSTEM_ONE_DEFAULT_MAX_RETRIES = 2;
+export const SYSTEM_ONE_MAX_RETRIES_LIMIT = 3;
+
+/** Room left before the engine watchdog fires so the executor can report its own failure. */
+const DEADLINE_MARGIN_MS = 250;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 8_000;
+const MAX_RESPONSE_CHARS = 1_048_576;
+const MAX_ERROR_BODY_CHARS = 65_536;
+
+export interface SystemOneTransportOptions {
+  /** Transport. Tests inject a fake; production uses the global `fetch`. */
+  fetch?: typeof fetch;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  now?: () => number;
+  random?: () => number;
+}
+
+export interface SystemOneRequest {
+  providerId: SystemOneHostId;
+  capability: SystemOneCapability;
+  endpoint: string;
+  apiKey: string;
+  /** The secret name the key was read under, named when the host rejects it. */
+  keyName: string;
+  body: string;
+  timeoutMs: number;
+  maxRetries: number;
+  env: NodeJS.ProcessEnv;
+}
+
+export type SystemOneSendResult =
+  | { ok: true; text: string; requestId?: string }
+  | { ok: false; error: string };
+
+type Attempt =
+  | { kind: "ok"; text: string; requestId?: string }
+  | { kind: "timeout" }
+  | { kind: "fail"; message: string; retryable: boolean; retryAfterMs?: number };
+
+const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const ERROR_CODE_RE = /^[A-Za-z0-9._:-]{1,64}$/;
+
+function readRequestId(headers: Headers): string | undefined {
+  // Cloudflare marks every response with `cf-ray` and sends no request id.
+  const value = headers.get("x-request-id") ?? headers.get("request-id") ?? headers.get("cf-ray");
+  return value && REQUEST_ID_RE.test(value) ? value : undefined;
+}
+
+/** Retry-After as delta-seconds or an HTTP date, in ms. Undefined when absent or unparseable. */
+function parseRetryAfter(value: string | null, now: number): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (/^\d+(\.\d+)?$/.test(trimmed)) return Math.round(Number(trimmed) * 1000);
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+
+/** Only a short identifier from the provider's error envelope. Never its message or echoed request. */
+function readErrorCode(text: string): string | undefined {
+  if (text.length === 0 || text.length > MAX_ERROR_BODY_CHARS) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed)) return undefined;
+  const nested = isRecord(parsed.error) ? parsed.error : undefined;
+  const detail = isRecord(parsed.detail) ? parsed.detail : undefined;
+  for (const candidate of [
+    nested?.code,
+    nested?.type,
+    detail?.error_type,
+    parsed.code,
+    parsed.type,
+  ]) {
+    if (typeof candidate === "string" && ERROR_CODE_RE.test(candidate)) return candidate;
+  }
+  // Cloudflare's envelope: `{ success: false, errors: [{ code: 10000, message }] }`.
+  return cloudflareErrorCode(parsed);
+}
+
+function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+/**
+ * POST once, retrying only transient failures inside one time budget.
+ * Retries: connection errors, HTTP 408 / 429 / 5xx (incl. 529). Never: 401, 422,
+ * other 4xx, redirects, or a bad success body (the caller validates that).
+ */
+export async function sendSystemOneRequest(
+  request: SystemOneRequest,
+  options: SystemOneTransportOptions = {},
+): Promise<SystemOneSendResult> {
+  const { timeoutMs, maxRetries } = request;
+  const doFetch = options.fetch ?? fetch;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const random = options.random ?? Math.random;
+
+  const deadlineAt = now() + timeoutMs - DEADLINE_MARGIN_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(0, deadlineAt - now()));
+  const timedOut = () =>
+    ({
+      ok: false,
+      error: `SystemOne request exceeded its ${timeoutMs}ms time budget`,
+    }) as const;
+
+  try {
+    for (let attempt = 0; ; attempt++) {
+      const result = await attemptOnce(doFetch, request, controller.signal, now);
+      if (result.kind === "ok") {
+        return { ok: true, text: result.text, requestId: result.requestId };
+      }
+      if (result.kind === "timeout" || controller.signal.aborted) return timedOut();
+
+      const attempts = attempt + 1;
+      const suffix = attempts > 1 ? ` after ${attempts} attempts` : "";
+      if (!result.retryable || attempt >= maxRetries) {
+        return { ok: false, error: `${result.message}${suffix}` };
+      }
+
+      const backoff = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+      const delay = result.retryAfterMs ?? Math.round(backoff * (0.5 + random() * 0.5));
+      if (delay >= deadlineAt - now()) {
+        return {
+          ok: false,
+          error: `${result.message}${suffix}; the ${delay}ms retry delay does not fit the ${timeoutMs}ms time budget`,
+        };
+      }
+      await sleep(delay, controller.signal);
+      if (controller.signal.aborted) return timedOut();
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function attemptOnce(
+  doFetch: typeof fetch,
+  request: SystemOneRequest,
+  signal: AbortSignal,
+  now: () => number,
+): Promise<Attempt> {
+  const { endpoint, apiKey, body } = request;
+  let res: Response;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: {
+        ...getOpenRouterAttributionHeaders(endpoint, request.env),
+        "content-type": "application/json",
+        accept: "application/json",
+        authorization: `Bearer ${apiKey}`,
+      },
+      body,
+      redirect: "manual",
+      signal,
+    });
+  } catch (err) {
+    if (signal.aborted) return { kind: "timeout" };
+    const code = (err as { code?: unknown })?.code;
+    const detail = typeof code === "string" && /^[A-Z0-9_]{3,40}$/.test(code) ? ` (${code})` : "";
+    return {
+      kind: "fail",
+      message: `SystemOne request failed: network error${detail}`,
+      retryable: true,
+    };
+  }
+
+  const requestId = readRequestId(res.headers);
+  const withId = (message: string) => (requestId ? `${message} [request ${requestId}]` : message);
+
+  if (res.status >= 200 && res.status < 300) {
+    let text: string;
+    try {
+      text = await res.text();
+    } catch {
+      if (signal.aborted) return { kind: "timeout" };
+      return {
+        kind: "fail",
+        message: withId("SystemOne response body could not be read"),
+        retryable: true,
+      };
+    }
+    if (text.length > MAX_RESPONSE_CHARS) {
+      return {
+        kind: "fail",
+        message: withId("SystemOne response exceeded the size limit"),
+        retryable: false,
+      };
+    }
+    return { kind: "ok", text, requestId };
+  }
+
+  if (res.status >= 300 && res.status < 400) {
+    return {
+      kind: "fail",
+      message: withId(
+        `SystemOne request was redirected (HTTP ${res.status}); redirects are refused`,
+      ),
+      retryable: false,
+    };
+  }
+
+  let errorText = "";
+  try {
+    errorText = await res.text();
+  } catch {
+    if (signal.aborted) return { kind: "timeout" };
+  }
+  const code = readErrorCode(errorText);
+  // The host answered but does not accept the key: name it, never retry.
+  if (res.status === 401 || res.status === 403) {
+    return {
+      kind: "fail",
+      message: withId(
+        systemOneKeyRejectedMessage(request.providerId, res.status, code, {
+          keyName: request.keyName,
+          capability: request.capability,
+        }),
+      ),
+      retryable: false,
+    };
+  }
+  const detail = code ? ` (${code})` : "";
+  const retryable = res.status === 408 || res.status === 429 || res.status >= 500;
+  return {
+    kind: "fail",
+    message: withId(`SystemOne API returned HTTP ${res.status}${detail}`),
+    retryable,
+    retryAfterMs: retryable ? parseRetryAfter(res.headers.get("retry-after"), now()) : undefined,
+  };
+}

package/templates/official/lead/HEARTBEAT.md

@@ -11,5 +11,5 @@
 ## Tracked Items
 
 - Live items only: active blockers and watch items. Cap 10, 20 max during a surge; prune before you add.
-- Each item states its lift trigger and a calendar date (e.g. `lift when X; check 2026-08-22`).
+- Each item states its lift trigger and a calendar date as a bare `MM-DD` (e.g. `lift when X; check 08-22`) or `DELETE MM-DD`. A full `YYYY-MM-DD` stamp does not arm the gate.
 - An item closes: move its durable facts to memory, then delete the line. Never strike it through.

package/templates/skills/apps/SKILL.md

@@ -645,6 +645,8 @@ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, o
 | `{ "$form": "title" }` | One current Form value. |
 | `{ "$form": "" }` | All current Form values. |
 | `{ "$state": "/queries/allIdeas/data" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |
+| `{ "$chain": "leafTaskId" }` | One chain-scope value, published by a component that runs a task chain; it carries `leafTaskId` and `newTaskId`. Where no chain scope is published, the sentinel is left in place and the action fails instead of silently dropping the parent. |
+| `{ "$chain": "" }` | The whole chain scope. |
 
 Each sentinel object must contain exactly the single key shown.
 
@@ -652,7 +654,7 @@ An action-chain step is `{ "action": "<type>", "params": {...} }`. Available act
 
 - `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `"create"`, `"update"`, or `"delete"`. `update`/`delete` require `rowId` (usually `{ "$row": "id" }`, or `{ "$state": "/route/params/<param>" }` in a Drawer footer); literal `values` keys must be model columns. Successful mutation refetches all queries on that model.
 - `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.
-- `app.action`: `{ name, input? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`.
+- `app.action`: `{ name, input?, parentTaskId? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ "$chain": "leafTaskId" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400.
 - `app.navigate`: `{ page, params? }`; `page` must be declared, supplied keys must be params of the target page, and every required target param must be supplied. `params` replace the current route params wholesale and may contain action sentinels. Navigation pushes history, so browser Back returns to the previous page/params; only `mode` is preserved automatically.
 - `ui.toast`: `{ message, description?, tone?, undo? }`, where `tone` is `"success"`, `"error"`, `"info"` (default), or `"warning"`. `undo: { label?, actions }` adds an Undo button (default label `Undo`) that runs `actions` as a chain; its steps are validated like any chain. Put it after the step it confirms, e.g. a row delete followed by `{ "action": "ui.toast", "params": { "message": "Order deleted", "undo": { "actions": [{ "action": "app.mutate", "params": { "model": "order", "op": "create", "values": { "title": { "$row": "title" } } } }] } } }`. Undo params resolve `$state` when Undo is pressed; `$row` / `$form` resolve when the toast is shown.
 - `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.

package/templates/skills/apps/content.md

@@ -640,6 +640,8 @@ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, o
 | `{ "$form": "title" }` | One current Form value. |
 | `{ "$form": "" }` | All current Form values. |
 | `{ "$state": "/queries/allIdeas/data" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |
+| `{ "$chain": "leafTaskId" }` | One chain-scope value, published by a component that runs a task chain; it carries `leafTaskId` and `newTaskId`. Where no chain scope is published, the sentinel is left in place and the action fails instead of silently dropping the parent. |
+| `{ "$chain": "" }` | The whole chain scope. |
 
 Each sentinel object must contain exactly the single key shown.
 
@@ -647,7 +649,7 @@ An action-chain step is `{ "action": "<type>", "params": {...} }`. Available act
 
 - `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `"create"`, `"update"`, or `"delete"`. `update`/`delete` require `rowId` (usually `{ "$row": "id" }`, or `{ "$state": "/route/params/<param>" }` in a Drawer footer); literal `values` keys must be model columns. Successful mutation refetches all queries on that model.
 - `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.
-- `app.action`: `{ name, input? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`.
+- `app.action`: `{ name, input?, parentTaskId? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ "$chain": "leafTaskId" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400.
 - `app.navigate`: `{ page, params? }`; `page` must be declared, supplied keys must be params of the target page, and every required target param must be supplied. `params` replace the current route params wholesale and may contain action sentinels. Navigation pushes history, so browser Back returns to the previous page/params; only `mode` is preserved automatically.
 - `ui.toast`: `{ message, description?, tone?, undo? }`, where `tone` is `"success"`, `"error"`, `"info"` (default), or `"warning"`. `undo: { label?, actions }` adds an Undo button (default label `Undo`) that runs `actions` as a chain; its steps are validated like any chain. Put it after the step it confirms, e.g. a row delete followed by `{ "action": "ui.toast", "params": { "message": "Order deleted", "undo": { "actions": [{ "action": "app.mutate", "params": { "model": "order", "op": "create", "values": { "title": { "$row": "title" } } } }] } } }`. Undo params resolve `$state` when Undo is pressed; `$row` / `$form` resolve when the toast is shown.
 - `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.

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

@@ -22,7 +22,7 @@ Two kinds of sections:
 ## The cap
 
 - Tracked items across all tracked sections: 10. Absolute maximum 20, only during a real surge.
-- Every tracked item states its lift trigger and a date. An item with no removal condition does not go in.
+- Every tracked item states its lift trigger and a date. An item with no removal condition does not go in. Write the date as a bare `MM-DD` (`check 10-20`) or `DELETE MM-DD` for a past-date prune: those are the only forms the gate can see.
 - Write an age trigger as a calendar date (opened date + N days), never as a day count computed at check time. A floored age fires a day late.
 - Never arm a defer chain to re-check a tracked item. The next heartbeat already checks it. Defer only for work no scheduled pass owns.
 - Incident detail goes to memory: `memory-store` at `swarm` scope, one line of pointer stays in the runbook.
@@ -63,7 +63,7 @@ A gate script can run before each checklist tick and decide whether the tick nee
 - `HEARTBEAT_CHECKLIST_GATE_MODE=enforce`: a quiet verdict skips the task. A wake verdict adds the gate's summary as a Gate Findings section. Enforce is opt-in; turn it on only after shadow tags agree with your own quiet outcomes.
 - The gate fails open. A timeout (60 s), a script error or a malformed result is an `error` verdict, and the task is created in both modes.
 - Preview a verdict with `script-run` on `heartbeat-jev-gate`, `args: { dryRun: true }`.
-- The gate sees a tracked item as due when its line contains today's date (a `YYYY-MM-DD` date matches) or a `DELETE MM-DD` marker on or before today. A line with no date is invisible to it, and a date already past is only caught through `DELETE MM-DD`, so the prune in step 2 still matters.
+- The gate sees a tracked item as due when its line contains today's `MM-DD` as a bare token (`check 10-20`) or a `DELETE MM-DD` marker on or before today. A full `YYYY-MM-DD` date does not count: a line that only carries a re-verification stamp (`2026-10-20 ~10:45Z`) is invisible to the gate, so write the due date bare. A line with no date is invisible too, and a date already past is only caught through `DELETE MM-DD`, so the prune in step 2 still matters.
 
 ## Example standing orders
 
@@ -74,5 +74,5 @@ A gate script can run before each checklist tick and decide whether the tick nee
 - Slack requests older than 1 hour without a task: create the task.
 
 ## Watch Items
-- Linear webhook retries since 2026-08-18. Lift when zero retries for 48 h (check 2026-08-22).
+- Linear webhook retries since 2026-08-18. Lift when zero retries for 48 h (check 08-22).
 ```

package/dist/cli-v1sjhn52.js

@@ -1,7 +0,0 @@
-import {
-  init_external
-} from "./cli-d9f7gzeq.js";
-
-// node_modules/zod/v4/classic/index.js
-init_external();
-init_external();

package/dist/handlers-2qjw434w.js

@@ -1,39 +0,0 @@
-import {
-  isUserAllowed2,
-  registerMessageHandler2
-} from "./cli-dm8p2dpf.js";
-import"./cli-bxrqvpg5.js";
-import"./cli-4yef8ghv.js";
-import"./cli-kgnkyabk.js";
-import"./cli-smvcw9z5.js";
-import"./cli-1eszr343.js";
-import"./cli-qz93y3x5.js";
-import"./cli-3h26v7yj.js";
-import"./cli-e8xyjvfc.js";
-import"./cli-npfe9t1s.js";
-import"./cli-73ezfhha.js";
-import"./cli-3ggwdtb0.js";
-import"./cli-pygdsgh8.js";
-import"./cli-1n9gdg56.js";
-import"./cli-vq9gqarq.js";
-import"./cli-qje9k2nh.js";
-import"./cli-0dxxwfkt.js";
-import"./cli-s9rr4gr2.js";
-import"./cli-8nyhf7za.js";
-import"./cli-ejs3m1sx.js";
-import"./cli-6eyncg0y.js";
-import"./cli-13p25grh.js";
-import"./cli-0adyhvq2.js";
-import"./cli-tkf4x6ha.js";
-import"./cli-v87dr6e3.js";
-import"./cli-gx0j2khs.js";
-import"./cli-sds5zzs8.js";
-import"./cli-445c1vp7.js";
-import"./cli-kvzgak7c.js";
-import"./cli-qp2m4btv.js";
-import"./cli-vcgscaan.js";
-import"./cli-wt645v7q.js";
-export {
-  isUserAllowed2 as isUserAllowed,
-  registerMessageHandler2 as registerMessageHandler
-};