agentfootprint/dist/esm/answer-validation/toolLedger.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * The run's tool calls, as a bounded read-only parcel for an authored check.
 *
 * Names, call ids and outcomes only. Arguments and results never enter it:
 * both are redaction-sensitive, and a rule about WHICH tools ran needs
 * neither. The ledger is tracked state of the run that owns the check, so it
 * cannot hold another run's calls; it is written only on an agent with
 * `answerValidation`, so every other agent commits the keys it always did.
 */
import type { AnswerToolCall, AnswerToolCallsView } from './types.js';
/** Longest tool name or call id listed. A model can send any name and a
 *  provider any id; a longer one is left out and the view marked incomplete. */
export declare const MAX_TOOL_CALL_TEXT = 256;
/**
 * The ledger as the run's state holds it: the view's fields plus the ids of
 * calls whose `stream.tool_start` bracket opened and whose `tool_end` has not
 * yet closed. A call still open at the check makes the view incomplete.
 */
export interface ToolCallLedger extends AnswerToolCallsView {
    readonly inFlight?: readonly string[];
}
/** A ledger that may have missed calls: what ran before this run observed it. */
export declare function incompleteToolCalls(): ToolCallLedger;
/**
 * The ledger after a call's `tool_start` bracket: the call is open until its
 * `tool_end` lands. Past `max` open calls, or for an oversized id, the ledger
 * cannot track it and says it is incomplete instead.
 */
export declare function startToolCall(prior: ToolCallLedger | undefined, callId: string, max: number): ToolCallLedger;
/**
 * The ledger after one call's `tool_end` bracket: the call is closed and
 * listed. Past `max` calls (or for an oversized name or id) nothing more is
 * listed and the ledger says it is incomplete, so a rule that counts can tell
 * "none ran" from "not listed". A call whose own work has not settled (a tool
 * that declared `pending`) makes it incomplete too. Returns `prior` itself
 * when nothing changes, so the caller can skip the write.
 */
export declare function appendToolCall(prior: ToolCallLedger | undefined, call: AnswerToolCall, max: number, settled?: boolean): ToolCallLedger;
/**
 * The ledger as one check sees it, read at the moment of the check: incomplete
 * when there is none, when a call is still open, or when the model's last
 * reply asked for calls that never went out (`undispatched` — the check runs
 * on the terminal branch, so a call on that reply was never dispatched: a run
 * cut off by its iteration or cost budget with calls still pending).
 */
export declare function ledgerAtCheck(ledger: ToolCallLedger | undefined, undispatched: number): AnswerToolCallsView;
/**
 * The parcel one validation receives: detached from the run's state and frozen
 * at every level, so a check can neither edit the ledger nor reach live state
 * through it. Anything that is not the declared shape is dropped, never passed on.
 */
export declare function toolCallsView(ledger: AnswerToolCallsView | undefined, max: number): AnswerToolCallsView;
/**
 * The outcome of one `stream.tool_end` bracket, in the view's words. `ran` is
 * whether the tool's own code ran: a call that did not run and carries no
 * `error` (a person declined it, a rule refused it, a paused batch settled it)
 * is `not-run`, never `ok`. A tool that ran but declared `failure`, `denied` or
 * `invalid` (a refused oversize result among them) is `error`.
 */
export declare function toolOutcomeOf(bracket: {
    readonly error?: boolean;
    readonly notExecuted?: boolean;
    readonly notDispatched?: unknown;
    readonly status?: string;
}, ran: boolean): AnswerToolCall['outcome'];