agentfootprint/dist/esm/core/runbook/walk.d.ts

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

/**
 * runbook/walk — the recorded walk: projection law, counters, mint.
 *
 * Pattern: pure projection (`projectWalk`) + one guarded side effect
 *          (`mintWalk`, which files the artifact and NEVER fails the answer).
 * Role:    core/runbook. The walk is not a debugging extra — a procedure that
 *          cannot show how it reached a verdict is a procedure somebody has
 *          to take on trust.
 * Emits:   nothing (the artifact capability emits its own `artifacts.*`).
 *
 * THE CAP LAW, and why a head slice is the wrong cap: in a chart walk the
 * per-key reads and writes come FIRST and the decisions come LAST, so a
 * naive head slice over a fleet sweep keeps four hundred writes and drops
 * every decision — a walk with the walking taken out. When the whole thing
 * does not fit, the CONTROL FLOW survives (stages, forks, subflows, and
 * every `condition` entry carrying its decide() evidence) and the projection
 * is DECLARED, so a reader knows which of the two they are holding.
 */
import type { ToolExecutionContext } from '../../tools/tools.js';
import type { WalkDescriptor } from './types.js';
/** The default row cap — a readable artifact, not an archive. The count is
 *  always reported, so a truncated walk says it is truncated instead of
 *  looking like a short run. */
export declare const DEFAULT_WALK_CAP = 500;
/** A narrative entry as this module reads it. `rawValue` is deliberately NOT
 *  in the list: it is a LIVE reference into engine memory and has no business
 *  in a value checked into an artifact store. */
export interface NarrativeEntryView {
    readonly type: string;
    readonly text: string;
    readonly depth: number;
    readonly stageName?: string;
    readonly stageId?: string;
    readonly runtimeStageId?: string;
    readonly subflowId?: string;
}
/** One walk row — plain data by construction (every field projected). */
export interface WalkRow {
    readonly step: number;
    readonly type: string;
    readonly depth: number;
    readonly stage: string | null;
    readonly stage_id: string | null;
    readonly runtime_stage_id: string | null;
    readonly subflow: string | null;
    readonly text: string;
}
/** The pure projection result — rows plus truthful counters. */
export interface ProjectedWalk {
    readonly rows: readonly WalkRow[];
    readonly projection: 'full' | 'control-flow';
    readonly shown: number;
    readonly total: number;
    readonly complete: boolean;
}
/** Apply the cap law. Counters are about the WHOLE narrative (`total`), so a
 *  projected walk cannot read as a short run. */
export declare function projectWalk(entries: readonly NarrativeEntryView[], cap: number): ProjectedWalk;
/** What the mint needs from the call. */
export interface WalkMintFacts {
    readonly toolName: string;
    readonly toolCallId: string;
    readonly runId?: string;
    readonly stepsExecuted: number;
}
/**
 * File the walk and build the descriptor. THE SPINE ALWAYS GETS A
 * DESCRIPTOR: with no store attached, or when the mint fails, the counters
 * still travel and the note names why there is no ticket — a failed mint
 * costs the TICKET, never the answer and never the counts.
 */
export declare function mintWalk(ctx: ToolExecutionContext, projected: ProjectedWalk, facts: WalkMintFacts): Promise<WalkDescriptor>;