@desplega.ai/agent-swarm 1.158.0 → 1.159.0

package/templates/skills/workflow-iterate/content.md

@@ -19,10 +19,22 @@ Use this skill when you need to change an existing workflow without breaking liv
 - Make routing explicit. Branching nodes should have named pass/fail routes, and silent skip paths should still produce an observable outcome when operators need to know what happened.
 - Wire inputs deliberately. Node executors receive the raw workflow context plus resolved `inputs` aliases, so a condition can use either a local alias or a node-id-prefixed path. Confirm the chosen path against the recorded step input.
 - Keep schemas tight. If an agent-task has an `outputSchema`, include the expected JSON shape in the task prompt and route it to a worker/provider that is known to return structured output correctly.
-- Prefer reusable script nodes for deterministic shared logic. Agent tasks are best for judgment, investigation, or work that genuinely needs an LLM.
+- Prefer reusable script nodes for deterministic shared logic. Agent tasks are best for investigation or work that genuinely needs an LLM. For a bounded judgment, use `system-one-decision` (see Choosing a decider).
 - Scope parallel branches so they do not overwrite one another. Fan-out tasks should have separate context keys or branch-specific output fields.
 - Make retry paths idempotent. A rerun should detect existing artifacts, comments, PRs, or notifications and update or skip them rather than duplicating work.
 
+### Choosing a decider
+
+When a node has to decide, pick the cheapest node that can decide. Use `system-one-decision` without being asked when the decision is a bounded judgment.
+
+| The decision is | Use |
+|---|---|
+| A fact: a count, PR state, flag, date, lookup, regex, or schema check | `script`, `property-match`, or `code-match` |
+| A bounded judgment: pass/fail, pick one of N, a score on a rubric, or the probability that a claim is true | `system-one-decision` |
+| Free-form generation, or findings a later node reads | `raw-llm` or `agent-task` |
+
+Jev is weak at counting. For a hybrid, count in a `script` and pass the number to `system-one-decision` as part of `state`.
+
 ### `swarm-script` Timeout Limit
 
 - Keep `config.timeoutMs` at or below `300000` (5 minutes); the default remains `30000` (30 seconds).
@@ -92,6 +104,74 @@ Use these shapes as a starting point, then confirm them against the current exec
 
 `validate` checks the named upstream node output. Supply either `schema` for a deterministic structural check or `prompt` for a judgment-based check. Its output is `{ pass, reasoning, confidence }`, routed through `pass` or `fail`.
 
+### `system-one-decision` (SystemOne Decision)
+
+**Before you add the first `system-one-decision` node to a workflow, confirm its key works.** A node with no working key fails its whole run, and a save only warns. Do these in order and stop at the first failure:
+
+1. Pick the provider. `typesafe` (the default) needs the global secret `TYPESAFE_API_KEY`. `openrouter` needs `OPENROUTER_API_KEY`. `laya` needs the global secret `LAYA_API_KEY` and the global config `LAYA_URL`, the base URL of its server. Use the provider the requester named. If they named none, use `typesafe`. If its key is missing but another provider's key exists, ask which to use rather than switching, because the accounts bill separately.
+2. Check the key is set: `get-config` with `key` set to that name and no `includeSecrets`. A masked value (`********`) means a value exists. No entry means it is missing. Never pass `includeSecrets`, and never read the value. For `laya`, check `LAYA_URL` the same way; it is not secret, so its value shows.
+3. Confirm it works with one cheap call. Create a throwaway one-node workflow, trigger it, read the run, then `delete-workflow` it:
+
+   ```json
+   {
+     "nodes": [
+       {
+         "id": "ping",
+         "type": "system-one-decision",
+         "config": {
+           "provider": "typesafe",
+           "state": "ping",
+           "questions": { "ping": { "type": "noul", "instructions": "Is the state the word ping?" } },
+           "returns": { "ping": { "type": "noul" } },
+           "timeoutMs": 15000,
+           "maxRetries": 0
+         }
+       }
+     ]
+   }
+   ```
+
+   A `completed` run means the key works. A `failed` run carries the reason: `<KEY> is not configured` (missing; for `laya` it can name `LAYA_URL` or `LAYA_API_KEY`, or both), or `<KEY> was rejected by <host> (HTTP 401)` (present but refused). To probe `laya`, set `"provider": "laya"` in the ping node. If `create-workflow` says `system-one-decision` is an unregistered executor type, the node is not deployed on this swarm yet: stop and say so.
+4. If the key is missing or was rejected, **do not build the node.** Ask a human for the key with `request-human-input` or in the thread. Name the exact key and where it goes: the Secrets page (Settings > Secrets), or for `LAYA_URL` a global config value (`set-config`, scope `global`). Never ask them to paste it into chat, a task, or a definition, and never write a key into a definition.
+
+Afterwards, a `warnings` entry on `create-workflow` or a patch tool means the key went missing since you checked. Treat it as step 4.
+
+```json
+{
+  "type": "system-one-decision",
+  "inputs": { "pr": "trigger.pullRequest" },
+  "config": {
+    "provider": "typesafe",
+    "model": "jev-1.13.0",
+    "state": "{{pr}}",
+    "questions": {
+      "ready": {
+        "type": "noul",
+        "instructions": "Is this pull request ready to merge?",
+        "criteria": { "true": "Tests pass and the change matches its description", "false": "Missing tests or scope creep" }
+      },
+      "risk": {
+        "type": "choice",
+        "instructions": "How risky is this change?",
+        "criteria": { "low": "Docs or tests only", "medium": "Contained behavior change", "high": "Touches auth, data, or billing" }
+      }
+    },
+    "returns": { "ready": { "type": "noul" }, "risk": { "type": "choice" } }
+  },
+  "next": "gate"
+}
+```
+
+- `provider` is `typesafe` (default), `openrouter`, or `laya`, and must be a literal, not a `{{token}}`. `model` is that provider's own id (`jev-1.13.0` on `typesafe`, `typesafe/jev-1.13` on `openrouter`, a checkpoint name such as `multilingual` on `laya`); leave it unset for the provider's default. `laya` has no default and sends no `model`, because it silently ignores one it does not know: leave it unset unless you mean a specific checkpoint. All three take the same request and return the same answers. There is no fallback between them. Never use OpenRouter's `typesafe/jev-router`, which is a chat router that hands the request to another model.
+- `state` is required: text, a string array, or a JSON object. An exact `{{token}}` keeps the upstream JSON type. Every question in one call shares the state and cannot see the other answers, so a dependent judgment needs its own node.
+- Each question is `noul` (probability that a claim is true; optional `criteria: { true, false }`), `choice` (2 to 255 options; `criteria: { option: description }`), or `score` (2 to 10 ordered levels; `criteria: [level, ...]`).
+- `returns` repeats every question id and its type. A mismatch is rejected when the workflow is saved.
+- The output is `{ model, answers, usage }`, plus `routing: { model }` on `laya` (the checkpoint that answered). Read a field as `<node-id>.answers.<question>.<field>`, for example `qualification.answers.risk.confidence`. A `noul` answer is only `{ type, noul }` and has no confidence. A `choice` answer has `choice`, `probabilities`, and `confidence`. A `score` answer has `score`, `legend`, `probabilities`, and `confidence`.
+- A valid low-confidence answer is a success. To have a person review the uncertain ones, set `humanReview` on the node (below). To route on a threshold yourself, keep it in the next node: `property-match` (`gt`, `lt`) or `code-match`, with the uncertain band routed to `human-in-the-loop`. Do not invent a global threshold.
+- `humanReview: { band: { min, max }, approvers, title?, timeout?, notifications? }` sends an answer to a person when `min <= confidence <= max` (0 to 1, both ends inside). It raises a `human-in-the-loop` approval (same approvers, timeout, notifications, `waiting` run state), so use the same `approvers` shape. `choice` and `score` are tested on their `confidence` (on `laya` that is its `answer_confidence`, the top probability); a `noul` on `max(noul, 1 - noul)`. Any answer in the band makes the run wait. `next` must then be a port map: `approved` (required, every accepted answer), and optionally `rejected` and `timeout`; a string or list `next` is refused. The output stays `{ model, answers, usage }` on every path, plus `review` (`status`, and per question `confidence`, `inBand`, `decidedBy`). A person's answer replaces the model's in `answers`; `probabilities` and `confidence` stay the model's.
+- Do not set `retry` or `validation.retry` on a `system-one-decision` node. It retries connection errors, 408, 429, and 5xx itself (`config.maxRetries`, 0 to 3, default 2) inside `config.timeoutMs` (default 30000). A 401, a 422, or an answer that fails validation ends after one attempt.
+- The node reads its provider's key (`TYPESAFE_API_KEY`, `OPENROUTER_API_KEY`, or `LAYA_API_KEY`, and for `laya` the server URL `LAYA_URL`) server-side. The key never appears in the definition, the step output, or an error. A run whose key or `LAYA_URL` is missing fails before any node executes, and a 401 or 403 fails the step as `<KEY> was rejected`. An unresolved `{{token}}` fails the step before any request.
+
 ### `swarm-script`
 
 ```json

package/templates/workflows/claude-code-changelog-watch/content.md

@@ -2,6 +2,8 @@
 
 This topology-preserving self-hosted port removes installation-specific identities, endpoints, and credentials while retaining the live workflow's nodes, edges, input mappings, guards, retries, cooldown, and triggers. Configure the declared template parameters and integrations before enabling it.
 
+Prerequisite: the `check` and `commit` nodes run the global script `claude-code-changelog-check`, which is not seeded. Author it before enabling the workflow, or every run fails at the first node.
+
 ```json
 {"name":"claude-code-changelog-watch","description":"Changelog watcher with deduplication: fetch, gate on a new version, publish an in-app receipt plus any configured delivery providers, then commit the version marker.","nodes":[{"id":"check","type":"swarm-script","label":"Fetch changelog + compare vs KV","config":{"scriptName":"claude-code-changelog-check","scope":"global","args":{"mode":"check"}},"next":"gate"},{"id":"gate","type":"property-match","label":"Gate: only continue on a new version","config":{"mode":"all","conditions":[{"field":"check.result.isNew","op":"eq","value":true}]},"next":{"true":"post"}},{"id":"post","type":"agent-task","label":"Post new version to Slack","config":{"model":"sonnet","tags":["changelog","claude-code","workflow"],"priority":50,"template":"**Claude Code new version announcement**\n\nA new Claude Code version was detected by the claude-code-changelog-watch workflow.\n\nNew version: {{check.result.latestVersion}} (released {{check.result.releaseDate}}, previous known: {{check.result.lastKnown}})\n\nRaw release notes:\n{{check.result.section}}\n\nSteps:\n1. ONE `slack-post` to the configured Slack notification target, **max 400 chars**:\n\n```\n:rocket: *Claude Code {{check.result.latestVersion}}* — <the one change that matters to us, one line>\n<https://code.claude.com/docs/en/changelog|changelog>\n```\n\nRules:\n- **One line.** Pick the single item that affects how we run the swarm (a fix we were hitting, a flag we use, a breaking change). Not 3-5 bullets.\n- If a second item genuinely matters, one more bullet. Never more than two.\n- **Routine release with nothing relevant to us ⇒ still post, but the one line is just the headline feature.** Never paste the release notes.\n- No preamble, no \"is out!\", no per-surface breakdown (VSCode/CLI/SDK), no closing line.\n\n2. Complete with output \"Posted Claude Code {{check.result.latestVersion}} to in-app activity and configured delivery providers.\" plus the charCount.\n\nDo NOT update any version state — the workflow's commit node handles that after you complete. Do NOT post more than once."},"next":"commit","inputs":{"check":"check"}},{"id":"commit","type":"swarm-script","label":"Commit new version to KV","config":{"scriptName":"claude-code-changelog-check","scope":"global","args":{"mode":"commit","version":"{{check.result.latestVersion}}"}},"inputs":{"check":"check"}}],"onNodeFailure":"fail"}
 ```

package/templates/workflows/pr-review-status-sweep/content.md

@@ -2,6 +2,8 @@
 
 This topology-preserving self-hosted port removes installation-specific identities, endpoints, and credentials while retaining the live workflow's nodes, edges, input mappings, guards, retries, cooldown, and triggers. Configure the declared template parameters and integrations before enabling it.
 
+Prerequisite: the `sweep` node runs the agent-scoped script `pr-review-status-sweep`, which is not seeded. Author it before enabling the workflow, or every run fails at that node.
+
 ```json
 {"name":"pr-review-status-sweep","description":"Cron-triggered deterministic sweep for {{REPO_URL}} open PRs. The steady-state path is swarm-script only: enumerate non-draft PRs, run global pr-review-status, enforce KV run/per-PR leases and idempotency markers, and stay silent on clean sweeps. The single Phase A agent-task node is gated on actionableCount > 0. Phase B is disabled: no auto-push, no merge, no thread resolution.","nodes":[{"id":"sweep","type":"swarm-script","label":"Deterministic PR review action-item sweep","config":{"scriptName":"pr-review-status-sweep","scope":"agent","args":{"repo":"{{REPO_URL}}","limit":50,"phaseBEnabled":false,"slackChannelId":null,"slackThreadTs":null}},"next":"has-action-items"},{"id":"has-action-items","type":"property-match","label":"Gate: only continue when actionItems > 0","config":{"mode":"all","conditions":[{"field":"sweep.result.actionableCount","op":"gt","value":0}]},"next":{"true":"handle-action-items"}},{"id":"handle-action-items","type":"agent-task","label":"Phase A handler for unprocessed review action items","config":{"template":"{{sweep.result.handlerPrompt}}","tags":["pr-review-status","phase-a","review-action-items"],"priority":60,"dir":"/workspace/repository","vcsRepo":"{{REPO_URL}}","model":"gpt-5.5"},"inputs":{"sweep":"sweep"}}],"onNodeFailure":"fail"}
 ```