@hachej/boring-agent 0.4.26 → 0.4.28

package/dist/run-ledger.js

@@ -0,0 +1,194 @@
+import { settleResult, validateResult, validationError } from './run-result.js';
+import { OVER_BUDGET, deliverRunEnd, endsWithError, isOverBudget } from './runs.js';
+/**
+ * The runs a home keeps in a person's own store, and the runner over them: start a run by its key (the same key is the same run),
+ * end it exactly once, deliver its end to the operation that started it, cancel it, and find again what a stopped process left.
+ * The store is the host's data (a table in its SQLite file); the model turns stay Pi's (the run is a native conversation).
+ */
+export const RUNS_TABLE = 'CREATE TABLE IF NOT EXISTS _host_agent_runs (key TEXT PRIMARY KEY, agent TEXT NOT NULL, status TEXT NOT NULL, output TEXT, error TEXT, deliver TEXT, validation TEXT, delivered INTEGER NOT NULL DEFAULT 0, person TEXT NOT NULL, usage TEXT, started_at TEXT)';
+/** Columns added after the table first shipped: a store created before them gets them here. */
+const LATE_COLUMNS = ['validation TEXT', 'usage TEXT', 'started_at TEXT'];
+/** A refusal with an HTTP-like `status` (404: no such agent; 409: the key belongs to another agent). */
+export class RunRefused extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'RunRefused';
+    }
+}
+/** The ledger over a store's synchronous SQL (`SyncSql`: `UPDATE ... RETURNING` is what makes an end happen once). */
+export function createRunLedger(sql) {
+    const rowsOf = (text, params = []) => sql(text, params);
+    let ready = false;
+    const ensure = () => {
+        if (ready)
+            return;
+        sql(RUNS_TABLE, []);
+        const have = new Set(sql('PRAGMA table_info(_host_agent_runs)', []).map(c => String(c.name)));
+        for (const column of LATE_COLUMNS)
+            if (!have.has(column.split(' ')[0]))
+                sql(`ALTER TABLE _host_agent_runs ADD COLUMN ${column}`, []);
+        ready = true;
+    };
+    const get = (key) => { ensure(); return rowsOf('SELECT * FROM _host_agent_runs WHERE key = ?', [key])[0]; };
+    return {
+        ensure, get,
+        /** Record a new running run. The caller has checked `get(key)` first. */
+        begin(run) {
+            ensure();
+            sql("INSERT INTO _host_agent_runs (key, agent, status, deliver, person, started_at) VALUES (?, ?, 'running', ?, ?, ?)", [run.key, run.agent, run.deliver, JSON.stringify(run.person), run.startedAt]);
+        },
+        /** End a run still running, once (a cancel and the run's own end race): false when something else ended it first. */
+        end(key, status, options = {}) {
+            ensure();
+            const changed = rowsOf("UPDATE _host_agent_runs SET status = ?, output = ?, error = ?, validation = ?, usage = ? WHERE key = ? AND status = 'running' RETURNING key", [status, options.output === undefined ? null : JSON.stringify(options.output), options.error ?? null, options.validation ? JSON.stringify(options.validation) : null, options.usage ? JSON.stringify(options.usage) : null, key]);
+            return changed.length > 0;
+        },
+        /** A completed run whose delivery-time check failed: its end becomes the failure (never after it was delivered). */
+        fail(key, status, error) {
+            ensure();
+            sql('UPDATE _host_agent_runs SET status = ?, output = NULL, error = ?, validation = NULL WHERE key = ? AND delivered = 0', [status, error, key]);
+        },
+        markDelivered(key) { ensure(); sql('UPDATE _host_agent_runs SET delivered = 1 WHERE key = ?', [key]); },
+        /** Runs a stopped process left: still running (they end `interrupted`), or ended and not delivered. */
+        left() { ensure(); return rowsOf("SELECT * FROM _host_agent_runs WHERE status = 'running' OR (deliver IS NOT NULL AND delivered = 0)"); },
+        view(row) {
+            return {
+                run: row.key, status: row.status, ...(row.started_at ? { startedAt: row.started_at } : {}),
+                ...(row.status === 'completed' && row.output !== null ? { output: JSON.parse(row.output) } : {}),
+                usage: row.usage ? JSON.parse(row.usage) : null,
+                ...(endsWithError(row.status) ? { error: row.error ?? row.status } : {}),
+            };
+        },
+    };
+}
+/**
+ * The runner of one person's store. A run lives in this process: one a restart cut short is found by `recover` and ends
+ * `interrupted`; one that ended and was not delivered is delivered then. Delivery is once (the host's receipt `deliver:<key>`).
+ */
+export function createRunner(options) {
+    const { ledger, person, context, has, prepare, invoke, admit, now = () => new Date().toISOString() } = options;
+    const live = new Map();
+    const delivering = new Map();
+    const overBudget = () => { if (!admit)
+        return false; try {
+        admit();
+        return false;
+    }
+    catch (error) {
+        return isOverBudget(error);
+    } };
+    const deliver = async (row) => {
+        const active = delivering.get(row.key);
+        if (active)
+            return active;
+        const pending = deliverPending(ledger.get(row.key));
+        delivering.set(row.key, pending);
+        try {
+            await pending;
+        }
+        finally {
+            delivering.delete(row.key);
+        }
+    };
+    const deliverPending = async (row) => {
+        if (!row.deliver || row.delivered)
+            return;
+        const view = ledger.view(row);
+        const checked = row.status === 'completed' && row.validation ? JSON.parse(row.validation) : undefined;
+        const sent = await deliverRunEnd({
+            operation: row.deliver, key: row.key, invoke,
+            end: { status: row.status, ...(view.output !== undefined ? { output: view.output } : {}), usage: view.usage, ...(view.error ? { error: view.error } : {}) },
+            ...(checked ? { recheck: async () => {
+                    const result = await validateResult(checked.card, view.output, checked.evidence, invoke, 'delivery', `result-delivery:${row.key}:${crypto.randomUUID()}`);
+                    return result.valid ? undefined : { end: 'invalid_output', error: result.hint ?? 'Return a supported result.' };
+                }, onFailure: (failure) => ledger.fail(row.key, failure.end, failure.error) } : {}),
+            ...(options.deliverAttempts !== undefined ? { attempts: options.deliverAttempts } : {}), ...(options.deliverBackoffMs !== undefined ? { backoffMs: options.deliverBackoffMs } : {}),
+        });
+        if (sent.delivered)
+            ledger.markDelivered(row.key);
+    };
+    /** Ends a run still running, once, then delivers it; false when something else ended it first. */
+    const end = async (key, status, endOptions = {}, beforeDeliver) => {
+        if (!ledger.end(key, status, endOptions))
+            return false;
+        await beforeDeliver?.();
+        await deliver({ key });
+        return true;
+    };
+    const answerOf = async (execution) => settleResult({ card: execution.card, conversation: execution.conversation, submission: execution.submission, invoke, context });
+    /**
+     * Runs left over by an earlier process. A run whose delivery is in flight is skipped, never awaited: a status read made from
+     * inside that delivery (its operation reading the run) would otherwise wait on itself.
+     */
+    const recover = async () => {
+        for (const row of ledger.left()) {
+            if (delivering.has(row.key))
+                continue;
+            if (row.status === 'running' && !live.has(row.key))
+                await end(row.key, 'interrupted', { error: 'the process stopped before the run ended' });
+            else if (row.status !== 'running')
+                await deliver(row);
+        }
+    };
+    return {
+        /** Starts the run of this key (a key already started is the same run, whatever else is asked): launched and returned at once. */
+        async start(agent, input, key, deliverTo) {
+            if (!(await has(agent)))
+                throw new RunRefused(404, `no agent ${agent}`);
+            const before = ledger.get(key);
+            if (before) {
+                if (before.agent !== agent)
+                    throw new RunRefused(409, `key ${key} is a run of ${before.agent}`);
+                return ledger.view(before);
+            }
+            ledger.begin({ key, agent, deliver: deliverTo, person, startedAt: now() });
+            // Over the host's spend cap: the run is never started, and ends (and is delivered) as `error: over_budget`.
+            const refused = overBudget();
+            const execution = refused ? Promise.resolve(null) : Promise.resolve().then(() => prepare(agent, input));
+            live.set(key, execution);
+            void (async () => {
+                try {
+                    const ready = await execution;
+                    if (refused) {
+                        await end(key, 'error', { error: OVER_BUDGET });
+                        return;
+                    }
+                    const answer = ready ? await answerOf(ready) : null;
+                    const usage = ready ? await Promise.resolve(options.usage?.(ready.conversation) ?? null).catch(() => null) : null;
+                    // A run cut short by the cap (a later turn refused) ends with the cap's code, not the model's error text.
+                    if (!answer || answer.error !== undefined)
+                        await end(key, (answer?.end ?? 'error'), { error: overBudget() ? OVER_BUDGET : answer?.error ?? `${agent} did not answer`, usage });
+                    else {
+                        const result = answer.result;
+                        await end(key, 'completed', { output: result === undefined ? undefined : 'output' in result ? result.output : result.text, ...(answer.validation ? { validation: answer.validation } : {}), usage });
+                    }
+                }
+                catch (error) {
+                    const failure = validationError(error);
+                    await end(key, failure.end, { error: overBudget() ? OVER_BUDGET : failure.error }).catch(() => { });
+                }
+                finally {
+                    live.delete(key);
+                }
+            })();
+            return ledger.view(ledger.get(key));
+        },
+        /** The run of this key as recorded, or null. Never waits on a delivery in flight: safe to call from inside one. */
+        async status(key) {
+            await recover();
+            const row = ledger.get(key);
+            return row ? ledger.view(row) : null;
+        },
+        /** Cancels it (its delivery gets `cancelled`); a run that has ended stays as it is; null: no such run. */
+        async cancel(key) {
+            if (!ledger.get(key))
+                return null;
+            // A run whose preparation failed has nothing to abort; the cancelled end is delivered either way.
+            await end(key, 'cancelled', {}, async () => { await (await live.get(key)?.catch(() => null))?.conversation.abort(context).catch(() => { }); });
+            return ledger.view(ledger.get(key));
+        },
+        recover,
+    };
+}

package/dist/run-outbox.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The outbox of runs an app operation asks for. The operation stages its starts in the SAME transaction as its writes and its
+ * receipt, in the store it touches (the app database and the agent home are two stores: this table is the only glue). After the
+ * commit the host launches each row with its key and removes it once the run is acknowledged; a row left behind (a crash, a
+ * refused call) is launched again later, which the key makes harmless. Runtime-neutral: `SyncSql` is the store's synchronous SQL
+ * (a Durable Object's `sql.exec`, `node:sqlite`); this file opens no transaction and no connection.
+ */
+/** The store's synchronous SQL: rows as plain objects (`SELECT`), or `[]` (a write). */
+export type SyncSql = (sql: string, params: unknown[]) => Record<string, unknown>[];
+export declare const EFFORTS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type Effort = typeof EFFORTS[number];
+export declare const MODEL_ID: RegExp;
+export declare const START_KEY: RegExp;
+export declare const AGENT_NAME: RegExp;
+export declare const OPERATION_NAME: RegExp;
+export declare const MAX_START_INPUT = 100000;
+export declare const MAX_STARTS = 20;
+export declare const OUTBOX_TABLE = "CREATE TABLE IF NOT EXISTS _host_agent_outbox (actor TEXT NOT NULL, key TEXT NOT NULL, agent TEXT NOT NULL, input TEXT NOT NULL, deliver TEXT, person TEXT NOT NULL, at TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL DEFAULT 0, PRIMARY KEY(actor, key))";
+/** A run an operation asks for: `input` is any JSON, `deliver` the operation that receives the run's end, `model` and `effort` this run's own. */
+export interface Start {
+    readonly key: string;
+    readonly agent: string;
+    readonly input?: unknown;
+    readonly deliver?: string | null;
+    readonly model?: string | null;
+    readonly effort?: Effort | null;
+}
+/** A start as stored: `input` is JSON text. */
+export interface CheckedStart {
+    readonly key: string;
+    readonly agent: string;
+    readonly input: string;
+    readonly deliver: string | null;
+    readonly model: string | null;
+    readonly effort: Effort | null;
+}
+export interface OutboxRow<P = unknown> {
+    readonly actor: string;
+    readonly key: string;
+    readonly agent: string;
+    readonly input: unknown;
+    readonly deliver: string | null;
+    readonly person: P;
+    readonly at: string;
+    readonly attempts: number;
+    readonly next_at: number;
+    readonly model?: string;
+    readonly effort?: Effort;
+}
+type Awaitable<T> = T | Promise<T>;
+/** The outbox of one store as its owner reads it. A remote store (a Durable Object other than the caller) offers the same calls over RPC. */
+export interface Outbox<P = unknown> {
+    /** The rows due at `now`, oldest first. */
+    due(now: number, limit?: number): Awaitable<OutboxRow<P>[]>;
+    pending(actor: string, key: string): Awaitable<OutboxRow<P> | null>;
+    /** The earliest due time, or null when the outbox is empty. */
+    next(): Awaitable<number | null>;
+    /** The run exists: drop the row. */
+    ack(actor: string, key: string): Awaitable<null>;
+    /** A launch that may work later: back off (1 s doubling, 5 min at most). */
+    retry(row: OutboxRow<P>, now: number): Awaitable<null>;
+}
+export type Launched = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly retry?: boolean;
+    readonly status?: number;
+    readonly error?: string;
+};
+/** The runs an operation asked for, checked once more by the host: bounded, well named, and a key never used twice for different runs. Throws a `{ status: 400 }` error. */
+export declare function checkStarts(starts: unknown): CheckedStart[];
+/**
+ * Stage rows inside the caller's transaction (its own BEGIN/COMMIT or `transactionSync`: this function never opens one). Keys are
+ * scoped by actor, and the store is already one app's one scope: Alice and Bob may use the same key. A key staged before and not
+ * yet launched keeps its first row.
+ */
+export declare function stageStarts(run: SyncSql, options: {
+    actor: string;
+    person: unknown;
+    starts: unknown;
+    at: string;
+}): void;
+/** The outbox of one store (`SyncSql` synchronous): see `Outbox`. */
+export declare function outboxOver<P = unknown>(run: SyncSql): Outbox<P>;
+/**
+ * Launch the rows that are due (or only `only` = { actor, key }, due or not) through `outbox`. `launch(row)` starts the run and
+ * answers `{ ok: true }` when it exists (a replay of the key counts), `{ ok: false, retry: true }` for a refusal that may pass
+ * (service down, overloaded), `{ ok: false }` for one that never will (the key belongs to another agent): that row is dropped and
+ * `onDrop(row, answer)` told. `cutoff` selects rows independently of `now`, the retry clock (a start-up can ignore old backoff).
+ * One failing row never stops the others; a row is removed only after the run was acknowledged.
+ */
+export declare function drainStarts<P = unknown>(outbox: Outbox<P>, options: {
+    now: number;
+    cutoff?: number;
+    launch: (row: OutboxRow<P>) => Promise<Launched>;
+    only?: {
+        actor: string;
+        key: string;
+    } | null;
+    onDrop?: (row: OutboxRow<P>, answer: Launched) => void;
+}): Promise<{
+    launched: string[];
+    retried: string[];
+    dropped: string[];
+}>;
+export {};
+//# sourceMappingURL=run-outbox.d.ts.map

package/dist/run-outbox.js

@@ -0,0 +1,115 @@
+/**
+ * The outbox of runs an app operation asks for. The operation stages its starts in the SAME transaction as its writes and its
+ * receipt, in the store it touches (the app database and the agent home are two stores: this table is the only glue). After the
+ * commit the host launches each row with its key and removes it once the run is acknowledged; a row left behind (a crash, a
+ * refused call) is launched again later, which the key makes harmless. Runtime-neutral: `SyncSql` is the store's synchronous SQL
+ * (a Durable Object's `sql.exec`, `node:sqlite`); this file opens no transaction and no connection.
+ */
+export const EFFORTS = Object.freeze(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+export const MODEL_ID = /^[A-Za-z0-9@:/._-]{1,120}$/;
+export const START_KEY = /^[\w.:-]{1,100}$/;
+export const AGENT_NAME = /^[a-z][a-z0-9-]{0,40}$/;
+export const OPERATION_NAME = /^[a-z][\w-]*\.[a-z][\w.-]*$/;
+export const MAX_START_INPUT = 100_000;
+export const MAX_STARTS = 20;
+const BACKOFF_FIRST_MS = 1000;
+const BACKOFF_MAX_MS = 5 * 60_000;
+export const OUTBOX_TABLE = 'CREATE TABLE IF NOT EXISTS _host_agent_outbox (actor TEXT NOT NULL, key TEXT NOT NULL, agent TEXT NOT NULL, input TEXT NOT NULL, deliver TEXT, person TEXT NOT NULL, at TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL DEFAULT 0, PRIMARY KEY(actor, key))';
+/** `options` (JSON: { model?, effort? }) came later than the table: a store created before it gets the column here. */
+function ready(run) {
+    run(OUTBOX_TABLE, []);
+    try {
+        run('ALTER TABLE _host_agent_outbox ADD COLUMN options TEXT', []);
+    }
+    catch (error) {
+        if (!/duplicate column/i.test(String(error?.message ?? error)))
+            throw error;
+    }
+}
+/** The runs an operation asked for, checked once more by the host: bounded, well named, and a key never used twice for different runs. Throws a `{ status: 400 }` error. */
+export function checkStarts(starts) {
+    const refuse = (message) => { throw Object.assign(new Error(message), { status: 400 }); };
+    if (!Array.isArray(starts) || starts.length > MAX_STARTS)
+        refuse(`an operation starts at most ${MAX_STARTS} agent runs`);
+    const seen = new Map();
+    return starts.map((s) => {
+        if (typeof s?.key !== 'string' || !START_KEY.test(s.key))
+            refuse("agents.start: key is 1 to 100 letters, digits, '.', ':', '_' or '-'");
+        if (typeof s.agent !== 'string' || !AGENT_NAME.test(s.agent))
+            refuse('agents.start: agent is an agent name');
+        if (s.deliver != null && (typeof s.deliver !== 'string' || !OPERATION_NAME.test(s.deliver)))
+            refuse('agents.start: deliver is an operation name');
+        const input = JSON.stringify(s.input ?? '');
+        if (typeof input !== 'string' || input.length > MAX_START_INPUT)
+            refuse(`agents.start: input must be JSON, at most ${MAX_START_INPUT} characters`);
+        if (s.model != null && (typeof s.model !== 'string' || !MODEL_ID.test(s.model)))
+            refuse('agents.start: model is a model id from the approved catalog');
+        if (s.effort != null && !EFFORTS.includes(s.effort))
+            refuse(`agents.start: effort is one of ${EFFORTS.join(', ')}`);
+        const start = { key: s.key, agent: s.agent, input: input, deliver: s.deliver ?? null, model: s.model ?? null, effort: s.effort ?? null };
+        const before = seen.get(start.key);
+        if (before && (before.agent !== start.agent || before.input !== start.input || before.deliver !== start.deliver || before.model !== start.model || before.effort !== start.effort))
+            refuse(`agents.start: key ${start.key} is used twice with different runs`);
+        seen.set(start.key, start);
+        return start;
+    }).filter((s, i, all) => all.findIndex(o => o.key === s.key) === i);
+}
+/**
+ * Stage rows inside the caller's transaction (its own BEGIN/COMMIT or `transactionSync`: this function never opens one). Keys are
+ * scoped by actor, and the store is already one app's one scope: Alice and Bob may use the same key. A key staged before and not
+ * yet launched keeps its first row.
+ */
+export function stageStarts(run, options) {
+    ready(run);
+    const who = JSON.stringify(options.person);
+    for (const s of checkStarts(options.starts)) {
+        const own = s.model || s.effort ? JSON.stringify({ ...(s.model ? { model: s.model } : {}), ...(s.effort ? { effort: s.effort } : {}) }) : null;
+        run('INSERT OR IGNORE INTO _host_agent_outbox (actor, key, agent, input, deliver, person, at, options) VALUES (?,?,?,?,?,?,?,?)', [options.actor, s.key, s.agent, s.input, s.deliver, who, options.at, own]);
+    }
+}
+const rowOf = ({ options, ...r }) => ({ ...r, input: JSON.parse(r.input), person: JSON.parse(r.person), ...(options ? JSON.parse(options) : {}) });
+/** The outbox of one store (`SyncSql` synchronous): see `Outbox`. */
+export function outboxOver(run) {
+    return {
+        due(now, limit = 20) { ready(run); return run('SELECT * FROM _host_agent_outbox WHERE next_at <= ? ORDER BY at, rowid LIMIT ?', [now, limit]).map(r => rowOf(r)); },
+        pending(actor, key) { ready(run); const r = run('SELECT * FROM _host_agent_outbox WHERE actor = ? AND key = ?', [actor, key])[0]; return r ? rowOf(r) : null; },
+        next() { ready(run); return run('SELECT MIN(next_at) AS at FROM _host_agent_outbox', [])[0]?.at ?? null; },
+        ack(actor, key) { ready(run); run('DELETE FROM _host_agent_outbox WHERE actor = ? AND key = ?', [actor, key]); return null; },
+        retry(row, now) { ready(run); run('UPDATE _host_agent_outbox SET attempts = attempts + 1, next_at = ? WHERE actor = ? AND key = ?', [now + Math.min(BACKOFF_FIRST_MS * 2 ** Math.min(row.attempts, 20), BACKOFF_MAX_MS), row.actor, row.key]); return null; },
+    };
+}
+/**
+ * Launch the rows that are due (or only `only` = { actor, key }, due or not) through `outbox`. `launch(row)` starts the run and
+ * answers `{ ok: true }` when it exists (a replay of the key counts), `{ ok: false, retry: true }` for a refusal that may pass
+ * (service down, overloaded), `{ ok: false }` for one that never will (the key belongs to another agent): that row is dropped and
+ * `onDrop(row, answer)` told. `cutoff` selects rows independently of `now`, the retry clock (a start-up can ignore old backoff).
+ * One failing row never stops the others; a row is removed only after the run was acknowledged.
+ */
+export async function drainStarts(outbox, options) {
+    const { now, cutoff = now, launch, only = null, onDrop = () => { } } = options;
+    const rows = only ? [await outbox.pending(only.actor, only.key)].filter((r) => r !== null) : await outbox.due(cutoff);
+    const out = { launched: [], retried: [], dropped: [] };
+    for (const row of rows) {
+        let r;
+        try {
+            r = await launch(row);
+        }
+        catch (error) {
+            r = { ok: false, retry: true, error: String(error?.message ?? error) };
+        }
+        if (r?.ok) {
+            await outbox.ack(row.actor, row.key);
+            out.launched.push(row.key);
+        }
+        else if (r?.retry) {
+            await outbox.retry(row, now);
+            out.retried.push(row.key);
+        }
+        else {
+            await outbox.ack(row.actor, row.key);
+            out.dropped.push(row.key);
+            onDrop(row, r);
+        }
+    }
+    return out;
+}

package/dist/run-result.d.ts

@@ -0,0 +1,201 @@
+import type { ConversationDocToken, ToolExecutionResult, Tx } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+/**
+ * The result protocol of a one-call run: the agent answers by calling one result tool (or in plain text), the host validates it and
+ * spends a repair budget on a wrong answer, in the run's own conversation. The pure half (`resultState`) and the settle loop are the
+ * same for every home, so they live here once. Pi owns the turns and the transcript; this reads the host's whole transcript and only
+ * submits a native follow-up input to ask for a corrected result.
+ */
+/** A message of the host's transcript as the protocol reads it (the pi-ai message, kept structural). */
+export interface ResultMessage {
+    readonly role: string;
+    readonly content?: unknown;
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly isError?: boolean;
+    readonly details?: unknown;
+}
+export interface ResultCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: unknown;
+}
+/** `result:` of an agent card: the schema of the answer, the host operation that checks it, and how many repairs it may spend. */
+export interface ResultConfig {
+    readonly schema?: JsonObjectSchema;
+    readonly validate?: string;
+    readonly repairs: number;
+}
+export interface JsonObjectSchema {
+    readonly type: 'object';
+    readonly properties?: Readonly<Record<string, unknown>>;
+    readonly [keyword: string]: unknown;
+}
+/** The result tool of a card (`tool.json`). */
+export interface ResultTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly input: JsonObjectSchema;
+}
+/** What the protocol needs of an agent card: its name, the result tool (structured results) and the `result:` settings. */
+export interface ResultCard {
+    readonly name: string;
+    readonly output?: ResultTool;
+    readonly result?: ResultConfig;
+}
+/** The host's call of a result validator (an operation), as the person whose run it is. `key` makes the call once. */
+export type ResultInvoke = (operation: string, input: unknown, key: string) => Promise<unknown>;
+export type ResultValidation = {
+    readonly valid: boolean;
+    readonly hint?: string;
+};
+/** The tool results a run obtained, as a validator sees them. */
+export interface ResultEvidence {
+    readonly name: string;
+    readonly arguments: unknown;
+    readonly results: {
+        readonly content: unknown;
+        readonly isError: boolean;
+    };
+}
+export type RunAnswer = {
+    readonly output: Record<string, unknown>;
+} | {
+    readonly text: string;
+};
+/** Why a run did not produce its result: `end` is the run's end status (`invalid_output`, `interrupted`, `revoked` or `error`). */
+export type ResultFailure = {
+    readonly error: string;
+    readonly end: string;
+};
+export type SettledResult = {
+    readonly result?: RunAnswer;
+    readonly validation?: ResultValidationRecord;
+    readonly error?: undefined;
+    readonly end?: undefined;
+} | ResultFailure;
+/** What delivery re-checks: the card and the evidence the result was accepted on. */
+export interface ResultValidationRecord {
+    readonly card: ResultCard;
+    readonly evidence: readonly ResultEvidence[];
+}
+/**
+ * The per-conversation count of repair attempts that left no result call (a model that answered in text instead of the tool).
+ * Defined without `history` and `fork`, exactly as the homes that ran this protocol before persisted it: pi-durable refuses a token
+ * whose semantics differ from the stored record, so adding them here would break every existing run store.
+ */
+export declare const ResultBudget: ConversationDocToken<{
+    misses: number;
+}>;
+/** Parse `result:` of a card. `legacy` is the card's `tool.json`, whose input is the default schema. Throws a plain Error naming the agent. */
+export declare function resultConfig(value: unknown, legacy: {
+    readonly input?: JsonObjectSchema;
+} | undefined, name: string): ResultConfig;
+export declare const callsOf: (messages: readonly ResultMessage[]) => ResultCall[];
+export interface ResultState {
+    /** The last result call a host tool result accepted, or null. */
+    readonly accepted: Record<string, unknown> | null;
+    readonly error?: string;
+    readonly end?: string;
+    /** Result calls made so far, plus the misses recorded for answers that made none. */
+    readonly attempts: number;
+    /** No attempt left and nothing accepted (or more attempts than the budget allows). */
+    readonly exhausted: boolean;
+}
+/** The state of a run's result from its transcript. Only a host tool result can accept a call; a later rejected call cannot replace an accepted one. */
+export declare function resultState(card: ResultCard, messages: readonly ResultMessage[], misses?: number): ResultState;
+/** The message of a one-call run: the input as JSON, and how to answer. */
+export declare function runMessage(card: Pick<ResultCard, 'output'>, input: unknown): string;
+/** A run's answer: only the last host-accepted result call, else the last markdown reply. */
+export declare function runResult(card: ResultCard, messages: readonly ResultMessage[] | undefined): RunAnswer | null;
+/** The model sees the complete result schema as the tool's parameters (nested items, descriptions, required), like a production tool. */
+export declare function resultParameters(card: Required<Pick<ResultCard, 'output'>>): JsonObjectSchema;
+export declare const resultDescription: (card: Required<Pick<ResultCard, "output">>) => string;
+/** The conversation of a run, as the protocol needs it: a native `Conversation` of a Harness satisfies it. */
+export interface ResultConversation {
+    readonly id: number;
+    commit<T>(fn: (tx: Tx) => Promise<T> | T, context: Context): Promise<T>;
+    submit(draft: {
+        readonly type: 'input';
+        readonly content: string;
+        readonly requestId?: string;
+    }, context: Context): Promise<ResultSubmission>;
+}
+export interface ResultSubmission {
+    wait(context: Context): Promise<{
+        readonly status: string;
+        readonly reason?: string;
+    }>;
+}
+/** Read the host's whole transcript, not a compacted model context or model-provided evidence. */
+export declare function resultMessages(reader: Pick<Tx, 'scanEntries'>, conversationId: number): Promise<ResultMessage[]>;
+/** The tool results a run obtained (every call but the result tool's own), with the arguments that actually executed. */
+export declare function evidenceOf(card: ResultCard, messages: readonly ResultMessage[]): ResultEvidence[];
+/**
+ * Check a result: the schema first (no coercion), then the card's `result.validate` operation, called through `invoke` with the
+ * evidence. `phase` is `attempt` while the agent answers and `delivery` for the check made again just before the run is delivered;
+ * `key` must be fresh for a delivery check. Throws when the validator answers something else than `{ valid, hint? }`.
+ */
+export declare function validateResult(card: ResultCard, output: unknown, evidence: readonly ResultEvidence[], invoke: ResultInvoke, phase: 'attempt' | 'delivery', key: string): Promise<ResultValidation>;
+/** `end` of a run from an error thrown while validating: a refusal by the host's authority is `revoked`, anything else `error`. */
+export declare function validationError(error: unknown): ResultFailure;
+/** Record the arguments that actually executed (after guards and coercion), never ones invented in the final answer. */
+export declare function withEvidence<T extends {
+    execute: (...args: never[]) => Promise<ToolExecutionResult>;
+}>(tool: T): T;
+/**
+ * Settle a one-call run in its own conversation: wait for the answer, read the result, check it, and while it is wrong and the card's
+ * repair budget lasts, ask for a corrected result with a native follow-up input (`repair:<conversation>:<n>`, so a replay finds the
+ * same submission). A result that passes is checked once more with phase `delivery` before it is returned. Not durable by itself:
+ * the caller records the end; a process that dies in the middle ends the run `interrupted`.
+ */
+export declare function settleResult(options: {
+    card: ResultCard;
+    conversation: ResultConversation;
+    submission: ResultSubmission;
+    invoke: ResultInvoke;
+    context: Context;
+    readResult?: (card: ResultCard, messages: readonly ResultMessage[]) => RunAnswer | null;
+}): Promise<SettledResult>;
+/** What the result tool's `execute` is given by the Harness (`api`): the invocation's conversation, call and task, and its transaction. */
+export interface ResultToolApi {
+    readonly conversationId: number;
+    readonly callId: string;
+    readonly taskId: number;
+    commit<T>(fn: (tx: Tx) => Promise<T> | T, context: Context): Promise<T>;
+    snapshot(token: typeof ResultBudget, conversationId: number, context: Context): Promise<{
+        readonly misses: number;
+    } | undefined>;
+}
+/** The `execute` of the result tool: validates the call the model made, spends the repair budget, and ends the turn when the budget is gone. */
+export declare function resultExecutor(card: ResultCard & {
+    readonly output: ResultTool;
+    readonly result: ResultConfig;
+}, invoke: ResultInvoke): (args: unknown, api: ResultToolApi, context: Context) => Promise<{
+    output: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+    details: {
+        resultValidation: ResultFailure;
+    };
+    control: {
+        terminate: true;
+    };
+} | {
+    control?: {
+        terminate: true;
+    };
+    output: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+    details: {
+        resultValidation: {
+            valid: boolean;
+        };
+    };
+}>;
+//# sourceMappingURL=run-result.d.ts.map