@parcha/agentrun-pi 0.1.0-beta.2 → 0.1.0-beta.20

package/README.md

@@ -1,25 +1,25 @@
 # agent.run() + Pi
 
-Describe a task in Pi. AgentRun turns it into a workflow you can inspect and runs its steps using your current Pi model. Requires Node 22.19+ and Pi 0.87.0.
+Describe a task in Pi, inspect the workflow, run it with your current model, and save its definition for new input. Requires Node 22.19+ and Pi 1.0.4 to below 1.4 (CI tests 1.0.4, 1.1.0, 1.2.0 and 1.3.0).
 
 ## Install
 
-If you do not have Pi, install the tested host version first:
+If you do not have Pi, install it first; 1.3.0 is the newest version CI tests:
 
 ```sh
-npm install -g @earendil-works/pi-coding-agent@0.87.0
+npm install -g @earendil-works/pi-coding-agent@1.3.0
 ```
 
 Then, in your project:
 
 ```sh
-pi install npm:@parcha/agentrun-pi@0.1.0-beta.2 -l
+pi install npm:@parcha/agentrun-pi@beta -l
 pi --offline
 ```
 
 `-l` writes project settings in `.pi/settings.json`. Omit it to install for all your Pi sessions. `--offline` skips startup downloads; it does not disable model calls. No AgentRun checkout or build is needed.
 
-On first launch, Pi asks whether you trust the project before loading its extension. If Pi is already open, use `/reload`. Reloading clears the current workflow definition; run the demo or describe your task again to create one.
+On first launch, Pi asks whether you trust the project before loading its extension. If Pi is already open, use `/reload`. The current draft is restored from a persisted Pi session branch when available; named definition saves are stored separately.
 
 For live tasks, configure model access in Pi first. AgentRun uses Pi's current model and authentication; it needs no separate model configuration. The scripted demo below works without provider access.
 
@@ -29,32 +29,79 @@ Try the bundled example inside Pi:
 /agentrun demo
 ```
 
-The demo shows the workflow graph, progress, and a completed result with call counts. It uses scripted responses over fictional sources. It makes no model calls and does not test model quality. Run `/agentrun status` to check the loaded skill and Pi host version. The tested version is 0.87.0; status flags a different host without blocking it. Missing Pi or Jev access does not prevent the scripted demo. To repeat it, run `/agentrun run` or `/agentrun demo`. A scripted demo stays scripted on rerun, including its missing-evidence path. Use `/agentrun demo live` to switch to real Pi and Jev calls. Workflows authored by Pi use real adapters.
+No Pi session at hand? The same scripted workflow runs from a shell, with no key and no network:
+
+```sh
+npx @parcha/agentrun-pi@beta demo
+```
+
+It prints each sub-question with its answer, then `Status: complete`, the answer and the scripted call counts, and exits 0. `npx @parcha/agentrun-pi@beta demo empty` runs the missing-evidence path and prints `Status: escalated`.
+
+The demo shows the workflow graph, progress, and a completed result with call counts. It uses scripted responses over fictional sources. It makes no model calls and does not test model quality. Run `/agentrun status` to check the loaded skill and Pi host version. Status names the supported range, 1.0.4 to below 1.4, and flags a host outside it without blocking it. Missing Pi or Jev access does not prevent the scripted demo. To repeat it, run `/agentrun run` or `/agentrun demo`. A scripted demo stays scripted on rerun, including its missing-evidence path. Use `/agentrun demo live` to switch to real Pi and Jev calls. Workflows authored by Pi use real adapters.
 
 For an offline Pi startup, use `pi --offline`. Without that flag, Pi may download optional command-line tools on first launch. This is separate from the scripted demo, which makes no network calls.
 
-## Describe, inspect, run
+## Preview, run, save, reuse
+
+```text
+/agentrun Preview a reusable workflow that identifies breaking changes and migration actions in supplied release notes. Do not run it yet.
+```
+
+The command loads the `agentrun-author` skill. Its source ships in `@parcha/agentrun-dsl`; this package registers it rendered with the Pi host rules. A preview validates and displays the graph without running it. Ask Pi to run when ready, or use `/agentrun run`. You can also invoke `/skill:agentrun-author <task>` directly.
+
+Open `/agentrun` to inspect the graph in the native terminal UI. Select a stage to see its contract, instructions or criteria, and observed evidence. The Actions page offers run, input, edit, save, load, and history. Arrow keys navigate, Enter inspects, `a` opens Actions, and Escape goes back or closes the view. Closing the inspector does not cancel execution; non-TUI hosts receive a text view.
+
+After inspecting a definition, save it and reuse it in a new Pi session in the same project:
+
+```text
+/agentrun input The release note says requests now require X-Workspace.
+/agentrun run
+/agentrun save release-review
+```
 
 ```text
-/agentrun Find the main entry points in this repository and summarize how requests reach them.
+/agentrun load release-review
+/agentrun input The next release removes /events; clients must use /v2/events.
+/agentrun run
 ```
 
-The command loads the packaged `agentrun-author` skill. Pi reads the available tools, builds a workflow, inspects its graph, then runs it with the task's input. You can also invoke `/skill:agentrun-author <task>` directly. Ask Pi to change a step or explain a result as you would in an ordinary conversation.
+Loading starts with empty input and does not execute. A save retains the definition, not input or execution permission. Scripted demo adapters are not saved: loading a saved demo uses live adapters and requires the corresponding model and Jev access. Each run restarts with the current input and model; it is not checkpoint resume.
 
 | Command | What happens |
 | --- | --- |
-| `/agentrun <task>` | Ask Pi to build, inspect, and run a workflow for the task. |
+| `/agentrun <task>` | Ask Pi to author, edit, or run; say when you want a preview only. |
 | `/agentrun help` | List commands and demo modes. |
-| `/agentrun` | Show the current workflow, or help if there is none. |
+| `/agentrun` | Inspect the current workflow, or show help if there is none. |
+| `/agentrun input <case or JSON>` | Set new input without changing the definition or running it. |
 | `/agentrun run` | Repeat the current workflow with its last supplied input. Scripted demos stay scripted; authored workflows use real adapters. |
+| `/agentrun dry-run` | Run the current workflow on synthetic values, with no model, Jev or tool call. |
+| `/agentrun save <name>` | Save an immutable, project-local definition revision. |
+| `/agentrun load <name> [digest]` | Load the newest or exact revision; input starts empty. |
+| `/agentrun list` | List saved revisions. |
+| `/agentrun history` | Inspect retained run receipts on this Pi branch. |
 | `/agentrun status` | Check skill discovery, active Pi selection, and Jev configuration without making provider calls. |
 | `/agentrun stop` | Request cancellation of the running workflow. |
 
-A progress widget shows active steps and the number finished. Results appear in Pi, with full output and events in the structured result.
+A progress widget shows active steps and the number finished. Results distinguish completion, escalation, failure, and interruption. Decision records show supplied evidence, criteria, answer, and route, not hidden reasoning or proof of correctness.
 
-Pi 0.87.0 cannot export a fresh session containing only slash-command results. To save an offline research receipt from the checkout, run `node examples/research-live.mjs --out research-result.json`. This runs the scripted example again and writes its result; it does not export the Pi session.
+Pi 1.1.0 cannot export a fresh session containing only slash-command results. To save an offline research receipt from the checkout, run `node examples/research-live.mjs --out research-result.json`. This runs the scripted example again and writes its result; it does not export the Pi session.
 
-One workflow runs at a time. Definitions and run state belong to the current Pi session; switching sessions or closing Pi does not create a saved workflow library. Named saves and reuse across sessions are planned for V2. This extension does not support them.
+A live run is durable. Its journal is kept in `.pi/agentrun/runs/<run id>/journal.json`, and `/agentrun run` after an interruption (`/agentrun stop`, a closed session, a killed process) or a failure continues the same run: committed steps are answered from the journal, a tool call that completed is answered from its receipt and is not made again, and the next step runs. The run is bound to its workflow, input, SOP text and tool names; a change to any of them starts a new run. A tool call that was in flight when the run stopped has an unknown outcome and is never made again: the resumed run fails naming it, and the person who knows whether it happened reconciles it before a new run. An agent step that was interrupted starts over from its first turn. A run that completed or escalated is not resumed; `/agentrun run` starts a new one. Scripted demos keep no journal.
+
+One workflow runs at a time. Named definitions are durable across sessions in the same project. Pi run receipts belong to the current branch and may remain in memory until Pi persists its session; saving a definition does not save a receipt.
+
+A host that does not run the extension can save, load and list the same definitions with `@parcha/agentrun-pi/workflows`, which loads nothing from pi:
+
+```ts
+import { WorkflowStore } from '@parcha/agentrun-pi/workflows';
+
+const store = new WorkflowStore(projectDirectory);   // records go to <projectDirectory>/.pi/agentrun/workflows/<name>/
+const saved = await store.save('release-review', workflow);   // an immutable revision, named by its SHA-256
+const again = await store.load('release-review');             // the last one saved; pass a digest for an exact revision
+const revisions = await store.list();                         // every revision, newest first
+```
+
+The argument is a project directory, not the workflows directory: the extension keeps its records for `ctx.cwd` in the same place, so a host that passes that directory and the extension read each other's records. Storage needs real directories and regular files (a symbolic link in the path or among the records fails with `WorkflowStoreError` code `unsafe_path`), and every load checks the record's metadata and the SHA-256 of its workflow. A `<name>/` directory copied into the workflows directory loads. A saved workflow is a procedure, not authority: the host still checks it against its current capabilities before it runs.
 
 ### Three demo modes
 
@@ -72,7 +119,9 @@ By default, the extension exposes currently active Pi built-in `read`, `grep`, `
 
 The user must issue `/agentrun run --trusted` for each run that needs code nodes or active built-in `bash`, `edit`, or `write` tools. This permits local, unsandboxed execution; authorization does not carry into the next run. A model cannot grant itself that permission with a tool argument.
 
-Native V1 does not supply SOP text. Workflows declaring `sopSection` stop before execution with a setup error; keep the required sections and use an SDK host that supplies the complete SOP.
+A dry run (`/agentrun dry-run`, the inspector's Dry-run action, or the tool's `dry-run` action, which also takes an `input`) runs the inspected workflow on synthetic values: agent and judge answers and tool results are synthesized from their schemas, so it makes no model, Jev or tool call, writes no run journal and leaves the last run's receipt as it was. Its `status` is `passed`, `failed` (`problems` say why), or `not_run`: a check could not run, for example a schema the generator cannot satisfy (`pattern`, `format`), a synthetic answer that escalated, or SOP text that was not supplied, and `skipped` says which. A `not_run` dry run proves nothing. A workflow with code nodes is `not_run` unless the user issues `/agentrun dry-run --trusted`, which runs its code in this process for that dry run only; a code node that throws is reported by its label, without what it threw. A dry run stops after 10,000 synthetic steps, or at `/agentrun stop`, as `not_run`.
+
+A workflow that names `sopSection`s needs SOP text. `/agentrun sop <file>` reads a Markdown file inside the project (up to 512 KiB) and checks that it has a `## <section>` heading for each section the workflow names; `/agentrun sop` shows what is set. The file's digest is kept with the session, and a run is refused if the file changed since it was supplied. A host that passes `sop` to `createAgentRunExtension` supplies the text itself and `/agentrun sop` is not used.
 
 Custom extension tools and the outer Pi session's permission hooks are **not inherited**, including in trusted runs. A configured host can explicitly supply its own tool definitions as described below. Shell/executor effect transports and artifact delivery are unavailable in this extension; declared tool effects must use an available tool.
 
@@ -81,7 +130,7 @@ A direct `call` to a Pi built-in returns a Pi tool result. Its `content` is an a
 Jev design guidance is bundled with the author skill and returned by `describe`
 under `authoring.jev`, including for hosts without a file-reading tool. No separate
 TypeSafe skill install is required for DSL authoring. The
-[source-read example](skills/author/examples/read-source-decision.json) preserves
+[source-read example](../dsl/skills/author/examples/read-source-decision.json) preserves
 original tool evidence through a Jev decision and deterministic projection; its
 fictional tests demonstrate wiring, not measured semantic accuracy. Explicit
 `tools: []` disables tools for an agent node; omission inherits the host allowlist.
@@ -164,7 +213,7 @@ const result = await runWorkflow(workflow, input, {
 });
 ```
 
-`ctx` supplies the active model and public model registry. Tools are explicitly supplied and receive the original context; outer hooks are not copied. The captured active model remains fixed for the run. The host thinking level is inherited when provided, and a node can override it. The runner bounds turns, submissions, and time, and refuses an absent model instead of selecting a fallback. These limits do not impose token or spending caps.
+`ctx` supplies the active model and public model registry. Tools are explicitly supplied and receive the original context; outer hooks are not copied. The captured active model remains fixed for the run. A node thinks at its own `thinking` level; a node that names none thinks at medium, not at the host session's level, unless the runner's own `thinkingLevel` option sets another. Thinking is never off: a level of `off` runs at medium. The runner bounds turns, submissions, and time, and refuses an absent model instead of selecting a fallback. These limits do not impose token or spending caps.
 
 For a standalone application, `createPiRunner(options)` accepts a configured SDK `ModelRuntime` and its selected `model`. Supply `tools` explicitly. It loads no ambient filesystem tools, workspace instructions, extensions, prompt templates, or skills. `createPiHostSessionFactory(ctx)` exposes the same native child session transport for integrations that own their own runner. Factories are unnecessary for ordinary extension use.
 
@@ -174,28 +223,51 @@ The child model delivers `{value: result}` through its `submit` tool. Schema and
 
 ## SDK: retain candidates and check fixed fixtures
 
-The SDK author saves candidate files separately from the native extension's session-local workflow. Supply configured runner options and host-owned acceptance checks:
+`authorWorkflow` lives in `@parcha/agentrun-dsl` beside the language it teaches. It saves candidate files separately from the native extension's current draft and named procedure revisions. Give it a Pi runner with no host tools, and bound its submissions by the candidate limit:
 
 ```js
-import { authorWorkflow } from '@parcha/agentrun-pi';
+import { authorWorkflow } from '@parcha/agentrun-dsl';
+import { createPiRunner } from '@parcha/agentrun-pi';
 
 const candidate = await authorWorkflow({
   request: 'Extract a numeric count from text',
   outputDir: './candidates',
   inputKeys: ['text'],
-  pi: options, // Your configured PiRunnerOptions.
+  runNode: createPiRunner({ ...options, tools: [], maxSubmissions: 4 }), // Your configured PiRunnerOptions.
   maxCandidates: 4,
   acceptance: workflow => checkAgainstYourFixtures(workflow),
 });
 console.log(candidate.path, candidate.checks);
 ```
 
-The host owns `checkAgainstYourFixtures`: return diagnostics, or `[]` to accept. Without that callback, acceptance is labeled `structural` and does not establish correct behavior. The author retains each submitted version and its feedback, never activates it, and cannot edit the host's acceptance checks.
+The host owns `checkAgainstYourFixtures`: return diagnostics, or `[]` to accept. Without that callback, acceptance is labeled `structural` and does not establish correct behavior. The author retains each submitted version and its feedback, never activates it, and cannot edit the host's acceptance checks. See [the author contract](../../docs/authoring.md#one-author-contract) for the host addendum.
 
 With `rubricSections`, every supplied section must appear on every generated LLM node, including child workflows. The author conservatively rejects Jev nodes, semantic `ask` predicates, and `verify` clauses under that policy; those need a separately reviewed question contract. Schema properties named `node`, `verify`, or `predicate` remain ordinary data. Supply the authoritative rubric as `deps.sop` when executing the candidate.
 
 The standalone CLI remains available as `node packages/pi/dist/cli.js --help` from source. It imports a trusted caller-owned `--config` module for `author` and `run`; importing that module executes its code. `validate` can evaluate code probes. Review executable workflows before using it.
 
+## Sign in, pick a model, check keys
+
+`@parcha/agentrun-pi/signin` is what a demo, or your own app, runs before its first model call. It is the only entry of this package that loads `@earendil-works/pi-ai`, an optional peer: install it beside the package (`npm install @earendil-works/pi-ai`) to use this entry. No other entry imports it.
+
+```js
+import { builtinModels } from '@earendil-works/pi-ai/providers/all';
+import { checkKeys, resolveModel, usageLimitError } from '@parcha/agentrun-pi/signin';
+
+const report = checkKeys(spec, { live: true, dir: demoDir });
+if (!report.ok) { console.error(report.text); process.exit(report.exitCode); } // 2: nothing was sent
+const { model, getApiKey, source } = await resolveModel(spec, { provider, model: modelId });
+const message = await builtinModels().completeSimple(model, context, { apiKey: await getApiKey() });
+if (usageLimitError(message)) throw usageLimitError(message);
+```
+
+- `checkKeys(spec, options)` lists what this run needs and what is missing: each key by its env name and where to create it, each program on `PATH` (refused outside its `platforms`, or below its `min` version as the first x.y.z that `<cmd> --version` prints), and each package as the demo's directory resolves it, with the exact `npm install --no-save <name>@<version>` line when it is missing. An item with `for: 'live'` or `for: 'kill'` counts only in that mode. A `oneOf` choice is met by any member, and an array member only by all of its items. A Jev judge asks for `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`. The check sends no request and prompts for nothing; a key's value is never printed.
+- `checkSetupPrompt(spec, text)` checks a demo's setup prompt against its spec: every key env name, program command and package name in the spec appears in it, and it names no credential env name (`*_API_KEY`, `*_KEY`, `*_TOKEN*`, `*_SECRET*`, `*_PROJECT_ID`) the spec does not list. `node scripts/check-setup-prompts.mjs` runs it for every `examples/*/demo.json` in CI.
+- `resolveModel(spec, options)` picks the model and its key. An explicit `provider` (and `model`) with that provider's env key wins, passed on as an explicit key; Anthropic takes `ANTHROPIC_API_KEY` only. Otherwise a stored ChatGPT sign-in is used, and the model is chosen from the account's own `GET /v1/models` by what the spec needs (text, tools, images): the spec's default when the account lists it, else the newest one pi-ai knows. With neither, it runs the sign-in. A sign-in's model takes only streaming Responses calls with `store: false` (`responsesOnly`, `unsupported`). The spec's eyes model resolves the same way: an explicit `eyes` model with its key, else the lead model when it meets the eyes' needs, else a `ResolveError` naming the gap; the ChatGPT plan takes no video input. The result serializes without its key.
+- `signIn(options)` runs pi-ai's own Sign in with ChatGPT once per install, with this app's name and a host id kept for the install. pi-ai's callback port is fixed at 1455; when another login holds it, the sign-in fails at once and says to finish or cancel that login. A pi-ai that ignores the app name (before 1.1) is refused before the page opens.
+- The sign-in lives in `$AGENTRUN_HOME/auth.json` (default `~/.config/agentrun/`): the directory is 0700 and the file 0600, written whole and renamed into place. An existing directory others can read is refused, not changed. Refreshes are serialized across processes by an operating-system lock, an exclusive SQLite transaction on `auth.json.lock` (an empty database beside it, through `node:sqlite`). The system frees it when its holder exits or is killed, so a crashed run leaves no lock to clear, the rotating refresh token is never sent twice, and a process that waited reads the new token. On Node 22, `node:sqlite` prints one experimental warning when the first write loads it. A token never reaches a log, a URL or a recording.
+- The plan's usage limit (`subscription_sharing_usage_limit_exceeded`) maps to `UsageLimitError`: "Your ChatGPT plan's usage limit is reached; wait, or set a provider key." It is never retried.
+
 ## Develop from source
 
 To change the extension itself, clone and build the repository:
@@ -205,19 +277,24 @@ git clone --branch main --single-branch https://github.com/Parcha-ai/agentrun.gi
 cd agentrun
 npm ci --ignore-scripts
 npm run build
-./node_modules/.bin/pi install ./packages/pi -l
-./node_modules/.bin/pi --offline
+agentrun_checkout="$PWD"
+mkdir -p ../agentrun-pi-project
+cd ../agentrun-pi-project
+"$agentrun_checkout/node_modules/.bin/pi" install "$agentrun_checkout/packages/pi" -l
+"$agentrun_checkout/node_modules/.bin/pi" --offline
 ```
 
-Use a separate project for this source installation. Pi loads the extension and skill from the checkout, so keep it in place. After source changes, rebuild and run `/reload`.
+These commands create a separate `agentrun-pi-project` beside the checkout. You can use your own project directory instead. Pi loads the extension and skill from the checkout, so keep it in place. After source changes, rebuild and run `/reload`.
 
 ## Dependencies and retained data
 
-Pi is optional for `@parcha/agentrun-dsl`. This package brings the Pi coding-agent SDK, its provider dependencies, and the Jev adapter; its dependency footprint is larger than the core. The release inventory records the locked versions.
+Pi is optional for `@parcha/agentrun-dsl`. This package depends on the DSL and the Jev adapter only. The Pi packages it uses (`@earendil-works/pi-coding-agent`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-tui`, and `@earendil-works/pi-ai` for the sign-in entry only) and `typebox` are optional peer dependencies at `*`, as Pi's package guidance requires, so an installed copy never shadows the host's. The release inventory records the locked versions.
+
+When loaded as an extension, Pi resolves its core packages and TypeBox through the host loader, and `pi install` adds nothing else. A standalone application or the `agentrun-pi` CLI has no host: install the peers yourself (`npm install @earendil-works/pi-coding-agent @earendil-works/pi-agent-core @earendil-works/pi-tui typebox`). This release supports Pi 1.0.4 to below 1.4, and CI tests 1.0.4, 1.1.0, 1.2.0 and 1.3.0; peer ranges at `*` do not make an older or newer host compatible. The sign-in entry needs pi-ai 1.1.0 or later: pi-ai 1.0.x ignores the app name and would put pi's name on ChatGPT's sign-in page, so `signIn` refuses it with `SignInError` (`APP_NAME_IGNORED`) before the page is shown. The offline loader regression checks competing local dependencies, a native file read, and the scripted workflow. Pi's [package guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md#dependencies) is the rule this follows.
 
-The SDK dependencies remain pinned so standalone applications and the CLI have a complete runtime. When loaded as an extension, Pi resolves its core packages and TypeBox through the host loader. The tested host is Pi 0.87.0; installed SDK pins do not make an older or newer host compatible. The offline loader regression checks competing local dependencies, a native file read, and the scripted workflow. Pi's [package guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md#dependencies) recommends peers for extension-only packages; this package also provides the standalone SDK.
+The durable entry (`@parcha/agentrun-pi/durable`) takes pi-durable and chord as optional peers from 1.0.4 to below 1.4; CI runs it on 1.0.4, 1.1.0, 1.2.0 and 1.3.0. A run that pi-durable 1.1 left (killed, paused, or with a tool call in flight) continues on 1.2. The move does not go back. A run that pi 1.2 left with a tool call in flight cannot be continued by pi 1.1: 1.1 waits on the newer task, and the only thing it writes is that task's mark from running back to pending, as pi does for any task a dead process left running. Continue such a run on 1.2, and do not downgrade pi under a live run. A host can call `refuseNewerTasks(harness, context)` from the durable entry after opening its Harness. On pi before 1.2, it then fails such a store with `NewerTaskError` (code `PI_TASK_NEWER`, naming the task's kind and version) instead of waiting.
 
-Candidate directories retain request text, rubric text, workflow versions, and feedback. Native Pi messages can contain workflow inputs and results. Choose storage and tool access appropriate for that data. The accompanying `skills/author/SKILL.md` describes the native and SDK authoring paths for agents.
+Candidate directories retain request text, rubric text, workflow versions, and feedback. Native Pi messages can contain workflow inputs and results. Choose storage and tool access appropriate for that data. The author skill in `@parcha/agentrun-dsl` describes the native and SDK authoring paths for agents.
 
 ## License
 

package/dist/cli.js

@@ -2,14 +2,15 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { runWorkflow, validateWorkflow } from "@parcha/agentrun-dsl";
-import { authorWorkflow } from "./author.js";
-import { createPiRunner } from "./runner.js";
+import { authorWorkflow, runWorkflow, validateWorkflow } from "@parcha/agentrun-dsl";
+import { runScriptedDemo } from "./demo-cli.js";
 const help = `Usage:
+  agentrun-pi demo [empty]            scripted demo; no key, no model calls, no network
   agentrun-pi validate workflow.json [--inputs key1,key2]
   agentrun-pi author --config ./pi.config.mjs --out ./candidates "Describe the workflow"
   agentrun-pi run --config ./pi.config.mjs workflow.json input.json
 
+The demo runs the same scripted workflow as /agentrun demo inside Pi; "empty" runs its missing-evidence path and exits 0 on the expected escalation.
 Config is trusted JavaScript exporting default PiRunnerOptions, optionally deps (Jev/effect adapters).
 Author saves candidates; it does not execute or activate them.
 Validate may execute code probes. Run executes trusted workflow code and exits 2 on escalation.
@@ -30,6 +31,12 @@ async function main(args) {
         args.splice(index, 2);
         return value;
     };
+    if (command === "demo") {
+        if (args.length > 1 || (args[0] && args[0] !== "empty"))
+            throw new Error("Usage: agentrun-pi demo [empty]");
+        process.exitCode = await runScriptedDemo(args[0] === "empty", line => console.log(line));
+        return;
+    }
     const configPath = flag("--config");
     const outputDir = flag("--out") ?? "./candidates";
     const inputKeys = (flag("--inputs") ?? "").split(",").filter(Boolean);
@@ -47,11 +54,15 @@ async function main(args) {
         throw new Error(help);
     if (!configPath)
         throw new Error("Supply --config with an explicit model and modelRuntime");
+    const { createPiRunner } = await import("./runner.js");
     const config = await import(pathToFileURL(resolve(configPath)).href);
     if (command === "author") {
         if (args.length !== 1)
             throw new Error(help);
-        const authored = await authorWorkflow({ request: args[0], outputDir, inputKeys, pi: config.default });
+        const maxCandidates = 4;
+        // The author session gets no host tools and stops at the candidate limit.
+        const runNode = createPiRunner({ ...config.default, tools: [], maxSubmissions: maxCandidates });
+        const authored = await authorWorkflow({ request: args[0], outputDir, inputKeys, runNode, maxCandidates });
         console.log(JSON.stringify({ path: authored.path, candidates: authored.candidates, checks: authored.checks }, null, 2));
     }
     else {

package/dist/demo-cli.d.ts

@@ -0,0 +1,2 @@
+/** The bundled scripted workflow, run through the interpreter with fixed answers: no model, no key, no network. */
+export declare function runScriptedDemo(noEvidence: boolean, print: (line: string) => void): Promise<number>;

package/dist/demo-cli.js

@@ -0,0 +1,25 @@
+import { runWorkflow } from "@parcha/agentrun-dsl";
+import { demoInput, demoWorkflow, scriptedDemoDeps } from "./demo.js";
+/** The bundled scripted workflow, run through the interpreter with fixed answers: no model, no key, no network. */
+export async function runScriptedDemo(noEvidence, print) {
+    const scripted = scriptedDemoDeps(noEvidence);
+    const calls = { effects: 0, judgments: 0, agentSteps: 0 };
+    const deps = {
+        runEffect: input => { calls.effects++; return scripted.runEffect(input); },
+        runJudge: input => { calls.judgments++; return scripted.runJudge(input); },
+        runNode: input => { calls.agentSteps++; return scripted.runNode(input); },
+    };
+    print("AgentRun on Pi · scripted demo, fictional sources, no model calls\n");
+    print(`Question: ${demoInput.question}\n`);
+    const result = await runWorkflow(demoWorkflow, demoInput, deps);
+    const state = result.state;
+    for (const finding of state.findings ?? [])
+        print(`  ${finding.question}\n    ${finding.answer}`);
+    print(`\nStatus: ${result.status}`);
+    if (result.status === "complete")
+        print(`Answer: ${state.report?.answer ?? ""}`);
+    else
+        print(`Escalation: ${result.escalation?.summary ?? ""}`);
+    print(`Calls: ${calls.effects} tool, ${calls.judgments} judgment, ${calls.agentSteps} agent step (all scripted)`);
+    return result.status === "escalated" && !noEvidence ? 2 : 0;
+}

package/dist/demo.js

@@ -8,6 +8,7 @@ export function demoSearchTool() {
         name: 'search', label: 'Search example sources',
         description: 'Read the bundled fictional wiki-migration sources. This does not search the internet.',
         parameters: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'], additionalProperties: false },
+        resultSchema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object' } } }, required: ['sources'], additionalProperties: false },
         async execute(_id, _args, signal) {
             signal?.throwIfAborted();
             return { content: [{ type: 'text', text: JSON.stringify({ sources: demoSources }) }], details: { sources: structuredClone(demoSources) } };

package/dist/durable/decision-recovery.d.ts

@@ -0,0 +1,23 @@
+import { type DecisionExchange, type DecisionReceipt } from "@parcha/agentrun-dsl";
+import type { DocumentReader } from "@earendil-works/pi-durable";
+import type { WorkflowInvocation } from "./task.js";
+type Context = WorkflowInvocation["context"];
+/** The interpreter's two decision hooks over one invocation of a workflow task. */
+export type DecisionRecovery = {
+    /** The interpreter's `recordDecision`: commits the receipt's row after every row recorded before it, and resolves
+     *  once that commit is durable; a commit that fails rejects this receipt's call. The task's state is untouched. */
+    recordDecision(receipt: DecisionReceipt, exchange: DecisionExchange): Promise<void>;
+    /** The interpreter's `recovery.decision`: the receipt rebuilt from the last answered row this run recorded under
+     *  `id`, or undefined when it recorded none (a request that failed, one recorded without its identity, or one another
+     *  run recorded, is asked again). */
+    decision(id: string): Promise<DecisionReceipt | undefined>;
+};
+/** The decision hooks a durable host gives the interpreter inside `WorkflowTaskHost.run`, over the invocation it is
+ *  handed (the run's key, the task's runtime and context): `recordDecision` as the interpreter's own, and `decision` as
+ *  `recovery.decision` beside the driver's recovery hooks. */
+export declare function decisionRecovery(invocation: {
+    key: string;
+    runtime: Pick<WorkflowInvocation["runtime"], "commit"> & DocumentReader;
+    context: Context;
+}): DecisionRecovery;
+export {};

package/dist/durable/decision-recovery.js

@@ -0,0 +1,57 @@
+// A workflow task's decision receipts, durable in its run's Session: each receipt is a row (decisions.ts) committed
+// through the task's own commit before the interpreter acts on its answers, and a resumed run's request is answered
+// from the row its earlier process committed, so the judge is not asked again and the run decides what it decided.
+// Every run in the Session shares the rows' document, and a receipt's id does not name its run, so each row carries
+// the run's key and a run is answered only from its own rows.
+import { DECISION_RECEIPT_VERSION } from "@parcha/agentrun-dsl";
+import { appendDecision, DECISION_ROW_VERSION, readDecisions } from "./decisions.js";
+/** A receipt as the row the run `key` stores: the receipt's own fields, its identity, and the request's size. */
+function rowOf(receipt, exchange, key) {
+    return {
+        v: DECISION_ROW_VERSION, at: receipt.at, node: receipt.node, kind: receipt.kind, item: receipt.item, execution_path: receipt.execution_path,
+        request_sha256: receipt.request_sha256,
+        request_bytes: Buffer.byteLength(JSON.stringify({ state: exchange.request.state, questions: exchange.request.questions })),
+        model: receipt.model, questions: receipt.questions, answers: receipt.answers, rule: receipt.rule, action: receipt.action,
+        usage: receipt.usage, cost_usd: receipt.cost_usd, latency_ms: receipt.latency_ms, ...(receipt.error !== undefined ? { error: receipt.error } : {}),
+        decision_id: receipt.id, request: receipt.request, state_sha256: receipt.state_sha256, run_key: key,
+    };
+}
+/** The receipt the run `key`'s last answered row under `id` is: a rule is set only on an answered receipt, and an
+ *  answered one carries no error. */
+function answeredReceipt(rows, id, key) {
+    const row = rows.findLast((stored) => stored.run_key === key && stored.decision_id === id && stored.rule !== null && stored.error === undefined
+        && stored.request !== undefined && stored.state_sha256 !== undefined && stored.execution_path !== null);
+    if (!row)
+        return undefined;
+    return {
+        v: DECISION_RECEIPT_VERSION, id, at: row.at, node: row.node, kind: row.kind, item: row.item, execution_path: row.execution_path,
+        request: row.request, status: "answered", state_sha256: row.state_sha256,
+        questions: row.questions, answers: row.answers, rule: row.rule, action: row.action,
+        model: row.model, usage: row.usage, cost_usd: row.cost_usd, request_sha256: row.request_sha256, latency_ms: row.latency_ms,
+    };
+}
+/** The decision hooks a durable host gives the interpreter inside `WorkflowTaskHost.run`, over the invocation it is
+ *  handed (the run's key, the task's runtime and context): `recordDecision` as the interpreter's own, and `decision` as
+ *  `recovery.decision` beside the driver's recovery hooks. */
+export function decisionRecovery(invocation) {
+    const { key, runtime, context } = invocation;
+    const harness = {
+        commit: async (change) => {
+            let result;
+            await runtime.commit(async (tx) => { result = await change(tx); return undefined; }, context);
+            return result;
+        },
+    };
+    let chain = Promise.resolve();
+    return {
+        recordDecision(receipt, exchange) {
+            const row = rowOf(receipt, exchange, key);
+            const committed = chain.then(() => appendDecision(harness, row, context));
+            chain = committed.catch(() => undefined);
+            return committed;
+        },
+        async decision(id) {
+            return answeredReceipt(await readDecisions(runtime, context), id, key);
+        },
+    };
+}

package/dist/durable/decisions.d.ts

@@ -0,0 +1,113 @@
+import type { Context } from "@earendil-works/chord";
+import { type DocumentReader, type Harness } from "@earendil-works/pi-durable";
+/** The session document that holds a run's decision rows. */
+export declare const DECISION_RECEIPTS_DOC = "agentrun.decisions";
+/** The stored row's version. */
+export declare const DECISION_ROW_VERSION = 1;
+/** How the answers became the action, with every threshold applied. */
+export type DecisionRowRule = 
+/** judge: each question's decoded value (choice, noul at 0.5, rounded score). */
+{
+    kind: "judge";
+}
+/** pick: the chosen option names an item by its position, or none. */
+ | {
+    kind: "pick";
+    options: string[];
+    none: string | null;
+}
+/** route: the chosen branch, or the unsure branch when the choice's confidence is below `gte`. */
+ | {
+    kind: "route";
+    unsure: {
+        gte: number;
+        branch: string;
+    } | null;
+}
+/** sift: an item is kept when its `keep` measure meets `gte`; every item without a keep rule. */
+ | {
+    kind: "sift";
+    items: number;
+    ids: string[];
+    keep: {
+        id: string;
+        measure: "confidence" | "value";
+        gte: number;
+    } | null;
+}
+/** ask: the predicate holds when p_yes meets `gte`. */
+ | {
+    kind: "ask";
+    gte: number;
+}
+/** verify: a noul question fails when p_yes is below its threshold (null: not judged, an empty field); a failed
+ *  question the submission holds is doubted, a failed one it lacks is unmet. */
+ | {
+    kind: "verify";
+    thresholds: Record<string, number | null>;
+    present: string[];
+};
+/** One stored decision row. */
+export type DecisionRow = {
+    v: typeof DECISION_ROW_VERSION;
+    at: string;
+    node: string;
+    kind: "judge" | "pick" | "sift" | "route" | "ask" | "verify";
+    item: number | null;
+    execution_path: string | null;
+    request_sha256: string | null;
+    request_bytes: number;
+    model: string | null;
+    questions: Record<string, unknown>;
+    answers: Record<string, unknown>;
+    rule: DecisionRowRule | null;
+    /** What the run did with the answers; null when the node did not act on them. */
+    action: unknown;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    } | null;
+    cost_usd: number | null;
+    latency_ms: number;
+    error?: string;
+    /** The request's spend is on its frozen driver's state, so a cost fold counts it there, not here. */
+    driver_spend?: true;
+    /** The receipt's id, its place among its node's requests, the digest of the state it was asked with, and the key of
+     *  the workflow run that asked it. A row that carries all four is the whole receipt again, so that run, resumed, can be
+     *  answered from it (`decisionRecovery`); another run in the same Session never is. */
+    decision_id?: string;
+    request?: {
+        index: number;
+        count: number;
+        items?: number[];
+    };
+    state_sha256?: string;
+    run_key?: string;
+};
+/** Commit one row, appended after every row committed before it. */
+export declare function appendDecision(harness: Pick<Harness, "commit">, row: DecisionRow, context?: Context): Promise<void>;
+/** Every row the run's Session holds, in commit order. */
+export declare function readDecisions(read: DocumentReader, context?: Context): Promise<DecisionRow[]>;
+/** Where a writer commits: the run's Session, opened when the first row needs it and released by `flush`. */
+export type DecisionSession = {
+    harness: Pick<Harness, "commit">;
+    release(): Promise<void>;
+};
+export type DecisionWriter = {
+    /** Commit `row` after every row recorded before it. It returns at once; a commit that fails is kept for
+     *  `settled` and `flush`, and the rows after it are still committed. */
+    record(row: DecisionRow): void;
+    /** Every row recorded so far is committed; the first that could not be is thrown, and kept for `flush`. The
+     *  Session stays open. */
+    settled(): Promise<void>;
+    /** Every row is committed and every Session the writer opened is released, also when a commit failed; a row
+     *  recorded while flush runs is committed too. Then the first failed commit is thrown, or, when none failed, the
+     *  first failed release. */
+    flush(): Promise<void>;
+};
+/** A writer that commits rows in the order they are recorded. `open` runs once, when the first row is committed, so
+ *  a run that records no row never opens its Session here. */
+export declare function createDecisionWriter(options: {
+    open: () => Promise<DecisionSession>;
+    context?: Context;
+}): DecisionWriter;

package/dist/durable/decisions.js

@@ -0,0 +1,71 @@
+// A run's decision rows as pi-durable stores them: the session document `agentrun.decisions`, one row per typed
+// question the run asked, in commit order. The row is a stored format (version 1) and does not change with the
+// interpreter: a host maps `@parcha/agentrun-dsl`'s `DecisionReceipt` to a row, with the facts only the host has (the
+// request's size and metering, whether the node acted on the answers), and this module stores and reads rows without
+// looking inside them.
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { defineDoc } from "@earendil-works/pi-durable";
+/** The session document that holds a run's decision rows. */
+export const DECISION_RECEIPTS_DOC = "agentrun.decisions";
+/** The stored row's version. */
+export const DECISION_ROW_VERSION = 1;
+const DecisionsDoc = defineDoc({ kind: DECISION_RECEIPTS_DOC, version: 1, scope: "session", initial: () => ({ receipts: [] }) });
+/** Commit one row, appended after every row committed before it. */
+export async function appendDecision(harness, row, context = BACKGROUND_CONTEXT) {
+    const stored = JSON.parse(JSON.stringify(row));
+    await harness.commit(async (tx) => { (await tx.doc(DecisionsDoc)).receipts.push(stored); }, context);
+}
+/** Every row the run's Session holds, in commit order. */
+export async function readDecisions(read, context = BACKGROUND_CONTEXT) {
+    const doc = await read.snapshot(DecisionsDoc, context);
+    return (doc?.receipts ?? []);
+}
+/** A writer that commits rows in the order they are recorded. `open` runs once, when the first row is committed, so
+ *  a run that records no row never opens its Session here. */
+export function createDecisionWriter(options) {
+    let session;
+    let chain = Promise.resolve();
+    let failure;
+    return {
+        record(row) {
+            const stored = JSON.parse(JSON.stringify(row));
+            chain = chain
+                .then(async () => appendDecision((await (session ??= options.open())).harness, stored, options.context))
+                .catch((error) => { failure ??= { error }; });
+        },
+        async settled() {
+            await chain;
+            if (failure)
+                throw failure.error;
+        },
+        async flush() {
+            let released;
+            // A row recorded while flush waits or releases joins the chain, so flush returns only when a full pass saw no new
+            // row. The Session is cleared before it is released: a row recorded meanwhile opens its own, which the next pass
+            // releases.
+            for (;;) {
+                const drained = chain;
+                await drained;
+                if (drained !== chain)
+                    continue;
+                const held = session;
+                session = undefined;
+                if (held) {
+                    const opened = await held.catch(() => undefined);
+                    try {
+                        await opened?.release();
+                    }
+                    catch (error) {
+                        released ??= { error };
+                    }
+                }
+                if (drained === chain)
+                    break;
+            }
+            const first = failure ?? released;
+            failure = undefined;
+            if (first)
+                throw first.error;
+        },
+    };
+}