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

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

/**
 * Trace toolpack types — RFC-003 Part C (the introspection toolpack).
 *
 * Pattern: artifact bag — everything a debugging LLM needs to navigate a
 *          COMPLETED run, captured once and handed to `traceToolpack()`.
 * Role:    Input contract. The toolpack never re-runs anything; it serves
 *          bounded, id-addressed views over these frozen artifacts.
 */
import type { RuntimeSnapshot } from 'footprintjs';
import type { ControlDepLookup } from 'foottrace';
import type { AgentfootprintEvent } from '../events/registry.js';
import type { InnerRunLookup } from '../core/innerRunRecords.js';
import type { TraceCauseArtifacts, TraceCauseOptions } from './causeTypes.js';
/**
 * The frozen evidence of one completed run.
 *
 * - `snapshot` — `executor.getSnapshot()`. Carries the commit log (what every
 *   step wrote, with verbs + redaction + `untrackedSources` honesty markers),
 *   the execution tree (per-step name/description/reads/errors), the final
 *   shared state, and the `commitValues` mode discriminant.
 * - `controlDeps` — OPTIONAL `controlDepRecorder().asLookup()` from the run.
 *   With it, causal slices include `[control: <rule label>]` edges to the
 *   decider that routed execution. Without it, slices say so explicitly.
 * - `narrative` — OPTIONAL narrative lines (e.g. rendered from
 *   `executor.getNarrativeEntries()`). When present, a `read_narrative` tool
 *   is added for bounded, paginated access to the human-readable story.
 * - `events` — OPTIONAL tail of the run's typed agentfootprint events. The
 *   commit log records what each step WROTE; it has no clock and no notion
 *   of a tool call as a thing with a duration. `inspect_tool_call` reads
 *   timings and outcomes from here, and says ⚠ when the tail is absent
 *   rather than inventing them. It is ALSO the only home of the Context
 *   Integrity channel (`agentfootprint.integrity.context_error` and the
 *   per-run `…disposition` accounting) — what `find_context_errors` reads,
 *   and what it reports as ABSENT rather than green when the tail is gone.
 * - `innerRuns` — OPTIONAL lookup of the records TOOLS kept of their own
 *   runs, keyed by `toolCallId`. Present when the agent mounts a
 *   `flowchartAsTool({ keepRecord: true })`. With it, `inspect_tool_run`
 *   descends THROUGH the tool boundary into the chart that ran; without it,
 *   that tool names the switch instead of answering emptily.
 */
export interface TraceToolpackArtifacts {
    readonly snapshot: RuntimeSnapshot;
    /** Optional host-authorized graph for this bag; no storage locations or caller scopes come from model arguments. */
    readonly cause?: TraceCauseArtifacts;
    readonly controlDeps?: ControlDepLookup;
    readonly narrative?: readonly string[];
    readonly events?: readonly AgentfootprintEvent[];
    readonly innerRuns?: InnerRunLookup;
}
/**
 * Bounding dials. Every output is bounded BY DEFAULT — these set the
 * defaults; per-call params (`maxDepth`, `maxNodes`, `maxChars`, `maxLines`)
 * let the LLM ask for more up to hard caps the consumer cannot exceed.
 * Cause tools are the exception: their resource controls are host-only ceilings.
 */
export interface TraceToolpackOptions {
    /** Host-only cause-tool ceilings, never overridable by model arguments. Snapshot-only capture cannot prove a root without engine attestation. */
    readonly cause?: TraceCauseOptions;
    /** Value-preview length in chars (trace_node / who_wrote). Default 160. */
    readonly previewChars?: number;
    /** Default causal-slice depth for trace_slice. Default 6 (hard cap 20). */
    readonly sliceMaxDepth?: number;
    /** Default causal-slice node budget for trace_slice. Default 25 (hard cap 100). */
    readonly sliceMaxNodes?: number;
    /** Default char budget for get_value. Default 2000 (hard cap 8000). */
    readonly valueMaxChars?: number;
}
/** Resolved options with defaults applied (internal). */
export interface ResolvedToolpackOptions {
    readonly previewChars: number;
    readonly sliceMaxDepth: number;
    readonly sliceMaxNodes: number;
    readonly valueMaxChars: number;
}
/** Hard caps — per-call params clamp to these regardless of what the LLM asks for. */
export declare const TOOLPACK_HARD_CAPS: {
    readonly sliceMaxDepth: 20;
    readonly sliceMaxNodes: 100;
    readonly valueMaxChars: 8000;
    readonly narrativeMaxLines: 200;
    /** `find_in_trace` hits per call — a search is a pointer list, not a dump. */
    readonly findMaxHits: 25;
    /**
     * `find_context_errors` findings per call. Findings are deduplicated at
     * filing time, so a run rarely has many — and a run that does has a
     * systemic problem the first page already shows.
     */
    readonly contextErrorsMax: 25;
};
export declare function resolveToolpackOptions(options?: TraceToolpackOptions): ResolvedToolpackOptions;
//# sourceMappingURL=types.d.ts.map