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

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>;

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,28 @@
+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. `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. */
+export declare function committedRoutes(state: unknown): Record<string, Json>;
+export {};

package/dist/durable/readers.js

@@ -0,0 +1,103 @@
+// 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;
+}
+/** 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;
+}
+/** 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. `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;
+        // 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 } : {}) };
+        });
+        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 } : {};
+}

package/dist/durable/receipts.d.ts

@@ -0,0 +1,54 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import { type InheritedReceipt, type InheritedUnknown } from "@parcha/agentrun-dsl/recovery";
+import type { DocumentStoreHost } from "./store.js";
+/** The run's paid-effect receipts, one per external call (the tool and the hash of its arguments): what the call answered
+ *  and which session paid for it. A record of spend, never a stop. Every session of the run is in the same Session, so a
+ *  continuation reads its predecessor's receipts here, with no copy at the handoff beyond the seed. A receipt holds the
+ *  result's text: the text blocks, joined by a newline. Another kind of block, an image for one, is not kept, and a repeat
+ *  is answered with the text alone. A call that returned nothing is a receipt too (its result reads `null`), so a repeat is
+ *  answered and not paid for again. The kind, version and key are a stored format. */
+export declare const ReceiptIndex: import("@earendil-works/pi-durable").SessionDocFamilyToken<{
+    tool: string;
+    argsHash: string;
+    result: JsonValue | null;
+    session: string | null;
+}, null>;
+/** Put a journal's paid receipts into the run's receipts before a continuation's first request. A receipt already held
+ *  is kept. A receipt with no session is the run `from` paid for. */
+export declare function seedReceipts(host: DocumentStoreHost, receipts: readonly Pick<InheritedReceipt, "tool" | "argsHash" | "result" | "session">[], from: string, context?: Context): Promise<void>;
+/** The part of a durable tool the wrapper reads and replaces: `execute` gets the call's arguments, pi-durable's call api
+ *  (`snapshot` and `commit` on the run's documents) and the call's context. */
+export type ReusableTool = {
+    name: string;
+    execute: (args: any, api: any, context: any) => Promise<any>;
+};
+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 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;
+    /** Effects whose outcome is unknown, from the handoff (`handoff.unknown`): a call equal to one is refused. */
+    unknown?: readonly Pick<InheritedUnknown, "name" | "argsHash" | "intent">[];
+    /** How a call's key is derived. Default: the gateway tool a `fetch` wrapper names, else the tool's own name. */
+    keyOf?: (toolName: string, args: unknown) => {
+        tool: string;
+        argsHash: string;
+    };
+};
+export type ReceiptReuse = {
+    /** The tool with its `execute` wrapped; a tool not named in `tools` is returned as it is. A wrapped call whose result
+     *  carries its blocks only under the key the loaded pi-durable does not read throws `ToolResultKeyError`, and no
+     *  receipt is written: the model would have received an empty result. */
+    wrap<T extends ReusableTool>(tool: T): T;
+    /** Calls answered from a receipt and calls refused as unknown, so far. */
+    readonly stats: {
+        reused: number;
+        refused: number;
+    };
+};
+export declare function reuseReceipts(options: ReuseReceiptsOptions): ReceiptReuse;

package/dist/durable/receipts.js

@@ -0,0 +1,92 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { defineDocFamily } from "@earendil-works/pi-durable";
+import { gatewayIntentOf, returnedFailure } from "@parcha/agentrun-dsl/recovery";
+import { resultBlocks, toolResult } from "./pi-versions.js";
+// Not buying an effect twice, structurally. A pi hook cannot answer a call without executing it, so a run that pays for
+// external calls wraps each paid tool: the call's paid result is recorded in the run's receipts, a repeat of a call another
+// session of the run paid for is answered from them and says so, and a call equal to an effect whose outcome is unknown
+// is refused. A continuation seeds the receipts from the handoff before its first request. The wrapper needs no pi tool
+// type: it decorates anything with a name and an `execute`, so a host applies it through pi-durable's `wrapTool` or to its
+// own registrations.
+/** The run's paid-effect receipts, one per external call (the tool and the hash of its arguments): what the call answered
+ *  and which session paid for it. A record of spend, never a stop. Every session of the run is in the same Session, so a
+ *  continuation reads its predecessor's receipts here, with no copy at the handoff beyond the seed. A receipt holds the
+ *  result's text: the text blocks, joined by a newline. Another kind of block, an image for one, is not kept, and a repeat
+ *  is answered with the text alone. A call that returned nothing is a receipt too (its result reads `null`), so a repeat is
+ *  answered and not paid for again. The kind, version and key are a stored format. */
+export const ReceiptIndex = defineDocFamily({
+    kind: "agentrun.receipts", version: 1, scope: "session", family: true, initial: () => ({ tool: "", argsHash: "", result: null, session: null }),
+});
+/** Put a journal's paid receipts into the run's receipts before a continuation's first request. A receipt already held
+ *  is kept. A receipt with no session is the run `from` paid for. */
+export async function seedReceipts(host, receipts, from, context = BACKGROUND_CONTEXT) {
+    if (!receipts.length)
+        return;
+    await host.commit(async (tx) => {
+        for (const receipt of receipts) {
+            const held = await tx.doc(ReceiptIndex, `${receipt.tool}:${receipt.argsHash}`, null);
+            if (held.result !== null)
+                continue;
+            held.tool = receipt.tool;
+            held.argsHash = receipt.argsHash;
+            held.session = receipt.session ?? from;
+            held.result = (typeof receipt.result === "string" ? receipt.result : JSON.stringify(receipt.result ?? null));
+        }
+    }, context);
+}
+/** The text of a result's blocks, joined by a newline: what a receipt holds. */
+const textOf = (blocks) => blocks.map((block) => block?.text ?? "").join("\n");
+/** A returned result that is itself a failure is no paid result: `isError`, or a failure envelope as the result itself,
+ *  its JSON text, or the text of its blocks (`blocks`, as the loaded pi-durable reads them). */
+const failed = (raw, blocks) => {
+    if (raw && typeof raw === "object" && raw.isError === true)
+        return true;
+    if (blocks)
+        return returnedFailure(textOf(blocks));
+    return returnedFailure(raw);
+};
+export function reuseReceipts(options) {
+    const keyOf = options.keyOf ?? gatewayIntentOf;
+    // An unknown is matched by the name and hash its admission recorded, and by the external call it was admitted for.
+    const unknown = new Set((options.unknown ?? []).flatMap((u) => [`${u.name}\n${u.argsHash}`, ...(u.intent ? [`${u.intent.tool}\n${u.intent.argsHash}`] : [])]));
+    const paid = new Set(options.tools);
+    const stats = { reused: 0, refused: 0 };
+    return {
+        stats,
+        wrap: (tool) => !paid.has(tool.name) ? tool : {
+            ...tool,
+            execute: async (args, api, context) => {
+                const intent = keyOf(tool.name, args);
+                if (unknown.has(`${intent.tool}\n${intent.argsHash}`) || unknown.has(`${tool.name}\n${intent.argsHash}`)) {
+                    stats.refused += 1;
+                    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 !== 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 } });
+                    }
+                }
+                const result = await tool.execute(args, api, context);
+                const blocks = resultBlocks(tool.name, result);
+                if (!failed(result, blocks)) {
+                    const value = textOf(blocks ?? []);
+                    await api.commit(async (tx) => {
+                        const receipt = await tx.doc(ReceiptIndex, key, null);
+                        if (receipt.result === null) {
+                            receipt.tool = intent.tool;
+                            receipt.argsHash = intent.argsHash;
+                            receipt.result = value;
+                            receipt.session = session;
+                        }
+                    }, context);
+                }
+                return result;
+            },
+        },
+    };
+}

package/dist/durable/record-file.d.ts

@@ -0,0 +1,10 @@
+import type { RecordContract } from "./record.js";
+/** The file envelope over a workspace directory, under the key the host names. `notBefore` is when the node's
+ *  conversation first opened, in epoch milliseconds: an older file is another run's and is refused. A file that is
+ *  not there fails with the file system's own `ENOENT`. A workspace that is the file system's root confines nothing,
+ *  and every path is refused there as outside it. */
+export declare function workspaceRecordFile(options: {
+    key: string;
+    workspace: string;
+    notBefore?: () => number;
+}): NonNullable<RecordContract["file"]>;

package/dist/durable/record-file.js

@@ -0,0 +1,56 @@
+// A record delivered as a workspace file: the reader behind the file envelope. The path is the model's, so it is
+// held to the workspace (a relative `.json` path, no symlink on the way, a regular file) and to this run (written
+// after the node's conversation opened), and the file must parse.
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+// A file system's modification times can trail the clock slightly; a file the node just wrote is not stale.
+const CLOCK_SKEW_MS = 2_000;
+/** The file envelope over a workspace directory, under the key the host names. `notBefore` is when the node's
+ *  conversation first opened, in epoch milliseconds: an older file is another run's and is refused. A file that is
+ *  not there fails with the file system's own `ENOENT`. A workspace that is the file system's root confines nothing,
+ *  and every path is refused there as outside it. */
+export function workspaceRecordFile(options) {
+    const { key } = options;
+    return {
+        key,
+        read: async (relative) => {
+            if (path.isAbsolute(relative) || path.extname(relative).toLowerCase() !== ".json")
+                throw new Error(`${key} must name a workspace-relative .json file`);
+            const root = path.resolve(options.workspace);
+            const target = path.resolve(root, relative);
+            if (!target.startsWith(`${root}${path.sep}`))
+                throw new Error(`${key} names a path outside the workspace: ${relative}`);
+            // Lexical containment alone would follow a symlink in the workspace out of it.
+            let cursor = root;
+            for (const segment of path.relative(root, target).split(path.sep).filter(Boolean)) {
+                cursor = path.join(cursor, segment);
+                const stat = await fs.lstat(cursor).catch(() => null);
+                if (!stat)
+                    break;
+                if (stat.isSymbolicLink())
+                    throw new Error(`${key} names a path outside the workspace through a symlink: ${relative}`);
+            }
+            // Non-blocking: a named pipe opens at once and is refused below, where a plain open would wait for its writer.
+            const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            let text;
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile())
+                    throw new Error(`${key} must name a regular file`);
+                if (options.notBefore && stat.mtimeMs < options.notBefore() - CLOCK_SKEW_MS)
+                    throw new Error(`${key} is stale; write it during this run before submitting`);
+                text = await handle.readFile({ encoding: "utf8" });
+            }
+            finally {
+                await handle.close();
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new Error(`${key} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,76 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import { type ConversationId, type DocumentReader, type HookApi, type HookRegistration, type ToolExecutionApi, type ToolRegistration } from "@earendil-works/pi-durable";
+import { type Delivery, type Disagreement, type RecordContract, type RecordStore } from "./record.js";
+/** The record a conversation delivered, or null while it has not, and the delivery attempts it has spent. */
+export declare const RecordDoc: import("@earendil-works/pi-durable").ConversationDocToken<{
+    record: JsonValue | null;
+    attempts: number;
+}>;
+/** The gate's own state beside the record: whether the second reading's round was spent, and what it still
+ *  disagreed with in the delivered record. */
+export declare const GateDoc: import("@earendil-works/pi-durable").ConversationDocToken<{
+    bounced: boolean;
+    disagreements: Disagreement[];
+}>;
+/** The core's store on a conversation's two documents, written through a tool call's commits. */
+export declare function recordStore(api: Pick<ToolExecutionApi, "commit" | "snapshot" | "conversationId">, context: Context): RecordStore;
+/** The record a conversation delivered, or undefined while it has not, with what its second reading still disagreed with. */
+export declare function deliveredRecord(reader: Pick<DocumentReader, "snapshot">, conversationId: ConversationId, context: Context): Promise<{
+    record: JsonValue;
+    disagreements: Disagreement[];
+} | undefined>;
+/** The `submit` tool as a model is shown it for one record: what it delivers, and the record's top-level fields with
+ *  their plain types and descriptions, none required, since a partial record is an attempt the core counts. A record
+ *  that may be delivered as a workspace file is offered the envelope under `fileKey`. */
+export declare function submitDefinition(record: {
+    schema: Record<string, unknown>;
+    label: string;
+    fileKey?: string;
+}): {
+    description: string;
+    parameters: Record<string, unknown>;
+};
+export type RecordToolOptions = {
+    /** The one record this tool delivers: its schema, what the model is told it delivers ("the summary record") and
+     *  the key it may be delivered under as a workspace file. Absent, the tool serves conversations with different
+     *  records: it is registered with open parameters, each conversation's contract names its schema and file key, and
+     *  the host presents each conversation its own definition (`submitDefinition`) in a request hook. */
+    record?: {
+        schema: Record<string, unknown>;
+        label: string;
+        fileKey?: string;
+    };
+    /** The delivery contract of the conversation that called: its schema, reviewers, host checks and file reader. It is
+     *  read on every call, so a host may resolve it late (a conversation pi resumed before its owner reached it again). */
+    contract(api: Pick<ToolExecutionApi, "conversationId" | "snapshot">, context: Context): RecordContract | Promise<RecordContract>;
+    /** Told each delivery after its commit: a host writes its own rows from it. A throw is the caller's own failure. */
+    onDelivery?(delivery: Delivery, conversationId: ConversationId): void | Promise<void>;
+    /** Whether an error is the host's own failure. Such an error ends the node's run with `fatalText`, and the host is
+     *  told through `onFatal`; any other error is the tool's and is thrown. */
+    fatal?: (error: unknown) => boolean;
+    onFatal?(error: unknown, conversationId: ConversationId): void;
+    fatalText?: string;
+    /** How a disagreement is told to the model when its record goes back (default `disagreementText`). */
+    say?: (disagreement: Disagreement) => string;
+};
+/** The `submit` tool. */
+export declare function recordTool(options: RecordToolOptions): ToolRegistration;
+export type RecordNudgeOptions = {
+    /** What is owed, as the nudge names it; undefined for a conversation this hook does not nudge (it owes no record). */
+    label(api: Pick<HookApi, "conversationId" | "snapshot">, context: Context): string | undefined | Promise<string | undefined>;
+    /** Counts one delivery attempt on the conversation's record, durably, before the model is nudged. A hook cannot
+     *  commit, so the conversation's owner supplies the write. */
+    spend(conversationId: ConversationId, context: Context): Promise<void>;
+    /** Delivery attempts the conversation gets (default `DELIVERY_ATTEMPTS`). */
+    maxAttempts?: number;
+};
+/** The nudge: a yield with the record still owed continues the run with a reminder, each nudge one delivery attempt;
+ *  past the attempts the run ends. The nudge that spends the last attempt still continues, so the model is asked once
+ *  more after it. */
+export declare function recordNudge(options: RecordNudgeOptions): HookRegistration;
+/** One nudge's delivery attempt, as a commit on the conversation's record. */
+export declare const spendNudge: (tx: {
+    doc(token: typeof RecordDoc, conversationId: ConversationId): Promise<{
+        attempts: number;
+    }>;
+}, conversationId: ConversationId) => Promise<void>;