@parcha/agentrun-pi 0.1.0-beta.14 → 0.1.0-beta.16

package/README.md

@@ -74,6 +74,7 @@ Loading starts with empty input and does not execute. A save retains the definit
 | `/agentrun` | Inspect the current workflow, or show help if there is none. |
 | `/agentrun input <case or JSON>` | Set new input without changing the definition or running it. |
 | `/agentrun run` | Repeat the current workflow with its last supplied input. Scripted demos stay scripted; authored workflows use real adapters. |
+| `/agentrun dry-run` | Run the current workflow on synthetic values, with no model, Jev or tool call. |
 | `/agentrun save <name>` | Save an immutable, project-local definition revision. |
 | `/agentrun load <name> [digest]` | Load the newest or exact revision; input starts empty. |
 | `/agentrun list` | List saved revisions. |
@@ -89,6 +90,19 @@ A live run is durable. Its journal is kept in `.pi/agentrun/runs/<run id>/journa
 
 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.
 
+A host that does not run the extension can save, load and list the same definitions with `@parcha/agentrun-pi/workflows`, which loads nothing from pi:
+
+```ts
+import { WorkflowStore } from '@parcha/agentrun-pi/workflows';
+
+const store = new WorkflowStore(projectDirectory);   // records go to <projectDirectory>/.pi/agentrun/workflows/<name>/
+const saved = await store.save('release-review', workflow);   // an immutable revision, named by its SHA-256
+const again = await store.load('release-review');             // the last one saved; pass a digest for an exact revision
+const revisions = await store.list();                         // every revision, newest first
+```
+
+The argument is a project directory, not the workflows directory: the extension keeps its records for `ctx.cwd` in the same place, so a host that passes that directory and the extension read each other's records. Storage needs real directories and regular files (a symbolic link in the path or among the records fails with `WorkflowStoreError` code `unsafe_path`), and every load checks the record's metadata and the SHA-256 of its workflow. A `<name>/` directory copied into the workflows directory loads. A saved workflow is a procedure, not authority: the host still checks it against its current capabilities before it runs.
+
 ### Three demo modes
 
 | Command | What it demonstrates |
@@ -105,6 +119,8 @@ 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.
 
+A dry run (`/agentrun dry-run`, the inspector's Dry-run action, or the tool's `dry-run` action, which also takes an `input`) runs the inspected workflow on synthetic values: agent and judge answers and tool results are synthesized from their schemas, so it makes no model, Jev or tool call, writes no run journal and leaves the last run's receipt as it was. Its `status` is `passed`, `failed` (`problems` say why), or `not_run`: a check could not run, for example a schema the generator cannot satisfy (`pattern`, `format`), a synthetic answer that escalated, or SOP text that was not supplied, and `skipped` says which. A `not_run` dry run proves nothing. A workflow with code nodes is `not_run` unless the user issues `/agentrun dry-run --trusted`, which runs its code in this process for that dry run only; a code node that throws is reported by its label, without what it threw. A dry run stops after 10,000 synthetic steps, or at `/agentrun stop`, as `not_run`.
+
 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.
@@ -230,6 +246,28 @@ With `rubricSections`, every supplied section must appear on every generated LLM
 
 The standalone CLI remains available as `node packages/pi/dist/cli.js --help` from source. It imports a trusted caller-owned `--config` module for `author` and `run`; importing that module executes its code. `validate` can evaluate code probes. Review executable workflows before using it.
 
+## Sign in, pick a model, check keys
+
+`@parcha/agentrun-pi/signin` is what a demo, or your own app, runs before its first model call. It is the only entry of this package that loads `@earendil-works/pi-ai`, an optional peer: install it beside the package (`npm install @earendil-works/pi-ai@~1.2.0`) to use this entry. No other entry imports it.
+
+```js
+import { builtinModels } from '@earendil-works/pi-ai/providers/all';
+import { checkKeys, resolveModel, usageLimitError } from '@parcha/agentrun-pi/signin';
+
+const report = checkKeys(spec, { live: true, dir: demoDir });
+if (!report.ok) { console.error(report.text); process.exit(report.exitCode); } // 2: nothing was sent
+const { model, getApiKey, source } = await resolveModel(spec, { provider, model: modelId });
+const message = await builtinModels().completeSimple(model, context, { apiKey: await getApiKey() });
+if (usageLimitError(message)) throw usageLimitError(message);
+```
+
+- `checkKeys(spec, options)` lists what this run needs and what is missing: each key by its env name and where to create it, each program on `PATH` (refused outside its `platforms`, or below its `min` version as the first x.y.z that `<cmd> --version` prints), and each package as the demo's directory resolves it, with the exact `npm install --no-save <name>@<version>` line when it is missing. An item with `for: 'live'` or `for: 'kill'` counts only in that mode. A `oneOf` choice is met by any member, and an array member only by all of its items. A Jev judge asks for `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`. The check sends no request and prompts for nothing; a key's value is never printed.
+- `checkSetupPrompt(spec, text)` checks a demo's setup prompt against its spec: every key env name, program command and package name in the spec appears in it, and it names no credential env name (`*_API_KEY`, `*_KEY`, `*_TOKEN*`, `*_SECRET*`, `*_PROJECT_ID`) the spec does not list. `node scripts/check-setup-prompts.mjs` runs it for every `examples/*/demo.json` in CI.
+- `resolveModel(spec, options)` picks the model and its key. An explicit `provider` (and `model`) with that provider's env key wins, passed on as an explicit key; Anthropic takes `ANTHROPIC_API_KEY` only. Otherwise a stored ChatGPT sign-in is used, and the model is chosen from the account's own `GET /v1/models` by what the spec needs (text, tools, images): the spec's default when the account lists it, else the newest one pi-ai knows. With neither, it runs the sign-in. A sign-in's model takes only streaming Responses calls with `store: false` (`responsesOnly`, `unsupported`). The spec's eyes model resolves the same way: an explicit `eyes` model with its key, else the lead model when it meets the eyes' needs, else a `ResolveError` naming the gap; the ChatGPT plan takes no video input. The result serializes without its key.
+- `signIn(options)` runs pi-ai's own Sign in with ChatGPT once per install, with this app's name and a host id kept for the install. pi-ai's callback port is fixed at 1455; when another login holds it, the sign-in fails at once and says to finish or cancel that login. A pi-ai that ignores the app name (before 1.1) is refused before the page opens.
+- The sign-in lives in `$AGENTRUN_HOME/auth.json` (default `~/.config/agentrun/`): the directory is 0700 and the file 0600, written whole and renamed into place. An existing directory others can read is refused, not changed. Refreshes are serialized across processes by an operating-system lock, an exclusive SQLite transaction on `auth.json.lock` (an empty database beside it, through `node:sqlite`). The system frees it when its holder exits or is killed, so a crashed run leaves no lock to clear, the rotating refresh token is never sent twice, and a process that waited reads the new token. On Node 22, `node:sqlite` prints one experimental warning when the first write loads it. A token never reaches a log, a URL or a recording.
+- The plan's usage limit (`subscription_sharing_usage_limit_exceeded`) maps to `UsageLimitError`: "Your ChatGPT plan's usage limit is reached; wait, or set a provider key." It is never retried.
+
 ## Develop from source
 
 To change the extension itself, clone and build the repository:
@@ -250,9 +288,9 @@ 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 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.
+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@~1.2.0 @earendil-works/pi-agent-core@~1.2.0 @earendil-works/pi-tui@~1.2.0 typebox`). The pi packages are pinned to 1.2: pi 1.3.0 pins its own packages to exact versions, and this release's ranges stop below 1.3 until the next one. The tested host is Pi 1.2.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.
+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.2.0 @earendil-works/pi-agent-core@~1.2.0 @earendil-works/pi-tui@~1.2.0 typebox`). The pi packages are pinned to 1.2: pi 1.3.0 pins its own packages to exact versions, and this release's ranges stop below 1.3 until the next one. The tested host is Pi 1.2.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/index.d.ts

@@ -16,4 +16,5 @@ export { closeNodeAttempt, hostScope, NodeBindingMismatch, NodeIndex, runNodeAtt
 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";
+export { createWorkflowExtension, type WorkflowCaller, type WorkflowEnding, type WorkflowHostParts, type WorkflowInvocation, type WorkflowOutcome, type WorkflowRequest, type WorkflowRun, type WorkflowStop, type WorkflowTaskHost } from "./task.js";
+export { createWorkflowTool, DURABLE_HOST_ADDENDUM, type WorkflowToolHost } from "./workflow-tool.js";

package/dist/durable/index.js

@@ -11,3 +11,4 @@ export { deliveredRecord, GateDoc, RecordDoc, recordNudge, recordStore, recordTo
 export { closeNodeAttempt, hostScope, NodeBindingMismatch, NodeIndex, runNodeAttempt, taskScope } from "./node.js";
 export { NodeDoc, NodeFailure, nodeRunner } from "./node-runner.js";
 export { createWorkflowExtension } from "./task.js";
+export { createWorkflowTool, DURABLE_HOST_ADDENDUM } from "./workflow-tool.js";

package/dist/durable/node.js

@@ -39,6 +39,19 @@ export class NodeBindingMismatch extends Error {
 /** Run one attempt. */
 export async function runNodeAttempt(scope, attempt, context) {
     let found;
+    /** The attempt's conversation when another task owns it: that task ended, and this one replaced it. */
+    let orphaned;
+    /** A new conversation for the attempt, owned by the scope's task, recorded under the attempt's session. */
+    const create = async (tx, entry) => {
+        const conversation = await tx.createConversation({ ownership: scope.owner !== undefined ? { kind: "task", taskId: scope.owner } : { kind: "ownerless" } });
+        await configure(tx, conversation.id, attempt.agent);
+        await attempt.init?.(tx, conversation.id);
+        entry.conversation = Number(conversation.id);
+        entry.digest = attempt.digest;
+        entry.startedMs = Date.now();
+        entry.closed = false;
+        found = { conversationId: conversation.id, digest: attempt.digest, resumed: false, startedMs: entry.startedMs };
+    };
     await scope.commit(async (tx) => {
         const entry = await tx.doc(NodeIndex, attempt.session, null);
         if (entry.conversation !== null) {
@@ -46,19 +59,23 @@ export async function runNodeAttempt(scope, attempt, context) {
             // An attempt under another binding is refused below, untouched.
             if (entry.digest === attempt.digest)
                 await attempt.adopt?.(tx, found.conversationId, entry);
+            if (scope.owner !== undefined && entry.digest === attempt.digest) {
+                const owner = (await tx.conversation(found.conversationId))?.owner?.taskId;
+                if (owner !== undefined && owner !== scope.owner)
+                    orphaned = found.conversationId;
+            }
             return;
         }
-        const conversation = await tx.createConversation({ ownership: scope.owner !== undefined ? { kind: "task", taskId: scope.owner } : { kind: "ownerless" } });
-        await configure(tx, conversation.id, attempt.agent);
-        await attempt.init?.(tx, conversation.id);
-        entry.conversation = Number(conversation.id);
-        entry.digest = attempt.digest;
-        entry.startedMs = Date.now();
-        found = { conversationId: conversation.id, digest: attempt.digest, resumed: false, startedMs: entry.startedMs };
+        await create(tx, entry);
     }, context);
-    const { conversationId, digest, resumed, startedMs } = found;
-    if (digest !== attempt.digest)
-        throw new NodeBindingMismatch(attempt.session, digest, attempt.digest);
+    if (found.digest !== attempt.digest)
+        throw new NodeBindingMismatch(attempt.session, found.digest, attempt.digest);
+    // The replaced task's conversation: its record, when it delivered one, is the node's; otherwise the attempt runs
+    // again in a conversation of this task, never on the request the old task's end aborted.
+    if (orphaned !== undefined && !(await deliveredRecord(scope, orphaned, context))) {
+        await scope.commit(async (tx) => { await create(tx, await tx.doc(NodeIndex, attempt.session, null)); }, context);
+    }
+    const { conversationId, resumed, startedMs } = found;
     await attempt.onOpen?.({ conversationId, resumed, startedMs });
     // A record the attempt already delivered is the node's record: nothing is requested for it.
     const already = await deliveredRecord(scope, conversationId, context);

package/dist/durable/readers.d.ts

@@ -17,7 +17,10 @@ export declare function withDurableFile<T>(file: string, read: (db: Database) =>
 /** A Session document of the run's store `file`, read-only; undefined when the file or the document is absent. */
 export declare function durableDoc<T = Record<string, unknown>>(file: string, kind: string, key?: string): T | undefined;
 /** The 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. */
+ *  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;
 /** 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/readers.js

@@ -32,24 +32,63 @@ function revisionsOf(db, id) {
     }
     return value;
 }
-/** A Session document's current value. `key` names a family member; a singleton has none. */
-function sessionDoc(db, kind, key) {
+/** The row of a Session document. `key` names a family member; a singleton has none. */
+function sessionDocId(db, kind, key) {
     const row = db.prepare("SELECT id FROM documents WHERE kind = ? AND scope_kind = 'session' AND owner_id = 0 AND family = ? AND key_value = ? AND retired_at IS NULL ORDER BY created_at DESC LIMIT 1")
         .get(JSON.stringify(kind), key === undefined ? 0 : 1, JSON.stringify(key ?? ""));
-    return row?.id === undefined ? undefined : revisionsOf(db, row.id);
+    return row?.id;
+}
+/** A Session document's current value. `key` names a family member; a singleton has none. */
+function sessionDoc(db, kind, key) {
+    const id = sessionDocId(db, kind, key);
+    return id === undefined ? undefined : revisionsOf(db, id);
+}
+/** The ids of the effects the map items of `table` own (the keyed layout's `maps`: `{ <map path>: { items, ... } }`), each
+ *  item's own nested maps included, read as the driver reads them back: item `i` of a map is its record at
+ *  `<map path>/items/<i>`, for every item the map started. */
+function itemEffects(db, key, table, into) {
+    if (!table || typeof table !== "object" || Array.isArray(table))
+        return;
+    for (const [mapPath, entry] of Object.entries(table)) {
+        const started = entry?.items;
+        if (typeof started !== "number" || !Number.isSafeInteger(started))
+            continue;
+        for (let index = 0; index < started; index += 1) {
+            const item = sessionDoc(db, "agentrun.items", effectKey(key, `${mapPath}/items/${index}`));
+            if (!item)
+                continue;
+            if (Array.isArray(item.effects))
+                for (const id of item.effects)
+                    if (typeof id === "string")
+                        into.push(id);
+            itemEffects(db, key, item.maps, 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);
 }
 /** 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. */
+ *  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) {
     return withDurableFile(file, (db) => {
         const doc = sessionDoc(db, "agentrun.driver", key);
         if (!doc || doc.binding === null)
             return undefined;
-        const effects = doc.effects.map((id) => {
+        // The driver's record lists the effects no map item owns; in the keyed layout each item's record lists its own. All of
+        // them, once each, in the order they were admitted: an effect's document is created by its admission, and a document's
+        // row is numbered when it is created (a later checkpoint folds its revisions, never its row).
+        const ids = [...doc.effects];
+        itemEffects(db, key, doc.state?.maps, ids);
+        const admitted = new Map();
+        for (const id of new Set(ids))
+            admitted.set(id, sessionDocId(db, "agentrun.effects", effectKey(key, id)) ?? Number.MAX_SAFE_INTEGER);
+        // A stable sort: an id whose document is missing keeps its place in the listing, after every admitted one.
+        const effects = [...admitted.keys()].sort((a, b) => admitted.get(a) - admitted.get(b)).map((id) => {
             const e = sessionDoc(db, "agentrun.effects", effectKey(key, id));
             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 } : {}) };
         });

package/dist/durable/receipts.d.ts

@@ -25,8 +25,10 @@ export type ReusableTool = {
 export type ReuseReceiptsOptions = {
     /** The tools whose calls are paid and keep a receipt: a tool whose answer is its own session's state keeps none. */
     tools: readonly string[];
-    /** The session this wrapper runs in: it never answers a call from a receipt its own session wrote. */
-    sessionId: string;
+    /** The session a call belongs to: a call is never answered from a receipt its own session wrote. Absent, each call's
+     *  own conversation, so a node run again in another conversation (its task replaced after it failed) is answered from
+     *  the receipt the conversation it replaces paid for, and does not pay again. */
+    sessionId?: string;
     /** 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;

package/dist/durable/receipts.js

@@ -62,9 +62,10 @@ export function reuseReceipts(options) {
                     return toolResult([{ type: "text", text: `${tool.name} is not called again: an identical earlier call was cut while it ran, so what it did outside is unknown. Work from what you have, or make a different call.` }], { isError: true, details: { effect_status: "unknown", refused: true } });
                 }
                 const key = `${intent.tool}:${intent.argsHash}`;
+                const session = options.sessionId ?? String(api?.conversationId);
                 if (options.answer) {
                     const receipt = await api.snapshot(ReceiptIndex, key, context);
-                    if (receipt?.result != null && receipt.session !== options.sessionId) {
+                    if (receipt?.result != null && receipt.session !== session) {
                         stats.reused += 1;
                         const text = typeof receipt.result === "string" ? receipt.result : JSON.stringify(receipt.result);
                         return toolResult([{ type: "text", text: `${text}\n\n(answered from the paid receipt of ${receipt.session}; the call was not dispatched again)` }], { details: { effect_status: "reused", source_session: receipt.session } });
@@ -80,7 +81,7 @@ export function reuseReceipts(options) {
                             receipt.tool = intent.tool;
                             receipt.argsHash = intent.argsHash;
                             receipt.result = value;
-                            receipt.session = options.sessionId;
+                            receipt.session = session;
                         }
                     }, context);
                 }

package/dist/durable/store.js

@@ -25,6 +25,19 @@ const DriverDoc = defineDocFamily({ kind: "agentrun.driver", version: 1, scope:
     initial: () => ({ binding: null, inputs: null, generation: 0, revision: 0, state: null, notes: [], effects: [] }) });
 const EffectDoc = defineDocFamily({ kind: "agentrun.effects", version: 1, scope: "session", family: true,
     initial: () => ({ driver: "", name: "", argsHash: "", status: "unknown", session: null, result: null }) });
+const ItemDoc = defineDocFamily({ kind: "agentrun.items", version: 1, scope: "session", family: true,
+    initial: () => ({ driver: "", effects: [] }) });
+/** A state by its digest; `sha256` is empty only for one never written. */
+const StateDoc = defineDocFamily({ kind: "agentrun.states", version: 1, scope: "session", family: true,
+    initial: () => ({ driver: "", sha256: "", state: null }) });
+/** A draft made to hold `value` whole: every field set, every other field removed. */
+function replaceWhole(draft, value) {
+    for (const field of Object.keys(draft))
+        if (!Object.hasOwn(value, field))
+            delete draft[field];
+    for (const [field, item] of Object.entries(value))
+        draft[field] = item;
+}
 /** A value as the journal stores it: plain JSON, every number finite. */
 function json(value) {
     return value === undefined ? null : JSON.parse(JSON.stringify(value, (_key, item) => {
@@ -107,23 +120,36 @@ async function openDocumentJournal(host, key, bound, options) {
         return done;
     };
     /** One Session commit on the journal's record: it checks this open's generation is the record's, advances the
-     *  revision, and lets `write` change the record (its state computed with that revision) and the effect documents. */
-    const commit = async (write) => host.commit(async (tx) => {
+     *  revision, and lets `write` change the record (its state computed with that revision) and the effect documents,
+     *  then writes the parts computed with that revision. */
+    const commit = async (write, parts) => host.commit(async (tx) => {
         const doc = await tx.doc(DriverDoc, key, null);
         if (doc.generation !== opened.generation)
             throw new RecoveryError("Run owner generation is not acquired");
         const next = doc.revision + 1;
         const value = await write(doc, next, tx);
+        const laid = parts?.(next);
+        for (const [path, item] of Object.entries(laid?.items ?? {})) {
+            replaceWhole(await tx.doc(ItemDoc, effectKey(key, path), null), json(item));
+        }
+        for (const [sha256, state] of Object.entries(laid?.states ?? {})) {
+            const held = await tx.doc(StateDoc, effectKey(key, sha256), null);
+            if (held.sha256 === "")
+                Object.assign(held, { driver: key, sha256, state: json(state) });
+        }
         doc.revision = next;
         return { revision: next, value };
     }, context).then((done) => { revision = done.revision; return done; });
+    /** A read in a commit of its own: it writes nothing the caller did not ask for. */
+    const read = (body) => inOrder(() => host.commit(body, context));
+    const storedEffect = (id, e) => ({ id, name: e.name, argsHash: e.argsHash, status: e.status, session: e.session, result: json(e.result), ...(e.intent ? { intent: json(e.intent) } : {}), ...(e.args !== undefined ? { args: json(e.args) } : {}), ...(Array.isArray(e.calls) ? { calls: json(e.calls) } : {}) });
     return {
         existing: opened.existing, generation: opened.generation, state: opened.state,
         get revision() { return revision; },
         effects: () => [...effects.values()],
         effect: (id) => effects.get(id),
         notes: () => [...notes],
-        save: (state, note) => inOrder(async () => {
+        save: (state, note, parts) => inOrder(async () => {
             let entry;
             const done = await commit((doc, next) => {
                 doc.state = json(typeof state === "function" ? state(next) : state);
@@ -131,7 +157,7 @@ async function openDocumentJournal(host, key, bound, options) {
                     entry = { revision: next, kind: note.kind, detail: json(note.detail), at: new Date().toISOString() };
                     doc.notes.push(entry);
                 }
-            });
+            }, parts);
             if (entry)
                 notes.push(entry);
             return done.revision;
@@ -142,7 +168,7 @@ async function openDocumentJournal(host, key, bound, options) {
             notes.push({ revision: done.revision, ...entry });
             return done.revision;
         }),
-        admit: (id, name, argsHash, state, session = null, intent, args) => inOrder(async () => {
+        admit: (id, name, argsHash, state, session = null, intent, args, parts, owner) => inOrder(async () => {
             effectKey(key, id);
             const known = effects.get(id);
             if (known)
@@ -152,13 +178,15 @@ async function openDocumentJournal(host, key, bound, options) {
             const keptArgs = args === undefined ? undefined : json(args);
             await commit(async (doc, _next, tx) => {
                 Object.assign(await tx.doc(EffectDoc, effectKey(key, id), null), { driver: key, name, argsHash, status: "unknown", session, result: null, ...(kept ? { intent: kept } : {}), ...(keptArgs !== undefined ? { args: keptArgs } : {}) });
-                doc.effects.push(id);
+                // An effect a map item owns is listed by that item's record, written in the same commit.
+                if (owner === undefined || !parts)
+                    doc.effects.push(id);
                 doc.state = stored;
-            });
+            }, parts);
             effects.set(id, { id, name, argsHash, status: "unknown", session, result: null, ...(kept ? { intent: kept } : {}), ...(keptArgs !== undefined ? { args: keptArgs } : {}) });
             return "new";
         }),
-        complete: (id, result, state = opened.state) => inOrder(async () => {
+        complete: (id, result, state = opened.state, parts) => inOrder(async () => {
             const known = effects.get(id);
             if (!known)
                 throw new RecoveryError(`Effect ${id} completes without an admission`);
@@ -171,7 +199,7 @@ async function openDocumentJournal(host, key, bound, options) {
                 effect.status = "completed";
                 effect.result = value;
                 doc.state = next;
-            });
+            }, parts);
             effects.set(id, { ...known, status: "completed", result: value });
         }),
         called: (id, calls) => inOrder(async () => {
@@ -188,5 +216,25 @@ async function openDocumentJournal(host, key, bound, options) {
             await queue;
             held.release();
         },
+        // Only paths and digests the driver wrote are asked for: a read of a document never written would create it.
+        items: (paths) => read(async (tx) => {
+            const found = [];
+            for (const path of paths) {
+                const item = await tx.doc(ItemDoc, effectKey(key, path), null);
+                if (item.driver === "") {
+                    found.push(undefined);
+                    continue;
+                }
+                found.push(json(item));
+                for (const id of (item.effects ?? []))
+                    if (!effects.has(id))
+                        effects.set(id, storedEffect(id, await tx.doc(EffectDoc, effectKey(key, id), null)));
+            }
+            return found;
+        }),
+        stateOf: (sha256) => read(async (tx) => {
+            const held = await tx.doc(StateDoc, effectKey(key, sha256), null);
+            return held.sha256 === "" ? undefined : json(held.state);
+        }),
     };
 }

package/dist/durable/task.d.ts

@@ -88,6 +88,10 @@ export type WorkflowHostParts = {
     deps: WorkflowDeps;
     interpret?: (workflow: Workflow, input: Record<string, unknown>, deps: WorkflowDeps) => ReturnType<typeof runWorkflow>;
 };
+/** What starting and reading a run asks of its caller: a Harness, or a tool's own `api` inside its invocation, whose
+ *  commits create the run's task in the calling conversation. A caller with no `root` names the conversation in
+ *  `start`'s options; one with no `abortTask` cannot start a run with a cancel. */
+export type WorkflowCaller = Pick<Harness, "commit" | "snapshot" | "getTask" | "waitForTask"> & Partial<Pick<Harness, "root" | "resume" | "abortTask">>;
 /** A started run. `wait` resolves with the run's outcome once its task is terminal, and rejects with the storage's error
  *  when the Session failed at one. */
 export type WorkflowRun = {
@@ -111,7 +115,7 @@ type WorkflowResult = Extract<WorkflowOutcome, {
 /** The task definition, the extension that carries it, and the host's three operations on a run. */
 export declare function createWorkflowExtension(host: WorkflowTaskHost): {
     extension: Extension;
-    start(harness: Harness, request: WorkflowRequest, context: Context, options?: {
+    start(harness: WorkflowCaller, request: WorkflowRequest, context: Context, options?: {
         conversationId?: number;
         background?: boolean;
         stop?: {
@@ -119,7 +123,7 @@ export declare function createWorkflowExtension(host: WorkflowTaskHost): {
             source?: string;
         };
     }): Promise<WorkflowRun>;
-    read(harness: Harness, key: string, context: Context): Promise<{
+    read(harness: WorkflowCaller, key: string, context: Context): Promise<{
         taskId: TaskId<WorkflowResult>;
         status: string;
         outcome?: WorkflowOutcome;

package/dist/durable/task.js

@@ -133,6 +133,11 @@ export function createWorkflowExtension(host) {
                         throw error;
                     }
                 };
+                /** The invocation ends when the host closes the Harness, and the task stays pending. */
+                const untilClosed = () => new Promise((resolve) => { if (runtime.signal.aborted)
+                    resolve();
+                else
+                    runtime.signal.addEventListener("abort", () => resolve(), { once: true }); });
                 let opened;
                 try {
                     opened = await open(task, runtime, context);
@@ -140,6 +145,13 @@ export function createWorkflowExtension(host) {
                 catch (error) {
                     if (runtime.signal.aborted)
                         throw error;
+                    // A run a later build stored in a schema this build does not know is left for that build: the task stays
+                    // pending, and this process's waiters get the refusal. Any other failure to open ends the run.
+                    if (codeOf(error) === "RECOVERY_SCHEMA_NEWER") {
+                        uncommittedOf(key, task.id).fail(error);
+                        await untilClosed();
+                        throw runtime.signal.reason;
+                    }
                     await commitEnd(failed(error), error);
                     return;
                 }
@@ -316,7 +328,11 @@ export function createWorkflowExtension(host) {
          *  step. So a pause given with a start that attaches to a run already running in this process is not taken now: it
          *  is recorded, and taken when the run's next invocation opens. `stop` pauses a run that is running here. */
         async start(harness, request, context, options = {}) {
-            const conversationId = options.conversationId ?? (await harness.root(context)).id;
+            if (options.stop?.action === "cancel" && !harness.abortTask)
+                throw new Error("A start with a cancel needs a caller that can abort a task: the Harness");
+            const conversationId = options.conversationId ?? (harness.root ? (await harness.root(context)).id : undefined);
+            if (conversationId === undefined)
+                throw new Error("A caller with no root conversation names the conversation the run belongs to: options.conversationId");
             const stop = options.stop ? { action: options.stop.action, source: options.stop.source ?? null } : null;
             const asked = json(request);
             const [taskId, started] = await harness.commit(async (tx) => {
@@ -348,7 +364,7 @@ export function createWorkflowExtension(host) {
                 uncommitted.delete(earlier);
             if (stop?.action === "cancel" && started !== "settled")
                 await harness.abortTask(taskId, context);
-            harness.resume();
+            harness.resume?.();
             return handle(harness, request.key, taskId, started);
         },
         /** The run's task and, once it is terminal, its outcome; undefined when no start named the key. */

package/dist/durable/workflow-tool.d.ts

@@ -0,0 +1,32 @@
+import { type Extension } from "@earendil-works/pi-durable";
+import { type AuthorHostAddendum, type WorkflowDeps } from "@parcha/agentrun-dsl";
+import { createWorkflowExtension, type WorkflowTaskHost } from "./task.js";
+/** What a pi-durable session adds to the workflow language, rendered for describe's `authoring.host`. */
+export declare const DURABLE_HOST_ADDENDUM: AuthorHostAddendum;
+export type WorkflowToolHost = {
+    /** The project whose saved workflows save, load and list keep: `<projectDir>/.pi/agentrun/workflows`, the store the
+     *  coding-agent extension keeps for its working directory. */
+    projectDir: string;
+    /** The tools a workflow may call, as describe lists them. Inspect admits only these names. */
+    tools?: readonly {
+        name: string;
+        description?: string;
+        parameters: unknown;
+        resultSchema?: unknown;
+    }[];
+    /** What a run's task runs with: `createWorkflowExtension`'s host. */
+    task: WorkflowTaskHost;
+    /** The host's code executor. Without it no code node runs: a dry run of a draft with code is not_run, and a run of
+     *  one is refused before it starts. Given, a run's task runs its code nodes through it. */
+    runCode?: WorkflowDeps["runCode"];
+    /** The SOP text for workflows that name sections. */
+    sop?: string;
+    /** The tool's name, `agentrun` by default: the agent definition lists it. */
+    name?: string;
+};
+/** 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 declare function createWorkflowTool(host: WorkflowToolHost): {
+    extension: Extension;
+    workflow: ReturnType<typeof createWorkflowExtension>;
+};