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

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;