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

package/README.md

@@ -1,6 +1,6 @@
 # agent.run() + Pi
 
-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).
+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). Pi 1.4 is not supported yet; the next release widens the range. Pin the peers you install to `@1.3.0` (the install lines below do): an unpinned install of Pi's packages now resolves 1.4.0, which this release does not support, and an unpinned `@earendil-works/pi-durable` or `@earendil-works/chord` fails with `ERESOLVE` against this package's peer range.
 
 ## Install
 
@@ -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.
 ```
@@ -65,7 +69,7 @@ After inspecting a definition, save it and reuse it in a new Pi session in the s
 /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.
+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. Loading a saved definition starts a new run with the current input and model. A run that was interrupted continues with `/agentrun run` (see the durable run below).
 
 | Command | What happens |
 | --- | --- |
@@ -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,26 @@ 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.
+
+## Durable workflows on pi-durable
+
+`@parcha/agentrun-pi/durable` runs a workflow as one pi-durable task, `agentrun.workflow`. `createWorkflowTool(host)` gives a pi-durable session the `agentrun` tool and the task its runs are; `createWorkflowExtension(host)` is the task alone, with `start`, `read` and `stop` for your own code. Install pi-durable and chord beside the package at the tested version: `npm install @earendil-works/pi-durable@1.3.0 @earendil-works/chord@1.3.0`. The `host` object supplies what a run needs (its tools, its node runner, its judge, an optional `reconcile`); see [the agentrun tool in a pi-durable session](../../docs/host-integration.md#the-agentrun-tool-in-a-pi-durable-session) and [Recovery and versions](../../docs/host-integration.md#recovery-and-versions). The code below is a description, not a sample: the host is yours.
+
+A run keeps its journal in the session's store. A process that is killed leaves the task pending, and `harness.resume()` in the next process runs the workflow again: committed nodes and effects are answered from the journal and not run again, and the run continues at the first step that did not commit. A typed question is a different matter: a route's answer is kept by the recovery wrapper itself, but any other question (`judge`, `pick`, `sift`, `ask`, `verify`) is answered again from its receipt only when the host wires both hooks of `decisionRecovery({ key, runtime, context })` (`recordDecision` in the dependencies it returns, `decision` in their `recovery`). Without them, a question inside a node that had not committed is asked again after a crash, and a second call can answer differently; see [Decision receipts](../../docs/host-integration.md#decision-receipts). An agent step is run again from its first turn after a crash, unless the host's node runner is the durable one (`nodeRunner`, from the same entry, with `durableNodes: true` in the `adapters` the host returns): then the step is one conversation the task owns, found again by its id, and a turn that committed is not requested again. Neither entry chooses this for you; it is the host's `runNode`. A tool call that was in flight at the crash has an unknown outcome and is never made again: the resume refuses it unless the host's `reconcile` settles it with a recorded result. A typed failure is a recorded outcome (`failed`, with a code), not a throw. A pause stops at a step boundary and the task stays pending until the host closes the Harness; reopening continues it. A cancel (pi's `abortTask`) ends the run for good, and a cancelled run never resumes.
 
 ## 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@1.3.0`) to use this entry. No other entry imports it.
 
 ```js
 import { builtinModels } from '@earendil-works/pi-ai/providers/all';
@@ -290,7 +310,7 @@ These commands create a separate `agentrun-pi-project` beside the checkout. You
 
 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.
+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@1.3.0 @earendil-works/pi-agent-core@1.3.0 @earendil-works/pi-tui@1.3.0 typebox@1.3.7`). 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 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.
 

package/dist/durable/decision-recovery.js

@@ -4,7 +4,7 @@
 // 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";
+import { appendDecision, DECISION_ROW_VERSION, readDecisionsFrom } 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 {
@@ -41,7 +41,12 @@ export function decisionRecovery(invocation) {
             await runtime.commit(async (tx) => { result = await change(tx); return undefined; }, context);
             return result;
         },
+        // The form the store holds is settled once per invocation, from this reader: the run's open.
+        snapshot: ((...args) => runtime.snapshot(...args)),
     };
+    // The run's rows as read so far: a resumed process reads the store once, and each later answer reads only the rows after them.
+    const known = [];
+    let next = 0;
     let chain = Promise.resolve();
     return {
         recordDecision(receipt, exchange) {
@@ -51,7 +56,10 @@ export function decisionRecovery(invocation) {
             return committed;
         },
         async decision(id) {
-            return answeredReceipt(await readDecisions(runtime, context), id, key);
+            const read = await readDecisionsFrom(harness, next, context);
+            known.push(...read.rows);
+            next = read.next;
+            return answeredReceipt(known, id, key);
         },
     };
 }

package/dist/durable/decisions.d.ts

@@ -84,13 +84,30 @@ export type DecisionRow = {
     state_sha256?: string;
     run_key?: string;
 };
+/** How many rows the keyed form holds: its next key. A few bytes, so rewriting it at every commit costs the same at every count. */
+export declare const DECISION_COUNT_DOC = "agentrun.decisions.count";
+/** A keyed row's key: its place, zero-padded so the keys sort in commit order. */
+export declare const decisionKey: (place: number) => string;
+export type DecisionForm = "single" | "keyed";
+/** What a writer commits through: a Harness, or anything with its `commit` and `snapshot`. It must be able to read the store: the form is the store's, and a writer that could not look would have to guess. */
+type Writer = Pick<Harness, "commit" | "snapshot">;
+/** The form a reader's store holds: `single` when the old document is there, else `keyed`. Settled once per reader (the run's open): a
+ *  run that began on the old document never switches mid-run. A reader with no way to read the store is refused, never guessed: a guess of `keyed` over an
+ *  old store would write both forms into one recording, and a guess of `single` would write the old list into a fresh one. */
+export declare function decisionForm(read: Partial<Pick<DocumentReader, "snapshot">>, context?: Context): Promise<DecisionForm>;
 /** Commit one row, appended after every row committed before it. */
-export declare function appendDecision(harness: Pick<Harness, "commit">, row: DecisionRow, context?: Context): Promise<void>;
+export declare function appendDecision(harness: Writer, 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[]>;
+/** The rows from place `from` on and the place after the last: for a keyed store only the new ones are read, so a reader that
+ *  keeps `next` reads each row once. The old document is read whole (its list is the rows; `next` is its length). */
+export declare function readDecisionsFrom(read: Pick<DocumentReader, "snapshot">, from: number, context?: Context): Promise<{
+    rows: DecisionRow[];
+    next: number;
+}>;
 /** 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">;
+    harness: Writer;
     release(): Promise<void>;
 };
 export type DecisionWriter = {
@@ -111,3 +128,4 @@ export declare function createDecisionWriter(options: {
     open: () => Promise<DecisionSession>;
     context?: Context;
 }): DecisionWriter;
+export {};

package/dist/durable/decisions.js

@@ -1,24 +1,76 @@
-// 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
+// A run's decision rows as pi-durable stores them, one row per typed question the run asked, in commit order. Two
+// forms, one per store: a run on a fresh store writes the KEYED family (below), one document of kind `agentrun.decisions`
+// per row, written once; a store that already holds the OLD single session document `agentrun.decisions` (its
+// `receipts` list, rewritten at every commit) keeps writing it to the end of its run, so a recording never holds both.
+// The row is a stored format (version 1) and is the same in both forms, byte for byte; it 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";
+import { defineDoc, defineDocFamily } 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;
+/** The old form: one session document whose `receipts` list is rewritten at every commit. Read, and written only in a store that holds it. */
 const DecisionsDoc = defineDoc({ kind: DECISION_RECEIPTS_DOC, version: 1, scope: "session", initial: () => ({ receipts: [] }) });
+/** The keyed form: one document per row, of the same kind, keyed by the row's place in the run's rows (`keyOf`), written once. The
+ *  document's value is exactly the row. */
+const DecisionRowDoc = defineDocFamily({ kind: DECISION_RECEIPTS_DOC, version: 1, scope: "session", family: true, initial: () => ({}) });
+/** How many rows the keyed form holds: its next key. A few bytes, so rewriting it at every commit costs the same at every count. */
+export const DECISION_COUNT_DOC = "agentrun.decisions.count";
+const DecisionCountDoc = defineDoc({ kind: DECISION_COUNT_DOC, version: 1, scope: "session", initial: () => ({ count: 0 }) });
+/** A keyed row's key: its place, zero-padded so the keys sort in commit order. */
+export const decisionKey = (place) => String(place).padStart(8, "0");
+const forms = new WeakMap();
+/** The form a reader's store holds: `single` when the old document is there, else `keyed`. Settled once per reader (the run's open): a
+ *  run that began on the old document never switches mid-run. A reader with no way to read the store is refused, never guessed: a guess of `keyed` over an
+ *  old store would write both forms into one recording, and a guess of `single` would write the old list into a fresh one. */
+export function decisionForm(read, context = BACKGROUND_CONTEXT) {
+    if (typeof read.snapshot !== "function")
+        return Promise.reject(new Error("agentrun.decisions: the writer cannot read the store, so it cannot tell which form the store holds; give it a Harness, or an object with commit and snapshot"));
+    let known = forms.get(read);
+    if (!known) {
+        known = read.snapshot(DecisionsDoc, context).then((old) => (old === undefined ? "keyed" : "single"));
+        forms.set(read, known);
+        known.catch(() => forms.delete(read));
+    }
+    return known;
+}
 /** 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);
+    if ((await decisionForm(harness, context)) === "single") {
+        await harness.commit(async (tx) => { (await tx.doc(DecisionsDoc)).receipts.push(stored); }, context);
+        return;
+    }
+    await harness.commit(async (tx) => {
+        const count = await tx.doc(DecisionCountDoc);
+        const place = count.count;
+        count.count = place + 1;
+        Object.assign(await tx.doc(DecisionRowDoc, decisionKey(place), null), 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 ?? []);
+    return (await readDecisionsFrom(read, 0, context)).rows;
+}
+/** The rows from place `from` on and the place after the last: for a keyed store only the new ones are read, so a reader that
+ *  keeps `next` reads each row once. The old document is read whole (its list is the rows; `next` is its length). */
+export async function readDecisionsFrom(read, from, context = BACKGROUND_CONTEXT) {
+    if ((await decisionForm(read, context)) === "single") {
+        const rows = ((await read.snapshot(DecisionsDoc, context))?.receipts ?? []);
+        return { rows: rows.slice(from), next: rows.length };
+    }
+    const total = (await read.snapshot(DecisionCountDoc, context))?.count ?? 0;
+    const rows = [];
+    for (let at = from; at < total; at += 64) {
+        const batch = await Promise.all(Array.from({ length: Math.min(64, total - at) }, (_, i) => read.snapshot(DecisionRowDoc, decisionKey(at + i), context)));
+        for (const doc of batch)
+            if (doc !== undefined)
+                rows.push(doc);
+    }
+    return { rows, next: total };
 }
 /** 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. */

package/dist/durable/index.d.ts

@@ -1,10 +1,11 @@
 export type { RecoveryBinding, RecoveryEffect, RecoveryJournal, RecoveryNote, RecoveryStore } from "@parcha/agentrun-dsl/recovery";
 export { documentStore, type DocumentStoreHost, type DocumentStoreOptions } from "./store.js";
-export { committedRoutes, durableDoc, readJournal, type JournalView } from "./readers.js";
+export { committedRoutes, durableDecisions, durableDoc, readJournal, type JournalView } from "./readers.js";
 export { recordCommits, recordingLines, snapshotLines, type RecordingLine, type RecordingSource } from "./recording.js";
 export { reuseReceipts, seedReceipts, ReceiptIndex, type ReceiptReuse, type ReuseReceiptsOptions, type ReusableTool } from "./receipts.js";
+export { effectResultOf } from "../effect-result.js";
 export { NewerTaskError, refuseNewerTasks, toolResult, ToolResultKeyError, type TextBlock } from "./pi-versions.js";
-export { DECISION_RECEIPTS_DOC, DECISION_ROW_VERSION, appendDecision, createDecisionWriter, readDecisions } from "./decisions.js";
+export { DECISION_COUNT_DOC, DECISION_RECEIPTS_DOC, DECISION_ROW_VERSION, appendDecision, createDecisionWriter, decisionKey, readDecisions } from "./decisions.js";
 export type { DecisionRow, DecisionRowRule, DecisionSession, DecisionWriter } from "./decisions.js";
 export { decisionRecovery, type DecisionRecovery } from "./decision-recovery.js";
 export { DELIVERY_ATTEMPTS, deliver, deliveryEnded, deliveryTerminates, deliveryText, disagreementText, extrasNotInRecord, fileSubmission, gate, healNullSpellings, lintRecordRoot, lintRecordSchema, mixedFileSubmission, nudgeText, nullSpellings, parseStringifiedContainers, repairRecord, spend, submitFooter, VIOLATIONS_SHOWN, } from "./record.js";

package/dist/durable/index.js

@@ -1,9 +1,10 @@
 export { documentStore } from "./store.js";
-export { committedRoutes, durableDoc, readJournal } from "./readers.js";
+export { committedRoutes, durableDecisions, durableDoc, readJournal } from "./readers.js";
 export { recordCommits, recordingLines, snapshotLines } from "./recording.js";
 export { reuseReceipts, seedReceipts, ReceiptIndex } from "./receipts.js";
+export { effectResultOf } from "../effect-result.js";
 export { NewerTaskError, refuseNewerTasks, toolResult, ToolResultKeyError } from "./pi-versions.js";
-export { DECISION_RECEIPTS_DOC, DECISION_ROW_VERSION, appendDecision, createDecisionWriter, readDecisions } from "./decisions.js";
+export { DECISION_COUNT_DOC, DECISION_RECEIPTS_DOC, DECISION_ROW_VERSION, appendDecision, createDecisionWriter, decisionKey, readDecisions } from "./decisions.js";
 export { decisionRecovery } from "./decision-recovery.js";
 export { DELIVERY_ATTEMPTS, deliver, deliveryEnded, deliveryTerminates, deliveryText, disagreementText, extrasNotInRecord, fileSubmission, gate, healNullSpellings, lintRecordRoot, lintRecordSchema, mixedFileSubmission, nudgeText, nullSpellings, parseStringifiedContainers, repairRecord, spend, submitFooter, VIOLATIONS_SHOWN, } from "./record.js";
 export { workspaceRecordFile } from "./record-file.js";

package/dist/durable/node-runner.d.ts

@@ -5,12 +5,18 @@ import { type RecoveryNodeParams } from "@parcha/agentrun-dsl/recovery";
 import { type NodeScope } from "./node.js";
 import { type Disagreement, type RecordContract } from "./record.js";
 import { type RecordToolOptions } from "./record-tool.js";
-/** A node's configuration: what its conversation's prompt and `submit` tool are drawn from. */
+/** A node's configuration: what its conversation's prompt and `submit` tool are drawn from. `input` is the node's
+ *  prompt state, the JSON object its user text was stringified from, for a reader that shows what the node was given;
+ *  it is absent when that text is not a JSON object, and in a document an older build wrote. A fork of the conversation
+ *  starts without it, as with the record: the runner never attaches a fork, so a fork is no node and waits for nothing. */
 export declare const NodeDoc: import("@earendil-works/pi-durable").ConversationDocToken<{
     system: string;
     label: string;
     schema: JsonValue | null;
     fileKey: string | null;
+    input?: {
+        [key: string]: JsonValue;
+    };
 }>;
 /** A node as the host is asked about it: the interpreter's request, and the attempt it runs as, with the sessions of
  *  the attempts before it (a host that refuses to repeat a call an earlier attempt left unknown reads them). */

package/dist/durable/node-runner.js

@@ -17,10 +17,24 @@ import { closeNodeAttempt, runNodeAttempt } from "./node.js";
 import { DELIVERY_ATTEMPTS, lintRecordRoot, submitFooter } from "./record.js";
 import { workspaceRecordFile } from "./record-file.js";
 import { RecordDoc, recordNudge, recordTool, spendNudge, submitDefinition } from "./record-tool.js";
-/** A node's configuration: what its conversation's prompt and `submit` tool are drawn from. */
+/** A node's configuration: what its conversation's prompt and `submit` tool are drawn from. `input` is the node's
+ *  prompt state, the JSON object its user text was stringified from, for a reader that shows what the node was given;
+ *  it is absent when that text is not a JSON object, and in a document an older build wrote. A fork of the conversation
+ *  starts without it, as with the record: the runner never attaches a fork, so a fork is no node and waits for nothing. */
 export const NodeDoc = defineDoc({
-    kind: "agentrun.node", version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ system: "", label: "", schema: null, fileKey: null }),
+    kind: "agentrun.node", version: 1, scope: "conversation", history: "latest", fork: "initial", initial: () => ({ system: "", label: "", schema: null, fileKey: null }),
 });
+/** The JSON object a node's user text holds, or nothing: the interpreter sends a node its prompt state stringified. */
+function inputOf(user) {
+    let value;
+    try {
+        value = JSON.parse(user);
+    }
+    catch {
+        return {};
+    }
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? { input: value } : {};
+}
 /** A node that delivered no record. `final` says a second attempt would spend the same again: the model did not
  *  answer, or the delivery attempts are spent. `unanswered` is pi's own account of a submission the model did not
  *  answer: its reason (`failed`, `aborted`, ...) and detail. */
@@ -165,6 +179,7 @@ export function nodeRunner(host, options = {}) {
                 const offered = (listed(agent.tools) ? agent.tools : listed(agent.extensions) ? agent.extensions.flatMap((selected) => selected.tools ?? []) : [])
                     .map((offer) => offer.name).filter((name) => name !== "submit");
                 const system = [...node.system, host.stance?.(node, { tools: offered })].filter(Boolean).join("\n\n");
+                const input = inputOf(node.user);
                 const reviewers = [
                     ...(host.verify ? [(candidate, at) => host.verify(candidate, node, at)] : []),
                     ...(review ? [async (candidate) => {
@@ -183,14 +198,14 @@ export function nodeRunner(host, options = {}) {
                     agent: withNodes(agent),
                     user: `${node.user}\n${submitFooter({ label, schema: node.schema, reviewed: reviewers.length > 0, ...(record.file ? { fileKey: record.file.key } : {}), ...(record.instructions ? { instructions: record.instructions } : {}) })}`,
                     init: async (tx, id) => {
-                        Object.assign(await tx.doc(NodeDoc, id), { system, label, schema: node.schema, fileKey: record.file?.key ?? null });
+                        Object.assign(await tx.doc(NodeDoc, id), { system, label, schema: node.schema, fileKey: record.file?.key ?? null, ...input });
                         await host.init?.(node, tx, id);
                     },
                     adopt: async (tx, id, stored) => {
                         const held = await tx.doc(NodeDoc, id);
                         if (held.schema !== null)
                             return;
-                        Object.assign(held, { system: typeof stored.system === "string" ? stored.system : system, label, schema: node.schema, fileKey: record.file?.key ?? null });
+                        Object.assign(held, { system: typeof stored.system === "string" ? stored.system : system, label, schema: node.schema, fileKey: record.file?.key ?? null, ...input });
                         // The older build selected an extension of its own for this conversation, which is not installed here.
                         const own = typeof stored.extension === "string" ? [{ name: stored.extension }] : [];
                         const given = withNodes(agent);

package/dist/durable/readers.d.ts

@@ -16,6 +16,10 @@ export type JournalView = {
 export declare function withDurableFile<T>(file: string, read: (db: Database) => T): T | null;
 /** A Session document of the run's store `file`, read-only; undefined when the file or the document is absent. */
 export declare function durableDoc<T = Record<string, unknown>>(file: string, kind: string, key?: string): T | undefined;
+/** The decision rows (`agentrun.decisions`) of the run's store `file`, in commit order, in whichever form the store holds: the single
+ *  document's `receipts` list, or the keyed documents (one row each, in the order of their keys). A reader that folds decisions from the
+ *  store uses this and not `durableDoc(file, "agentrun.decisions").receipts`, which is nothing in the keyed form. */
+export declare function durableDecisions(file: string): Array<Record<string, unknown>>;
 /** The journal `key` holds in the run's store `file`, as the last commit left it; undefined when the file holds no
  *  such journal or none has bound it. `effects` are every effect the journal admitted, once each, in the order they were
  *  admitted, in either layout: in the keyed one (`agentrun.frozen_run.v4`) the effects a map item owns, nested maps

package/dist/durable/readers.js

@@ -5,6 +5,7 @@
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import { apply } from "@earendil-works/chord/delta";
+import { decisionKey } from "./decisions.js";
 import { effectKey } from "./store.js";
 /** The run's store `file`, opened read-only for `read`; null when there is no such file. Every query of one `read` runs
  *  in one read transaction, so what it returns is one commit's view, whatever a writer commits meanwhile. */
@@ -69,6 +70,25 @@ function itemEffects(db, key, table, into) {
 export function durableDoc(file, kind, key) {
     return (withDurableFile(file, (db) => sessionDoc(db, kind, key)) ?? undefined);
 }
+/** The decision rows (`agentrun.decisions`) of the run's store `file`, in commit order, in whichever form the store holds: the single
+ *  document's `receipts` list, or the keyed documents (one row each, in the order of their keys). A reader that folds decisions from the
+ *  store uses this and not `durableDoc(file, "agentrun.decisions").receipts`, which is nothing in the keyed form. */
+export function durableDecisions(file) {
+    return withDurableFile(file, (db) => {
+        const single = sessionDoc(db, "agentrun.decisions");
+        if (single)
+            return Array.isArray(single.receipts) ? single.receipts : [];
+        const count = sessionDoc(db, "agentrun.decisions.count")?.count;
+        const rows = [];
+        if (typeof count === "number")
+            for (let place = 0; place < count; place += 1) {
+                const row = sessionDoc(db, "agentrun.decisions", decisionKey(place));
+                if (row)
+                    rows.push(row);
+            }
+        return rows;
+    }) ?? [];
+}
 /** The journal `key` holds in the run's store `file`, as the last commit left it; undefined when the file holds no
  *  such journal or none has bound it. `effects` are every effect the journal admitted, once each, in the order they were
  *  admitted, in either layout: in the keyed one (`agentrun.frozen_run.v4`) the effects a map item owns, nested maps

package/dist/durable/receipts.d.ts

@@ -32,7 +32,10 @@ export type ReuseReceiptsOptions = {
     /** Whether a repeat of another session's paid call is answered from its receipt (a continuation's sessions do). Receipts
      *  are recorded either way. */
     answer: boolean;
-    /** Effects whose outcome is unknown, from the handoff (`handoff.unknown`): a call equal to one is refused. */
+    /** Effects whose outcome is unknown, from the handoff (`handoff.unknown`): a call equal to one is refused, with a tool
+     *  result whose `details.effect_status` is "unknown". A workflow call that runs a wrapped tool passes its result through
+     *  `effectResultOf`, which turns that refusal into the DSL's thrown signal. A durable task runs the host's own `runEffect`
+     *  (`WorkflowHostParts`), so a durable host calls it there; without it the refusal reads as the call's result. */
     unknown?: readonly Pick<InheritedUnknown, "name" | "argsHash" | "intent">[];
     /** How a call's key is derived. Default: the gateway tool a `fetch` wrapper names, else the tool's own name. */
     keyOf?: (toolName: string, args: unknown) => {

package/dist/durable/recording.js

@@ -54,6 +54,11 @@ function documentLine(id, kind, key, value, version, conv, commit) {
             data: { doc: kind, ...(key !== undefined ? { key } : {}), value, version },
         } };
 }
+const conversationLine = (record, commit) => ({ commit, rank: -1, id: Number(record.id), line: { channel: "durable", source: "pi", kind: "pi.conversation", commit, conv: Number(record.id), data: {
+            id: Number(record.id),
+            ...(record.parent ? { parent: { conversationId: Number(record.parent.conversationId), at: Number(record.parent.at) } } : {}),
+            ...(record.owner ? { owner: { conversationId: Number(record.owner.conversationId), taskId: Number(record.owner.taskId) } } : {}),
+        } } });
 const entryLine = (entry, commit) => ({ commit, rank: 1, id: Number(entry.id), line: {
         channel: "durable", source: "pi", kind: String(entry?.kind ?? "pi.entry"), commit, conv: Number(entry.conversationId), data: entry,
     } });
@@ -74,14 +79,23 @@ function numbered(placed, genAt, extra = {}) {
     }
     return lines;
 }
+/** A document's revisions in commit order, each with the document's whole value after it: a base replaces the value,
+ *  a delta is applied to a copy of it. */
+function* replayed(revisions) {
+    let value;
+    for (const rev of revisions) {
+        value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
+        yield [rev, value];
+    }
+}
 /** Each node attempt's conversation and path, from every `agentrun.nodes` document's latest value. */
 function nodeConversations(db) {
     const out = new Map();
     for (const doc of db.prepare("SELECT id, key_value FROM documents WHERE kind = ? AND family = 1").all(JSON.stringify("agentrun.nodes"))) {
+        // Only the latest value is kept: a document rewritten whole at each commit has as many values as revisions.
         let value;
-        for (const rev of db.prepare("SELECT kind, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(doc.id)) {
-            value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
-        }
+        for (const [, next] of replayed(db.prepare("SELECT kind, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(doc.id)))
+            value = next;
         const found = nodeConversation(JSON.parse(doc.key_value), value);
         if (found)
             out.set(found[0], found[1]);
@@ -92,9 +106,7 @@ function nodeConversations(db) {
 function driverGenerations(db) {
     const out = [];
     for (const { id } of db.prepare("SELECT id FROM documents WHERE kind = ?").all(JSON.stringify("agentrun.driver"))) {
-        let value;
-        for (const rev of db.prepare("SELECT seq, kind, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(id)) {
-            value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
+        for (const [rev, value] of replayed(db.prepare("SELECT seq, kind, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(id))) {
             if (typeof value?.generation === "number")
                 out.push([rev.seq, value.generation]);
         }
@@ -132,13 +144,17 @@ export function recordingLines(file, options = {}) {
             const kind = JSON.parse(doc.kind);
             const key = doc.family === 1 ? JSON.parse(doc.key_value) : undefined;
             const conv = doc.scope_kind === "conversation" ? doc.owner_id : doc.scope_kind === "task" ? taskConversation.get(doc.owner_id) : undefined;
-            let value;
-            for (const rev of db.prepare("SELECT seq, kind, version, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(doc.id)) {
-                value = rev.kind === "base" ? JSON.parse(rev.content) : apply(structuredClone(value), JSON.parse(rev.content));
+            for (const [rev, value] of replayed(db.prepare("SELECT seq, kind, version, content FROM document_revisions WHERE document_id = ? ORDER BY seq").all(doc.id))) {
                 if (rev.seq > after)
                     placed.push(documentLine(doc.id, kind, key, structuredClone(value), rev.version, conv, rev.seq));
             }
         }
+        // A conversation's row carries no commit of its own: it is read at the first commit that wrote anything of it (an entry, or a revision of one of its documents, which pi writes in the commit that creates it), and one with neither yet at the store's last commit, the latest it can have been made.
+        const last = db.prepare("SELECT next_seq FROM durable_metadata WHERE singleton = 1").get().next_seq - 1;
+        const seen = "SELECT conversation_id AS cid, commit_seq AS seq FROM entries UNION ALL SELECT d.owner_id AS cid, r.seq AS seq FROM documents d JOIN document_revisions r ON r.document_id = d.id WHERE d.scope_kind = 'conversation'";
+        for (const row of db.prepare(`SELECT c.record AS record, COALESCE(MIN(x.seq), ?) AS commit_seq FROM conversations c LEFT JOIN (${seen}) x ON x.cid = c.id GROUP BY c.id HAVING COALESCE(MIN(x.seq), ?) > ?`).all(last, last, after)) {
+            placed.push(conversationLine(JSON.parse(row.record), row.commit_seq));
+        }
         for (const entry of db.prepare("SELECT commit_seq, record FROM entries WHERE commit_seq > ?").all(after)) {
             placed.push(entryLine(JSON.parse(entry.record), entry.commit_seq));
         }
@@ -181,7 +197,9 @@ function publicationLines(publication, state) {
             placed.push(entryLine(structuredClone(change.value), commit));
         else if (change.type === "task")
             placed.push(taskLine(structuredClone(change.value), commit));
-        // A conversation's or a submission's record, and a document copy (it carries no value), make no line.
+        else if (change.type === "conversation")
+            placed.push(conversationLine(change.value, commit));
+        // A submission's record, and a document copy (it carries no value), make no line.
     }
     if (written !== undefined)
         state.gen = written;
@@ -267,7 +285,7 @@ export async function snapshotLines(storage, options) {
         ...conversations.map((conversation) => ({ scope: { kind: "conversation", conversationId: conversation.id }, conv: Number(conversation.id) })),
         ...tasks.map((task) => ({ scope: { kind: "task", taskId: task.id }, conv: Number(task.conversationId) })),
     ];
-    const placed = [];
+    const placed = conversations.map((conversation) => conversationLine(conversation, at));
     let driverGen;
     for (const { scope, conv } of scopes) {
         for (const record of await scanAll((cursor) => storage.scanDocuments({ scope, at: "current" }, page, cursor, context))) {

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/durable/workflow-tool.js

@@ -8,6 +8,7 @@ import { Type } from "typebox";
 import { inspectWorkflow, WORKFLOW_NODE_KINDS } from "@parcha/agentrun-dsl";
 import { canonicalHash } from "@parcha/agentrun-dsl/recovery";
 import { extensionStructuralLimits, WorkflowExtensionService } from "../extension-service.js";
+import { checkHostTools } from "../host-tools.js";
 import { modelJson } from "../presentation.js";
 import { WorkflowStore } from "../workflow-store.js";
 import { progressLines, WorkflowObservation } from "../workflow-view.js";
@@ -36,6 +37,8 @@ const answer = (value) => toolResult([{ type: "text", text: modelJson(value) }],
 /** The tool, and the workflow task its runs are: install `extension` (it carries both) and list the tool's name in the
  *  agent definition. `workflow` reads and stops runs from the host's side. */
 export function createWorkflowTool(host) {
+    // The host's tools pass the check the coding-agent extension's do; the tool's own name and the node runner's submit are reserved.
+    checkHostTools(host.tools ?? [], { reserved: [host.name ?? "agentrun", "submit"], executable: false });
     const names = (host.tools ?? []).map((tool) => tool.name);
     const checker = () => new WorkflowExtensionService({ allowedTools: names });
     /** Inspect's checks, after naming any tool the workflow uses (a call's, or an agent node's) that the host did not

package/dist/effect-result.d.ts

@@ -0,0 +1,7 @@
+/** A tool's result at a workflow call's effect boundary. A call `reuseReceipts` refused (an identical earlier call was cut
+ *  while it ran) is an effect whose outcome is unknown, so it becomes the DSL's one signal for that: a thrown
+ *  `RecoveryError` with code `FROZEN_EFFECT_UNKNOWN`, the refusal its cause. A refusal is keyed by the exact shape only
+ *  `reuseReceipts` writes — `{ isError: true, details: { effect_status: "unknown", refused: true } }` — not by
+ *  `effect_status: "unknown"` alone, which an ordinary tool (an inconclusive classifier) may carry in its own answer.
+ *  Any other result is the effect's result, returned as it is. */
+export declare function effectResultOf<T>(result: T, label: string): T;

package/dist/effect-result.js

@@ -0,0 +1,17 @@
+// The boundary where a pi tool's result becomes a workflow call's effect result. It imports only the DSL, so the plain
+// extension and the durable host both use it.
+import { RecoveryError } from "@parcha/agentrun-dsl/recovery";
+/** A tool's result at a workflow call's effect boundary. A call `reuseReceipts` refused (an identical earlier call was cut
+ *  while it ran) is an effect whose outcome is unknown, so it becomes the DSL's one signal for that: a thrown
+ *  `RecoveryError` with code `FROZEN_EFFECT_UNKNOWN`, the refusal its cause. A refusal is keyed by the exact shape only
+ *  `reuseReceipts` writes — `{ isError: true, details: { effect_status: "unknown", refused: true } }` — not by
+ *  `effect_status: "unknown"` alone, which an ordinary tool (an inconclusive classifier) may carry in its own answer.
+ *  Any other result is the effect's result, returned as it is. */
+export function effectResultOf(result, label) {
+    const row = result;
+    const details = row?.details;
+    if (row?.isError === true && details?.effect_status === "unknown" && details?.refused === true) {
+        throw new RecoveryError(`${label}: an identical earlier call was cut while it ran, so whether it happened is unknown`, "FROZEN_EFFECT_UNKNOWN", { cause: result });
+    }
+    return result;
+}

package/dist/extension-service.js

@@ -145,7 +145,7 @@ function localDiagnostic(error) {
             };
         if (reason === 'invalid_state' || reason === 'invalid_questions')
             return { code: `jev_${reason}`, stage,
-                message: reason === 'invalid_state' ? 'Jev state must be JSON-serializable text, an object, an array or null. No request was sent.'
+                message: reason === 'invalid_state' ? 'Jev state must be JSON-serializable text, an object or an array. No request was sent.'
                     : 'Jev needs a nonempty JSON question map. No request was sent.' };
     }
     // Trusted validation can invoke authored factories; its free-form problems may contain thrown text.
@@ -257,7 +257,8 @@ export class WorkflowExtensionService {
         this.rubricSections = freeze(snapshot(options.rubricSections ?? {}));
         if (Object.entries(this.rubricSections).some(([name, text]) => !name.trim() || typeof text !== 'string' || !text.trim()))
             throw new ExtensionServiceError('configuration', 'Rubric sections require nonempty names and text.');
-        this.limits = { ...defaults, ...options.limits };
+        // A field given as undefined is an omitted one: it keeps its default.
+        this.limits = { ...defaults, ...Object.fromEntries(Object.entries(options.limits ?? {}).filter(([, value]) => value !== undefined)) };
         for (const key of Object.keys(ceilings)) {
             const value = this.limits[key];
             if (value === null && ['deadlineMs', 'maxAgentCalls', 'maxJudgeCalls', 'maxToolCalls'].includes(key))

package/dist/extension.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { Compile } from 'typebox/compile';
+import { checkHostTools } from './host-tools.js';
 import { Text } from '@earendil-works/pi-tui';
 import { createReadToolDefinition, createBashToolDefinition, createEditToolDefinition, createWriteToolDefinition, createGrepToolDefinition, createFindToolDefinition, createLsToolDefinition, VERSION as PI_VERSION, } from '@earendil-works/pi-coding-agent';
 import { formatWorkflowTree, inspectWorkflow, AUTHOR_SKILL_NAME } from '@parcha/agentrun-dsl';
@@ -8,6 +9,7 @@ import { createJevRunner } from '@parcha/agentrun-jev';
 import { createPiHostRunner, PI_MODEL_SETUP_MESSAGE } from './host-session.js';
 import { piHostLine } from './pi-host.js';
 import { workflowToolContext } from './tool-context.js';
+import { effectResultOf } from './effect-result.js';
 import { WorkflowExtensionService, ExtensionServiceError, extensionStructuralLimits } from './extension-service.js';
 import { demoInput, demoSearchTool, demoWorkflow, scriptedDemoDeps } from './demo.js';
 import { cleanText as safe, formatRunReport, modelJson } from './presentation.js';
@@ -40,6 +42,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')
@@ -52,7 +56,8 @@ export function createAgentRunExtension(options = {}) {
         throw new Error('onWorkflowEvent must be a host callback');
     if (options.sop !== undefined && (typeof options.sop !== 'string' || !options.sop.trim()))
         throw new Error('sop must be nonempty text');
-    const limits = { ...nativeLimits, ...options.runtimeLimits };
+    // A field given as undefined is an omitted one: it keeps its default.
+    const limits = { ...nativeLimits, ...Object.fromEntries(Object.entries(options.runtimeLimits ?? {}).filter(([, value]) => value !== undefined)) };
     for (const [key, value] of Object.entries(limits)) {
         if (!(key in nativeLimits) || value !== null && (!Number.isSafeInteger(value) || value < 1 || value > nativeLimits[key])) {
             throw new Error('runtimeLimits must use known fields with positive bounded integers or explicit null');
@@ -74,21 +79,8 @@ function registerExtension(pi, configuration) {
     const toolSet = (ctx, trusted = false) => {
         if (configuration.hostTools) {
             const supplied = configuration.hostTools(ctx);
-            if (!Array.isArray(supplied) || supplied.length > 100)
-                throw new Error('Host must supply at most 100 explicit tool definitions');
-            const names = new Set();
-            return supplied.map(tool => {
-                if (!tool || typeof tool.name !== 'string' || !tool.name.trim() || tool.name.length > 200
-                    || ['agentrun', 'submit'].includes(tool.name) || names.has(tool.name))
-                    throw new Error('Host tools contain an invalid, reserved or duplicate name');
-                if (typeof tool.execute !== 'function' || !tool.parameters || typeof tool.parameters !== 'object')
-                    throw new Error('Host tools require an executable definition and parameter schema');
-                Compile(tool.parameters);
-                if (tool.resultSchema)
-                    Compile(tool.resultSchema);
-                names.add(tool.name);
-                return { ...tool, parameters: structuredClone(tool.parameters), ...(tool.resultSchema ? { resultSchema: structuredClone(tool.resultSchema) } : {}) };
-            });
+            checkHostTools(supplied, { reserved: ['agentrun', 'submit'], executable: true });
+            return supplied.map(tool => ({ ...tool, parameters: structuredClone(tool.parameters), ...(tool.resultSchema ? { resultSchema: structuredClone(tool.resultSchema) } : {}) }));
         }
         const active = new Set(pi.getActiveTools());
         const builtins = new Set(pi.getAllTools().filter(t => t.sourceInfo.source === 'builtin').map(t => t.name));
@@ -188,15 +180,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);
@@ -289,6 +276,8 @@ function registerExtension(pi, configuration) {
                         throw new ToolInputValidationError(node.label, tool.name, error.problems);
                     throw error;
                 }
+                // A call the receipts refused is an effect whose outcome is unknown: the DSL's signal, thrown, never a returned value.
+                result = effectResultOf(result, node.label);
                 return !configuration.hostTools && ['search', 'support_demo_lookup', 'support_demo_handoff'].includes(node.tool ?? '') ? result.details : { content: result.content, ...(result.details === undefined ? {} : { details: result.details }) };
             },
         };
@@ -382,8 +371,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 +505,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 +598,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/host-tools.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Refuses a host's tool list unless it is an array of at most 100 tools, each with a name of 1 to 200 characters that
+ * is not blank, not in `reserved` and not repeated, and an object parameter schema (and result schema, when given) the
+ * compiler takes. With `executable`, each tool also needs an `execute` function. Throws on the first problem.
+ */
+export declare function checkHostTools(tools: unknown, options: {
+    reserved: readonly string[];
+    executable: boolean;
+}): void;

package/dist/host-tools.js

@@ -0,0 +1,27 @@
+// The one check of a host's tool list, wherever a host registers tools: the coding-agent extension (`hostTools`) and
+// the pi-durable workflow tool (`tools`). It loads without pi's coding agent, agent core or TUI.
+import { Compile } from 'typebox/compile';
+/** The most tools a host may register. */
+const MAX_HOST_TOOLS = 100;
+/**
+ * Refuses a host's tool list unless it is an array of at most 100 tools, each with a name of 1 to 200 characters that
+ * is not blank, not in `reserved` and not repeated, and an object parameter schema (and result schema, when given) the
+ * compiler takes. With `executable`, each tool also needs an `execute` function. Throws on the first problem.
+ */
+export function checkHostTools(tools, options) {
+    if (!Array.isArray(tools) || tools.length > MAX_HOST_TOOLS)
+        throw new Error(`Host must supply at most ${MAX_HOST_TOOLS} explicit tool definitions`);
+    const names = new Set();
+    for (const tool of tools) {
+        if (!tool || typeof tool.name !== 'string' || !tool.name.trim() || tool.name.length > 200
+            || options.reserved.includes(tool.name) || names.has(tool.name))
+            throw new Error('Host tools contain an invalid, reserved or duplicate name');
+        if ((options.executable && typeof tool.execute !== 'function') || !tool.parameters || typeof tool.parameters !== 'object') {
+            throw new Error(options.executable ? 'Host tools require an executable definition and parameter schema' : 'Host tools require a parameter schema');
+        }
+        Compile(tool.parameters);
+        if (tool.resultSchema)
+            Compile(tool.resultSchema);
+        names.add(tool.name);
+    }
+}

package/dist/skills/author/references/language.md

@@ -12,7 +12,7 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
 - The input contract: the run starts from the input object and nothing else. `input.schemaId`, when present, is enforced before the first node. A node may read only input keys and keys an earlier node wrote.
 - `output.schemaId` validates the final value; `output.path` selects it from state and must name an input key or a key an earlier node wrote.
 - State is one object. Each step writes its result under one key: its `as`, or, for an agent, decide, extract or code node without `as`, its label. A report writes `report_markdown`. A code node without `as` that returns an object merges that object's top-level fields instead.
-- Keys that begin with `$` are engine-owned: `$host` (host state), `<as>$answers` (raw judge answers and confidences) and `<as>$verify` (verifier results). Read them; never write one. No `as` may begin with `$`, and neither may the label of an agent, decide, extract or code node without `as`.
+- Keys that hold a `$` are engine-owned: `$host` (host state), `<as>$answers` (raw judge answers and confidences) and `<as>$verify` (verifier results). Read them; never write one. No `as` may hold a `$`, and neither may the label of an agent, decide, extract or code node without `as`.
 - `{dot.path}` placeholders are replaced from state in `state` maps (including `verify.state` and `ask.state`), call `args`, `input`, `env` and `produces`, a child workflow's `input`, and `escalate.summary`; `pick` and `sift` `describe` templates also see `{item...}`. A placeholder that is the whole string keeps its value's type. Every key a state map, call or child input interpolates must be produced upstream. `instructions`, `code` and `command` are literal and never interpolated.
 
 ## Node kinds

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.23",
   "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.23",
     "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.23",
+    "@parcha/agentrun-jev": "0.1.0-beta.23"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",