@signalridge/pi-workflows 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.3.1
+### Patch Changes
+
+- 7d2c6c9: Keep generated workflow capability references synchronized when Changesets versions the package.
+
+## 1.3.0
+### Minor Changes
+
+- bae8689: Complete the managed workflow parity and hardening pass. Workflows now forward and validate exact model/thinking, toolset, denylist, thread, and per-call worktree intent while pi-subagents remains the policy and lifecycle owner. Script resume accepts edited revisions, workflow removal is durable, stale lifecycle events are rejected, provider-limit errors pause runs, and the live progress/effort/trigger settings are persisted and bounded. Run identity is durable before dispatch, pause/dispose stop owned agents and reject waiters, and every background start/resume delivers its result. The protocol adds only optional fields and capability metadata, preserving older policy-free managed-spawn consumers; workflows fail closed with a diagnostic when the peer does not advertise managed policy support.
+- b6cf242: Rewrite `pi-workflows` from a declarative DAG engine to a JavaScript orchestration runtime.
+  
+  - **Scripts, not DAGs**: a workflow is now a raw JavaScript module executed in a determinism-guarded `node:vm` realm. The script declares `export const meta = { name, description, phases }` first and uses runtime globals `agent()`, `parallel()`, `pipeline()`, `workflow()`, `verify()`, `judgePanel()`, `loopUntilDry()`, `completenessCheck()`, `retry()`, `gate()`, `checkpoint()`, `phase()`, `log()`, `args`, `cwd`, restricted `process`, and `budget`. The `workflow` tool takes `script`/`name`/`args`/`background`/`maxAgents`/`concurrency`/`agentRetries`/`tokenBudget`/`agentTimeoutMs`/`resumeFromRunId` instead of `tasks`/`phases`/`synthesis`.
+  - **Determinism guardrail**: `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable (regex precheck plus in-realm stubs); `new Date(arg)`, `Date.UTC`, and `Date.parse` still work. The meta contract rejects spread, computed keys, methods, template interpolation, and `__proto__`/`constructor`/`prototype`.
+  - **Resume with cache replay**: an edited script replays the longest unchanged prefix from the journal (zero tokens for replayed calls) and runs live from the first changed or inserted call. Journal schema v2→v3: `run_created` carries the script text, hash, and meta; call identity is the lexical call index; each completed `agent()`/`checkpoint()` call journals `{ index, runId, callHash, result, storeDelta }`. Schema-v2 (declarative) journals are quarantined rather than replayed.
+  - **Spawn-key generation rotation (A4)**: live dispatches use `${runId}/call-${callIndex}/attempt-${generation}`; a resume of an edited call rotates the generation so pi-subagents never raises a fingerprint conflict. Per-call store deltas replay additively in call order.
+  - **Command surface expanded to 11+**: `/workflows` now supports `run`, `status`, `watch`, `stop`, `pause`, `resume`, `rm`, and `save <name> [runId]` subcommands; new `/workflows-models`, `/workflows-trigger` (persisted keyword arming via an input hook), `/workflows-progress`, `/effort`, `/ultracode`, the five built-in workflow commands (`/deep-research`, `/adversarial-review`, `/code-review`, `/multi-perspective`, `/codebase-audit`), and one command per saved workflow registered at `session_start` with name-clash checks. `stop` and `rm` are destructive and take no implicit target — a bare `/workflows rm` asks for a run id rather than acting on the first listed run; the reversible `pause` and `resume` still default to it. Each builtin command routes its free text to the `args` key its own script reads (`question`, `task`, `topic`, `scope`) rather than a generic `prompt` no script consumes, and a builtin whose name another extension already registered is skipped rather than clobbered, since Pi cannot unregister commands.
+  - **`/code-review` resolves its own diff**: no argument auto-scopes `git diff HEAD` with generated and vendored artifacts excluded; a numeric argument reads `gh pr diff <n>`; an argument containing `..` reads that revision range; anything else is a path. It degrades to the unscoped `git diff HEAD` when the auto scope fails or when the exclusions emptied a non-empty diff, reports a genuinely clean tree as clean rather than as a degradation, and caps the diff before handing it to the review agents. Commands run as argv arrays, never shell strings.
+  - **Keyword arming authorizes the tool rather than opening UI**: typing the bounded word `workflow`/`workflows` annotates the message to tell the model the `workflow` tool is available for this turn, with an explicit escape hatch so a conversational or trivial turn is still answered directly. Matching uses token boundaries that treat identifier, path, and flag punctuation as part of the token, so `myworkflow`, `workflow_name`, `WorkflowEngine`, `--workflow-id`, `src/workflow-editor.ts`, `workflow.ts`, and the `/workflows` command never arm — while a sentence-ending dot ("run a workflow.") still does. `/workflows-trigger` takes `set <word>` (matched exactly; only the default word also matches its plural), `off`, and `on`. Extension-submitted text never arms, and an already-annotated message cannot stack a second directive.
+  - **Saved workflows (A7)**: project scope takes precedence over user scope, persisted under the package-owned workflow directories with atomic writes and backups; nested `workflow(savedName, args)` calls are one level deep.
+  - **UI (A10)**: the navigator renders runs → phases → calls → detail; a live widget shows active runs and clears when idle; background-run results deliver through a session-bound endpoint, falling back to a durable marker when no endpoint is bound yet. Child-agent output still passes through `safe-text.ts` before truncation.
+  - **Capability contract (A11)**: a machine-readable declaration is the single source of truth for the runtime surface; the runtime validates its bindings against it at run start, so docs and reality cannot drift.
+  
+  Intentional adaptations from upstream (documented in the README): no host-side web tools (agents reach the web via configured tools / MCP), no duplicate agent registry (agentType resolves in pi-subagents), and no second model-tier catalogue (tier routing uses pi-subagents' `workflow.tiers`). The managed protocol now carries optional exact model/thinking, toolset, denylist, thread, and worktree requests while pi-subagents retains final policy ownership.
+
+### Patch Changes
+
+- b6cf242: Peer dependency ranges now name the versions actually validated against, so an untested host combination fails at install time instead of silently at runtime: `@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui`, and `pi-agent-core` move from `"*"` to `^0.84.0`, and `typebox` from `"*"` to `^1.3.11`.
+  
+  Shared dependencies now carry ONE declared range across every package that uses them, and `bun run check:shared-deps` keeps it that way.
+  
+  `@narumitw/pi-tui-kit` was declared at three disjoint floors — `^0.54.0`, `^0.51.0`, and `^0.49.1` across nine packages — and the lockfile duly resolved three copies (0.54.0, 0.51.0, 0.49.3) installed side by side. For a shared rendering surface drawing into one terminal inside one host process, that means a theme rendering one way in one extension and another way in the next, with nothing failing at install to say so. All nine now declare `^0.54.0` and the install resolves a single copy. `@sinclair/typebox` likewise converges on `^0.34.50`.
+  
+  The new check covers `dependencies` and `peerDependencies` and compares range strings rather than their semantics: two ranges that merely overlap are still a finding, because the goal is one intentional answer per dependency rather than an accidental intersection. `devDependencies` are deliberately out of scope — a build tool is not a shared surface, and `pi-subagents` intentionally carries its own toolchain. `docs/package-boundaries.md` documents the Kit as a shared surface for the first time.
+- Updated dependencies [bae8689]
+  - @signalridge/pi-subagents-protocol@1.3.0
+
 ## 1.2.1
 ### Patch Changes
 

package/README.md

@@ -1,10 +1,21 @@
 # @signalridge/pi-workflows
 
-Declarative DAG orchestration for Pi. The `workflow` tool validates phases, task dependencies, cycles, bounded synthesis input, and optional `small`/`medium`/`large` semantic tiers, then submits ready tasks through the additive `subagents:rpc:spawn-managed` event-bus protocol. `pi-subagents` remains the only owner of model, thinking, queue, concurrency, tools, skills, cwd, isolation, retry, and session policy.
+JavaScript orchestration for Pi. A workflow is a raw JavaScript module executed
+in a determinism-guarded `node:vm` realm; the runtime supplies `agent()`,
+`parallel()`, `pipeline()`, `workflow()`, quality helpers (`verify`,
+`judgePanel`, `loopUntilDry`, `completenessCheck`, `retry`, `gate`), human
+`checkpoint()`, `phase()`, `log()`, `args`, `cwd`, restricted `process`, and
+`budget`. Every live `agent()` call is dispatched through the additive
+`subagents:rpc:spawn-managed` event-bus protocol — `pi-subagents` remains the
+only owner of model, thinking, queue, concurrency, tools, skills, cwd,
+isolation, retry, and session policy.
 
 ## Install
 
-`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=1.0.0` with protocol v3 managed-spawn support. They are separate Pi packages: the peer dependency documents the requirement but intentionally does not auto-load or duplicate the subagent extension.
+`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=1.5.0`
+with protocol v3 managed-spawn, workflow-tier, and managed-policy support. They are separate Pi packages: the peer
+dependency documents the requirement but intentionally does not auto-load or
+duplicate the subagent extension.
 
 ```bash
 pi install npm:@signalridge/pi-subagents
@@ -13,29 +24,143 @@ pi install npm:@signalridge/pi-workflows
 
 ## Use from this checkout
 
-From the repository root, load both local package directories once:
+From the repository root, load both local package directories once. Disable
+extension discovery so the npm-installed copies do not also load — an npm copy
+of one alongside a local checkout of the other loads both, and the duplicate
+registers its tools twice:
 
 ```bash
-pi -e ./packages/pi-subagents
-pi -e ./packages/pi-workflows
+pi -ne -e ./packages/pi-subagents -e ./packages/pi-workflows
 ```
 
-Pi activates each package from its own `pi.extensions` manifest. Install `pi-workflows` and `pi-subagents` from the same source — an npm copy of one alongside a local checkout of the other loads both, and the duplicate registers its tools twice.
+`-ne` skips the installed extension catalogue while keeping explicit `-e`
+paths; without it, first remove the installed copies (`pi remove
+@signalridge/pi-subagents @signalridge/pi-workflows`) or accept duplicate tool
+registration.
 
-At `session_start`, this extension sends `subagents:rpc:ping` and verifies protocol version 3 plus the `managedSpawn`, `lifecycleOwner`, owner-scoped `ownedStop`, `ownedQuiescence`, and `workflowTiers` capabilities. The package floor and capability check prevent older v3 peers from receiving tiered requests they cannot validate. If the fork is missing, old, or duplicated incorrectly, workflow execution returns a diagnostic naming the required packages instead of dispatching agents. The legacy unowned stop RPC remains available to older external callers, but workflow cleanup never falls back to it.
+Pi activates each package from its own `pi.extensions` manifest.
 
-## Tools and command
+## Writing a workflow
 
-- `workflow`: run a foreground or background workflow. `depends_on` is a scheduling barrier only. A task may additionally declare `inputs`, a duplicate-free subset of its own `depends_on`, to have those dependencies' journaled results appended to its dispatch prompt: each result is capped at 6,000 characters, the appended section at 24,000, and the whole prompt at the protocol's 100,000-character ceiling. When the task prompt leaves less than 512 characters of headroom, nothing is appended and the prompt dispatches unchanged. Omitting `inputs` dispatches exactly the authored prompt.
-- `workflow_control`: `list`, `get`, `pause`, `resume`, or `stop` a run. `get` returns bounded task and synthesis details including status, agent ID, compactions, and result/error previews.
-- `/workflows`: TUI run list/detail navigator. Live agent conversation navigation remains in pi-subagents FleetView.
+A workflow script starts with the only legal export — a literal-only meta
+contract — and then runs inside an async function:
 
-Composed input sections are a pure function of the journaled prefix — declared `inputs` order, journaled result fields only — so a replay reproduces the same prompt and the managed spawn fingerprint stays stable across a branch rewind.
+```js
+export const meta = {
+  name: "example",
+  description: "Fan out three checks and synthesize",
+  phases: [{ title: "scan" }, { title: "synthesize" }],
+};
 
-State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries, which do not enter model context. Results and synthesis instructions are capped before journaling or dispatch. Interrupted runs reset unreconciled dispatches to a recoverable state and reuse their managed spawn keys; completed task facts are not dispatched again. A task failure stops remaining owned agents, journals their terminal callbacks, blocks dependents, and settles the workflow as failed.
-Restore rotation is journaled atomically per run (`run_recovery`) so a failed append leaves no partial generation; older multi-entry recovery prefixes remain replayable and are migrated with independent `attempt_recovery` entries.
-Each atomic recovery also carries a deterministic bounded `recoveryId` derived from its branch/run and attempt rotations. Replay treats an exact normalized duplicate as a no-op, quarantines same-ID conflicts, and accepts older schema-v2 atomic entries without an ID only through deterministic legacy normalization.
-Managed lifecycle calls are owner-scoped to the exact `{ runId, nodeId, attemptId }` generation. Branch replacement stops/quiesces owned agents and tracks in-flight dispatch RPCs; if a peer cannot settle, the run is quarantined conservatively and late lifecycle or spawn replies are ignored. Foreground `AbortSignal`s cancel only the caller's wait. The session signal may cancel an outstanding RPC wait during shutdown, but neither signal is used to cancel a managed child; explicit stop/quiescence owns child cancellation.
+phase("scan");
+const findings = await parallel([
+  () => agent("Check for cross-package imports", { label: "imports", tier: "small" }),
+  () => agent("Check for secrets", { label: "secrets", tier: "small" }),
+  () => agent("Check for dead code", { label: "dead-code", tier: "small" }),
+]);
 
+phase("synthesize");
+const report = await agent("Summarize the findings: " + JSON.stringify(findings), {
+  label: "report",
+});
+return report;
+```
+
+The meta statement must be the first statement and use only literals — spread,
+computed keys, methods, template interpolation, and the reserved keys
+`__proto__`/`constructor`/`prototype` are rejected. `Date.now()`,
+`Math.random()`, and no-argument `new Date()` are unavailable (a regex precheck
+plus in-realm stubs); pass timestamps and randomness through `args`. The vm is
+a determinism guardrail, not a security boundary — scripts are generated by the
+user's own LLM and run on the user's own machine.
+
+### Runtime globals
+
+- `agent(prompt, { label, phase, schema, model, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
+  — dispatch one subagent through the managed spawn protocol. Returns text, a
+  schema-validated value, or recoverable `null` after retries. `schema` is a
+  plain JSON Schema; the reply is parsed and validated client-side with bounded
+  repair across attempts, and exhaustion throws `SCHEMA_NONCOMPLIANCE`.
+  Explicit `model` and `isolation: "worktree"` are resolved and enforced by pi-subagents; `tier` remains the provider-neutral route.
+  `tier`; see "Model routing"). `thread` chains sequential turns within a named
+  conversation thread.
+- `parallel(thunks)` — run thunks concurrently, preserve input order. Recoverable
+  thunk failures become `null`; non-recoverable failures (token budget, agent
+  limit) halt the run. Fan-out that breaches `maxAgents` cancels only its own
+  batch.
+- `pipeline(items, ...stages)` — items run concurrently, stages per item run
+  sequentially with `(previousValue, originalItem, index)`.
+- `workflow(savedName, childArgs?)` — run a saved workflow inline; one nested
+  level, sharing the limiter, counters, token accounting, and store.
+- `verify(item, { reviewers, threshold, lens })`, `judgePanel(attempts,
+  { judges, rubric })`, `loopUntilDry({ round, key, consecutiveEmpty,
+  maxRounds })`, `completenessCheck(taskArgs, results)`, `retry(thunk,
+  { attempts, until })`, `gate(thunk, validator, { attempts })` — quality
+  helpers built purely on `agent()`/`parallel()` so call sequencing stays
+  stable and resume keeps working.
+- `checkpoint(prompt, { default, headless, kind, choices, timeoutMs })` —
+  journaled human confirmation. Foreground runs thread the real UI; background
+  runs are headless and take the declared `default`.
+- `phase(title, { budget })`, `log(message)`, `args`, `cwd`, `process.cwd()`,
+  `budget` (`{ total, spent(), remaining() }`).
+
+### Resume
+
+A script edit replays the longest unchanged prefix from the journal and runs
+live from the first changed or inserted `agent()`/`checkpoint()` call. Pass
+`resumeFromRunId` with the edited script; unchanged calls report zero tokens,
+and edited calls rotate their managed spawn key generation so pi-subagents
+never raises a fingerprint conflict.
+
+## Tools and commands
+
+- `workflow`: run a script (`script`) or a saved/built-in workflow (`name`),
+  with `args`, `background` (default true), `maxAgents`, `concurrency`,
+  `agentRetries`, `tokenBudget`, `agentTimeoutMs`, and `resumeFromRunId`.
+- `workflow_control`: `list`, `get`, `pause`, `resume`, `stop`, or `rm` a run; `rm` writes a durable removal tombstone.
+- `/workflows`: TUI navigator plus `run`, `status`, `watch`, `stop`, `pause`,
+  `resume`, `rm`, and `save <name> [runId]` subcommands.
+- `/workflows-models`: points at pi-subagents' `/agents → Model tiers` — there
+  is deliberately no second tier configuration file.
+- `/effort` and `/ultracode`: standing `off|high|ultra` effort guidance that auto-arms substantive messages.
+- `/workflows-progress`: `compact|detailed|status|max <N>` controls the persisted live panel.
+- `/deep-research`, `/adversarial-review`, `/code-review`,
+  `/multi-perspective`, `/codebase-audit`: the five built-in workflows. A
+  saved workflow with the same name takes precedence.
+- `/workflows-trigger`: `set <keyword>`, `off`, or `on`. See keyword arming below.
+- `/<saved-name>`: every saved workflow registers its own slash command at
+  `session_start` (Pi cannot unregister commands, so registration happens there
+  rather than at factory time, and existing commands are never overwritten).
+
+### Keyword arming
+
+Typing the bounded word `workflow` or `workflows` in an ordinary message counts
+as an explicit opt-in to multi-agent orchestration: the message is annotated to
+tell the model the `workflow` tool is authorized for this turn.
+
+Arming **authorizes; it does not compel**. The annotation says the model may run
+a workflow and may still decline, so "how do workflows work?" stays an ordinary
+question with an ordinary answer. Nothing is swallowed and no UI opens.
+
+Only a standalone word arms. A workflow is also a thing people write code about,
+so none of `myworkflow`, `workflow_name`, `WorkflowEngine`, `--workflow-id`,
+`src/workflow-editor.ts`, `workflow.ts`, or the `/workflows` command matches. A
+sentence-ending dot is not a filename dot: "please run a workflow." arms, and
+`workflow.json` does not. Set a different word with `/workflows-trigger set
+<word>` (matched exactly — only the default word also matches its plural) or
+turn it off entirely with `/workflows-trigger off`.
+
+Saved workflows use project scope first and a user scope fallback; writes are atomic and names are path-safe.
+written atomically with a backup.
+
+## Model routing
+
+The managed protocol carries semantic tiers plus optional exact model/thinking, toolset, denylist, thread, and worktree requests. pi-subagents resolves model references, validates scope, creates/cleans worktrees, and owns tool/session policy. Workflows fail closed with a diagnostic when the peer does not advertise managed-policy support; explicit selectors otherwise fail closed when unavailable, and workflows never bypass the companion's policy.
+
+## Intentional adaptations from upstream
+
+- **No host-side web tools.** Agents reach the web through configured pi-web-access/MCP tools or an agent type's tool policy.
+- **Agent registry and tier catalogue ownership.** `agentType` and `small|medium|large` profiles resolve in pi-subagents, avoiding a second registry/config schema.
+- **Schema validation is client-side.** The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including `additionalProperties`), and repairs across bounded attempts.
 
-Interrupted-attempt recovery is intentionally bounded to three generations per task, including synthesis. Normal interruptions retry with a fresh managed attempt; if the same node is interrupted repeatedly beyond that bound, the workflow fails safely instead of creating an unbounded outer retry loop.
+State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v3), including script revisions and durable removals. Interrupted/provider-limited runs replay from the journal; schema-v2 declarative journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.2.1",
-  "description": "Declarative DAG workflows backed by pi-subagents managed spawning.",
+  "version": "1.3.1",
+  "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
   "private": false,
@@ -15,17 +15,22 @@
     "lifecycle": "stable"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "@signalridge/pi-subagents": ">=1.0.0"
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
+    "@signalridge/pi-subagents": ">=1.5.0"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.49",
-    "@signalridge/pi-subagents-protocol": "^1.0.0"
+    "@signalridge/pi-subagents-protocol": "^1.3.0",
+    "@sinclair/typebox": "^0.34.50",
+    "acorn": "^8.16.0"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "skills/workflow-authoring",
+      "skills/workflow-patterns"
     ]
   },
   "repository": {
@@ -44,7 +49,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "src"
+    "src",
+    "skills"
   ],
   "scripts": {
     "test": "vitest run test --config vitest.config.ts",

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: workflow-authoring
+description: Guidance for writing, editing, reviewing, and debugging JavaScript workflow code for @signalridge/pi-workflows. Use when authoring or changing workflow scripts; not for merely running an existing workflow.
+metadata:
+  version: "1.2.1"
+---
+
+# Workflow authoring
+
+Load this skill when workflow JavaScript changes. Running an existing workflow needs no authoring reference.
+
+## Choose a branch
+
+Read only what the task needs:
+
+- **Write or edit:** start with [runtime](references/runtime.md). Add [pattern selection](references/pattern-selection.md) for topology, [lifecycle](references/lifecycle.md) for limits or resume, and [focused recipes](references/focused-recipes.md) for the matching concern.
+- **Helper task:** read [quality helpers](references/quality-helpers.md) only for `verify` or `judgePanel`, the [retry helper](references/retry-helper.md) only for `retry`, and [specialized helpers](references/specialized-helpers.md) only for `completenessCheck`, `loopUntilDry`, `gate`, or `checkpoint`.
+- **Review:** use the [review checklist](references/review.md), plus only the matching [quality](references/quality-helpers.md) or [specialized](references/specialized-helpers.md) helper contracts.
+- **Debug:** use the [debugging map](references/debugging.md).
+- **Routing:** read [registry ownership](references/registry-ownership.md) before using `model`, `tier`, phase models, or `agentType`; use environment-specific names only when context supplies them.
+- **Exact lookup or portability:** start with the generated [capability index](references/capabilities.md). Follow its exhaustive-facts pointer only for constraints or support boundaries. Use [versions](references/versions.md) when moving scripts between installations.
+
+## Invariants
+
+- Start with literal `export const meta = { name, description }`; declare phases as an array of used `{ title }` objects and enter each named phase.
+- Call `agent()` at least once, give every call a short unique `label`, and return plain JSON data explicitly.
+- Pair ordered results with stable work IDs before filtering. When one agent consumes another's selected result, include both its stable ID and actual data in the downstream prompt. Treat recoverable `null` as missing coverage and report it.
+- Bound fan-out, loops, retries, agents, and concurrency to the task. Treat invocation-level token and time caps as opt-in user constraints, not defaults.
+- Use `log()` for new code; `console` is compatibility-only.
+- Write plain JavaScript without imports or filesystem modules. Pass nondeterminism through `args`; `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable.

package/skills/workflow-authoring/examples/adversarial-verification.js

@@ -0,0 +1,63 @@
+export const meta = {
+  name: "adversarial_verification",
+  description: "Produce claims and challenge them in separate skeptical contexts",
+  phases: [{ title: "Produce" }, { title: "Verify" }],
+};
+
+// ADAPT: validate and bound topics; define the evidence standard and schemas.
+const topics =
+  args && Array.isArray(args.topics) ? args.topics : [{ id: "sample", topic: "Verify one sample claim" }];
+const rubric = args && typeof args.rubric === "string" ? args.rubric : "Evidence is direct and sufficient";
+const productionSchema = {
+  type: "object",
+  properties: {
+    claim: { type: "string" },
+    evidence: { type: "array", items: { type: "string" } },
+  },
+  required: ["claim", "evidence"],
+};
+const verdictSchema = {
+  type: "object",
+  properties: { upheld: { type: "boolean" }, reason: { type: "string" } },
+  required: ["upheld", "reason"],
+};
+
+phase("Produce");
+const productions = await parallel(
+  topics.map((topic, index) => () =>
+    agent(`Develop a claim and cite its evidence.\n\n${JSON.stringify(topic)}`, {
+      label: `produce:${index}:${String(topic.id)}`,
+      schema: productionSchema,
+    }),
+  ),
+);
+const producerFailures = topics.flatMap((topic, index) =>
+  productions[index] === null ? [String(topic.id)] : [],
+);
+const reviewable = topics.flatMap((topic, index) =>
+  productions[index] === null ? [] : [{ topic, production: productions[index] }],
+);
+
+phase("Verify");
+// INVARIANT: each skeptic is a fresh agent call, never the producer reviewing itself.
+const verdicts = await parallel(
+  reviewable.map(({ topic, production }, index) => () =>
+    agent(
+      `Act as a skeptic. Try to refute this production under the rubric.\nRubric: ${rubric}\nProduction: ${JSON.stringify(production)}`,
+      { label: `skeptic:${index}:${String(topic.id)}`, schema: verdictSchema },
+    ),
+  ),
+);
+const skepticFailures = reviewable.flatMap(({ topic }, index) =>
+  verdicts[index] === null ? [String(topic.id)] : [],
+);
+
+return {
+  reviewed: reviewable.flatMap(({ topic, production }, index) =>
+    verdicts[index] === null
+      ? []
+      : [{ id: String(topic.id), production, verdict: verdicts[index] }],
+  ),
+  failed: { producers: producerFailures, skeptics: skepticFailures },
+  complete: producerFailures.length === 0 && skepticFailures.length === 0,
+};

package/skills/workflow-authoring/examples/bounded-semantic-retry.js

@@ -0,0 +1,56 @@
+export const meta = {
+  name: "bounded_semantic_retry",
+  description: "Separate recoverable transport retries from a visible bounded semantic attempt ledger",
+  phases: [{ title: "Attempt" }],
+};
+
+// ADAPT: define task-owned acceptance, prompts, bounds, and structured result fields.
+const maxSemanticAttempts =
+  args && Number.isInteger(args.maxSemanticAttempts) ? Math.max(1, Math.min(args.maxSemanticAttempts, 5)) : 3;
+const transportRetries =
+  args && Number.isInteger(args.transportRetries) ? Math.max(0, Math.min(args.transportRetries, 3)) : 0;
+const resultSchema = {
+  type: "object",
+  properties: {
+    accepted: { type: "boolean" },
+    answer: { type: "string" },
+    feedback: { type: "string" },
+  },
+  required: ["accepted", "answer", "feedback"],
+};
+const attempts = [];
+let feedback = "";
+let acceptedResult = null;
+
+phase("Attempt");
+for (let attempt = 1; attempt <= maxSemanticAttempts; attempt++) {
+  const result = await agent(
+    `Produce an acceptable answer.${feedback ? ` Address this prior feedback: ${feedback}` : ""}`,
+    {
+      label: `semantic-attempt:${attempt}`,
+      schema: resultSchema,
+      // Runtime retries repeat this same logical call after recoverable execution failures.
+      retries: transportRetries,
+    },
+  );
+  if (result === null) {
+    attempts.push({ attempt, status: "missing", result: null });
+    feedback = "The previous logical attempt produced no usable coverage.";
+    continue;
+  }
+  const status = result.accepted ? "accepted" : "rejected";
+  attempts.push({ attempt, status, result });
+  if (result.accepted) {
+    acceptedResult = result;
+    break;
+  }
+  feedback = result.feedback;
+}
+
+// INVARIANT: semantic exhaustion is returned visibly; it is not presented as success or thrown away.
+return {
+  ok: acceptedResult !== null,
+  exhausted: acceptedResult === null && attempts.length === maxSemanticAttempts,
+  result: acceptedResult,
+  attempts,
+};

package/skills/workflow-authoring/examples/classify-and-act.js

@@ -0,0 +1,67 @@
+export const meta = {
+  name: "classify_and_act",
+  description: "Classify bounded work before routing each item to an appropriate actor",
+  phases: [{ title: "Classify" }, { title: "Act" }],
+};
+
+// ADAPT: validate and bound items, categories, prompts, and schemas for the task.
+const items =
+  args && Array.isArray(args.items) ? args.items : [{ id: "sample", task: "Classify one sample item" }];
+const categories = ["direct", "parallel", "iterative"];
+const instructionsByCategory = {
+  direct: "Handle directly in one focused pass.",
+  parallel: "Divide independent parts, account for each part, then combine them.",
+  iterative: "Work in bounded rounds and stop when the task-specific condition is met.",
+};
+const classificationSchema = {
+  type: "object",
+  properties: {
+    category: { type: "string", enum: categories },
+    reason: { type: "string" },
+  },
+  required: ["category", "reason"],
+};
+const actionSchema = {
+  type: "object",
+  properties: { outcome: { type: "string" } },
+  required: ["outcome"],
+};
+
+phase("Classify");
+const classifications = await parallel(
+  items.map((item, index) => () =>
+    agent(`Classify this item as ${categories.join(", ")}.\n\n${JSON.stringify(item)}`, {
+      label: `classify:${index}:${String(item.id)}`,
+      schema: classificationSchema,
+    }),
+  ),
+);
+const failedClassification = items.flatMap((item, index) =>
+  classifications[index] === null ? [String(item.id)] : [],
+);
+const routed = items.flatMap((item, index) =>
+  classifications[index] === null ? [] : [{ item, classification: classifications[index] }],
+);
+
+// INVARIANT: no routed action starts until the complete classification set exists.
+phase("Act");
+const actions = await parallel(
+  routed.map(({ item, classification }, index) => () =>
+    agent(
+      `${instructionsByCategory[classification.category]}\n\n${JSON.stringify(item)}`,
+      { label: `act:${index}:${String(item.id)}`, schema: actionSchema },
+    ),
+  ),
+);
+const failedAction = routed.flatMap(({ item }, index) => (actions[index] === null ? [String(item.id)] : []));
+
+// INVARIANT: retain identities for failures in either stage.
+return {
+  handled: routed.flatMap(({ item, classification }, index) =>
+    actions[index] === null
+      ? []
+      : [{ id: String(item.id), category: classification.category, result: actions[index] }],
+  ),
+  failed: { classification: failedClassification, action: failedAction },
+  complete: failedClassification.length === 0 && failedAction.length === 0,
+};

package/skills/workflow-authoring/examples/defensive-json-parsing.js

@@ -0,0 +1,63 @@
+export const meta = {
+  name: "defensive_json_parsing",
+  description: "Parse agent() text output as JSON defensively when schema isn't used, flagging unparseable results instead of reading undefined fields",
+  phases: [{ title: "Extract" }],
+};
+
+// Asking a model to "return STRICT JSON" in the prompt does not change what
+// agent() gives back: without `schema`, the result is always the assistant's
+// raw text. Reading a field off unparsed text (or off a plain-text agent()
+// call in general) fails silently — `result.verdict` is `undefined`, not an
+// error, and a fleet of such calls can look fully "successful" while every
+// aggregator downstream gets undefined values. Prefer the `schema` option
+// (see structured-output.js) whenever the shape matters; use this pattern
+// only when a schema genuinely isn't available (e.g. an agentType/model that
+// cannot be schema-validated).
+function parseOrFlag(text, requiredKeys) {
+  if (typeof text !== "string") return { ok: false, raw: text };
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fence ? fence[1] : text;
+  let value;
+  try {
+    value = JSON.parse(candidate.trim());
+  } catch {
+    return { ok: false, raw: text };
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return { ok: false, raw: text };
+  for (const key of requiredKeys) {
+    if (!(key in value)) return { ok: false, raw: text };
+  }
+  return { ok: true, value };
+}
+
+// ADAPT: validate and bound work, then keep required fields as small as downstream JavaScript needs.
+const work = args && Array.isArray(args.work) ? args.work.slice(0, 8) : [{ id: "sample" }];
+const requiredKeys = ["verdict", "reason"];
+const outputs = [];
+const missing = [];
+const unparseable = [];
+
+phase("Extract");
+for (let index = 0; index < work.length; index++) {
+  const item = work[index];
+  const id = String(item.id);
+  const result = await agent(
+    `Review this item and return STRICT JSON only, no prose: {"verdict": "pass" | "fail", "reason": string}. Item: ${JSON.stringify(item)}`,
+    { label: `defensive:${index}:${id}` },
+  );
+  if (result === null) {
+    missing.push(id);
+    outputs.push({ id, status: "missing", verdict: null });
+    continue;
+  }
+  const parsed = parseOrFlag(result, requiredKeys);
+  if (!parsed.ok) {
+    unparseable.push(id);
+    outputs.push({ id, status: "unparseable", verdict: null });
+    continue;
+  }
+  // INVARIANT: field access happens only after parseOrFlag confirms the required keys exist.
+  outputs.push({ id, status: "complete", verdict: parsed.value.verdict });
+}
+
+return { outputs, missing, unparseable, complete: missing.length === 0 && unparseable.length === 0 };

package/skills/workflow-authoring/examples/fan-out-and-synthesize.js

@@ -0,0 +1,47 @@
+export const meta = {
+  name: "fan_out_and_synthesize",
+  description: "Run bounded independent work, retain a complete coverage ledger, then synthesize",
+  phases: [{ title: "Fan out" }, { title: "Synthesize" }],
+};
+
+// ADAPT: validate and bound args.work for the task before invoking this workflow.
+const work = args && Array.isArray(args.work) ? args.work : [];
+
+phase("Fan out");
+const fanOutResults = await parallel(
+  work.map((unit, index) => () =>
+    agent(
+      `Complete this independent work unit. Return only evidence relevant to it.\n\n${JSON.stringify(unit)}`,
+      // INVARIANT: index plus a stable task-owned id keeps labels unique.
+      { label: `fanout:${index}:${String(unit.id)}` },
+    ),
+  ),
+);
+
+// INVARIANT: preserve every intended identity before filtering or synthesis.
+const ledger = work.map((unit, index) => ({
+  id: String(unit.id),
+  status: fanOutResults[index] === null ? "failed" : "complete",
+  result: fanOutResults[index],
+}));
+
+phase("Synthesize");
+const synthesis = await agent(
+  `Synthesize the complete fan-out ledger below. Distinguish covered work from failed/missing coverage; do not invent results.\n\n${JSON.stringify(ledger)}`,
+  {
+    label: "synthesize-complete-set",
+    // ADAPT: keep the schema small and aligned with downstream field access.
+    schema: {
+      type: "object",
+      properties: {
+        summary: { type: "string" },
+        coveredIds: { type: "array", items: { type: "string" } },
+        failedIds: { type: "array", items: { type: "string" } },
+      },
+      required: ["summary", "coveredIds", "failedIds"],
+    },
+  },
+);
+
+// INVARIANT: return plain serializable data, including missing-coverage identities.
+return { ledger, synthesis };