agentfootprint/dist/esm/recorders/observability/StatusRecorder.d.ts

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

/**
 * StatusRecorder — Claude Code-style live status line for Agent runs.
 *
 * Pattern: Facade over EventDispatcher's wildcard subscription.
 * Role:    Tier 3 observability — the low-level helper behind
 *          `attachStatus(dispatcher, { onStatus })` (exported from
 *          `agentfootprint/observe`). For the high-level, uniform path use
 *          `agent.enable.liveStatus({ strategy: chatBubbleLiveStatus({ onLine }) })`.
 *          One callback receives a human-readable status string at every
 *          meaningful moment.
 * Emits:   Does NOT emit; READS core events via the dispatcher and calls
 *          `onStatus`.
 */
import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
import type { AgentfootprintEventMap } from '../../events/registry.js';
export interface StatusOptions {
    /**
     * Called with a human-readable status string at each meaningful moment
     * (iteration start, tool start/end, route decision, turn end).
     */
    readonly onStatus: (status: string) => void;
    /**
     * Custom formatter. Return `null` to skip an event; return a string
     * to emit that status. Omit for the built-in renderer.
     */
    readonly format?: (event: StatusEvent) => string | null;
}
/**
 * Subset of events the thinking renderer formats. Discriminated on `type`.
 */
export type StatusEvent = AgentfootprintEventMap['agentfootprint.agent.turn_start'] | AgentfootprintEventMap['agentfootprint.agent.turn_end'] | AgentfootprintEventMap['agentfootprint.agent.iteration_start'] | AgentfootprintEventMap['agentfootprint.agent.route_decided'] | AgentfootprintEventMap['agentfootprint.stream.tool_start'] | AgentfootprintEventMap['agentfootprint.stream.tool_progress'] | AgentfootprintEventMap['agentfootprint.stream.tool_end'];
/**
 * Attach a thinking-status subscription to the event dispatcher.
 * Returns an Unsubscribe — call to detach.
 *
 * Holds one small piece of state: how many mid-call reports each in-flight
 * tool call has filed (9.54.0), so the generic progress line can say "3 so
 * far" instead of repeating one indistinguishable sentence. The tally is
 * per-`toolCallId` — parallel calls count separately — and is dropped when
 * that call ends, so nothing accumulates across a long-lived run.
 */
export declare function attachStatus(dispatcher: EventDispatcher, options: StatusOptions): Unsubscribe;