@parcha/agentrun-pi 0.1.0-beta.11 → 0.1.0-beta.13

package/README.md

@@ -1,19 +1,19 @@
 # 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 0.87.0.
+Describe a task in Pi, inspect the workflow, run it with your current model, and save its definition for new input. Requires Node 22.19+ and Pi 1.1.0.
 
 ## Install
 
 If you do not have Pi, install the tested host version first:
 
 ```sh
-npm install -g @earendil-works/pi-coding-agent@0.87.0
+npm install -g @earendil-works/pi-coding-agent@1.1.0
 ```
 
 Then, in your project:
 
 ```sh
-pi install npm:@parcha/agentrun-pi@0.1.0-beta.4 -l
+pi install npm:@parcha/agentrun-pi@beta -l
 pi --offline
 ```
 
@@ -29,7 +29,15 @@ Try the bundled example inside Pi:
 /agentrun demo
 ```
 
-The demo shows the workflow graph, progress, and a completed result with call counts. It uses scripted responses over fictional sources. It makes no model calls and does not test model quality. Run `/agentrun status` to check the loaded skill and Pi host version. The tested version is 0.87.0; status flags a different host without blocking it. Missing Pi or Jev access does not prevent the scripted demo. To repeat it, run `/agentrun run` or `/agentrun demo`. A scripted demo stays scripted on rerun, including its missing-evidence path. Use `/agentrun demo live` to switch to real Pi and Jev calls. Workflows authored by Pi use real adapters.
+No Pi session at hand? The same scripted workflow runs from a shell, with no key and no network:
+
+```sh
+npx @parcha/agentrun-pi@beta demo
+```
+
+It prints each sub-question with its answer, then `Status: complete`, the answer and the scripted call counts, and exits 0. `npx @parcha/agentrun-pi@beta demo empty` runs the missing-evidence path and prints `Status: escalated`.
+
+The demo shows the workflow graph, progress, and a completed result with call counts. It uses scripted responses over fictional sources. It makes no model calls and does not test model quality. Run `/agentrun status` to check the loaded skill and Pi host version. The tested version is 1.1.0; status flags a different host without blocking it. Missing Pi or Jev access does not prevent the scripted demo. To repeat it, run `/agentrun run` or `/agentrun demo`. A scripted demo stays scripted on rerun, including its missing-evidence path. Use `/agentrun demo live` to switch to real Pi and Jev calls. Workflows authored by Pi use real adapters.
 
 For an offline Pi startup, use `pi --offline`. Without that flag, Pi may download optional command-line tools on first launch. This is separate from the scripted demo, which makes no network calls.
 
@@ -75,7 +83,9 @@ 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 0.87.0 cannot export a fresh session containing only slash-command results. To save an offline research receipt from the checkout, run `node examples/research-live.mjs --out research-result.json`. This runs the scripted example again and writes its result; it does not export the Pi session.
+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.
+
+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.
 
 One workflow runs at a time. Named definitions are durable across sessions in the same project. Pi run receipts belong to the current branch and may remain in memory until Pi persists its session; saving a definition does not save a receipt.
 
@@ -95,7 +105,7 @@ By default, the extension exposes currently active Pi built-in `read`, `grep`, `
 
 The user must issue `/agentrun run --trusted` for each run that needs code nodes or active built-in `bash`, `edit`, or `write` tools. This permits local, unsandboxed execution; authorization does not carry into the next run. A model cannot grant itself that permission with a tool argument.
 
-Native V1 does not supply SOP text. Workflows declaring `sopSection` stop before execution with a setup error; keep the required sections and use an SDK host that supplies the complete SOP.
+A workflow that names `sopSection`s needs SOP text. `/agentrun sop <file>` reads a Markdown file inside the project (up to 512 KiB) and checks that it has a `## <section>` heading for each section the workflow names; `/agentrun sop` shows what is set. The file's digest is kept with the session, and a run is refused if the file changed since it was supplied. A host that passes `sop` to `createAgentRunExtension` supplies the text itself and `/agentrun sop` is not used.
 
 Custom extension tools and the outer Pi session's permission hooks are **not inherited**, including in trusted runs. A configured host can explicitly supply its own tool definitions as described below. Shell/executor effect transports and artifact delivery are unavailable in this extension; declared tool effects must use an available tool.
 
@@ -240,9 +250,11 @@ These commands create a separate `agentrun-pi-project` beside the checkout. You
 
 ## Dependencies and retained data
 
-Pi is optional for `@parcha/agentrun-dsl`. This package brings the Pi coding-agent SDK, its provider dependencies, and the Jev adapter; its dependency footprint is larger than the core. The release inventory records the locked versions.
+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 `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`). The tested host is Pi 1.1.0; peer ranges at `*` do not make an older or newer host compatible. The offline loader regression checks competing local dependencies, a native file read, and the scripted workflow. Pi's [package guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md#dependencies) is the rule this follows.
 
-The SDK dependencies remain pinned so standalone applications and the CLI have a complete runtime. When loaded as an extension, Pi resolves its core packages and TypeBox through the host loader. The tested host is Pi 0.87.0; installed SDK pins do not make an older or newer host compatible. The offline loader regression checks competing local dependencies, a native file read, and the scripted workflow. Pi's [package guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md#dependencies) recommends peers for extension-only packages; this package also provides the standalone SDK.
+The durable entry (`@parcha/agentrun-pi/durable`) takes pi-durable and chord as optional peers from 1.0.4 to below 1.3; CI runs it on 1.0.4, 1.1.0 and 1.2.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.
 
 Candidate directories retain request text, rubric text, workflow versions, and feedback. Native Pi messages can contain workflow inputs and results. Choose storage and tool access appropriate for that data. The author skill in `@parcha/agentrun-dsl` describes the native and SDK authoring paths for agents.
 

package/dist/cli.js

@@ -3,12 +3,14 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { authorWorkflow, runWorkflow, validateWorkflow } from "@parcha/agentrun-dsl";
-import { createPiRunner } from "./runner.js";
+import { runScriptedDemo } from "./demo-cli.js";
 const help = `Usage:
+  agentrun-pi demo [empty]            scripted demo; no key, no model calls, no network
   agentrun-pi validate workflow.json [--inputs key1,key2]
   agentrun-pi author --config ./pi.config.mjs --out ./candidates "Describe the workflow"
   agentrun-pi run --config ./pi.config.mjs workflow.json input.json
 
+The demo runs the same scripted workflow as /agentrun demo inside Pi; "empty" runs its missing-evidence path and exits 0 on the expected escalation.
 Config is trusted JavaScript exporting default PiRunnerOptions, optionally deps (Jev/effect adapters).
 Author saves candidates; it does not execute or activate them.
 Validate may execute code probes. Run executes trusted workflow code and exits 2 on escalation.
@@ -29,6 +31,12 @@ async function main(args) {
         args.splice(index, 2);
         return value;
     };
+    if (command === "demo") {
+        if (args.length > 1 || (args[0] && args[0] !== "empty"))
+            throw new Error("Usage: agentrun-pi demo [empty]");
+        process.exitCode = await runScriptedDemo(args[0] === "empty", line => console.log(line));
+        return;
+    }
     const configPath = flag("--config");
     const outputDir = flag("--out") ?? "./candidates";
     const inputKeys = (flag("--inputs") ?? "").split(",").filter(Boolean);
@@ -46,6 +54,7 @@ async function main(args) {
         throw new Error(help);
     if (!configPath)
         throw new Error("Supply --config with an explicit model and modelRuntime");
+    const { createPiRunner } = await import("./runner.js");
     const config = await import(pathToFileURL(resolve(configPath)).href);
     if (command === "author") {
         if (args.length !== 1)

package/dist/demo-cli.d.ts

@@ -0,0 +1,2 @@
+/** The bundled scripted workflow, run through the interpreter with fixed answers: no model, no key, no network. */
+export declare function runScriptedDemo(noEvidence: boolean, print: (line: string) => void): Promise<number>;

package/dist/demo-cli.js

@@ -0,0 +1,25 @@
+import { runWorkflow } from "@parcha/agentrun-dsl";
+import { demoInput, demoWorkflow, scriptedDemoDeps } from "./demo.js";
+/** The bundled scripted workflow, run through the interpreter with fixed answers: no model, no key, no network. */
+export async function runScriptedDemo(noEvidence, print) {
+    const scripted = scriptedDemoDeps(noEvidence);
+    const calls = { effects: 0, judgments: 0, agentSteps: 0 };
+    const deps = {
+        runEffect: input => { calls.effects++; return scripted.runEffect(input); },
+        runJudge: input => { calls.judgments++; return scripted.runJudge(input); },
+        runNode: input => { calls.agentSteps++; return scripted.runNode(input); },
+    };
+    print("AgentRun on Pi · scripted demo, fictional sources, no model calls\n");
+    print(`Question: ${demoInput.question}\n`);
+    const result = await runWorkflow(demoWorkflow, demoInput, deps);
+    const state = result.state;
+    for (const finding of state.findings ?? [])
+        print(`  ${finding.question}\n    ${finding.answer}`);
+    print(`\nStatus: ${result.status}`);
+    if (result.status === "complete")
+        print(`Answer: ${state.report?.answer ?? ""}`);
+    else
+        print(`Escalation: ${result.escalation?.summary ?? ""}`);
+    print(`Calls: ${calls.effects} tool, ${calls.judgments} judgment, ${calls.agentSteps} agent step (all scripted)`);
+    return result.status === "escalated" && !noEvidence ? 2 : 0;
+}

package/dist/durable/decision-recovery.d.ts

@@ -0,0 +1,23 @@
+import { type DecisionExchange, type DecisionReceipt } from "@parcha/agentrun-dsl";
+import type { DocumentReader } from "@earendil-works/pi-durable";
+import type { WorkflowInvocation } from "./task.js";
+type Context = WorkflowInvocation["context"];
+/** The interpreter's two decision hooks over one invocation of a workflow task. */
+export type DecisionRecovery = {
+    /** The interpreter's `recordDecision`: commits the receipt's row after every row recorded before it, and resolves
+     *  once that commit is durable; a commit that fails rejects this receipt's call. The task's state is untouched. */
+    recordDecision(receipt: DecisionReceipt, exchange: DecisionExchange): Promise<void>;
+    /** The interpreter's `recovery.decision`: the receipt rebuilt from the last answered row this run recorded under
+     *  `id`, or undefined when it recorded none (a request that failed, one recorded without its identity, or one another
+     *  run recorded, is asked again). */
+    decision(id: string): Promise<DecisionReceipt | undefined>;
+};
+/** The decision hooks a durable host gives the interpreter inside `WorkflowTaskHost.run`, over the invocation it is
+ *  handed (the run's key, the task's runtime and context): `recordDecision` as the interpreter's own, and `decision` as
+ *  `recovery.decision` beside the driver's recovery hooks. */
+export declare function decisionRecovery(invocation: {
+    key: string;
+    runtime: Pick<WorkflowInvocation["runtime"], "commit"> & DocumentReader;
+    context: Context;
+}): DecisionRecovery;
+export {};

package/dist/durable/decision-recovery.js

@@ -0,0 +1,57 @@
+// A workflow task's decision receipts, durable in its run's Session: each receipt is a row (decisions.ts) committed
+// through the task's own commit before the interpreter acts on its answers, and a resumed run's request is answered
+// from the row its earlier process committed, so the judge is not asked again and the run decides what it decided.
+// 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";
+/** 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 {
+        v: DECISION_ROW_VERSION, at: receipt.at, node: receipt.node, kind: receipt.kind, item: receipt.item, execution_path: receipt.execution_path,
+        request_sha256: receipt.request_sha256,
+        request_bytes: Buffer.byteLength(JSON.stringify({ state: exchange.request.state, questions: exchange.request.questions })),
+        model: receipt.model, questions: receipt.questions, answers: receipt.answers, rule: receipt.rule, action: receipt.action,
+        usage: receipt.usage, cost_usd: receipt.cost_usd, latency_ms: receipt.latency_ms, ...(receipt.error !== undefined ? { error: receipt.error } : {}),
+        decision_id: receipt.id, request: receipt.request, state_sha256: receipt.state_sha256, run_key: key,
+    };
+}
+/** The receipt the run `key`'s last answered row under `id` is: a rule is set only on an answered receipt, and an
+ *  answered one carries no error. */
+function answeredReceipt(rows, id, key) {
+    const row = rows.findLast((stored) => stored.run_key === key && stored.decision_id === id && stored.rule !== null && stored.error === undefined
+        && stored.request !== undefined && stored.state_sha256 !== undefined && stored.execution_path !== null);
+    if (!row)
+        return undefined;
+    return {
+        v: DECISION_RECEIPT_VERSION, id, at: row.at, node: row.node, kind: row.kind, item: row.item, execution_path: row.execution_path,
+        request: row.request, status: "answered", state_sha256: row.state_sha256,
+        questions: row.questions, answers: row.answers, rule: row.rule, action: row.action,
+        model: row.model, usage: row.usage, cost_usd: row.cost_usd, request_sha256: row.request_sha256, latency_ms: row.latency_ms,
+    };
+}
+/** The decision hooks a durable host gives the interpreter inside `WorkflowTaskHost.run`, over the invocation it is
+ *  handed (the run's key, the task's runtime and context): `recordDecision` as the interpreter's own, and `decision` as
+ *  `recovery.decision` beside the driver's recovery hooks. */
+export function decisionRecovery(invocation) {
+    const { key, runtime, context } = invocation;
+    const harness = {
+        commit: async (change) => {
+            let result;
+            await runtime.commit(async (tx) => { result = await change(tx); return undefined; }, context);
+            return result;
+        },
+    };
+    let chain = Promise.resolve();
+    return {
+        recordDecision(receipt, exchange) {
+            const row = rowOf(receipt, exchange, key);
+            const committed = chain.then(() => appendDecision(harness, row, context));
+            chain = committed.catch(() => undefined);
+            return committed;
+        },
+        async decision(id) {
+            return answeredReceipt(await readDecisions(runtime, context), id, key);
+        },
+    };
+}

package/dist/durable/decisions.d.ts

@@ -0,0 +1,113 @@
+import type { Context } from "@earendil-works/chord";
+import { type DocumentReader, type Harness } from "@earendil-works/pi-durable";
+/** The session document that holds a run's decision rows. */
+export declare const DECISION_RECEIPTS_DOC = "agentrun.decisions";
+/** The stored row's version. */
+export declare const DECISION_ROW_VERSION = 1;
+/** How the answers became the action, with every threshold applied. */
+export type DecisionRowRule = 
+/** judge: each question's decoded value (choice, noul at 0.5, rounded score). */
+{
+    kind: "judge";
+}
+/** pick: the chosen option names an item by its position, or none. */
+ | {
+    kind: "pick";
+    options: string[];
+    none: string | null;
+}
+/** route: the chosen branch, or the unsure branch when the choice's confidence is below `gte`. */
+ | {
+    kind: "route";
+    unsure: {
+        gte: number;
+        branch: string;
+    } | null;
+}
+/** sift: an item is kept when its `keep` measure meets `gte`; every item without a keep rule. */
+ | {
+    kind: "sift";
+    items: number;
+    ids: string[];
+    keep: {
+        id: string;
+        measure: "confidence" | "value";
+        gte: number;
+    } | null;
+}
+/** ask: the predicate holds when p_yes meets `gte`. */
+ | {
+    kind: "ask";
+    gte: number;
+}
+/** verify: a noul question fails when p_yes is below its threshold (null: not judged, an empty field); a failed
+ *  question the submission holds is doubted, a failed one it lacks is unmet. */
+ | {
+    kind: "verify";
+    thresholds: Record<string, number | null>;
+    present: string[];
+};
+/** One stored decision row. */
+export type DecisionRow = {
+    v: typeof DECISION_ROW_VERSION;
+    at: string;
+    node: string;
+    kind: "judge" | "pick" | "sift" | "route" | "ask" | "verify";
+    item: number | null;
+    execution_path: string | null;
+    request_sha256: string | null;
+    request_bytes: number;
+    model: string | null;
+    questions: Record<string, unknown>;
+    answers: Record<string, unknown>;
+    rule: DecisionRowRule | null;
+    /** What the run did with the answers; null when the node did not act on them. */
+    action: unknown;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    } | null;
+    cost_usd: number | null;
+    latency_ms: number;
+    error?: string;
+    /** The request's spend is on its frozen driver's state, so a cost fold counts it there, not here. */
+    driver_spend?: true;
+    /** The receipt's id, its place among its node's requests, the digest of the state it was asked with, and the key of
+     *  the workflow run that asked it. A row that carries all four is the whole receipt again, so that run, resumed, can be
+     *  answered from it (`decisionRecovery`); another run in the same Session never is. */
+    decision_id?: string;
+    request?: {
+        index: number;
+        count: number;
+        items?: number[];
+    };
+    state_sha256?: string;
+    run_key?: string;
+};
+/** Commit one row, appended after every row committed before it. */
+export declare function appendDecision(harness: Pick<Harness, "commit">, 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[]>;
+/** 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">;
+    release(): Promise<void>;
+};
+export type DecisionWriter = {
+    /** Commit `row` after every row recorded before it. It returns at once; a commit that fails is kept for
+     *  `settled` and `flush`, and the rows after it are still committed. */
+    record(row: DecisionRow): void;
+    /** Every row recorded so far is committed; the first that could not be is thrown, and kept for `flush`. The
+     *  Session stays open. */
+    settled(): Promise<void>;
+    /** Every row is committed and every Session the writer opened is released, also when a commit failed; a row
+     *  recorded while flush runs is committed too. Then the first failed commit is thrown, or, when none failed, the
+     *  first failed release. */
+    flush(): Promise<void>;
+};
+/** 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. */
+export declare function createDecisionWriter(options: {
+    open: () => Promise<DecisionSession>;
+    context?: Context;
+}): DecisionWriter;

package/dist/durable/decisions.js

@@ -0,0 +1,71 @@
+// 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
+// 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";
+/** 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;
+const DecisionsDoc = defineDoc({ kind: DECISION_RECEIPTS_DOC, version: 1, scope: "session", initial: () => ({ receipts: [] }) });
+/** 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);
+}
+/** 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 ?? []);
+}
+/** 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. */
+export function createDecisionWriter(options) {
+    let session;
+    let chain = Promise.resolve();
+    let failure;
+    return {
+        record(row) {
+            const stored = JSON.parse(JSON.stringify(row));
+            chain = chain
+                .then(async () => appendDecision((await (session ??= options.open())).harness, stored, options.context))
+                .catch((error) => { failure ??= { error }; });
+        },
+        async settled() {
+            await chain;
+            if (failure)
+                throw failure.error;
+        },
+        async flush() {
+            let released;
+            // A row recorded while flush waits or releases joins the chain, so flush returns only when a full pass saw no new
+            // row. The Session is cleared before it is released: a row recorded meanwhile opens its own, which the next pass
+            // releases.
+            for (;;) {
+                const drained = chain;
+                await drained;
+                if (drained !== chain)
+                    continue;
+                const held = session;
+                session = undefined;
+                if (held) {
+                    const opened = await held.catch(() => undefined);
+                    try {
+                        await opened?.release();
+                    }
+                    catch (error) {
+                        released ??= { error };
+                    }
+                }
+                if (drained === chain)
+                    break;
+            }
+            const first = failure ?? released;
+            failure = undefined;
+            if (first)
+                throw first.error;
+        },
+    };
+}

package/dist/durable/index.d.ts

@@ -0,0 +1,19 @@
+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 { recordCommits, recordingLines, snapshotLines, type RecordingLine, type RecordingSource } from "./recording.js";
+export { reuseReceipts, seedReceipts, ReceiptIndex, type ReceiptReuse, type ReuseReceiptsOptions, type ReusableTool } from "./receipts.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 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";
+export type { Delivery, DeliveryCount, DeliveryEvent, Disagreement, GateState, Reading, RecordContract, RecordState, RecordStore, Refusal, Reviewer } from "./record.js";
+export { workspaceRecordFile } from "./record-file.js";
+export { deliveredRecord, GateDoc, RecordDoc, recordNudge, recordStore, recordTool, spendNudge, submitDefinition } from "./record-tool.js";
+export type { RecordNudgeOptions, RecordToolOptions } from "./record-tool.js";
+export { closeNodeAttempt, hostScope, NodeBindingMismatch, NodeIndex, runNodeAttempt, taskScope } from "./node.js";
+export type { NodeAttempt, NodeOutcome, NodeScope, NodeSettlement } from "./node.js";
+export { NodeDoc, NodeFailure, nodeRunner } from "./node-runner.js";
+export type { NodeHost, NodeRecord, NodeRequest } from "./node-runner.js";
+export { createWorkflowExtension, type WorkflowEnding, type WorkflowHostParts, type WorkflowInvocation, type WorkflowOutcome, type WorkflowRequest, type WorkflowRun, type WorkflowStop, type WorkflowTaskHost } from "./task.js";

package/dist/durable/index.js

@@ -0,0 +1,13 @@
+export { documentStore } from "./store.js";
+export { committedRoutes, durableDoc, readJournal } from "./readers.js";
+export { recordCommits, recordingLines, snapshotLines } from "./recording.js";
+export { reuseReceipts, seedReceipts, ReceiptIndex } from "./receipts.js";
+export { NewerTaskError, refuseNewerTasks, toolResult, ToolResultKeyError } from "./pi-versions.js";
+export { DECISION_RECEIPTS_DOC, DECISION_ROW_VERSION, appendDecision, createDecisionWriter, 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";
+export { deliveredRecord, GateDoc, RecordDoc, recordNudge, recordStore, recordTool, spendNudge, submitDefinition } from "./record-tool.js";
+export { closeNodeAttempt, hostScope, NodeBindingMismatch, NodeIndex, runNodeAttempt, taskScope } from "./node.js";
+export { NodeDoc, NodeFailure, nodeRunner } from "./node-runner.js";
+export { createWorkflowExtension } from "./task.js";

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

@@ -0,0 +1,100 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import { type AgentChange, type ConversationId, type Extension, type Tx } from "@earendil-works/pi-durable";
+import type { WorkflowDeps } from "@parcha/agentrun-dsl";
+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. */
+export declare const NodeDoc: import("@earendil-works/pi-durable").ConversationDocToken<{
+    system: string;
+    label: string;
+    schema: JsonValue | null;
+    fileKey: string | null;
+}>;
+/** 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). */
+export type NodeRequest = Omit<Parameters<NonNullable<WorkflowDeps["runNode"]>>[0], "review" | "signal"> & {
+    sessionId: string;
+    attempt: number;
+    earlierSessionIds: readonly string[];
+};
+/** What a host says of a node's record beside its schema. */
+export type NodeRecord = Pick<RecordContract, "contracts" | "checks"> & {
+    /** What the model is told it delivers (default: `the <label> record`). */
+    label?: string;
+    /** The host's own delivery instructions, said with the contract that ends the node's task. */
+    instructions?: string;
+    /** The record may be delivered as a JSON file the node wrote in `workspace`, named under `key`. */
+    file?: {
+        key: string;
+        workspace: string;
+    };
+};
+export type NodeHost = {
+    /** The agent a node's conversation runs with: its model, thinking level, working directory and the host's own
+     *  extensions and tools. The runner adds its extension and `submit` where the host did not place them. */
+    agent(node: NodeRequest): AgentChange | Promise<AgentChange>;
+    /** Duty text for a node's system prompt, after the interpreter's. `offered` names the tools the agent lists. */
+    stance?(node: NodeRequest, offered: {
+        tools: readonly string[];
+    }): string | undefined;
+    record?(node: NodeRequest): NodeRecord | Promise<NodeRecord>;
+    /** A second reading of a node's record, before the node's own verify clause: what it disagrees with. */
+    verify?(record: unknown, node: NodeRequest, context: {
+        round: boolean;
+    }): Disagreement[] | Promise<Disagreement[]>;
+    /** Called, and awaited, when a node's conversation exists and before any request of this process reaches a model:
+     *  the host attaches its observers to that conversation. A throw fails the node's call and releases nothing: what
+     *  pi resumed of the node waits for the attempt's next entry, or ends with the Harness's close. */
+    onNodeOpen?(node: NodeRequest & {
+        conversationId: ConversationId;
+        resumed: boolean;
+    }): void | Promise<void>;
+    /** Written in the commit that creates a node's conversation, after the runner's own document: the documents the
+     *  host's extensions read for it (a plane's configuration). */
+    init?(node: NodeRequest, tx: Tx, conversationId: ConversationId): void | Promise<void>;
+    /** Delivery attempts a node gets (default `DELIVERY_ATTEMPTS`). */
+    maxAttempts?: number;
+    /** The host's part in every `submit` call: its rows, and which errors are its own failure. The one delivery it may
+     *  be told before `onNodeOpen` is `already`, the answer of a call that a process died inside after its commit. */
+    submit?: Pick<RecordToolOptions, "onDelivery" | "fatal" | "onFatal" | "fatalText">;
+    /** The digest an attempt is bound by. Absent, one of the node's label, path, kind, item and attempt. */
+    digest?(node: NodeRequest): string;
+};
+/** 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. */
+export declare class NodeFailure extends Error {
+    readonly node: string;
+    readonly final: boolean;
+    readonly executionPath?: string | undefined;
+    readonly unanswered?: {
+        reason: string;
+        detail?: JsonValue;
+    } | undefined;
+    readonly code = "NODE_NOT_DELIVERED";
+    constructor(message: string, node: string, final: boolean, executionPath?: string | undefined, unanswered?: {
+        reason: string;
+        detail?: JsonValue;
+    } | undefined);
+}
+/** 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 declare function nodeRunner(host: NodeHost, options?: {
+    name?: string;
+}): {
+    extension: Extension;
+    /** The extension a conversation an older build opened still selects, under that build's name for it: the system
+     *  text that build kept as the `task` section, and this runner's `submit`. Each of its requests and calls waits for
+     *  the runner to reach the node, which then moves the conversation to `extension`. Install one for each node an
+     *  older build left unfinished, before the Harness resumes. */
+    legacy(entry: {
+        extension: string;
+        system: string | null;
+    }): Extension;
+    on(scope: NodeScope, context: Context): {
+        runNode(params: RecoveryNodeParams): Promise<unknown>;
+        closeStepSession(sessionId: string): Promise<void>;
+    };
+};