agentfootprint/dist/esm/answer-account/shown.d.ts

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

/**
 * "Show me" — the leaf values behind an account's pointers, allow-listed.
 *
 * The server hands `{ account, shown }` to a reader who may not be an engineer,
 * so what leaves is decided HERE, by one list: a pointer whose event type and
 * path are on `SHOW_ME_ALLOW_LIST` shows its leaf; anything else says
 * `not-shown-here`. The deny list (`DENIED_SEGMENTS`) wins over the allow-list if
 * a future pointer ever names one: injection bodies (skill bodies, app
 * prompts), tool arguments, tool results (only a derived `{ rows, at }` count
 * leaves), a decision's `why` (it can carry a person's note), `resumeInput`,
 * every state key but `turnNumber`, `userMessage`, the tool words of
 * `coverageDeclared` and the routing verdict's leaves (`SHOWN_STATE_PATHS`),
 * history content, and any event of another run.
 *
 * Bounds: a leaf over 2,048 serialized characters is `too-large`; the whole map
 * stops at its share of the op's body, measured in serialized UTF-8 bytes
 * (`size.ts` · `SHOWN_BYTES`, 64 KiB less the body's frame) — no later pointer
 * adds a key; one `#more` entry says the rest is withheld as `too-large`.
 */
import type { AnswerAccount, AnswerAccountDeclarations, AnswerAccountShownLeaf, RecordPointer } from './types.js';
export declare const MAX_LEAF_CHARS = 2048;
/**
 * The map's size, in its own unit — serialized UTF-8 bytes (`size.ts` ·
 * `SHOWN_BYTES`): what the account and the body's frame leave of the op's
 * 192 KiB body. Each entry is measured as JSON writes it (`jsonBytes`), so a
 * leaf of characters JSON writes six bytes wide costs six.
 */
export declare const MAX_SHOWN_BYTES: number;
/**
 * The one key added when the map reaches `MAX_SHOWN_BYTES`: every pointer with
 * no key of its own is then withheld as `too-large`. Never a `pointerKey` (those
 * start with a pointer kind), so it cannot collide with one.
 */
export declare const SHOWN_MORE_KEY = "#more";
/**
 * Event type (without the `agentfootprint.` prefix) → the payload leaves "show me" may show.
 * A call id (`toolCallId`) is an identity the account's facts carry, never content.
 */
export declare const SHOW_ME_ALLOW_LIST: Readonly<Record<string, readonly string[]>>;
/** The two state keys the account reads for a sentence (R3-S2 adds `userMessage`). */
export declare const SHOWN_STATE_KEYS: readonly string[];
/**
 * State keys whose LEAVES "show me" may show, by path shape — the committed
 * `coverageDeclared` rows a call before a pause is read from: the same tool
 * words `tools.absent` / `tools.coverage_declared` show for a call of this leg.
 */
export declare const SHOWN_STATE_PATHS: Readonly<Record<string, readonly string[]>>;
/**
 * Is this pointer's leaf one the allow-list admits (and the deny list does not
 * refuse)? The DENY list is asked FIRST and wins: a future edit that puts a
 * denied leaf on the allow-list still shows nothing (`allowList` is a parameter
 * only so a test can pin exactly that).
 */
export declare function isShowable(p: RecordPointer, allowList?: Readonly<Record<string, readonly string[]>>): boolean;
/** Every pointer the account uses, in first-use order. */
export declare function accountPointers(account: AnswerAccount): RecordPointer[];
/**
 * The leaf map for an account's pointers — one entry per distinct pointer, keyed
 * by `pointerKey`. `recording` is the same recording the account was built from.
 */
export declare function showLeaves(account: AnswerAccount, recording: {
    readonly events?: unknown;
    readonly snapshot?: unknown;
}, declarations?: AnswerAccountDeclarations): Record<string, AnswerAccountShownLeaf>;