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

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

package/dist/durable/record-tool.js

@@ -0,0 +1,123 @@
+import { defineDoc, defineTool, GenerationTask, hook, } from "@earendil-works/pi-durable";
+import { DELIVERY_ATTEMPTS, deliver, deliveryTerminates, deliveryText, fileSubmission, mixedFileSubmission, nudgeText, repairRecord, VIOLATIONS_SHOWN, } from "./record.js";
+import { toolResult } from "./pi-versions.js";
+/** The record a conversation delivered, or null while it has not, and the delivery attempts it has spent. */
+export const RecordDoc = defineDoc({
+    kind: "agentrun.record", version: 1, scope: "conversation", history: "latest", fork: "initial", initial: () => ({ record: null, attempts: 0 }),
+});
+/** 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 const GateDoc = defineDoc({
+    kind: "agentrun.gate", version: 1, scope: "conversation", history: "latest", fork: "initial", initial: () => ({ bounced: false, disagreements: [] }),
+});
+/** Where `prepareArguments` carries a call's arguments to `execute`. A record's own fields are never read as it. */
+const RAW = "_raw";
+/** The core's store on a conversation's two documents, written through a tool call's commits. */
+export function recordStore(api, context) {
+    const id = api.conversationId;
+    return {
+        read: async () => ({
+            record: (await api.snapshot(RecordDoc, id, context)) ?? { record: null, attempts: 0 },
+            gate: (await api.snapshot(GateDoc, id, context)) ?? { bounced: false, disagreements: [] },
+        }),
+        reject: () => api.commit(async (tx) => { const state = await tx.doc(RecordDoc, id); state.attempts += 1; return state.attempts; }, context),
+        bounce: () => api.commit(async (tx) => {
+            (await tx.doc(GateDoc, id)).bounced = true;
+            const state = await tx.doc(RecordDoc, id);
+            state.attempts += 1;
+            return state.attempts;
+        }, context),
+        accept: (record, disagreements) => api.commit(async (tx) => {
+            const state = await tx.doc(RecordDoc, id);
+            state.record = record;
+            state.attempts += 1;
+            if (disagreements.length)
+                (await tx.doc(GateDoc, id)).disagreements = disagreements;
+        }, context),
+    };
+}
+/** The record a conversation delivered, or undefined while it has not, with what its second reading still disagreed with. */
+export async function deliveredRecord(reader, conversationId, context) {
+    const state = await reader.snapshot(RecordDoc, conversationId, context);
+    if (state?.record == null)
+        return undefined;
+    return { record: state.record, disagreements: [...((await reader.snapshot(GateDoc, conversationId, context))?.disagreements ?? [])] };
+}
+/** 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 function submitDefinition(record) {
+    const { schema, label, fileKey } = record;
+    const declared = schema.properties && typeof schema.properties === "object" ? schema.properties : {};
+    return {
+        description: fileKey
+            ? `Deliver ${label}. Submit it inline, or for a large record write JSON in the workspace and pass {"${fileKey}":"relative/path.json"}. It ends the run. These parameters are the output schema: submit validates the record against it and returns the violations to fix, up to ${VIOLATIONS_SHOWN} per call, so there is no schema file to find and no need to validate the record yourself first.`
+            : `Deliver ${label}. Submit it inline as the tool arguments. It ends the run. These parameters are the output schema: submit validates the record against it and returns the violations to fix, up to ${VIOLATIONS_SHOWN} per call.`,
+        parameters: { type: "object", additionalProperties: true, properties: {
+                ...Object.fromEntries(Object.entries(declared).filter(([key]) => key !== RAW).map(([key, property]) => [key, { ...(typeof property?.type === "string" ? { type: property.type } : {}), ...(typeof property?.description === "string" ? { description: property.description } : {}) }])),
+                ...(fileKey ? { [fileKey]: { type: "string", description: "Workspace-relative path to the complete JSON record" } } : {})
+            } },
+    };
+}
+/** A call's arguments as the core decides them: a file submission as it is, an inline record repaired as a transport
+ *  spelling. The reserved file key beside inline fields is the transport's, never the record's. */
+function carried(args, schema, fileKey) {
+    if (fileKey && (fileSubmission(args, fileKey) !== null || mixedFileSubmission(args, schema, fileKey)))
+        return args;
+    const inline = fileKey && args && typeof args === "object" && !Array.isArray(args) ? (({ [fileKey]: _reserved, ...rest }) => rest)(args) : args;
+    return repairRecord(inline, schema);
+}
+/** The `submit` tool. */
+export function recordTool(options) {
+    const { record } = options;
+    const shown = record ? submitDefinition(record) : { description: "Deliver the record. It ends the run.", parameters: { type: "object", additionalProperties: true } };
+    const answer = (delivery, maxAttempts) => toolResult([{ type: "text", text: deliveryText(delivery, maxAttempts, options.say) }], {
+        ...(delivery.status === "rejected" || delivery.status === "bounced" ? { isError: true } : {}),
+        ...(deliveryTerminates(delivery) ? { control: { terminate: true } } : {}),
+    });
+    return defineTool({
+        name: "submit",
+        description: shown.description,
+        parameters: shown.parameters,
+        // Every call's arguments are carried to `execute`; one record's are repaired here, before the Harness validates.
+        prepareArguments: (args) => ({ [RAW]: record ? carried(args, record.schema, record.fileKey) : args }),
+        replay: "safe",
+        executionMode: "sequential",
+        execute: async (args, api, context) => {
+            try {
+                const contract = await options.contract(api, context);
+                const raw = args[RAW];
+                const delivery = await deliver({ ...contract, ...(options.fatal ? { fatal: options.fatal } : {}) }, recordStore(api, context), record ? raw : carried(raw, contract.schema, contract.file?.key));
+                await options.onDelivery?.(delivery, api.conversationId);
+                return answer(delivery, contract.maxAttempts ?? DELIVERY_ATTEMPTS);
+            }
+            catch (error) {
+                if (!options.fatal?.(error))
+                    throw error;
+                options.onFatal?.(error, api.conversationId);
+                return toolResult([{ type: "text", text: options.fatalText ?? "The run cannot record this submission; the run stops." }], { isError: true, control: { terminate: true } });
+            }
+        },
+    });
+}
+/** 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 function recordNudge(options) {
+    return hook(GenerationTask, {
+        onYield: async (_answer, api, context) => {
+            const state = await api.snapshot(RecordDoc, api.conversationId, context);
+            if (state?.record != null)
+                return undefined;
+            const label = await options.label(api, context);
+            if (label === undefined || (state?.attempts ?? 0) >= (options.maxAttempts ?? DELIVERY_ATTEMPTS))
+                return undefined;
+            await options.spend(api.conversationId, context);
+            return { continue: nudgeText(label) };
+        },
+    });
+}
+/** One nudge's delivery attempt, as a commit on the conversation's record. */
+export const spendNudge = async (tx, conversationId) => {
+    (await tx.doc(RecordDoc, conversationId)).attempts += 1;
+};