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

package/dist/durable/node-runner.js

@@ -0,0 +1,243 @@
+// 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 { 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";
+    constructor(message, node, final, executionPath, unanswered) {
+        super(message);
+        this.node = node;
+        this.final = final;
+        this.executionPath = executionPath;
+        this.unanswered = unanswered;
+        this.name = "NodeFailure";
+    }
+}
+/** `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 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) => new NodeFailure(message, node.label, final, node.executionPath, unanswered);
+                // 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: await host.agent(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;
+                        throw fail(`${node.label}: the model did not answer (${reason})`, true, { reason, ...(detail !== undefined ? { detail } : {}) });
+                    }
+                    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);
+                }
+                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,81 @@
+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;
+    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);
+            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 };
+    }, context);
+    const { conversationId, digest, resumed, startedMs } = found;
+    if (digest !== attempt.digest)
+        throw new NodeBindingMismatch(attempt.session, digest, attempt.digest);
+    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>;

package/dist/durable/pi-versions.js

@@ -0,0 +1,66 @@
+// What differs between the pi-durable versions this package supports (1.0.4 to 1.2.x), in one place.
+//
+// A tool result's blocks are `content` up to 1.1 and `output` from 1.2. Each version reads its own key, ignores the other
+// and stores only what it read, so a result that carries both is read the same by all of them. A result that carries only
+// the other version's key reaches the model empty, with no error from pi: where this package receives a result it did not
+// write, that is refused here. A storage error fails a 1.2 Session, and its later calls reject with `SessionFailed`
+// whose cause is that error; 1.1 rejected with the error itself. No pi-durable name that one of the versions lacks is
+// imported by name, since a missing named export fails the module at load.
+import * as piDurable from "@earendil-works/pi-durable";
+/** 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 const RESULT_KEY = "SessionFailed" in piDurable ? "output" : "content";
+const OTHER_KEY = RESULT_KEY === "output" ? "content" : "output";
+/** A tool result every supported pi-durable reads as `blocks`: the blocks under both keys, each its own copy. */
+export function toolResult(blocks, fields = {}) {
+    return { ...fields, content: blocks.map((block) => ({ ...block })), output: blocks.map((block) => ({ ...block })) };
+}
+/** A tool result whose blocks the loaded pi-durable would not read: it reached the model empty. */
+export class ToolResultKeyError extends Error {
+    tool;
+    code = "TOOL_RESULT_KEY";
+    constructor(tool) {
+        super(`${tool} returned its result under "${OTHER_KEY}", and the loaded pi-durable reads "${RESULT_KEY}": the model would receive an empty result. Return the blocks under "${RESULT_KEY}", or under both keys.`);
+        this.tool = tool;
+        this.name = "ToolResultKeyError";
+    }
+}
+/** 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 function resultBlocks(tool, result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const own = result[RESULT_KEY];
+    if (own !== undefined)
+        return Array.isArray(own) ? own : undefined;
+    if (result[OTHER_KEY] !== undefined)
+        throw new ToolResultKeyError(tool);
+    return undefined;
+}
+/** The storage error behind a Session that failed at one (`SessionFailed` on 1.2, matched by name), else the error. */
+export function storageError(error) {
+    return error instanceof Error && error.name === "SessionFailed" && error.cause !== undefined ? error.cause : error;
+}
+/** 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 class NewerTaskError extends Error {
+    kind;
+    version;
+    code = "PI_TASK_NEWER";
+    constructor(kind, version) {
+        super(`A live ${kind} task is version ${version}, which pi-durable 1.2 or later runs and the loaded pi-durable (before 1.2) cannot: continue the run on pi-durable 1.2 or later.`);
+        this.kind = kind;
+        this.version = version;
+        this.name = "NewerTaskError";
+    }
+}
+/** 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 async function refuseNewerTasks(harness, context) {
+    if (RESULT_KEY === "output")
+        return;
+    const newer = (await harness.inspect(context)).tasks.find(({ record }) => record.kind === "pi.tool" && record.version > 1)?.record;
+    if (newer)
+        throw new NewerTaskError(newer.kind, newer.version);
+}

package/dist/durable/readers.d.ts

@@ -0,0 +1,25 @@
+import type { RecoveryEffect, RecoveryNote } from "@parcha/agentrun-dsl/recovery";
+type Database = import("node:sqlite").DatabaseSync;
+type Json = any;
+/** A journal read back from the file: what `documentStore` keeps under one key. */
+export type JournalView = {
+    binding: string;
+    inputs: Record<string, string> | null;
+    generation: number;
+    revision: number;
+    state: Json;
+    notes: RecoveryNote[];
+    effects: RecoveryEffect[];
+};
+/** The run's store `file`, opened read-only for `read`; null when there is no such file. Every query of one `read` runs
+ *  in one read transaction, so what it returns is one commit's view, whatever a writer commits meanwhile. */
+export declare function withDurableFile<T>(file: string, read: (db: Database) => T): T | null;
+/** 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. */
+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. */
+export declare function committedRoutes(state: unknown): Record<string, Json>;
+export {};

package/dist/durable/readers.js

@@ -0,0 +1,64 @@
+// Read-only views of a run's durable file, synchronously and without the Harness: a document by its address, a
+// journal as `documentStore` wrote it, and the route decisions a frozen snapshot holds. A reader that only looks at
+// what ran (the run card, a tail that inherits what a run decided) uses them; the Harness stays the only writer. The
+// readers take the store file itself (pi-durable's SQLite file, wherever the host keeps it), never a directory.
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import { apply } from "@earendil-works/chord/delta";
+import { effectKey } from "./store.js";
+/** The run's store `file`, opened read-only for `read`; null when there is no such file. Every query of one `read` runs
+ *  in one read transaction, so what it returns is one commit's view, whatever a writer commits meanwhile. */
+export function withDurableFile(file, read) {
+    if (!fs.existsSync(file))
+        return null;
+    const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+    const db = new DatabaseSync(file, { readOnly: true, timeout: 5000 });
+    try {
+        db.exec("BEGIN");
+        return read(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/** A document's value: its latest base with every later delta applied, as the storage materializes it. */
+function revisionsOf(db, id) {
+    const base = db.prepare("SELECT seq, content FROM document_revisions WHERE document_id = ? AND kind = 'base' ORDER BY seq DESC LIMIT 1").get(id);
+    if (!base)
+        return undefined;
+    let value = JSON.parse(base.content);
+    for (const delta of db.prepare("SELECT content FROM document_revisions WHERE document_id = ? AND seq > ? ORDER BY seq").all(id, base.seq)) {
+        value = apply(value, JSON.parse(delta.content));
+    }
+    return value;
+}
+/** A Session document's current value. `key` names a family member; a singleton has none. */
+function sessionDoc(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);
+}
+/** 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. */
+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) => {
+            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 } : {}) };
+        });
+        return { binding: doc.binding, inputs: doc.inputs, generation: doc.generation, revision: doc.revision, state: doc.state, notes: doc.notes, effects };
+    }) ?? undefined;
+}
+/** Every committed route decision a frozen snapshot holds (each judge's answer, whole), by execution path. Empty for a
+ *  state that is no snapshot. */
+export function committedRoutes(state) {
+    const routes = state?.pin?.routes;
+    return routes && typeof routes === "object" && !Array.isArray(routes) ? { ...routes } : {};
+}