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

package/README.md

@@ -1,6 +1,6 @@
 # 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
 
@@ -13,13 +13,13 @@ npm install -g @earendil-works/pi-coding-agent@0.87.0
 Then, in your project:
 
 ```sh
-pi install npm:@parcha/agentrun-pi@0.1.0-beta.2 -l
+pi install npm:@parcha/agentrun-pi@0.1.0-beta.3 -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.
 
@@ -33,28 +33,51 @@ The demo shows the workflow graph, progress, and a completed result with call co
 
 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 Find the main entry points in this repository and summarize how requests reach them.
+/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 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.
+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 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
 
@@ -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,23 +197,24 @@ 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.
 
@@ -205,11 +229,14 @@ 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
 
@@ -217,7 +244,7 @@ Pi is optional for `@parcha/agentrun-dsl`. This package brings the Pi coding-age
 
 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) {
@@ -259,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')
@@ -456,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 {