agentfootprint/dist/types/trace-toolpack/bounded.d.ts

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

/**
 * Bounded serialization helpers for the trace toolpack.
 *
 * Pattern: pure functions — no state, no events.
 * Role:    The token-economics layer. EVERY value the toolpack serves goes
 *          through these: previews are capped, truncation is EXPLICIT
 *          (never silent), and nested-path keys round-trip between the
 *          engine's DELIM encoding and LLM-friendly dot notation.
 */
/**
 * footprintjs's canonical nested-path delimiter (ASCII unit separator,
 * `src/lib/memory/utils.ts`). Internal to the engine — the toolpack
 * translates it to/from dot notation so the LLM never sees a control char.
 */
export declare const FP_PATH_DELIM = "\u001F";
/** Engine path → LLM-friendly dotted display form. */
export declare function displayKey(path: string): string;
/**
 * LLM-supplied key → engine path. Exact keys pass through; a dotted key
 * that doesn't exist verbatim but matches a known DELIM-joined path is
 * translated back. `knownPaths` is the set of every path seen in the
 * commit log's trace entries.
 */
export declare function normalizeKey(key: string, knownPaths: ReadonlySet<string>): string;
/** Replace every DELIM in an already-formatted text block with '.' for display. */
export declare function displayText(text: string): string;
/**
 * Serialize a value to compact JSON, total-function style: cycles, BigInt
 * and other non-JSON values degrade to a tagged placeholder instead of
 * throwing — a debugger tool must never crash on the evidence it serves.
 */
export declare function safeStringify(value: unknown): string;
/** A bounded preview of a value: capped text + the TRUE total size, never silent. */
export interface BoundedPreview {
    /** The (possibly truncated) serialized text. */
    readonly text: string;
    /** Full serialized length in chars — so the consumer knows what it's NOT seeing. */
    readonly totalChars: number;
    /** True when `text` is shorter than the full serialization. */
    readonly truncated: boolean;
}
/** Serialize + cap at `maxChars`. Truncation is reported, never silent. */
export declare function boundedPreview(value: unknown, maxChars: number): BoundedPreview;
/** Render a preview with its honesty suffix when truncated. */
export declare function renderPreview(preview: BoundedPreview, fetchHint?: string): string;
/** Clamp an LLM-supplied numeric param into [min, hardCap], with a default. */
export declare function clampParam(requested: number | undefined, fallback: number, min: number, hardCap: number): number;
//# sourceMappingURL=bounded.d.ts.map