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

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
 
@@ -69,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 |
 | --- | --- |
@@ -260,9 +260,15 @@ 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. 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.
+`@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';
@@ -304,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 DurableReadOptions, 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

@@ -12,15 +12,30 @@
 import { randomUUID } from "node:crypto";
 import { configure, defineDoc, defineExtension, GenerationTask, hook, section, } from "@earendil-works/pi-durable";
 import { canonicalSha256, runStopOf } from "@parcha/agentrun-dsl/recovery";
+import { SUBMIT_TOOL } from "../host-tools.js";
 import { nodeThinking } from "../thinking.js";
 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. */
@@ -64,7 +79,7 @@ async function underStop(signal, work) {
     }
 }
 const listed = (value) => Array.isArray(value);
-const isSubmit = (tool) => tool.name === "submit";
+const isSubmit = (tool) => tool.name === SUBMIT_TOOL;
 /** The node runner over a host. Install `extension` in the registry before the Harness opens; `on` binds the runner
  *  to where its conversations live (`taskScope`, `hostScope`). */
 export function nodeRunner(host, options = {}) {
@@ -163,8 +178,9 @@ export function nodeRunner(host, options = {}) {
                 const { agent, record } = await underStop(signal, async () => ({ agent: leveled(await host.agent(node), node), record: await host.record?.(node) ?? {} }));
                 const label = record.label ?? `the ${node.label} record`;
                 const offered = (listed(agent.tools) ? agent.tools : listed(agent.extensions) ? agent.extensions.flatMap((selected) => selected.tools ?? []) : [])
-                    .map((offer) => offer.name).filter((name) => name !== "submit");
+                    .map((offer) => offer.name).filter((name) => name !== SUBMIT_TOOL);
                 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 +199,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

@@ -11,17 +11,26 @@ export type JournalView = {
     notes: RecoveryNote[];
     effects: RecoveryEffect[];
 };
+/** How a reader opens the store file. `immutable` opens it as SQLite's immutable file, for a store no process writes any
+ *  more and with no write-ahead log beside it (an ended run's): nothing beside it is read or made. */
+export type DurableReadOptions = {
+    immutable?: boolean;
+};
 /** 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. */
-export declare function withDurableFile<T>(file: string, read: (db: Database) => T): T | null;
+export declare function withDurableFile<T>(file: string, read: (db: Database) => T, options?: DurableReadOptions): 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;
+export declare function durableDoc<T = Record<string, unknown>>(file: string, kind: string, key?: string, options?: DurableReadOptions): 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
  *  included, are listed by that item's record, not the driver's, and are read from there. `state` is the driver's own
  *  record: in the keyed layout what lies in each map item stays in the item's record. */
-export declare function readJournal(file: string, key: string): JournalView | undefined;
+export declare function readJournal(file: string, key: string, options?: DurableReadOptions): JournalView | undefined;
 /** Every committed route decision a frozen snapshot holds (each judge's answer, whole), by execution path. Empty for a
  *  state that is no snapshot. */
 export declare function committedRoutes(state: unknown): Record<string, Json>;

package/dist/durable/readers.js

@@ -4,15 +4,17 @@
 // readers take the store file itself (pi-durable's SQLite file, wherever the host keeps it), never a directory.
 import fs from "node:fs";
 import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 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. */
-export function withDurableFile(file, read) {
+export function withDurableFile(file, read, options = {}) {
     if (!fs.existsSync(file))
         return null;
     const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
-    const db = new DatabaseSync(file, { readOnly: true, timeout: 5000 });
+    const db = new DatabaseSync(options.immutable ? `${pathToFileURL(file).href}?immutable=1` : file, { readOnly: true, timeout: 5000 });
     try {
         db.exec("BEGIN");
         return read(db);
@@ -66,15 +68,34 @@ function itemEffects(db, key, table, into) {
     }
 }
 /** A Session document of the run's store `file`, read-only; undefined when the file or the document is absent. */
-export function durableDoc(file, kind, key) {
-    return (withDurableFile(file, (db) => sessionDoc(db, kind, key)) ?? undefined);
+export function durableDoc(file, kind, key, options = {}) {
+    return (withDurableFile(file, (db) => sessionDoc(db, kind, key), options) ?? 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
  *  included, are listed by that item's record, not the driver's, and are read from there. `state` is the driver's own
  *  record: in the keyed layout what lies in each map item stays in the item's record. */
-export function readJournal(file, key) {
+export function readJournal(file, key, options = {}) {
     return withDurableFile(file, (db) => {
         const doc = sessionDoc(db, "agentrun.driver", key);
         if (!doc || doc.binding === null)
@@ -93,7 +114,7 @@ export function readJournal(file, key) {
             return { id, name: e?.name ?? "", argsHash: e?.argsHash ?? "", status: e?.status ?? "unknown", session: e?.session ?? null, result: e?.result ?? null, ...(e?.intent ? { intent: e.intent } : {}), ...(e?.args !== undefined ? { args: e.args } : {}), ...(Array.isArray(e?.calls) ? { calls: e.calls } : {}) };
         });
         return { binding: doc.binding, inputs: doc.inputs, generation: doc.generation, revision: doc.revision, state: doc.state, notes: doc.notes, effects };
-    }) ?? undefined;
+    }, options) ?? undefined;
 }
 /** Every committed route decision a frozen snapshot holds (each judge's answer, whole), by execution path. Empty for a
  *  state that is no snapshot. */

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

@@ -1,5 +1,6 @@
 import { defineDoc, defineTool, GenerationTask, hook, } from "@earendil-works/pi-durable";
 import { DELIVERY_ATTEMPTS, deliver, deliveryTerminates, deliveryText, fileSubmission, mixedFileSubmission, nudgeText, repairRecord, VIOLATIONS_SHOWN, } from "./record.js";
+import { SUBMIT_TOOL } from "../host-tools.js";
 import { toolResult } from "./pi-versions.js";
 /** The record a conversation delivered, or null while it has not, and the delivery attempts it has spent. */
 export const RecordDoc = defineDoc({
@@ -76,7 +77,7 @@ export function recordTool(options) {
         ...(deliveryTerminates(delivery) ? { control: { terminate: true } } : {}),
     });
     return defineTool({
-        name: "submit",
+        name: SUBMIT_TOOL,
         description: shown.description,
         parameters: shown.parameters,
         // Every call's arguments are carried to `execute`; one record's are repaired here, before the Harness validates.

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/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 { assertHostTools, SUBMIT_TOOL } 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,9 @@ 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.
+    const name = host.name ?? "agentrun";
+    assertHostTools(host.tools ?? [], { reserved: [name, SUBMIT_TOOL], 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
@@ -83,7 +87,7 @@ export function createWorkflowTool(host) {
         },
     });
     const tool = defineTool({
-        name: host.name ?? "agentrun",
+        name,
         description: "Compose and run AgentRun workflows in this session. Describe lists the tools a workflow may use, as a call's tool or an agent node's tools, and the language; a workflow uses only the tools describe lists, which the host registers. Inspect validates a complete workflow and keeps it as this conversation's draft. Dry-run checks the draft on synthetic values (or the given input) with no model, Jev or tool call. Run starts the draft as a durable task of this conversation and answers with its outcome. Running the same draft on the same input again, after a restart too, reaches the same run and makes no effect twice; again: true starts a fresh run of them, which a later run then reaches. Save, load and list keep named definition revisions.",
         parameters: Type.Object({ ...workflowToolProperties(), again: Type.Optional(Type.Boolean({ description: "Run only: start a fresh run of the same draft and input instead of reaching the one already run." })) }),
         executionMode: "sequential",

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 { assertHostTools, SUBMIT_TOOL } 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';
@@ -27,6 +29,8 @@ const constructors = {
     write: createWriteToolDefinition, grep: createGrepToolDefinition, find: createFindToolDefinition, ls: createLsToolDefinition,
 };
 const mutatingTools = new Set(['bash', 'edit', 'write']);
+/** The extension's own tool's name, which a host tool may not take. */
+const toolName = 'agentrun';
 const help = 'Describe a task: /agentrun <what you want done>\nTry support triage: /agentrun triage (fictional, no model calls)\nInspect: /agentrun · Change input: /agentrun input\nSave: /agentrun save <name> · Load: /agentrun load <name>\nLibrary: /agentrun list · History: /agentrun history\nRun: /agentrun run · Dry run: /agentrun dry-run · SOP text: /agentrun sop <file> · Setup: /agentrun status\nStop: /agentrun stop (closing the inspector does not stop a run)\nOther examples: /agentrun demo | demo empty | demo live';
 const textResult = (text, details = {}) => ({ content: [{ type: 'text', text: safe(text) }], details });
 function singleTextInput(workflow) {
@@ -54,7 +58,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');
@@ -76,21 +81,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) } : {}) };
-            });
+            assertHostTools(supplied, { reserved: [toolName, SUBMIT_TOOL], 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));
@@ -286,6 +278,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 }) };
             },
         };
@@ -475,10 +469,10 @@ function registerExtension(pi, configuration) {
             await pending;
     };
     pi.registerTool({
-        name: 'agentrun', label: 'AgentRun workflow',
+        name: toolName, label: 'AgentRun workflow',
         description: `Use the ${AUTHOR_SKILL_NAME} skill to compose workflows.` + ' Describe lists available tools and their schemas. Inspect or run an AgentRun DSL workflow in this Pi session. First inspect to show its graph. Dry-run checks the inspected workflow on synthetic values (or the given input) with no model, Jev or tool call; code runs only with the user command /agentrun dry-run --trusted. Agent nodes capture the active Pi model when execution starts. Code needs the user command /agentrun run --trusted for each run. ' + (configuration.hostTools
             ? 'Only the explicit host-configured tools are available, including during trusted runs. Outer permission hooks are not inherited. '
-            : 'Enabled read-only Pi built-ins are available to declared steps. Shell/write/edit need the trusted command for each run; custom extension tools and permission hooks are not inherited. The search and support_demo tools use fictional supplied sources only. ') + 'Save stores a named procedure revision, not its input or permission. Load preflights current host capabilities. Run always restarts; there is no checkpoint resume. Scripted demos stay scripted on rerun.',
+            : 'Enabled read-only Pi built-ins are available to declared steps. Shell/write/edit need the trusted command for each run; custom extension tools and permission hooks are not inherited. The search and support_demo tools use fictional supplied sources only. ') + 'Save stores a named procedure revision, not its input or permission. Load preflights current host capabilities. A run this session left interrupted or failed resumes from its journal when its draft, input, SOP and tools are unchanged; any other run starts new. Scripted demos stay scripted on rerun.',
         parameters: workflowToolParameters(),
         executionMode: 'sequential',
         renderResult(result, options) {

package/dist/host-session.js

@@ -1,4 +1,5 @@
 import { Agent } from '@earendil-works/pi-agent-core';
+import { SUBMIT_TOOL } from './host-tools.js';
 import { createPiRunner } from './runner.js';
 import { workflowToolContext } from './tool-context.js';
 export const PI_MODEL_SETUP_MESSAGE = 'AgentRun requires an active Pi model. Use /login to connect a provider, then /model to select it. Try /agentrun demo without model access.';
@@ -28,7 +29,7 @@ export function createPiHostSessionFactory(context) {
             parameters: tool.parameters,
             async execute(id, args, signal, onUpdate) {
                 const result = await tool.execute(id, args, signal, onUpdate, toolContext);
-                if (tool.name === 'submit' && result.details?.accepted === true)
+                if (tool.name === SUBMIT_TOOL && result.details?.accepted === true)
                     delivered = true;
                 return result;
             },

package/dist/host-tools.d.ts

@@ -0,0 +1,12 @@
+/** The tool a workflow node delivers its result with (the runner's and the durable record tool's), so no host tool may
+ *  take its name. */
+export declare const SUBMIT_TOOL = "submit";
+/**
+ * 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 assertHostTools(tools: unknown, options: {
+    reserved: readonly string[];
+    executable: boolean;
+}): void;

package/dist/host-tools.js

@@ -0,0 +1,30 @@
+// 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;
+/** The tool a workflow node delivers its result with (the runner's and the durable record tool's), so no host tool may
+ *  take its name. */
+export const SUBMIT_TOOL = 'submit';
+/**
+ * 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 assertHostTools(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/runner.js

@@ -1,5 +1,6 @@
 import { Compile } from "typebox/compile";
 import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, ModelRuntime, } from "@earendil-works/pi-coding-agent";
+import { SUBMIT_TOOL } from "./host-tools.js";
 import { PiRunError } from "./run-error.js";
 import { nodeThinking } from "./thinking.js";
 export { PiRunError } from "./run-error.js";
@@ -49,7 +50,7 @@ export function createPiRunner(options) {
     const timeoutMs = options.timeoutMs === null ? null : positive(options.timeoutMs ?? 120_000, "timeoutMs");
     const names = new Set();
     for (const tool of options.tools ?? []) {
-        if (tool.name === "submit" || names.has(tool.name))
+        if (tool.name === SUBMIT_TOOL || names.has(tool.name))
             throw new Error(`Reserved or duplicate Pi tool: ${tool.name}`);
         names.add(tool.name);
     }
@@ -96,7 +97,7 @@ export function createPiRunner(options) {
         let unsubscribe;
         const result = (text, ok) => ({ content: [{ type: "text", text }], details: { accepted: ok } });
         const submit = {
-            name: "submit", label: "Submit result", description: "Deliver a result matching the required JSON Schema. Rejection feedback must be corrected in this session.",
+            name: SUBMIT_TOOL, label: "Submit result", description: "Deliver a result matching the required JSON Schema. Rejection feedback must be corrected in this session.",
             parameters,
             executionMode: "sequential",
             async execute(id, args) {
@@ -162,7 +163,7 @@ export function createPiRunner(options) {
                 cwd, model: options.model, modelRuntime: options.modelRuntime,
                 thinkingLevel: nodeThinking(request.thinking, options.thinkingLevel), maxTurns: maxTurns ?? undefined, resourceLoader, settingsManager,
                 sessionManager,
-                tools: [...requested, "submit"],
+                tools: [...requested, SUBMIT_TOOL],
                 customTools: [...(options.tools ?? []).filter(tool => requested.includes(tool.name)).map(tool => ({
                         ...tool,
                         executionMode: "sequential",
@@ -192,7 +193,7 @@ export function createPiRunner(options) {
             unsubscribe = session.subscribe(event => {
                 // Native events carry correlation IDs, including SDK-rejected calls. Custom
                 // sessions without IDs use execute's counter so one attempt is not counted twice.
-                if (event.type === "tool_execution_start" && event.toolName === "submit" && event.toolCallId !== undefined && !accepted && !stopped && !fatal) {
+                if (event.type === "tool_execution_start" && event.toolName === SUBMIT_TOOL && event.toolCallId !== undefined && !accepted && !stopped && !fatal) {
                     submissions++;
                     pendingSubmissions.set(event.toolCallId, {
                         ...(Object.hasOwn(event, "args") ? { args: structuredClone(event.args) } : {}), executed: false,
@@ -200,7 +201,7 @@ export function createPiRunner(options) {
                     if (maxSubmissions !== null && submissions > maxSubmissions)
                         stop("submission_limit");
                 }
-                if (event.type === "tool_execution_end" && event.toolName === "submit") {
+                if (event.type === "tool_execution_end" && event.toolName === SUBMIT_TOOL) {
                     if (event.toolCallId !== undefined)
                         pendingSubmissions.delete(event.toolCallId);
                     if (!accepted && !stopped && !fatal && maxSubmissions !== null && submissions >= maxSubmissions)
@@ -228,7 +229,8 @@ export function createPiRunner(options) {
                 throw new PiRunError(stopped, turns, submissions);
             if (accepted)
                 return submission;
-            throw new PiRunError(maxTurns !== null && turns >= maxTurns ? "turn_limit" : "no_submission", turns, submissions);
+            // The loop ends only on one of the three above or at the turn cap, so what is left is the cap.
+            throw new PiRunError("turn_limit", turns, submissions);
         }
         catch (error) {
             if (fatal)

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-tool.d.ts

@@ -1,6 +1,6 @@
 import { Type } from 'typebox';
 import { type AuthorHostAddendum, type DryRunResult, type WorkflowDeps } from '@parcha/agentrun-dsl';
-import type { WorkflowExtensionService } from './extension-service.js';
+import { type WorkflowExtensionService } from './extension-service.js';
 export declare const WORKFLOW_TOOL_ACTIONS: readonly ["describe", "inspect", "dry-run", "run", "save", "load", "list"];
 /** The tool's fields: one action, and the fields an action reads. A host's tool may add its own. */
 export declare const workflowToolProperties: () => {

package/dist/workflow-tool.js

@@ -2,6 +2,7 @@
 // and the dry run. Nothing here imports pi's coding agent, its agent core or its TUI, so a pi-durable host can use it.
 import { Type } from 'typebox';
 import { compileTransform, dryRunWorkflow, formatWorkflowTree, inspectWorkflow, loadAuthorReference, renderAuthorHostAddendum, } from '@parcha/agentrun-dsl';
+import { ExtensionServiceError } from './extension-service.js';
 import { PI_HOST_ADDENDUM } from './host-addendum.js';
 export const WORKFLOW_TOOL_ACTIONS = ['describe', 'inspect', 'dry-run', 'run', 'save', 'load', 'list'];
 /** The tool's fields: one action, and the fields an action reads. A host's tool may add its own. */
@@ -35,7 +36,9 @@ export function inspectCandidate(checker, candidate, input) {
         inspection = checker.preflight(candidate, input);
     }
     catch (error) {
-        throw new Error(`Cannot inspect workflow: ${error instanceof Error ? error.message : 'Invalid workflow'}`);
+        const message = `Cannot inspect workflow: ${error instanceof Error ? error.message : 'Invalid workflow'}`;
+        // The service's refusal keeps its type and code, so a host branches on it as it does for a run; either keeps its cause.
+        throw error instanceof ExtensionServiceError ? Object.assign(new ExtensionServiceError(error.code, message), { cause: error }) : new Error(message, { cause: error });
     }
     return { inspection, tree: formatWorkflowTree(inspection) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-pi",
-  "version": "0.1.0-beta.21",
+  "version": "0.1.0-beta.26",
   "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.21",
+    "@parcha/pi-durable-disk": "0.1.0-beta.26",
     "typebox": "1.3.7"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.21",
-    "@parcha/agentrun-jev": "0.1.0-beta.21"
+    "@parcha/agentrun-dsl": "0.1.0-beta.26",
+    "@parcha/agentrun-jev": "0.1.0-beta.26"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",