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

package/dist/durable/receipts.d.ts

@@ -0,0 +1,52 @@
+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 this wrapper runs in: it never answers a call from a receipt its own session wrote. */
+    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,91 @@
+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}`;
+                if (options.answer) {
+                    const receipt = await api.snapshot(ReceiptIndex, key, context);
+                    if (receipt?.result != null && receipt.session !== options.sessionId) {
+                        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 = options.sessionId;
+                        }
+                    }, 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;
+};

package/dist/durable/record.d.ts

@@ -0,0 +1,157 @@
+/** The record a node delivered, or null while it has not, and the delivery attempts it has spent. */
+export type RecordState = {
+    record: unknown;
+    attempts: number;
+};
+/** What the second reading disagrees with in a record: its question, the kind of reading, the verdict and why. */
+export type Disagreement = {
+    id: string;
+    kind: string;
+    verdict: string;
+    reasons: string[];
+};
+/** Whether the second reading's round was spent, and what it still disagreed with in the delivered record. */
+export type GateState = {
+    bounced: boolean;
+    disagreements: Disagreement[];
+};
+/** Delivery attempts a node gets: rejections, the second reading's one bounce and nudges, each once. */
+export declare const DELIVERY_ATTEMPTS = 6;
+/** The most schema violations one rejected delivery lists; the submit tool's description tells the model the number. */
+export declare const VIOLATIONS_SHOWN = 8;
+/** One reviewer's reading of a structurally valid record. `no_verdict` is a reviewer that could not answer. */
+export type Reading = "disagrees" | "agrees" | "no_verdict";
+/** The second reading on one structurally valid submission: it sends the record back only while its round
+ *  is unspent and a reviewer disagrees. A reviewer with no verdict never sends a record back. */
+export declare function gate(bounced: boolean, readings: readonly Reading[]): "accept" | "bounce";
+/** What a node is answered with. Only `delivered` is a delivery; each of the others spends one attempt. */
+export type DeliveryEvent = "rejected" | "bounce" | "nudge" | "delivered";
+/** A node's delivery, as far as the attempts count it. */
+export type DeliveryCount = {
+    attempts: number;
+    delivered: boolean;
+};
+/** Whether a node's delivery has ended: it delivered, or its attempts are spent. */
+export declare const deliveryEnded: (max: number, state: DeliveryCount) => boolean;
+/** One answer applied to the count. An ended delivery takes no further answer; every other answer counts once. */
+export declare function spend(max: number, state: DeliveryCount, event: DeliveryEvent): DeliveryCount;
+/** What makes a schema one no `submit` call can satisfy: a call's arguments are an object, so the schema must be a
+ *  JSON Schema object whose root type, when it names one, admits an object. A node runner refuses such a schema
+ *  before any conversation exists. */
+export declare function lintRecordRoot(schema: unknown): string[];
+/** What an author should fix in a record schema, for a host or a validator to report: the root findings above, and
+ *  a schema that declares its fields and requires one that is not among them, which the tool's shown fields never
+ *  name. A record of the second kind can still be delivered (the tool's parameters are open, and the delivery
+ *  contract that ends the node's task carries the schema with its `required`), so a runner does not refuse it. A
+ *  schema that declares no `properties` is not held to it. */
+export declare function lintRecordSchema(schema: unknown): string[];
+/** Where the schema expects an object or an array and the submitted value is a string that parses to one, the
+ *  parsed value; where it expects a number, an integer, a boolean or null and admits no string, the scalar a
+ *  string spells. Some model families serialise nested tool arguments as strings: the content is valid and
+ *  every submit fails on its spelling. A string that parses to a container the field also admits is read as that
+ *  container; only against a scalar does a field that admits a string keep the string. */
+export declare function parseStringifiedContainers(value: unknown, schema: Record<string, unknown> | undefined, depth?: number, rootDefinitions?: Record<string, unknown>): unknown;
+/** The path of every string that spells "no value" in a field whose schema admits JSON null. */
+export declare function nullSpellings(value: unknown, schema: unknown, root?: unknown, at?: string): string[];
+/** The record with every such string replaced by JSON null, in place. A repair the record as a whole refuses
+ *  (it satisfied its schema before and does not after) is undone in full, so a spelling stays only where null
+ *  is inadmissible; `undo: false` leaves that judgement to a caller that repairs more of the record and judges the
+ *  whole. `""` is a value and stays. */
+export declare function healNullSpellings<T>(record: T, schema: Record<string, unknown>, options?: {
+    undo?: boolean;
+}): T;
+/** A record's transport spellings repaired against its schema, without touching `args`. */
+export declare function repairRecord(args: unknown, schema: Record<string, unknown>): unknown;
+/** The file a submission names and nothing else: `{ <key>: "relative/path.json" }`. */
+export declare function fileSubmission(args: unknown, key: string): string | null;
+/** A submission with fields beside the file key. Fields that form a whole record on their own are that record;
+ *  otherwise the file holds the record, and each field beside it may only restate the file's value. A schema
+ *  that declares the file key as its own field keeps it inline. */
+export declare function mixedFileSubmission(args: unknown, schema: Record<string, unknown> | undefined, key: string): {
+    file: string;
+    extras: Record<string, unknown>;
+} | null;
+/** The fields beside the file key that the file's record does not hold with the same value. */
+export declare function extrasNotInRecord(record: unknown, extras: Record<string, unknown>): string[];
+/** One host check's refusal of a candidate: the problems the model must fix, and the reason they are grouped under. */
+export type Refusal = {
+    problems: string[];
+    reason?: string;
+};
+/** A second reader of a structurally valid record. It returns what it disagrees with (nothing when it agrees or
+ *  has no verdict). `round` says whether a disagreement still sends the record back. A reviewer that throws
+ *  decides nothing, unless the contract's `fatal` claims the error. */
+export type Reviewer = (candidate: unknown, context: {
+    round: boolean;
+}) => Disagreement[] | Promise<Disagreement[]>;
+export type RecordContract = {
+    /** The node's record schema, the `submit` tool's contract. */
+    schema: Record<string, unknown>;
+    /** Delivery attempts the node gets (default `DELIVERY_ATTEMPTS`). */
+    maxAttempts?: number;
+    /** A record may be delivered as a workspace file named under `key`; `read` returns the file's parsed JSON or
+     *  throws (an error whose `code` is `ENOENT` for a file that is not there). Absent, a record is inline only. */
+    file?: {
+        key: string;
+        read(path: string): Promise<unknown>;
+    };
+    /** Contracts the host owns, held before the schema: each problem is said with the core's own findings. */
+    contracts?: (candidate: unknown) => string[] | Promise<string[]>;
+    /** Checks held after the schema, in order; the first refusal is the rejection. One that throws refuses with
+     *  what it threw. */
+    checks?: ReadonlyArray<(candidate: unknown) => Refusal | null | Promise<Refusal | null>>;
+    /** The second reading, in order. */
+    reviewers?: readonly Reviewer[];
+    /** Whether a reviewer's error is the caller's own failure, to be thrown and not absorbed. */
+    fatal?: (error: unknown) => boolean;
+};
+/** The two states behind a node's delivery. Each write is one atomic change; `reject` and `bounce` return the
+ *  attempts spent after it. The bounce spends the round before the model is told, so a crash cannot grant it twice. */
+export type RecordStore = {
+    read(): Promise<{
+        record: RecordState;
+        gate: GateState;
+    }>;
+    reject(): Promise<number>;
+    bounce(): Promise<number>;
+    accept(record: unknown, disagreements: Disagreement[]): Promise<void>;
+};
+/** What one submission came to. `spent` says the delivery attempts are gone and the node's run ends here. */
+export type Delivery = {
+    status: "already";
+} | {
+    status: "rejected";
+    attempts: number;
+    spent: boolean;
+    reason: string;
+    problems: string[];
+} | {
+    status: "bounced";
+    attempts: number;
+    spent: boolean;
+    disagreements: Disagreement[];
+} | {
+    status: "accepted";
+    record: unknown;
+    disagreements: Disagreement[];
+};
+/** Decide one `submit` call. `args` are the call's arguments as the model sent them, or as `repairRecord`
+ *  already repaired them. */
+export declare function deliver(contract: RecordContract, store: RecordStore, args: unknown): Promise<Delivery>;
+/** The `submit` tool's answer to the model for one delivery. */
+export declare function deliveryText(delivery: Delivery, maxAttempts?: number, say?: (disagreement: Disagreement) => string): string;
+/** One disagreement as the model reads it. */
+export declare const disagreementText: (d: Disagreement) => string;
+/** Whether a delivery ends the node's run: a record was delivered, or the attempts are spent. */
+export declare const deliveryTerminates: (delivery: Delivery) => boolean;
+/** The delivery contract a node's task ends with: the label, the file envelope when one is offered, the
+ *  authoritative schema and the host's own delivery instructions. The model sees the exact schema only here. */
+export declare function submitFooter(record: {
+    label: string;
+    schema: Record<string, unknown>;
+    fileKey?: string;
+    instructions?: string;
+    reviewed?: boolean;
+}): string;
+/** What a yield without a record is answered with, when the delivery has an attempt left for it. */
+export declare const nudgeText: (label: string) => string;