@parcha/agentrun-pi 0.1.0-beta.1 → 0.1.0-beta.3

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 0.87.0.
 
-## Install from source
+## Install
 
-Build the extension and use the included Pi CLI. From a new terminal:
+If you do not have Pi, install the tested host version first:
 
 ```sh
-git clone --branch main --single-branch https://github.com/Parcha-ai/agentrun.git
-cd agentrun
-npm ci --ignore-scripts
-npm run build
-./node_modules/.bin/pi install ./packages/pi -l
-./node_modules/.bin/pi --offline
+npm install -g @earendil-works/pi-coding-agent@0.87.0
 ```
 
-`-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.
+Then, in your project:
+
+```sh
+pi install npm:@parcha/agentrun-pi@0.1.0-beta.3 -l
+pi --offline
+```
 
-On first launch, Pi asks whether you trust the project before loading its extension. Review the checkout before accepting.
+`-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.
 
-Already built this checkout? Start at the `pi install` line. The included CLI is the tested Pi 0.87.0 version; a global Pi installation is unnecessary. If Pi 0.87.0 is already open, use `/reload`. Keep this checkout: Pi loads the extension and skill from it. Rebuild after source changes, then reload. `/reload` 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.
 
@@ -31,30 +31,53 @@ Try the bundled example inside Pi:
 
 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.
 
-For an offline Pi startup, use `./node_modules/.bin/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.
+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.
+
+## 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.
 
-## Describe, inspect, run
+After inspecting a definition, save it and reuse it in a new Pi session in the same project:
 
 ```text
-/agentrun Find the main entry points in this repository and summarize how requests reach them.
+/agentrun input The release note says requests now require X-Workspace.
+/agentrun run
+/agentrun save release-review
 ```
 
-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.
+```text
+/agentrun load release-review
+/agentrun input The next release removes /events; clients must use /v2/events.
+/agentrun run
+```
+
+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 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.
 
-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.
+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.
 
 ### Three demo modes
 
@@ -64,7 +87,7 @@ One workflow runs at a time. Definitions and run state belong to the current Pi
 | `/agentrun demo empty` | Scripted insufficient-evidence path, without model calls. |
 | `/agentrun demo live` | Real Pi agent steps and Jev system one decisions over the same fictional sources. |
 
-Live mode uses your active Pi model and requires configured TypeSafe access for Jev. It still does not search the web or prove accuracy on real research. See the [Jev adapter configuration](../jev/README.md). Live calls can incur usage charges; scripted mode needs no provider access.
+Live mode uses your active Pi model and requires configured TypeSafe access for Jev. It still does not search the web or prove accuracy on real research. See the [Jev adapter configuration](https://github.com/Parcha-ai/agentrun/tree/main/packages/jev#readme). Live calls can incur usage charges; scripted mode needs no provider access.
 
 ## Tools and execution
 
@@ -81,7 +104,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.
@@ -174,35 +197,54 @@ 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.
 
+## Develop from source
+
+To change the extension itself, clone and build the repository:
+
+```sh
+git clone --branch main --single-branch https://github.com/Parcha-ai/agentrun.git
+cd agentrun
+npm ci --ignore-scripts
+npm run build
+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
+```
+
+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.
 
 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.
 
-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,8 +2,7 @@
 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 { authorWorkflow, runWorkflow, validateWorkflow } from "@parcha/agentrun-dsl";
 import { createPiRunner } from "./runner.js";
 const help = `Usage:
   agentrun-pi validate workflow.json [--inputs key1,key2]
@@ -51,7 +50,10 @@ async function main(args) {
     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.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/extension-service.js

@@ -2,8 +2,7 @@ import { types as utilTypes } from 'node:util';
 import { JevError, isJevResponseReason } from '@parcha/agentrun-jev';
 import { PiRunError } from './runner.js';
 import { ToolInputValidationError } from './tool-input-error.js';
-import { inspectWorkflow, runWorkflow, validateWorkflow, EffectOutcomeUnknownError, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, EffectDeadlineExceededError, } from '@parcha/agentrun-dsl';
-import { workflowPolicyErrors } from './admission.js';
+import { inspectWorkflow, runWorkflow, validateWorkflow, candidatePolicyErrors, EffectOutcomeUnknownError, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, EffectDeadlineExceededError, } from '@parcha/agentrun-dsl';
 export class ExtensionServiceError extends Error {
     code;
     constructor(code, message) {
@@ -111,6 +110,7 @@ function localDiagnostic(error) {
             empty_selection: 'The selection list is empty and none is not allowed. Handle missing evidence explicitly.',
             missing_map_result: 'A map body did not produce its resultPath. Select a path in the completed body state; a body with as is collected automatically when resultPath is omitted.',
             parallel_write_conflict: 'Parallel branches changed the same top-level state key. Give independent branches distinct output keys and combine them after the parallel node.',
+            reserved_state_key: 'A node or host hook wrote an engine-owned "$"-prefixed state key such as $host. Choose another state key; host state is written only through decodeSubmission.',
         };
         return { code: error.code, stage: error.stage.slice(0, 200),
             // Parallel patch keys may be computed from source values, unlike authored paths.
@@ -258,7 +258,7 @@ export class WorkflowExtensionService {
         const inspection = inspectWorkflow(workflow);
         if (inspection.nodes.length > extensionStructuralLimits.maxNodes)
             throw new ExtensionServiceError('bounds', 'A workflow may contain at most 200 nodes.');
-        const errors = workflowPolicyErrors(workflow, { allowExecutableCandidates: options.allowExecutableCandidates === true, rubricSections: this.rubricSections, allowedEffectTools: [...this.allowedTools] });
+        const errors = candidatePolicyErrors(workflow, { allowExecutableCandidates: options.allowExecutableCandidates === true, rubricSections: this.rubricSections, allowedEffectTools: [...this.allowedTools] });
         for (const entry of inspection.nodes) {
             const node = entry.path.split('/').slice(1).reduce((item, key) => item[key.replace(/~1/g, '/').replace(/~0/g, '~')], workflow);
             if (node.node === 'artifact')
@@ -455,9 +455,17 @@ export class WorkflowExtensionService {
                     failure.errors.slice(0, 100).forEach(collect);
             };
             collect(error);
+            const failedStep = events.findLast(event => event.type === 'node.end' && event.detail?.status === 'failed');
+            const failedPath = failedStep?.executionPath;
+            const toolFailed = failedStep && failedStep.detail?.kind === 'call'
+                && events.some(event => event.type === 'effect.failed' && event.executionPath === failedPath);
+            const observedStage = failedStep?.label.slice(0, 200);
             report = { digest: prepared.digest, status: code === 'cancelled' || code === 'deadline' ? 'interrupted' : 'failed', calls, events,
                 error: !owned && !signal.aborted && !invalidInput && localDiagnostic(error) || { code,
-                    ...(invalidInput ? { stage: 'input', problems: error.problems.slice(0, 8).map(problem => problem.slice(0, 500)) } : {}), message: owned ? reason.message : signal.aborted ? 'Workflow interrupted.' : invalidInput ? 'Input does not match this workflow. Pass input with action run, or inspect the workflow with its input before running.' : 'Workflow failed. Check the prepared graph, input contracts and host adapter access; provider error bodies are omitted.' },
+                    ...(invalidInput ? { stage: 'input', problems: error.problems.slice(0, 8).map(problem => problem.slice(0, 500)) } : observedStage ? { stage: observedStage } : {}),
+                    message: owned ? reason.message : signal.aborted ? 'Workflow interrupted.' : invalidInput ? 'Input does not match this workflow. Pass input with action run, or inspect the workflow with its input before running.'
+                        : toolFailed ? 'A registered tool call failed. Inspect the tool step and reconcile any effect before a new run. Underlying error text is omitted.'
+                            : 'Workflow failed. Inspect the affected step, input contracts and host adapters. Underlying error text is omitted.' },
                 ...(unknown.length ? { uncertainEffects: unknown } : {}), ...(traceTruncated ? { traceTruncated: true } : {}) };
         }
         finally {