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

package/dist/durable/index.d.ts

@@ -0,0 +1,20 @@
+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 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

@@ -0,0 +1,14 @@
+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";
+export { createWorkflowTool, DURABLE_HOST_ADDENDUM } from "./workflow-tool.js";

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

@@ -0,0 +1,106 @@
+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. The node's
+     *  own thinking level outranks the host's; when neither names one, the node thinks at medium (never at the level its
+     *  conversation would copy from its owner's, and never off). */
+    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";
+    /** The item a map that collects its items' failures ends on this (`isItemFailure`): the node's delivery attempts are
+     *  spent, or its model will not answer (`model_error`, as a provider's content filter). Never an abort, a stale or
+     *  faulted run, a missing model, or a schema no record can satisfy. */
+    readonly itemFailure: boolean;
+    constructor(message: string, node: string, final: boolean, executionPath?: string | undefined, unanswered?: {
+        reason: string;
+        detail?: JsonValue;
+    } | undefined, itemFailure?: boolean);
+}
+/** 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>;
+    };
+};

package/dist/durable/node-runner.js

@@ -0,0 +1,253 @@
+// A workflow's LLM nodes on pi-durable, behind `runNode`: each attempt is one conversation (node.ts), and one
+// extension serves them all.
+//
+// What differs per node lives with its conversation: the agent the host chose for it, and its configuration document
+// (its system text, and the record it owes: label, schema, file key). The `task` section renders the system text from
+// that document. A conversation an older build opened has no such document: the runner writes it when it reaches the
+// node, with the system text that build kept on the node's index entry, and gives the conversation its agent. `submit`
+// is registered once with open parameters; each request presents it with the node's own label and fields, and each
+// call is decided against the node's schema. What cannot be stored (the node's reviewers, the host's checks, a
+// committer for the nudge) is attached when the runner reaches the node, and a request, a call or a yield that pi
+// resumed first waits for it, so nothing of a node runs before its host observes it.
+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 { 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. */
+export const NodeDoc = defineDoc({
+    kind: "agentrun.node", version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ system: "", label: "", schema: null, fileKey: null }),
+});
+/** 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 class NodeFailure extends Error {
+    node;
+    final;
+    executionPath;
+    unanswered;
+    code = "NODE_NOT_DELIVERED";
+    /** The item a map that collects its items' failures ends on this (`isItemFailure`): the node's delivery attempts are
+     *  spent, or its model will not answer (`model_error`, as a provider's content filter). Never an abort, a stale or
+     *  faulted run, a missing model, or a schema no record can satisfy. */
+    itemFailure;
+    constructor(message, node, final, executionPath, unanswered, itemFailure = false) {
+        super(message);
+        this.node = node;
+        this.final = final;
+        this.executionPath = executionPath;
+        this.unanswered = unanswered;
+        this.name = "NodeFailure";
+        this.itemFailure = final && itemFailure;
+    }
+}
+/** `work` under a run's stop: its result, or the stop's reason as soon as the stop lands, and at once when it already
+ *  has. The listener lives only as long as the wait. */
+async function underStop(signal, work) {
+    if (!signal)
+        return work();
+    let onStop;
+    const stopped = new Promise((_, reject) => { onStop = () => reject(signal.reason); });
+    stopped.catch(() => undefined);
+    if (signal.aborted)
+        onStop();
+    else
+        signal.addEventListener("abort", onStop, { once: true });
+    try {
+        return await Promise.race([work(), stopped]);
+    }
+    finally {
+        signal.removeEventListener("abort", onStop);
+    }
+}
+const listed = (value) => Array.isArray(value);
+const isSubmit = (tool) => tool.name === "submit";
+/** 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 = {}) {
+    const maxAttempts = host.maxAttempts ?? DELIVERY_ATTEMPTS;
+    const attached = new Map();
+    const waiting = new Map();
+    /** What the runner attached to a conversation, once it has: the wait ends with the caller's own abort. */
+    const reached = (id, context) => {
+        const found = attached.get(Number(id));
+        if (found)
+            return Promise.resolve(found);
+        return new Promise((resolve, reject) => {
+            const waiters = waiting.get(Number(id)) ?? new Set();
+            waiting.set(Number(id), waiters);
+            const signal = context.abortSignal;
+            const take = (value) => { signal?.removeEventListener("abort", stopped); resolve(value); };
+            const stopped = () => { waiters.delete(take); reject(signal?.reason ?? new Error("the node was stopped before its runner reached it again")); };
+            waiters.add(take);
+            if (signal?.aborted)
+                stopped();
+            else
+                signal?.addEventListener("abort", stopped, { once: true });
+        });
+    };
+    const attach = (id, value) => {
+        attached.set(Number(id), value);
+        for (const take of waiting.get(Number(id)) ?? [])
+            take(value);
+        waiting.delete(Number(id));
+        return () => { if (attached.get(Number(id)) === value)
+            attached.delete(Number(id)); };
+    };
+    /** The contract of a `submit` call: a call cut after its record was committed is answered from the record and
+     *  waits for nobody; any other waits for the runner. Only a conversation of an older build's node may be reached
+     *  with no configuration document yet. */
+    const contractOf = (legacy) => async (api, context) => {
+        if ((await api.snapshot(RecordDoc, api.conversationId, context))?.record != null)
+            return { schema: {} };
+        if (!legacy && !(await api.snapshot(NodeDoc, api.conversationId, context))?.schema)
+            throw new Error("submit was called in a conversation that is no workflow node");
+        return (await reached(api.conversationId, context)).contract;
+    };
+    /** Each request presents `submit` as the node's own record's tool. */
+    const present = async (request, api, context) => {
+        const node = await api.snapshot(NodeDoc, api.conversationId, context);
+        if (!node?.schema)
+            return undefined;
+        await reached(api.conversationId, context);
+        const shown = submitDefinition({ schema: node.schema, label: node.label, ...(node.fileKey ? { fileKey: node.fileKey } : {}) });
+        return { messages: request.messages.map((message) => message.role === "system" && message.toolsAdded?.some(isSubmit)
+                ? { ...message, toolsAdded: message.toolsAdded.map((offered) => isSubmit(offered) ? { ...offered, ...shown } : offered) } : message) };
+    };
+    const nudge = recordNudge({
+        maxAttempts,
+        label: async (api, context) => (await api.snapshot(NodeDoc, api.conversationId, context))?.label || undefined,
+        spend: async (id, context) => (await reached(id, context)).commit((tx) => spendNudge(tx, id), context),
+    });
+    const tool = recordTool({ ...host.submit, contract: contractOf(false) });
+    const extension = defineExtension({
+        name: options.name ?? "agentrun-nodes",
+        tools: [tool],
+        sections: [section("task", async (input, context) => (await input.read.snapshot(NodeDoc, input.conversationId, context))?.system || undefined, { tag: false })],
+        hooks: [hook(GenerationTask, { beforeRequest: present }), nudge],
+    });
+    /** The host's agent at the node's thinking level. A level left unset would follow the conversation's creation: a
+     *  task's node copies its owner's level, and a node no task owns starts off. */
+    const leveled = (agent, node) => ({ ...agent, thinkingLevel: nodeThinking(node.thinking, agent.thinkingLevel) });
+    /** The host's agent with the runner's extension first and `submit` last, unless the host placed them. */
+    const withNodes = (agent) => ({
+        ...agent,
+        extensions: listed(agent.extensions)
+            ? (agent.extensions.some((selected) => selected.name === extension.name) ? agent.extensions : [extension, ...agent.extensions])
+            : { ...agent.extensions, add: [extension, ...(agent.extensions?.add ?? [])] },
+        ...(listed(agent.tools) && !agent.tools.some(isSubmit) ? { tools: [...agent.tools, tool] } : {}),
+    });
+    return {
+        extension,
+        legacy: (entry) => defineExtension({
+            name: entry.extension,
+            tools: [recordTool({ ...host.submit, contract: contractOf(true) })],
+            sections: entry.system === null ? [] : [section("task", () => entry.system ?? undefined, { tag: false })],
+            hooks: [hook(GenerationTask, { beforeRequest: async (request, api, context) => { await reached(api.conversationId, context); return present(request, api, context); } }), nudge],
+        }),
+        on: (scope, base) => ({
+            closeStepSession: (sessionId) => closeNodeAttempt(scope, sessionId, base),
+            runNode: async (params) => {
+                const { review, signal, step, ...asked } = params;
+                // An attempt the driver admitted is found again by its session; any other call is a conversation of its own.
+                const node = { ...asked, sessionId: step?.sessionId ?? `unjournaled:${randomUUID()}`, attempt: step?.attempt ?? 0, earlierSessionIds: step?.earlierSessionIds ?? [] };
+                const fail = (message, final, unanswered, itemFailure = false) => new NodeFailure(message, node.label, final, node.executionPath, unanswered, itemFailure);
+                // Only a schema no submit call can satisfy is refused here: any other is the node's contract as its author wrote it.
+                const lint = lintRecordRoot(node.schema);
+                if (lint.length)
+                    throw fail(`${node.kind} node "${node.label}" cannot deliver a record of its schema: ${lint.join("; ")}`, true);
+                // The host's own answers are awaited under the stop too: one that lands meanwhile opens no conversation.
+                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");
+                const system = [...node.system, host.stance?.(node, { tools: offered })].filter(Boolean).join("\n\n");
+                const reviewers = [
+                    ...(host.verify ? [(candidate, at) => host.verify(candidate, node, at)] : []),
+                    ...(review ? [async (candidate) => {
+                            const verdict = await review(candidate);
+                            return verdict.accepted ? [] : [{ id: "verify", kind: "verify", verdict: "fails", reasons: [`/: violates "the verify clause of ${node.label}" - ${verdict.message}`] }];
+                        }] : []),
+                ];
+                // The run's stop ends the wait at once, whatever the node is doing; the attempt goes on only under a pause.
+                let onStop;
+                const stopped = new Promise((_, reject) => { onStop = () => reject(signal.reason); });
+                stopped.catch(() => undefined);
+                let opened;
+                const attempt = runNodeAttempt(scope, {
+                    session: node.sessionId,
+                    digest: host.digest?.(node) ?? canonicalSha256({ step: node.label, path: node.executionPath ?? null, kind: node.kind, item: node.item?.index ?? null, attempt: node.attempt }),
+                    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 });
+                        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 });
+                        // 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);
+                        await configure(tx, id, { ...given, ...(listed(given.extensions) ? {} : { extensions: { ...given.extensions, remove: [...(given.extensions?.remove ?? []), ...own] } }),
+                            ...(listed(agent.tools) ? {} : { tools: null }) });
+                    },
+                    onOpen: async ({ conversationId, resumed, startedMs }) => {
+                        opened = { conversationId, detach: () => undefined };
+                        // What pi resumed of this node waits for the attach below, so the host observes the node first. A host
+                        // that throws here attaches nothing: that work stays waiting, for the attempt's next entry or the close.
+                        await host.onNodeOpen?.({ ...node, conversationId, resumed });
+                        // A stop that landed before the node's request is submitted: nothing is asked of a model.
+                        if (signal?.aborted)
+                            throw signal.reason;
+                        opened.detach = attach(conversationId, { commit: scope.commit, contract: {
+                                schema: node.schema, maxAttempts, ...(reviewers.length ? { reviewers } : {}),
+                                ...(record.contracts ? { contracts: record.contracts } : {}), ...(record.checks ? { checks: record.checks } : {}),
+                                ...(record.file ? { file: workspaceRecordFile({ ...record.file, notBefore: () => startedMs }) } : {}),
+                            } });
+                    },
+                }, base);
+                attempt.catch(() => undefined);
+                // Listened for from here, where the `finally` below is the only way out: no listener outlives the call.
+                if (signal?.aborted)
+                    onStop();
+                else
+                    signal?.addEventListener("abort", onStop, { once: true });
+                try {
+                    const outcome = await Promise.race([attempt, stopped]);
+                    if (outcome.delivered)
+                        return outcome.delivered.record;
+                    if (outcome.settled?.status === "unanswered") {
+                        const { reason, detail } = outcome.settled;
+                        // Only the model's own refusal to answer is the item's: an abort, a stale or faulted run and a missing model are the run's.
+                        throw fail(`${node.label}: the model did not answer (${reason})`, true, { reason, ...(detail !== undefined ? { detail } : {}) }, reason === "model_error");
+                    }
+                    const spent = ((await scope.snapshot(RecordDoc, outcome.conversationId, base))?.attempts ?? 0) >= maxAttempts;
+                    throw fail(`${node.label} did not submit (${spent ? "its delivery attempts are spent" : "it ended its run without a record"})`, spent, undefined, spent);
+                }
+                catch (error) {
+                    if (!signal?.aborted)
+                        throw error;
+                    // A pause keeps the node's work for the process that resumes it; any other stop ends that work, and a
+                    // request submitted as the stop landed is withdrawn once it is known.
+                    const end = async () => { if (opened)
+                        await (await scope.conversation(opened.conversationId, base))?.abort(base).catch(() => undefined); };
+                    if (runStopOf(signal.reason)?.stop !== "pause") {
+                        await end();
+                        void attempt.then(end, end);
+                    }
+                    throw signal.reason ?? error;
+                }
+                finally {
+                    signal?.removeEventListener("abort", onStop);
+                    void attempt.then(() => opened?.detach(), () => opened?.detach());
+                }
+            },
+        }),
+    };
+}

package/dist/durable/node.d.ts

@@ -0,0 +1,88 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import { type AgentChange, type ConversationId, type DocumentReader, type InputSubmissionDraft, type Submission, type TaskId, type Tx } from "@earendil-works/pi-durable";
+import type { Disagreement } from "./record.js";
+/** The node index: an attempt's conversation by its session id, the digest of what it was bound to, when it started,
+ *  and whether its owner closed it without a record. */
+export declare const NodeIndex: import("@earendil-works/pi-durable").SessionDocFamilyToken<{
+    conversation: number | null;
+    digest: string | null;
+    startedMs: number | null;
+    closed: boolean;
+}, null>;
+/** Where a node's conversation lives and who writes there: a workflow task's runtime, a tool call's api, or the
+ *  Harness. `owner` is the task that owns the conversation (aborting it aborts the node); absent, nobody does. */
+export type NodeScope = {
+    commit(write: (tx: Tx) => Promise<void>, context: Context): Promise<void>;
+    conversation(id: ConversationId, context: Context): Promise<{
+        submit(submission: InputSubmissionDraft, context: Context): Promise<Submission>;
+        abort(context: Context): Promise<void>;
+    } | undefined>;
+    snapshot: DocumentReader["snapshot"];
+    owner?: TaskId;
+};
+/** A task's runtime as a node scope: the task owns the conversations its nodes run in. */
+export declare function taskScope(runtime: {
+    taskId: TaskId;
+    snapshot: DocumentReader["snapshot"];
+    conversation: NodeScope["conversation"];
+    commit(change: (tx: Tx) => Promise<undefined>, context: Context): Promise<void>;
+}): NodeScope;
+/** The Harness as a node scope: the host drives the node, and no task owns its conversation. */
+export declare function hostScope(harness: {
+    snapshot: DocumentReader["snapshot"];
+    conversation: NodeScope["conversation"];
+    commit<T>(change: (tx: Tx) => T | Promise<T>, context: Context): Promise<T>;
+}): NodeScope;
+export type NodeAttempt = {
+    /** The attempt's identity: the key of its index entry, and of its request (`node:<session>`). */
+    session: string;
+    /** A digest of what the attempt is bound to. An attempt found under another digest is refused, never continued. */
+    digest: string;
+    /** The agent the attempt's conversation is created with: model, thinking, extensions, tools, instructions. */
+    agent: AgentChange;
+    /** The node's input: the conversation's one user turn. */
+    user: string;
+    /** Written in the commit that creates the conversation: the documents the conversation's tools and sections read. */
+    init?(tx: Tx, conversationId: ConversationId): void | Promise<void>;
+    /** Run in the commit that finds the conversation an earlier process created, with its index entry as stored (an
+     *  older build's entry holds more fields): what a conversation that older build opened needs to run here. */
+    adopt?(tx: Tx, conversationId: ConversationId, stored: Readonly<Record<string, unknown>>): void | Promise<void>;
+    /** Called, and awaited, once the conversation exists and before its request: the host attaches what observes it.
+     *  `resumed` says an earlier process created it, `startedMs` when. */
+    onOpen?(at: {
+        conversationId: ConversationId;
+        resumed: boolean;
+        startedMs: number;
+    }): void | Promise<void>;
+};
+/** How an attempt's submission ended: answered, or not, with pi's reason (`aborted`, `failed`, ...) and detail. */
+export type NodeSettlement = {
+    status: "done";
+} | {
+    status: "unanswered";
+    reason: string;
+    detail?: JsonValue;
+};
+/** How an attempt came out. `delivered` is the record its conversation committed, if it did; `settled` is how the
+ *  submission ended, absent when the record was already there and no request was made. */
+export type NodeOutcome = {
+    conversationId: ConversationId;
+    resumed: boolean;
+    settled?: NodeSettlement;
+    delivered?: {
+        record: JsonValue;
+        disagreements: Disagreement[];
+    };
+};
+/** An attempt found bound to something else than it is asked to run under. */
+export declare class NodeBindingMismatch extends Error {
+    readonly session: string;
+    readonly stored: string | null;
+    readonly asked: string;
+    readonly code = "NODE_BINDING_MISMATCH";
+    constructor(session: string, stored: string | null, asked: string);
+}
+/** Run one attempt. */
+export declare function runNodeAttempt(scope: NodeScope, attempt: NodeAttempt, context: Context): Promise<NodeOutcome>;
+/** An attempt its owner closed without a record: the mark a reader tells it from one still running by. */
+export declare function closeNodeAttempt(scope: Pick<NodeScope, "commit">, session: string, context: Context): Promise<void>;

package/dist/durable/node.js

@@ -0,0 +1,98 @@
+import { configure, defineDocFamily, } from "@earendil-works/pi-durable";
+import { deliveredRecord } from "./record-tool.js";
+/** The node index: an attempt's conversation by its session id, the digest of what it was bound to, when it started,
+ *  and whether its owner closed it without a record. */
+export const NodeIndex = defineDocFamily({
+    kind: "agentrun.nodes", version: 1, scope: "session", family: true, initial: () => ({ conversation: null, digest: null, startedMs: null, closed: false }),
+});
+/** A task's runtime as a node scope: the task owns the conversations its nodes run in. */
+export function taskScope(runtime) {
+    return {
+        owner: runtime.taskId,
+        snapshot: runtime.snapshot.bind(runtime),
+        conversation: (id, context) => runtime.conversation(id, context),
+        commit: (write, context) => runtime.commit(async (tx) => { await write(tx); return undefined; }, context),
+    };
+}
+/** The Harness as a node scope: the host drives the node, and no task owns its conversation. */
+export function hostScope(harness) {
+    return {
+        snapshot: harness.snapshot.bind(harness),
+        conversation: (id, context) => harness.conversation(id, context),
+        commit: (write, context) => harness.commit(write, context),
+    };
+}
+/** An attempt found bound to something else than it is asked to run under. */
+export class NodeBindingMismatch extends Error {
+    session;
+    stored;
+    asked;
+    code = "NODE_BINDING_MISMATCH";
+    constructor(session, stored, asked) {
+        super(`node attempt ${session} is bound to ${stored ?? "nothing"}, not ${asked}: it is not continued under another binding`);
+        this.session = session;
+        this.stored = stored;
+        this.asked = asked;
+        this.name = "NodeBindingMismatch";
+    }
+}
+/** 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) {
+            found = { conversationId: entry.conversation, digest: entry.digest, resumed: true, startedMs: entry.startedMs ?? 0 };
+            // 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;
+        }
+        await create(tx, entry);
+    }, context);
+    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);
+    if (already)
+        return { conversationId, resumed, delivered: already };
+    const handle = await scope.conversation(conversationId, context);
+    if (!handle)
+        throw new Error(`node attempt ${attempt.session} names conversation ${String(conversationId)}, which does not exist`);
+    const submission = await handle.submit({ type: "input", content: attempt.user, requestId: `node:${attempt.session}` }, context);
+    const ended = await submission.wait(context);
+    const settled = ended.status === "unanswered"
+        ? { status: "unanswered", reason: ended.reason, ...(ended.detail !== undefined ? { detail: ended.detail } : {}) } : { status: "done" };
+    const delivered = await deliveredRecord(scope, conversationId, context);
+    return { conversationId, resumed, settled, ...(delivered ? { delivered } : {}) };
+}
+/** An attempt its owner closed without a record: the mark a reader tells it from one still running by. */
+export async function closeNodeAttempt(scope, session, context) {
+    await scope.commit(async (tx) => { const entry = await tx.doc(NodeIndex, session, null); if (entry.conversation !== null)
+        entry.closed = true; }, context);
+}

package/dist/durable/pi-versions.d.ts

@@ -0,0 +1,34 @@
+import type { Harness, ToolExecutionResult } from "@earendil-works/pi-durable";
+import type { Context } from "@earendil-works/chord";
+/** The key the loaded pi-durable reads a tool result's blocks from. 1.2 renamed `content` to `output` in the release
+ *  that added `SessionFailed`, so that export tells the two apart. */
+export declare const RESULT_KEY: "content" | "output";
+export type TextBlock = {
+    type: "text";
+    text: string;
+};
+/** A tool result every supported pi-durable reads as `blocks`: the blocks under both keys, each its own copy. */
+export declare function toolResult(blocks: readonly TextBlock[], fields?: Omit<ToolExecutionResult, "content" | "output">): ToolExecutionResult;
+/** A tool result whose blocks the loaded pi-durable would not read: it reached the model empty. */
+export declare class ToolResultKeyError extends Error {
+    readonly tool: string;
+    readonly code = "TOOL_RESULT_KEY";
+    constructor(tool: string);
+}
+/** The blocks of a result `tool` returned, as the loaded pi-durable reads them; undefined for a result with no blocks
+ *  (pi then shows what the tool streamed). A result whose blocks are only under the other version's key throws
+ *  `ToolResultKeyError`. */
+export declare function resultBlocks(tool: string, result: unknown): unknown[] | undefined;
+/** The storage error behind a Session that failed at one (`SessionFailed` on 1.2, matched by name), else the error. */
+export declare function storageError(error: unknown): unknown;
+/** A live task of a newer pi-durable than the loaded one: pi-durable 1.2 keeps a tool call in flight as a version 2
+ *  `pi.tool` task, which an earlier version waits on without running. */
+export declare class NewerTaskError extends Error {
+    readonly kind: string;
+    readonly version: number;
+    readonly code = "PI_TASK_NEWER";
+    constructor(kind: string, version: number);
+}
+/** Refuse a store a newer pi-durable left with a tool call in flight, instead of waiting on it: a host calls this after
+ *  opening its Harness and before resuming it. On pi-durable 1.2 it does nothing. */
+export declare function refuseNewerTasks(harness: Pick<Harness, "inspect">, context: Context): Promise<void>;