agentfootprint/dist/esm/recorders/observability/commentary/artifactPhrases.d.ts

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

/**
 * artifactPhrases — the plain-English vocabulary the artifact / tool-result
 * commentary lines are built from, plus the two size humanizers.
 *
 * Why its own module (and not more branches inside `commentaryTemplates.ts`):
 * these are TRANSLATIONS of library unions (`ArtifactOp`,
 * `ArtifactRefusalReason`, `ArtifactSweepReason`) into words a non-engineer
 * reads. Keeping them here means a new union member is one edit in one place —
 * and the exhaustive `Record<Union, string>` types below make the compiler,
 * not a reviewer, the thing that catches the omission. (`PermissionCapability`
 * taught the repo what two drifting copies of one union cost.)
 *
 * LAW, inherited from the artifact events themselves: META ONLY. These
 * sentences may say how BIG a payload was and what KIND it was; they never
 * carry the payload, a digest, or a raw refusal `detail` string. A ref is an
 * identifier, not prose — it belongs in DETAILS, so no phrase here prints one.
 *
 * Not exported from any barrel: this is prose plumbing for the commentary
 * engine, not public API.
 */
import type { ArtifactOp, ArtifactRefusalReason } from '../../../artifacts/capability.js';
import type { ArtifactSweepReason } from '../../../artifacts/types.js';
import type { ArtifactHandOverFailureCause } from '../../../events/payloads.js';
/**
 * Humanize a byte count for prose. Deliberately a LOCAL copy of the same
 * three-branch rule `bug-report/build.ts#formatBytes` uses: the commentary
 * engine is a leaf that a viewer bundles on its own, and importing a
 * bug-report module (zip building, manifests) to borrow four lines would drag
 * that whole graph in behind a sentence. The shapes are pinned by tests on
 * both sides.
 */
export declare function humanizeBytes(bytes: number): string;
/**
 * Humanize a character count for prose — `tools.result_refused` measures the
 * stringified result in CHARACTERS, not bytes, and saying "bytes" there would
 * be a small lie in the one sentence whose whole job is the true size.
 */
export declare function humanizeChars(chars: number): string;
/** What was being attempted at the door that refused. Exhaustive by type. */
export declare const ARTIFACT_OP_PHRASES: Readonly<Record<ArtifactOp, string>>;
/** Why the door said no, in a sentence a reader can act on. Exhaustive. */
export declare const ARTIFACT_REFUSAL_PHRASES: Readonly<Record<ArtifactRefusalReason, string>>;
/** Why an artifact left the store without its owner asking. Exhaustive. */
export declare const ARTIFACT_SWEEP_PHRASES: Readonly<Record<ArtifactSweepReason, string>>;
/** What went wrong with an app's own filing for a turn (the artifact
 *  hand-over). Exhaustive by type; the reply was delivered in every case. */
export declare const HAND_OVER_FAILURE_PHRASES: Readonly<Record<ArtifactHandOverFailureCause, string>>;
/**
 * Look a phrase up without ever rendering a blank. An event that arrives with
 * a vocabulary this build does not know (an older or newer emitter) still gets
 * an honest sentence: we say we do not know, rather than printing the raw
 * union member into prose or leaving a hole where the reason should be.
 */
export declare function phraseFor(table: Readonly<Record<string, string>>, value: string | undefined, fallback: string): string;