agentfootprint 6.43.0 → 6.45.0

package/dist/esm/conventions.d.ts

@@ -0,0 +1,203 @@
+/**
+ * conventions — subflow + stage ID constants (builder↔recorder protocol).
+ *
+ * Pattern: Single Source of Truth constants (Ward Cunningham's SSOT).
+ * Role:    Contract between `core/` builders and `recorders/core/` observers.
+ *          Builders mount subflows with these IDs; recorders pattern-match
+ *          on the IDs to emit grouped domain events.
+ * Emits:   N/A (constants only).
+ *
+ * Rename any ID here → both builders and recorders stay in sync.
+ */
+import type { ContextSlot } from './events/types.js';
+/** Subflow IDs — mounted by builders, observed by recorders. */
+export declare const SUBFLOW_IDS: {
+    /** Injection Engine subflow. Evaluates every Injection's trigger
+     *  and writes activeInjections[] for the slot subflows to consume. */
+    readonly INJECTION_ENGINE: "sf-injection-engine";
+    /** Inner subflow inside LLMCall that wraps the invocation
+     *  (seed + slots + call-llm + optional thinking + extract-final).
+     *  Mounted by LLMCall's outer `client` chart. */
+    readonly LLM_CALL: "sf-llm-call";
+    /** System-prompt slot subflow. Observed by ContextRecorder. */
+    readonly SYSTEM_PROMPT: "sf-system-prompt";
+    /** Messages slot subflow. */
+    readonly MESSAGES: "sf-messages";
+    /** Tools slot subflow. */
+    readonly TOOLS: "sf-tools";
+    /** ReAct router subflow (inside Agent). */
+    readonly ROUTE: "sf-route";
+    /** Tool-call execution subflow (inside Agent loop). */
+    readonly TOOL_CALLS: "sf-tool-calls";
+    /** Merge step inside Parallel. */
+    readonly MERGE: "sf-merge";
+    /** Final-answer composition inside Agent. Mounted via
+     *  `addSubFlowChartBranch('final', ...)` so the subflow id is the
+     *  Route decider's branch key — `'final'`, no `sf-` prefix. The
+     *  decider returns `'final'` as a routing value AND the same string
+     *  becomes the subflow's id. */
+    readonly FINAL: "final";
+    /** Cache subflow (v2.14). Wraps the whole per-turn cache machinery —
+     *  decide markers → CacheGate decider → apply/skip — as ONE collapsible
+     *  boundary in the chart. Provider-independent decision layer; the
+     *  attached provider's CacheStrategy turns markers into wire format.
+     *  UpdateSkillHistory stays OUTSIDE (in the main loop) so the rolling
+     *  skillHistory window persists across iterations without round-tripping
+     *  through this subflow. */
+    readonly CACHE: "sf-cache";
+    /** Cache decision subflow (v2.6). Walks activeInjections, emits
+     *  agnostic CacheMarker[]. Provider-independent. Standalone building
+     *  block; the agent now uses the `decideCacheMarkers` stage inside
+     *  `sf-cache` instead of mounting this directly. */
+    readonly CACHE_DECISION: "sf-cache-decision";
+    /** Thinking-normalization mount (v2.14). Wraps the consumer's
+     *  ThinkingHandler.normalize() in a real footprintjs subflow so it
+     *  has its own runtimeStageId for tracing. The result lands on the
+     *  parent LLMCall's `thinkingBlocks` payload, so this subflow is
+     *  pure plumbing from the agent step's POV — never a user-facing
+     *  step in the StepGraph. */
+    readonly THINKING: "sf-thinking";
+};
+export type SubflowId = (typeof SUBFLOW_IDS)[keyof typeof SUBFLOW_IDS];
+/** Stage IDs — plain function stages that builders mount. */
+export declare const STAGE_IDS: {
+    readonly SEED: "seed";
+    /** Relevance entry router (`entryByRelevance`). A once-per-turn function stage
+     *  mounted between Initialize and InjectionEngine (off the ReAct loop) that
+     *  picks the starting skill by embedding similarity → sets `currentSkillId`. */
+    readonly PICK_ENTRY: "pick-entry";
+    /** Context-assembly selector stage. Runs AFTER InjectionEngine and
+     *  fans the 3 slot subflows (system-prompt / messages / tools) out in
+     *  PARALLEL (selector picks all 3 every iteration; failFast so a
+     *  required slot's throw aborts the turn). They converge before
+     *  CacheDecision. Shared by buildAgentChart + buildDynamicAgentChart;
+     *  the flat viz proof chart uses the same id as its root selector. */
+    readonly CONTEXT: "context";
+    /** Outer "client" stage in LLMCall's wrapped chart. Receives args on
+     *  the first visit, $break()s on the second (post-loop) visit with
+     *  the LLM answer as TraversalResult. This is the lens-friendly
+     *  affordance — the User pill maps to this stage. */
+    readonly CLIENT: "client";
+    readonly CALL_LLM: "call-llm";
+    /** Final-response extraction stage that runs after CallLLM (and
+     *  optional sf-thinking). For LLMCall this is mostly symmetric with
+     *  Agent's `sf-final` branch — gives lens a "Final" node and a
+     *  clear commit boundary marking "we have the answer." */
+    readonly EXTRACT_FINAL: "extract-final";
+    readonly FINAL: "final";
+    readonly FORMAT_MERGE: "format-merge";
+    readonly MERGE_LLM: "merge-llm";
+    readonly EXTRACT_MERGE: "extract-merge";
+    /** Updates the rolling skill-history window before CacheGate
+     *  evaluates skill-churn (v2.6). */
+    readonly UPDATE_SKILL_HISTORY: "update-skill-history";
+    /** CacheGate decider stage — routes to apply-markers / no-markers
+     *  based on kill switch / hit rate / skill churn (v2.6). */
+    readonly CACHE_GATE: "cache-gate";
+    /** CacheGate branch (routing key) when markers SHOULD be applied
+     *  this iteration. Pass-through stage; markers stay in scope. (v2.6) */
+    readonly APPLY_MARKERS: "apply-markers";
+    /** CacheGate branch (routing key) when markers should be SKIPPED
+     *  this iteration. Stage clears scope.cacheMarkers. (v2.6) */
+    readonly SKIP_CACHING: "no-markers";
+    /** BuildLLMRequest stage — calls strategy.prepareRequest to apply
+     *  markers to the wire request (v2.6). */
+    readonly BUILD_LLM_REQUEST: "build-llm-request";
+};
+export type StageId = (typeof STAGE_IDS)[keyof typeof STAGE_IDS];
+/** True when a subflow id corresponds to one of the 3 context slots. */
+export declare function isSlotSubflow(id: string): id is typeof SUBFLOW_IDS.SYSTEM_PROMPT | typeof SUBFLOW_IDS.MESSAGES | typeof SUBFLOW_IDS.TOOLS;
+/** Map a slot subflow id to its ContextSlot type. Undefined for non-slot ids. */
+export declare function slotFromSubflowId(id: string): ContextSlot | undefined;
+/**
+ * Resolve the context slot a scope write belongs to FROM THE WRITE'S OWN
+ * `runtimeStageId` — not from a "currently-open slot" stack.
+ *
+ * Why: once the 3 slot subflows run in PARALLEL (selector fan-out), their
+ * entry/write/exit events INTERLEAVE — a stack top is unreliable, so a write
+ * inside `sf-messages` could be attributed to (or dropped against)
+ * `sf-tools`. The write's `runtimeStageId` (`[subflowPath/]stageId#index`)
+ * always encodes which slot subflow enclosed it; we scan the path segments
+ * innermost-first for a slot id. Matches the sequential result exactly
+ * (the write is still inside its own slot), so it is behavior-preserving.
+ */
+export declare function slotFromRuntimeStageId(runtimeStageId: string): ContextSlot | undefined;
+/** True when an id is any of the library's known subflow IDs. */
+export declare function isKnownSubflow(id: string): id is SubflowId;
+/** True when an id is any of the library's known stage IDs. */
+export declare function isKnownStage(id: string): id is StageId;
+/**
+ * Semantic role of a stage, used by renderers to decide visual emphasis.
+ *
+ * The agent's chart mixes a handful of stages users actually care about
+ * (the HEROES — what context was built, what the model decided, what it did)
+ * with mechanism stages (PLUMBING). This is the ONE place that says which is
+ * which; renderers stay generic and style purely off this role (e.g. heroes
+ * prominent, plumbing muted). Keeping it here — the semantic owner — avoids
+ * the "name-based filter list duplicated across renderers" anti-pattern.
+ *
+ * - `hero-slot`   — a context slot (system-prompt / messages / tools)
+ * - `hero-llm`    — the LLM invocation
+ * - `hero-action` — tool execution (the agent's actions)
+ * - `plumbing`    — mechanism (injection engine, cache, route, thinking, …)
+ * - `boundary`    — neutral chart boundaries (Initialize root, Final) +
+ *                   anything unrecognised (rendered normally, never muted)
+ */
+export type StageRole = 'hero-slot' | 'hero-llm' | 'hero-action' | 'plumbing' | 'boundary';
+/**
+ * Classify a stage id into its {@link StageRole}. Accepts a path-qualified id
+ * (`sf-llm-call/call-llm`) — only the LOCAL segment matters, so it works at
+ * any nesting depth. Built entirely from the id constants above, so adding a
+ * stage to the chart only requires listing it here.
+ */
+export declare function stageRole(id: string): StageRole;
+/**
+ * A {@link Milestone}'s kind — the domain vocabulary for "meaningful step you'd
+ * scrub to" in the agent's run.
+ */
+export type MilestoneKind = 'iteration' | 'slot' | 'llm-turn' | 'tool-call' | 'decision';
+/**
+ * A time-travel milestone: a domain-declared scrub stop. Conceptually each
+ * milestone marks the boundary of a COLLECTION of commits (the commits that
+ * belong to that step) — so the Lens slider can step stage-by-stage
+ * (iteration → llm-turn → tool-call → …) instead of stopping only on
+ * structural subflow boundaries. The renderer iterates whatever the domain
+ * classifies; it never hardcodes agent vocabulary.
+ */
+export interface Milestone {
+    readonly kind: MilestoneKind;
+    /** Human-readable base label ("LLM turn"); the renderer may add an ordinal. */
+    readonly label: string;
+}
+/**
+ * Classify a stage id into a {@link Milestone}, or `null` when the stage is NOT
+ * a milestone boundary (its commits fold into the surrounding milestone's
+ * collection). This is the DOMAIN's declaration of which steps are scrub-worthy;
+ * the Lens consumes it to build the time-travel slider (see
+ * agentfootprint-lens `cursorPositionsAtDrill`).
+ *
+ * Mirrors {@link stageRole}: accepts a runtimeStageId (`call-llm#17`), a
+ * path-qualified id (`sf-llm-call/call-llm`), or a bare local id — only the
+ * LOCAL stage segment matters, so it works at any nesting depth and for both
+ * commit ids and subflow-group ids.
+ */
+export declare function milestoneFor(id: string): Milestone | null;
+/**
+ * Scope-key convention for context injections.
+ *
+ * Each slot subflow writes its injections to a well-known scope key.
+ * ContextRecorder observes writes to these keys to emit context.injected
+ * events. Builders that mount slot subflows MUST write injections to the
+ * corresponding key; this is the data-level contract between builder and
+ * recorder.
+ */
+export declare const INJECTION_KEYS: {
+    readonly SYSTEM_PROMPT: "systemPromptInjections";
+    readonly MESSAGES: "messagesInjections";
+    readonly TOOLS: "toolsInjections";
+};
+export type InjectionKey = (typeof INJECTION_KEYS)[keyof typeof INJECTION_KEYS];
+/** Map a slot to its injection scope key. */
+export declare function injectionKeyForSlot(slot: 'system-prompt' | 'messages' | 'tools'): InjectionKey;
+/** True when a scope key is any of the known injection keys. */
+export declare function isInjectionKey(key: string): key is InjectionKey;

package/dist/esm/core/Agent.d.ts

@@ -0,0 +1,355 @@
+/**
+ * Agent — ReAct primitive (LLM + tools + iteration loop).
+ *
+ * Pattern: Builder (GoF) → produces a Runner backed by a footprintjs FlowChart.
+ * Role:    Layer-5 primitive (core/). Assembles the 3-slot context
+ *          pipeline + callLLM + route decider + tool-calls subflow +
+ *          loopTo. Composition nestable anywhere that accepts a Runner.
+ * Emits:   Via internal recorders:
+ *            agentfootprint.agent.turn_start / turn_end
+ *            agentfootprint.agent.iteration_start / iteration_end
+ *            agentfootprint.agent.route_decided
+ *            agentfootprint.stream.llm_start / llm_end
+ *            agentfootprint.stream.tool_start / tool_end
+ *            agentfootprint.context.* (via ContextRecorder)
+ */
+import { type CombinedNarrativeEntry, type FlowchartCheckpoint, type ObserverDrainResult, type RunOptions, type RuntimeSnapshot } from 'footprintjs';
+import type { CachePolicy, CacheStrategy } from '../cache/types.js';
+import type { ReliabilityConfig } from '../reliability/types.js';
+import { type RunnerPauseOutcome } from './pause.js';
+import type { MemoryDefinition } from '../memory/define.types.js';
+import type { Injection, InjectionContext } from '../lib/injection-engine/types.js';
+import type { EntryScoring } from '../lib/injection-engine/skillGraph.js';
+import { type ResolvedOutputFallback } from './outputFallback.js';
+import { type AgentRunCheckpoint } from './runCheckpoint.js';
+import { type OutputSchemaParser } from './outputSchema.js';
+import { RunnerBase } from './RunnerBase.js';
+import type { ToolRegistryEntry } from './tools.js';
+import type { ToolProvider } from '../tool-providers/types.js';
+import type { AgentInput, AgentOptions, AgentOutput, ObserverDeliveryOptions } from './agent/types.js';
+import { AgentBuilder } from './agent/AgentBuilder.js';
+import type { ThinkingHandler } from '../thinking/types.js';
+export { AgentBuilder };
+export type { AgentInput, AgentOptions, AgentOutput, ObserverDeliveryOptions };
+export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly provider;
+    private readonly model;
+    private readonly temperature?;
+    private readonly maxTokens?;
+    private readonly maxIterations;
+    private readonly systemPromptValue;
+    /**
+     * Cache policy for the base system prompt (set via
+     * `.system(text, { cache })`). Default `'always'` — base prompt is
+     * stable per-turn, ideal cache anchor. CacheDecision subflow reads
+     * this when computing the SystemPrompt slot's cache markers.
+     */
+    private readonly systemPromptCachePolicy;
+    /**
+     * Global cache kill switch from `Agent.create({ caching: 'off' })`.
+     * Threaded into agent scope at seed-time as `scope.cachingDisabled`;
+     * read by the CacheGate decider every iteration (highest-priority rule).
+     */
+    private readonly cachingDisabledValue;
+    /**
+     * Provider-specific CacheStrategy. Auto-resolved from
+     * `getDefaultCacheStrategy(provider.name)` at agent build time
+     * unless the consumer explicitly passes one via builder option.
+     * Phase 7+ implementations (Anthropic, OpenAI, Bedrock) register
+     * themselves in the strategyRegistry on import.
+     */
+    private readonly cacheStrategy;
+    private readonly registry;
+    /**
+     * The Injection list — Skills, Steering, Instructions, Facts (and
+     * RAG, Memory). Evaluated each iteration by the
+     * InjectionEngine subflow; active set is filtered by slot subflows.
+     */
+    private readonly injections;
+    /** Skill-graph cursor resolver (`graph.nextSkill`), set when built via
+     *  `.skillGraph(graph)`. Plumbed into the Injection Engine so route triggers
+     *  are `from`-gated against the persisted `currentSkillId`. */
+    private readonly skillGraphNextSkill?;
+    /** Skill-graph reachable-set resolver (`graph.reachableSkills`), set when built
+     *  via `.skillGraph(graph)`. Plumbed into the tool-calls handler so `read_skill`
+     *  is gated to in-graph jumps. Undefined → gate off. */
+    private readonly skillGraphReachable?;
+    /** Skill-graph relevance entry scorer (`graph.scoreEntries`), set when built via
+     *  `.skillGraph(graph)` with `.entryByRelevance()`. Drives the PickEntry stage.
+     *  Undefined → no relevance entry routing (cold-start entry as before). */
+    private readonly skillGraphScoreEntries?;
+    private readonly pricingTable?;
+    private readonly costBudget?;
+    private readonly permissionChecker?;
+    private readonly toolArgValidation?;
+    /** Snapshot read-tracking policy (#18/#14) — forwarded to the internal
+     *  executor. Agent default is `'summary'` (cheap markers), NOT
+     *  footprintjs's `'full'`. See AgentOptions.readTracking. */
+    private readonly readTracking;
+    /** Commit-log value encoding (#13c-B) — forwarded to the internal
+     *  executor. Agent default is `'delta'` (append/delete verbs; growing
+     *  arrays like `history` record only their tails — lossless, linear
+     *  retained memory), NOT footprintjs's `'full'`. See
+     *  AgentOptions.commitValues. */
+    private readonly commitValues;
+    private readonly credentialProvider?;
+    /** Evidence bridge (#5) — present iff a CAUSAL memory is mounted. */
+    private readonly causalEvidence?;
+    /** Observer delivery tier (RFC-001 Block 10). `'inline'` (default) is
+     *  byte-identical to pre-10 releases; `'deferred'` routes the bridge
+     *  recorders + consumer attachments through footprintjs's bounded
+     *  capture queue. See AgentOptions.observerDelivery. */
+    private readonly observerDelivery;
+    /** Queue dials forwarded on every deferred attach (first attach
+     *  configures the executor's single dispatcher). */
+    private readonly observerDeliveryOptions?;
+    /**
+     * Voice config — shared by viewers (Lens, ChatThinkKit, CLI tail).
+     * `appName` is the active actor in narration ("Chatbot called…").
+     * `commentaryTemplates` drives Lens's third-person panel.
+     * `thinkingTemplates` drives chat-bubble first-person status.
+     * Defaults to bundled English; consumer overrides via builder.
+     */
+    readonly appName: string;
+    readonly commentaryTemplates: Readonly<Record<string, string>>;
+    readonly thinkingTemplates: Readonly<Record<string, string>>;
+    private currentRunContext;
+    /**
+     * Memory subsystems registered via `.memory()`. Each definition mounts
+     * its `read` subflow before the InjectionEngine on every turn; per-id
+     * scope keys (`memoryInjectionKey(id)`) keep multi-memory layering
+     * collision-free.
+     */
+    private readonly memories;
+    /**
+     * Optional terminal contract. Set via the builder's `.outputSchema()`.
+     * When present, `agent.runTyped()` parses + validates the final
+     * answer against this parser. `agent.run()` keeps returning the
+     * raw string; consumers opt into typed mode explicitly.
+     */
+    private readonly outputSchemaParser?;
+    /**
+     * Optional 3-tier degradation for output-schema validation
+     * failures. Set via the builder's `.outputFallback({...})`. When
+     * present, `parseOutput()` and `runTyped()` fall through:
+     *   primary → fallback → canned (in order; canned guarantees no-throw).
+     */
+    private readonly outputFallbackCfg?;
+    /** Side-channel for `resumeOnError(...)` — when set, the seed
+     *  function restores `scope.history` from this instead of starting
+     *  fresh. Cleared on first read so subsequent runs start clean. */
+    private pendingResumeHistory?;
+    /**
+     * Optional `ToolProvider` set via the builder's `.toolProvider()`.
+     * When present, the Tools slot subflow consults it per iteration
+     * (Block A5 follow-up) — the provider's tools land alongside any
+     * tools registered statically via `.tool()` / `.tools()`. The
+     * tool-call dispatcher also consults it for per-iteration execute
+     * lookup so dynamic chains (`gatedTools`, `skillScopedTools`)
+     * dispatch correctly when their visible-set changes mid-turn.
+     */
+    private readonly externalToolProvider?;
+    /**
+     * Optional rules-based reliability config (v2.11.5+). Set via the
+     * builder's `.reliability({...})`. When present, every CallLLM
+     * execution is wrapped in a retry/fallback/fail-fast loop driven
+     * by `preCheck` and `postDecide` rules. Consumed by `buildCallLLMStage`.
+     */
+    private readonly reliabilityConfig?;
+    /**
+     * Resolved ThinkingHandler (v2.14+). Auto-wired by `provider.name`
+     * via `findThinkingHandler` UNLESS the builder explicitly set one
+     * (or `null` to opt out). When undefined, the NormalizeThinking
+     * sub-subflow is NOT mounted at chart build time — zero overhead
+     * for non-thinking agents.
+     */
+    private readonly thinkingHandler?;
+    /**
+     * v2.14+ — request-side thinking budget. When set, every LLMRequest
+     * carries `thinking: { budget }`. AnthropicProvider translates to the
+     * wire format. Undefined = no thinking activation (default behavior).
+     */
+    private readonly thinkingBudget?;
+    /** Threaded to footprintjs `flowChart()` so every node the Agent
+     *  builder creates is observed by these recorders at build time. Set
+     *  from `opts.structureRecorders`; undefined when consumer didn't
+     *  attach any. */
+    private readonly structureRecorders?;
+    /** Per-COMPOSITION translator (L1b). Set from `opts.groupTranslator`;
+     *  undefined when consumer didn't attach one. */
+    private readonly agentGroupTranslator?;
+    /** ReAct loop mode — 'dynamic' (default, re-engineer all slots each turn,
+     *  flat chart), 'classic' (engineer context once, loop→Messages only, flat
+     *  chart), or 'dynamic-grouped' (dynamic semantics + LLM turn wrapped in an
+     *  sf-llm-call subflow for richer Lens grouping). Set from `opts.reactMode`.
+     *  See AgentOptions. */
+    private readonly reactMode;
+    constructor(opts: AgentOptions, systemPromptValue: string, registry: readonly ToolRegistryEntry[], voice: {
+        readonly appName: string;
+        readonly commentaryTemplates: Readonly<Record<string, string>>;
+        readonly thinkingTemplates: Readonly<Record<string, string>>;
+    }, injections?: readonly Injection[], memories?: readonly MemoryDefinition[], outputSchemaParser?: OutputSchemaParser<unknown>, toolProvider?: ToolProvider, systemPromptCachePolicy?: CachePolicy, cachingDisabled?: boolean, cacheStrategy?: CacheStrategy, outputFallbackCfg?: ResolvedOutputFallback<unknown>, reliabilityConfig?: ReliabilityConfig, thinkingHandlerValue?: ThinkingHandler | null, thinkingBudgetValue?: number, skillGraphNextSkill?: (ctx: InjectionContext) => string | undefined, skillGraphReachable?: (currentSkillId?: string) => readonly string[], skillGraphScoreEntries?: (ctx: InjectionContext, signal?: AbortSignal) => Promise<EntryScoring>);
+    static create(opts: AgentOptions): AgentBuilder;
+    /**
+     * Cache policy for the base system prompt. Read by the CacheDecision
+     * subflow (v2.6 Phase 4) to know how to treat the SystemPrompt slot's
+     * cache markers. Exposed as a method (not direct field access) so
+     * the Agent's encapsulation boundary stays clean.
+     */
+    getSystemPromptCachePolicy(): CachePolicy;
+    /**
+     * The footprintjs `RuntimeSnapshot` from the most recent `run()` /
+     * `resume()`. Feeds Lens's Trace tab (ExplainableShell `runtimeSnapshot`
+     * prop) so consumers can scrub the execution timeline post-run without
+     * threading a recorder through the call site.
+     *
+     * Returns `undefined` before the first run completes. Returns the
+     * snapshot of the most recent run on every call after — including
+     * across multiple turns of the same Agent instance.
+     */
+    getLastSnapshot(): RuntimeSnapshot | undefined;
+    /**
+     * Structured narrative entries from the most recent run. Pairs with
+     * `getLastSnapshot()` for ExplainableShell's `narrativeEntries` prop.
+     * Empty array (not `undefined`) when no run has completed — matches
+     * the prop's expected shape so consumers can wire it directly without
+     * a defensive guard.
+     */
+    getLastNarrativeEntries(): readonly CombinedNarrativeEntry[];
+    /**
+     * The FlowChart compiled for the most recent run (or a freshly-built
+     * one if no run has happened yet). Feeds ExplainableShell's `spec`
+     * prop. Returning the cached chart matters: the spec must match what
+     * `getLastSnapshot()` traced, otherwise the Trace view's stage tree
+     * desyncs from the snapshot's runtime tree.
+     */
+    protected getGroupTranslator(): import('./translator.js').GroupTranslator | undefined;
+    /** Agent has no nested-runner members (tools are function executors,
+     *  not Runner instances). Slot ids + tool names live in `extra` so
+     *  Lens can render an Agent card with slot rows + a tool list without
+     *  inspecting `buildTimeStructure`.
+     *
+     *  Memories are NOT included as members — they're an internal
+     *  mechanism, not a composition-level concept. Consumers who need
+     *  memory visibility should listen for `agentfootprint.memory.*`
+     *  events at runtime. */
+    protected buildUIGroupMetadata(): import('./translator.js').GroupMetadata;
+    /**
+     * Parse + validate a raw agent answer against the agent's
+     * `outputSchema` parser. Throws `OutputSchemaError` on JSON parse
+     * or schema validation failure (the rawOutput is preserved on the
+     * error for triage). Throws a plain `Error` if the agent has no
+     * outputSchema set.
+     *
+     * Use this when you need to keep `agent.run()` returning the raw
+     * string for logging/observability and validate at a different
+     * layer; otherwise prefer `agent.runTyped()`.
+     */
+    parseOutput<T = unknown>(raw: string): T;
+    /**
+     * Async sister of `parseOutput()`. When the agent is configured
+     * with `.outputFallback({...})`, this is the version that engages
+     * the 3-tier degradation chain on validation failure (the sync
+     * `parseOutput` always throws on failure for back-compat).
+     *
+     * Without `outputFallback`, behaves identically to `parseOutput`
+     * — returns sync-style on the happy path, throws OutputSchemaError
+     * on validation failure.
+     */
+    parseOutputAsync<T = unknown>(raw: string): Promise<T>;
+    /**
+     * Run the agent and return the schema-validated typed output.
+     * Convenience over `parseOutputAsync(await agent.run({...}))`.
+     *
+     * Throws `OutputSchemaError` on parse / validation failure UNLESS
+     * `.outputFallback({...})` is configured, in which case the
+     * 3-tier degradation chain (primary → fallback → canned) engages.
+     *
+     * Throws if the agent has no outputSchema set or if the run
+     * pauses (use `run()` directly when pauses are expected).
+     */
+    runTyped<T = unknown>(input: AgentInput, options?: RunOptions): Promise<T>;
+    run(input: AgentInput, options?: RunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Resume an agent run from a checkpoint produced by a prior
+     * `RunCheckpointError`. Unlike `agent.resume()` (which takes a
+     * `FlowchartCheckpoint` from an intentional pause), this takes
+     * an `AgentRunCheckpoint` (conversation-history snapshot) and
+     * replays the agent run with that history restored.
+     *
+     * The next iteration retries the call that originally failed —
+     * with the latest provider state (circuit breaker may have
+     * closed, vendor may have recovered, etc.).
+     *
+     * **Resume = REPLAY from the last completed iteration boundary,
+     * not exact-state restore.** Only the conversation history is
+     * restored; everything else re-seeds fresh:
+     *
+     *   - **Tool re-execution / idempotency**: tool side effects from
+     *     the FAILED iteration are not in the checkpoint. The model
+     *     re-decides from the restored history and may re-issue those
+     *     tool calls — they WILL execute again (there is no built-in
+     *     toolCallId dedup). Mutating tools (payments, emails, DB
+     *     writes) must be idempotent — key on stable call content, not
+     *     `ctx.toolCallId` (a re-issued call gets a new id).
+     *   - **Fresh `runId`**: the resumed run's events carry a new
+     *     `runId`; use `checkpoint.runId` to correlate back to the
+     *     failing run.
+     *   - **Iteration counter + budget reset**: the resumed run starts
+     *     at iteration 1 with a full `maxIterations` budget
+     *     (`checkpoint.lastCompletedIteration` is diagnostic only).
+     *     Token/cost accumulators also restart at zero.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const result = await agent.run({ message: 'long task' });
+     * } catch (err) {
+     *   if (err instanceof RunCheckpointError) {
+     *     await checkpointStore.put(sessionId, err.checkpoint);
+     *     // hours / restart later:
+     *     const checkpoint = await checkpointStore.get(sessionId);
+     *     const result = await agent.resumeOnError(checkpoint);
+     *   }
+     * }
+     * ```
+     */
+    resumeOnError(checkpoint: AgentRunCheckpoint | unknown, options?: RunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Install a per-run checkpoint tracker. Listens for the agent's
+     * own iteration_end events on `this.dispatcher` and snapshots the
+     * conversation history into the tracker. Returns a stop function.
+     *
+     * @internal
+     */
+    private installCheckpointTracker;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    private createExecutor;
+    /**
+     * Flush the deferred-observer backlog of the most recent run's executor,
+     * then await async listener completions under a deadline (RFC-001 §11 —
+     * the serverless / graceful-shutdown pattern). Resolves immediately with
+     * zeros before the first run or when `observerDelivery` is `'inline'`
+     * and no recorder opted into `'deferred'` itself.
+     *
+     * `pending === 0` means a full drain; non-zero honestly reports
+     * continuations still outstanding at the deadline — never silent loss.
+     *
+     * @example Lambda-style handler
+     * ```ts
+     * export const handler = async (event) => {
+     *   const reply = await agent.run({ message: event.message });
+     *   // settle "one beat behind" observer work BEFORE the freeze:
+     *   await agent.drainObservers({ timeoutMs: 5_000 });
+     *   return reply;
+     * };
+     * ```
+     */
+    drainObservers(opts?: {
+        timeoutMs?: number;
+    }): Promise<ObserverDrainResult>;
+    private finalizeResult;
+    private buildChart;
+}