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

package/README.md

@@ -17,9 +17,11 @@ 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.
+`pi --offline` opens Pi's terminal interface, so run it in an interactive terminal; with no terminal attached it prints nothing and exits. `-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`. The current draft is restored from a persisted Pi session branch when available; named definition saves are stored separately.
+On first launch, Pi asks "Trust project folder?" before loading the extension, with five choices: Trust, Trust parent folder, Trust (this session only), Do not trust, and Do not trust (this session only). Choose Trust, or Trust (this session only), to load it. 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.
+
+With no model configured, `pi --offline` prints two warnings at startup: `Warning: fd not found. Offline mode enabled, skipping download.` (the optional `fd` tool is not installed and `--offline` skips fetching it) and `Warning: No models available. Use /login to log into a provider via OAuth or API key.` Both are expected here and the scripted demo needs neither. The `[Skills]` list shows `agentrun-author` and the `[Extensions]` list shows `@parcha/agentrun-pi` when the extension loaded.
 
 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.
 
@@ -43,6 +45,8 @@ For an offline Pi startup, use `pi --offline`. Without that flag, Pi may downloa
 
 ## Preview, run, save, reuse
 
+**This section needs a configured model.** Authoring a workflow from a task is a model call, so the preview below, and the `input`, `run`, `save` and `load` steps after it, are for a Pi with a model selected. With no model, `/agentrun <task>` answers `AgentRun requires an active Pi model. Use /login to connect a provider, then /model to select it. Try /agentrun demo without model access.` and `/agentrun demo` (above) is the one workflow you have: `/agentrun input`, `run` and `save` act on that scripted demo, not on a release review.
+
 ```text
 /agentrun Preview a reusable workflow that identifies breaking changes and migration actions in supplied release notes. Do not run it yet.
 ```
@@ -84,7 +88,7 @@ Loading starts with empty input and does not execute. A save retains the definit
 
 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 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.
+Pi 1.1.0 cannot export a fresh session containing only slash-command results. To save an offline research receipt, run [`examples/research-live.mjs`](https://github.com/Parcha-ai/agentrun/blob/main/examples/research-live.mjs) from a checkout of the repository (the `examples/` directory is in the repository, not in the npm package): `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.
 
 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.
 
@@ -103,13 +107,14 @@ const revisions = await store.list();                         // every revision,
 
 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
+### Demo modes
 
 | Command | What it demonstrates |
 | --- | --- |
 | `/agentrun demo` | Scripted successful execution over the bundled fictional sources, without model calls. |
 | `/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. |
+| `/agentrun triage` | A second scripted workflow, support-ticket triage over a fictional ticket, without model calls. |
 
 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.
 
@@ -160,7 +165,7 @@ The native model-facing interface starts with `agentrun` and `action: "describe"
 
 ### Configure the native extension from a host
 
-Hosts that own a restricted corpus, an approved Jev transport, or shared accounting can configure the same native extension:
+Hosts that own a restricted corpus, an approved Jev transport, or shared accounting can configure the same native extension. This is a sketch, not a runnable sample: `approvedToolsFor`, `makeHostJudge` and `sharedBudget` stand for your own host's code. See [Integrate with your application](../../docs/host-integration.md) for what a host supplies.
 
 ```js
 import { createAgentRunExtension } from '@parcha/agentrun-pi/extension';
@@ -201,7 +206,7 @@ An operator may select a different active Pi model between inspection and execut
 
 ## SDK: embed the runner
 
-The native extension handles configuration above. For another Pi extension that already has a context:
+The native extension handles configuration above. For another Pi extension that already has a context, this sketch shows the call (not runnable as it stands: `ctx` is the context Pi hands your extension, and `workflow`, `input` and `allowedTools` are yours; see [Integrate with your application](../../docs/host-integration.md)):
 
 ```js
 import { runWorkflow } from '@parcha/agentrun-dsl';
@@ -223,7 +228,7 @@ The child model delivers `{value: result}` through its `submit` tool. Schema and
 
 ## SDK: retain candidates and check fixed fixtures
 
-`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:
+`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. This is a sketch, not runnable as it stands: `options` is your configured `PiRunnerOptions` and `checkAgainstYourFixtures` is your own function (see [Integrate with your application](../../docs/host-integration.md)):
 
 ```js
 import { authorWorkflow } from '@parcha/agentrun-dsl';
@@ -244,11 +249,20 @@ The host owns `checkAgainstYourFixtures`: return diagnostics, or `[]` to accept.
 
 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.
+The package also installs a command line, `agentrun-pi`. Try it from an empty directory after `npm install @parcha/agentrun-pi@beta`:
+
+```sh
+npx agentrun-pi --help
+npx agentrun-pi demo
+cp node_modules/@parcha/agentrun-dsl/skills/author/examples/review-release-notes.json workflow.json
+npx agentrun-pi validate workflow.json --inputs notes
+```
+
+`--inputs` names the keys of the workflow's input object; `review-release-notes.json` takes one, `notes`. `demo` needs no key and no peers. `author` and `run` import a trusted caller-owned `--config` module (its code runs when imported) that exports your runner options, and need the peers listed under Dependencies. `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.
+`@parcha/agentrun-pi/signin` is what a demo, or your own app, runs before its first model call. The sample below is a sketch, not runnable as written: `spec` is a demo's spec (the `demo.json` of an example in the repository's `examples/` directory), and `provider`, `modelId` and `context` are your app's. 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';

package/dist/durable/store.js

@@ -47,6 +47,10 @@ function json(value) {
         return item;
     }));
 }
+/** A journal effect from its stored document. */
+function storedEffect(id, e) {
+    return { id, name: e.name, argsHash: e.argsHash, status: e.status, session: e.session, result: json(e.result), ...(e.intent ? { intent: json(e.intent) } : {}), ...(e.args !== undefined ? { args: json(e.args) } : {}), ...(Array.isArray(e.calls) ? { calls: json(e.calls) } : {}) };
+}
 /** The journals open in this process. The run's lock keeps every other process off the run, and the journal's generation
  *  fences a stale writer; this keeps a second open of one key off it here. Without an owner a host's own keys are
  *  tracked; with one, the keys by owner. */
@@ -100,8 +104,7 @@ async function openDocumentJournal(host, key, bound, options) {
         doc.generation += 1;
         const effects = [];
         for (const id of doc.effects) {
-            const e = await tx.doc(EffectDoc, effectKey(key, id), null);
-            effects.push({ id, name: e.name, argsHash: e.argsHash, status: e.status, session: e.session, result: json(e.result), ...(e.intent ? { intent: json(e.intent) } : {}), ...(e.args !== undefined ? { args: json(e.args) } : {}), ...(Array.isArray(e.calls) ? { calls: json(e.calls) } : {}) });
+            effects.push(storedEffect(id, await tx.doc(EffectDoc, effectKey(key, id), null)));
         }
         return { existing, generation: doc.generation, revision: doc.revision, state: json(doc.state), notes: json(doc.notes), effects };
     }, context).catch((error) => { held.undo(); throw storeFailure(error); });
@@ -142,7 +145,6 @@ async function openDocumentJournal(host, key, bound, options) {
     }, context).then((done) => { revision = done.revision; return done; });
     /** A read in a commit of its own: it writes nothing the caller did not ask for. */
     const read = (body) => inOrder(() => host.commit(body, context));
-    const storedEffect = (id, e) => ({ id, name: e.name, argsHash: e.argsHash, status: e.status, session: e.session, result: json(e.result), ...(e.intent ? { intent: json(e.intent) } : {}), ...(e.args !== undefined ? { args: json(e.args) } : {}), ...(Array.isArray(e.calls) ? { calls: json(e.calls) } : {}) });
     return {
         existing: opened.existing, generation: opened.generation, state: opened.state,
         get revision() { return revision; },

package/dist/extension.js

@@ -40,6 +40,8 @@ function singleTextInput(workflow) {
 }
 const nativeLimits = Object.freeze({ deadlineMs: 600_000, modelRequests: 50, judgeCalls: 100, toolAttempts: 100,
     nodeMaxTurns: 8, nodeMaxSubmissions: 3, nodeTimeoutMs: 120_000 });
+/** Forgets a session's last run (its observation, report and run id), so the next run starts fresh. */
+const clearRun = (s) => { s.observation = undefined; s.report = undefined; s.runId = undefined; };
 /** Configure the native extension without granting configuration to workflow authors. */
 export function createAgentRunExtension(options = {}) {
     if (options.hostTools !== undefined && typeof options.hostTools !== 'function')
@@ -188,15 +190,10 @@ function registerExtension(pi, configuration) {
         if (changed) {
             s.demo = undefined;
             s.savedName = undefined;
-            s.observation = undefined;
-            s.report = undefined;
-            s.runId = undefined;
-        }
-        if (input !== undefined) {
-            s.observation = undefined;
-            s.report = undefined;
-            s.runId = undefined;
+            clearRun(s);
         }
+        if (input !== undefined)
+            clearRun(s);
         s.input = nextInput;
         if (workflow !== undefined || input !== undefined)
             persist(s);
@@ -382,8 +379,9 @@ function registerExtension(pi, configuration) {
             persist(s, true);
             const ordinal = ++runOrdinal;
             let sequence = 0;
+            const runDeps = sop ? { ...deps, sop: sop.text } : deps;
             const report = await s.service.run(s.input, {
-                deps: observation.observe(driver ? withRecovery(driver, sop ? { ...deps, sop: sop.text } : deps) : sop ? { ...deps, sop: sop.text } : deps),
+                deps: observation.observe(driver ? withRecovery(driver, runDeps) : runDeps),
                 signal: driver ? AbortSignal.any([signal, driver.signal]) : signal,
                 ...(configuration.onWorkflowEvent ? { onTraceEvent: (event) => configuration.onWorkflowEvent({ workflowDigest: prepared.digest, runOrdinal: ordinal, sequence: ++sequence, event }) } : {}),
                 onEvent: event => {
@@ -515,9 +513,7 @@ function registerExtension(pi, configuration) {
                 s.input = structuredClone(args.input ?? {});
                 s.savedName = saved.name;
                 s.demo = undefined;
-                s.report = undefined;
-                s.observation = undefined;
-                s.runId = undefined;
+                clearRun(s);
                 persist(s);
                 const preview = view(ctx, s);
                 return textResult(modelJson({ preview: formatWorkflowView(preview), workflow: s.draft, input: s.input }), { ...result, saved, view: preview });
@@ -610,9 +606,7 @@ function registerExtension(pi, configuration) {
                     s.savedName = saved.name;
                     s.input = {};
                     s.demo = undefined;
-                    s.report = undefined;
-                    s.observation = undefined;
-                    s.runId = undefined;
+                    clearRun(s);
                     persist(s);
                     show(s, `Loaded procedure. Supply new input with /agentrun input. Loading never executes it.\n\n${formatWorkflowView(view(ctx, s))}`);
                 }

package/dist/workflow-session.js

@@ -124,7 +124,7 @@ function snapshotEntry(entry) {
         return undefined;
     }
 }
-function interrupted(s) {
+function markInterrupted(s) {
     if (!s.running)
         return s;
     s.running = false;
@@ -145,7 +145,7 @@ export function restoreWorkflowSession(branch) {
     for (let i = branch.length - 1; i >= 0; i--) {
         const snapshot = snapshotEntry(Object.getOwnPropertyDescriptor(branch, String(i))?.value);
         if (snapshot)
-            return interrupted(snapshot);
+            return markInterrupted(snapshot);
     }
     return undefined;
 }
@@ -162,7 +162,7 @@ export function workflowRunHistory(branch) {
         if (seen.has(key))
             continue;
         seen.add(key);
-        results.push(interrupted(snapshot));
+        results.push(markInterrupted(snapshot));
     }
     return results;
 }

package/dist/workflow-store.js

@@ -11,11 +11,11 @@ export class WorkflowStoreError extends Error {
         this.name = 'WorkflowStoreError';
     }
 }
-const validName = (name) => {
+const assertValidName = (name) => {
     if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name))
         throw new WorkflowStoreError('invalid_name', 'Use a workflow name of 1–64 lowercase letters, digits, hyphens or underscores, starting with a letter or digit.');
 };
-const validDigest = (digest) => {
+const assertValidDigest = (digest) => {
     if (typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest))
         throw new WorkflowStoreError('invalid_revision', 'A workflow revision must be its complete SHA-256 digest.');
 };
@@ -50,7 +50,7 @@ export class WorkflowStore {
     constructor(projectDirectory) { this.projectDirectory = resolve(projectDirectory); }
     async directory(name, create = false) {
         if (name !== undefined)
-            validName(name);
+            assertValidName(name);
         let directory = await realpath(this.projectDirectory);
         for (const component of ['.pi', 'agentrun', 'workflows', ...(name === undefined ? [] : [name])]) {
             directory = join(directory, component);
@@ -78,8 +78,8 @@ export class WorkflowStore {
         return directory;
     }
     async read(name, digest) {
-        validName(name);
-        validDigest(digest);
+        assertValidName(name);
+        assertValidDigest(digest);
         const directory = await this.directory(name);
         if (!directory)
             throw new WorkflowStoreError('not_found', 'Saved workflow revision not found.');
@@ -159,7 +159,7 @@ export class WorkflowStore {
         const revisions = [];
         const latest = new Map();
         for (const name of await readdir(directory)) {
-            validName(name);
+            assertValidName(name);
             const child = await this.directory(name);
             if (!child)
                 continue;
@@ -180,7 +180,7 @@ export class WorkflowStore {
             || Number(b.digest === latest.get(b.name)) - Number(a.digest === latest.get(a.name)) || a.digest.localeCompare(b.digest));
     }
     async load(name, digest) {
-        validName(name);
+        assertValidName(name);
         if (digest !== undefined)
             return this.read(name, digest);
         const latest = await this.latest(name);
@@ -197,7 +197,7 @@ export class WorkflowStore {
     }
     /** Publish a complete immutable revision atomically; identical saves are idempotent. */
     async save(name, value) {
-        validName(name);
+        assertValidName(name);
         const { workflow, digest } = checkedWorkflow(value);
         const directory = (await this.directory(name, true));
         const temporary = join(directory, `.pending-${randomUUID()}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-pi",
-  "version": "0.1.0-beta.20",
+  "version": "0.1.0-beta.21",
   "description": "Pi extension for building, running and evaluating AgentRun workflows",
   "type": "module",
   "license": "Apache-2.0",
@@ -50,12 +50,12 @@
     "@earendil-works/pi-coding-agent": "1.1.0",
     "@earendil-works/pi-durable": "1.1.0",
     "@earendil-works/pi-tui": "1.1.0",
-    "@parcha/pi-durable-disk": "0.1.0-beta.20",
+    "@parcha/pi-durable-disk": "0.1.0-beta.21",
     "typebox": "1.3.7"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.20",
-    "@parcha/agentrun-jev": "0.1.0-beta.20"
+    "@parcha/agentrun-dsl": "0.1.0-beta.21",
+    "@parcha/agentrun-jev": "0.1.0-beta.21"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",