agentfootprint 6.43.0 → 6.45.0

package/dist/esm/core/agent/types.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Agent type definitions — both PUBLIC types (AgentOptions, AgentInput,
+ * AgentOutput) consumed by `Agent.create({...}).run({...})` callers AND
+ * the INTERNAL `AgentState` shape used by stage functions.
+ *
+ * These were originally inline in `core/Agent.ts`; extracted here as
+ * part of the v2.11.1 decomposition. `core/Agent.ts` re-exports them
+ * for back-compat (the 28+ existing import sites continue to work).
+ */
+import type { AttachRecorderOptions, ReadTrackingMode, StructureRecorder, CommitValuesMode } from 'footprintjs';
+import type { GroupTranslator } from '../translator.js';
+import type { LLMMessage, LLMProvider, LLMToolSchema, PermissionChecker, PricingTable } from '../../adapters/types.js';
+import type { CacheMarker, CacheStrategy } from '../../cache/types.js';
+import type { ActiveInjection } from '../../lib/injection-engine/types.js';
+import type { InjectionRecord } from '../../recorders/core/types.js';
+import type { MemoryIdentity } from '../../memory/identity/types.js';
+import type { CredentialProvider } from '../../identity/types.js';
+import type { ToolArgValidationMode } from './toolArgsValidation.js';
+import type { ThinkingBlock } from '../../thinking/types.js';
+import type { ReliabilityScope } from '../../reliability/types.js';
+/**
+ * Dials for the deferred observer queue (RFC-001) — only meaningful with
+ * `observerDelivery: 'deferred'` (passing them without it throws at
+ * construction). Same vocabulary as footprintjs's `AttachRecorderOptions`
+ * minus `delivery` (the Agent option IS the delivery switch):
+ * `capture` (default `'clone'` — hooks receive the same event shape as
+ * inline), `maxQueue` (default 10 000), `overflow` (default
+ * `'drop-oldest'`), `sampleEvery`, `flushBudgetMs` (default 2).
+ */
+export type ObserverDeliveryOptions = Omit<AttachRecorderOptions, 'delivery'>;
+export interface AgentOptions {
+    readonly provider: LLMProvider;
+    /** Human-friendly name shown in events/metrics. Default: 'Agent'. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default: 'agent'. */
+    readonly id?: string;
+    readonly model: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    /** Hard budget on ReAct iterations. Default: 10. Hard cap: 50. */
+    readonly maxIterations?: number;
+    /**
+     * Pricing adapter. When set, Agent emits `agentfootprint.cost.tick`
+     * after every LLM response (once per ReAct iteration) with per-call
+     * and cumulative USD. Run-scoped — the cumulative resets each `.run()`.
+     */
+    readonly pricingTable?: PricingTable;
+    /**
+     * Cumulative USD budget per run. With `pricingTable`, Agent emits a
+     * one-shot `agentfootprint.cost.limit_hit` (`action: 'warn'`) when
+     * cumulative USD crosses this budget. Execution continues — consumers
+     * choose whether to abort by listening to the event.
+     */
+    readonly costBudget?: number;
+    /**
+     * Permission adapter. When set, the Agent calls
+     * `permissionChecker.check({capability: 'tool_call', ...})` BEFORE every
+     * `tool.execute()`. Emits `agentfootprint.permission.check` with the
+     * decision. On `deny`, the tool is skipped and its result is a
+     * synthetic denial string; on `allow` / `gate_open`, execution proceeds
+     * normally.
+     */
+    readonly permissionChecker?: PermissionChecker;
+    /**
+     * Tool-args validation mode (#9). Default `'enforce'`: LLM-produced args
+     * are validated against the tool's declared `inputSchema` BEFORE dispatch.
+     * On mismatch the tool is NOT executed — the model receives a structured
+     * retry message as the tool result (paths + expected shapes + received
+     * TYPES, never the supplied values) and corrects itself on the next
+     * iteration. Emits `agentfootprint.validation.args_invalid`.
+     * `'warn'` emits the event but executes anyway; `'off'` disables.
+     * Validation is an honest JSON-Schema subset (type/required/properties/
+     * items/enum/explicit additionalProperties:false) — unsupported keywords
+     * are ignored, never false-rejecting.
+     */
+    readonly toolArgValidation?: ToolArgValidationMode;
+    /**
+     * Read-tracking policy for the snapshot's per-stage read view
+     * (footprintjs `StageSnapshot.stageReads`) — the observability-cost
+     * lever for LONG runs. Forwarded to the Agent's internal
+     * `FlowChartExecutor` as `{ readTracking }`.
+     *
+     * - `'summary'` (Agent default) — each tracked read records a cheap
+     *   `ReadSummaryMarker` (type + size proxy + short preview) instead of
+     *   a `structuredClone` of the value. Measured at N=200 full-feature
+     *   iterations, `'full'` clones ~18MB of read values that nothing in
+     *   the agentfootprint/lens/explainable-ui stack consumes.
+     * - `'full'` — footprintjs's own default: every tracked read clones the
+     *   value into `stageReads`. Set explicitly if you inspect
+     *   `agent.getSnapshot()` read VALUES (not just keys/shapes).
+     * - `'off'` — reads are not recorded; `stageReads` is absent.
+     *
+     * Narrative, recorder events (`onRead` payloads), and commit history are
+     * IDENTICAL in every mode — the policy scopes ONLY the snapshot's
+     * `stageReads` payload. Note the Agent default (`'summary'`) is
+     * deliberately cheaper than footprintjs's (`'full'`); see CHANGELOG
+     * behavior-change callout.
+     */
+    readonly readTracking?: ReadTrackingMode;
+    /**
+     * Commit-log value encoding (#13c-B) — forwarded to the internal
+     * executor as `{ commitValues }`. Agent default is **`'delta'`**: a
+     * stage whose net change to a tracked array is "the old array plus a
+     * tail" (the agent's `history` every iteration) records ONLY the tail
+     * (`append` verb); key removals record a `delete` verb. LOSSLESS — any
+     * step's full value reconstructs by replay (`commitValueAt` from
+     * `footprintjs/trace`), which is why this is safe for audit trails.
+     * Retained commit-log memory becomes linear instead of quadratic.
+     * Set `'full'` for footprintjs's default encoding (every changed key
+     * stores its full final value) if a downstream consumer reads
+     * `bundle.overwrite[key]` as the complete value.
+     */
+    readonly commitValues?: CommitValuesMode;
+    /**
+     * Credential provider for downstream OAuth (declare-and-push). When set, a
+     * tool that declares `needs: { credential }` has it resolved BEFORE `execute`
+     * and injected as `ctx.credential`; tools can also pull via `ctx.credentials`.
+     * From `agentfootprint/identity` (`agentCoreIdentity({ region })`,
+     * `staticTokens({ ... })`, or any `CredentialProvider`).
+     */
+    readonly credentials?: CredentialProvider;
+    /**
+     * Global cache kill switch (v2.6+). `'off'` disables the cache
+     * layer entirely — the CacheGate decider routes to `'no-markers'`
+     * every iteration regardless of other rules. Default: caching
+     * enabled (auto-resolved per provider via the strategy registry).
+     *
+     * Use `'off'` for low-frequency agents (cron jobs running once per
+     * hour) where the cache TTL guarantees zero cache hits and the
+     * cache-write penalty isn't worth paying.
+     */
+    readonly caching?: 'off';
+    /**
+     * Optional explicit CacheStrategy override (v2.6+). Defaults to
+     * `getDefaultCacheStrategy(provider.name)` — so Anthropic/OpenAI/
+     * Bedrock/Mock providers auto-resolve to their respective strategies
+     * once those land in Phase 7+.
+     */
+    readonly cacheStrategy?: CacheStrategy;
+    /**
+     * Optional build-time recorders threaded into footprintjs's
+     * `flowChart()` factory. Each recorder fires `onStageAdded` once per
+     * node in the Agent's internal chart (Seed, CallLLM, Route, tool
+     * handler, slot mounts, PrepareFinal, BreakFinal), and
+     * `onSubflowMounted` once per mounted subflow. Recorders own their
+     * own accumulators — agentfootprint just threads them through.
+     *
+     * Cascade: each slot subflow (system-prompt, messages, tools)
+     * was built earlier with its OWN recorders (or none).
+     * footprintjs does NOT propagate StructureRecorders into mounted
+     * subflows — attach the same recorders to every nested composition
+     * for full coverage.
+     *
+     * When omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `agent.getUIGroup()` invokes
+     * it with the Agent's `GroupMetadata` (kind `'Agent'`, id, name,
+     * empty `members[]`, plus `extra.slots` and `extra.toolNames`).
+     * Tools are not `Runner` instances (they're function executors)
+     * so they're conveyed by name in `extra`, not as group members.
+     * Returns `undefined` when omitted.
+     */
+    readonly groupTranslator?: GroupTranslator;
+    /**
+     * How the ReAct loop behaves — a single setting with three honest choices.
+     * Default `'dynamic'`. (Merged in 6.0.0 from the old `reactMode` +
+     * `reactStructure` pair, which had a silently-ignored combination.)
+     *
+     * `'dynamic'` (default) — every iteration re-runs the InjectionEngine and
+     * all three slots (system-prompt ‖ messages ‖ tools), because which
+     * injections are active can change per turn (a skill activates, a rule
+     * fires, a tool-return triggers something). The right shape when the agent
+     * uses skills, rule/on-tool-return triggers, or any per-turn context
+     * steering. Flat chart shape.
+     *
+     * `'classic'` — textbook ReAct: context is engineered ONCE. The
+     * InjectionEngine, system-prompt and tools run a single time up front; the
+     * loop targets only the Messages slot, so each iteration just appends the
+     * new tool result and re-calls the LLM. Use when the system prompt and tool
+     * set are FIXED for the whole run (the common case). Flat chart shape — the
+     * chart reads honestly: `ToolCalls → Messages` loops, static slots outside.
+     * CAVEAT: because static slots are cached after turn 1, do NOT use `'classic'`
+     * with skills or dynamic-trigger injections — a mid-run activation would not
+     * surface into the cached system-prompt/tools. Use `'dynamic'` for those.
+     *
+     * `'dynamic-grouped'` — same semantics as `'dynamic'`, but the whole LLM turn
+     * (injection engine + 3 slots + cache + call + thinking) is wrapped in a
+     * single `sf-llm-call` SUBFLOW — the same boundary the `LLMCall` primitive
+     * produces. Lens (and any explainable-ui consumer) renders it as an LLM group
+     * with its slots inside, with zero bespoke collapsing. Behaviour is identical
+     * to `'dynamic'`; only the chart's nesting differs. (Grouping is dynamic-only:
+     * it re-seeds context every turn by design, so there is no classic-grouped.)
+     */
+    readonly reactMode?: 'classic' | 'dynamic' | 'dynamic-grouped';
+    /**
+     * Observer delivery tier (RFC-001 Block 10). Default `'inline'` —
+     * byte-identical to every prior release: the Agent's bridge recorders
+     * (and your `.recorder()` attachments) run synchronously inside the
+     * producing statement, so a slow `agent.on()` listener taxes every
+     * stage of every iteration.
+     *
+     * `'deferred'` moves observation off the hot path: every observer event
+     * is captured into footprintjs's bounded queue (≈ microseconds) and
+     * delivered at the next microtask checkpoint — "one beat behind", with
+     * listener work overlapping the LLM/tool await windows instead of
+     * serializing with the loop. Same events, same payloads, same order;
+     * only the timing meta (`wallClockMs` / `runOffsetMs`) reflects the
+     * later delivery. Terminal boundaries (run resolve, reject, pause)
+     * drain the queue synchronously BEFORE control returns, so crash
+     * reports / checkpoints always carry the complete record.
+     *
+     * Exception kept inline for correctness: the causal-evidence harvest
+     * recorder (mounted with CAUSAL memories) — the memory write stage
+     * reads its accumulators MID-run, so it cannot run one beat behind.
+     *
+     * Per-recorder override: a consumer recorder that declares its own
+     * `delivery` field keeps it — the agent-level option is the default
+     * tier for recorders that don't declare one.
+     *
+     * For serverless / graceful shutdown, settle async listener work with
+     * `await agent.drainObservers({ timeoutMs })` before the process exits.
+     * Queue stats surface on `agent.getLastSnapshot()?.observerStats`.
+     */
+    readonly observerDelivery?: 'inline' | 'deferred';
+    /**
+     * Queue dials for `observerDelivery: 'deferred'` — see
+     * `ObserverDeliveryOptions`. Throws at construction when set without
+     * `observerDelivery: 'deferred'` (no silently-ignored combinations).
+     */
+    readonly observerDeliveryOptions?: ObserverDeliveryOptions;
+}
+export interface AgentInput {
+    readonly message: string;
+    /**
+     * Multi-tenant memory scope. Populated to `scope.identity` so memory
+     * subflows registered via `.memory()` can isolate reads/writes per
+     * tenant + principal + conversation.
+     *
+     * Defaults to `{ conversationId: '<runId>' }` when omitted, so agents
+     * without memory work unchanged.
+     */
+    readonly identity?: MemoryIdentity;
+}
+export type AgentOutput = string;
+/**
+ * Internal scope state for the Agent's flowchart. Recorders never read
+ * this directly — they read the InjectionRecord convention keys + emit
+ * events. Each stage function under `./stages/` receives a TypedScope
+ * over this shape and reads/writes via typed properties.
+ *
+ * Mutability conventions (followed by every Agent stage):
+ *   • Per-iteration scalars (iteration, finalContent, llmLatestContent,
+ *     etc.) are OVERWRITTEN each pass; commitLog preserves history.
+ *   • Cumulative scalars (cumTokensInput, totalInputTokens, turnNumber)
+ *     accumulate monotonically across the run.
+ *   • Arrays from slot subflows (systemPromptInjections,
+ *     messagesInjections, toolsInjections, dynamicToolSchemas,
+ *     cacheMarkers) use `arrayMerge: ArrayMergeMode.Replace` semantics —
+ *     each iteration's value REPLACES the prior iteration's, not
+ *     appends.
+ */
+export interface AgentState {
+    userMessage: string;
+    history: readonly LLMMessage[];
+    iteration: number;
+    maxIterations: number;
+    finalContent: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    turnStartMs: number;
+    runIdentity: MemoryIdentity;
+    newMessages: readonly LLMMessage[];
+    turnNumber: number;
+    contextTokensRemaining: number;
+    systemPromptInjections: readonly InjectionRecord[];
+    messagesInjections: readonly InjectionRecord[];
+    toolsInjections: readonly InjectionRecord[];
+    llmLatestContent: string;
+    llmLatestToolCalls: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }[];
+    pausedToolCallId: string;
+    pausedToolName: string;
+    pausedToolStartMs: number;
+    cumTokensInput: number;
+    cumTokensOutput: number;
+    cumEstimatedUsd: number;
+    costBudgetHit: boolean;
+    /** Active set output by InjectionEngine subflow each iteration —
+     *  POJO projections (no functions) suitable for scope round-trip. */
+    activeInjections: readonly ActiveInjection[];
+    /** IDs of LLM-activated Skills the LLM has activated this turn
+     *  (via the `read_skill` tool). InjectionEngine matches by id. */
+    activatedInjectionIds: readonly string[];
+    /** Most recent tool result — drives `on-tool-return` triggers. */
+    lastToolResult?: {
+        toolName: string;
+        result: string;
+    };
+    /** Tool schemas resolved by the tools slot subflow each iteration
+     *  (registry + injection-supplied). Used by callLLM. */
+    dynamicToolSchemas: readonly LLMToolSchema[];
+    /** Provider-agnostic cache markers emitted by CacheDecision subflow.
+     *  Cleared each iteration by the SkipCaching branch when the
+     *  CacheGate decides to skip (kill switch / hit-rate / churn). */
+    cacheMarkers: readonly CacheMarker[];
+    /** Global cache kill switch from `Agent.create({ caching: 'off' })`. */
+    cachingDisabled: boolean;
+    /** Running cache hit rate from recent iterations (0..1). Computed
+     *  by cacheRecorder (Phase 9); `undefined` until first metrics. */
+    recentHitRate: number | undefined;
+    /** Rolling window of active-skill IDs across recent iterations.
+     *  Maintained by the UpdateSkillHistory function stage; consumed
+     *  by CacheGate's skill-churn rule. */
+    skillHistory: readonly (string | undefined)[];
+    /** The skill-graph CURSOR — which skill node a `skillGraph()` agent is
+     *  currently *in*, persisted across ReAct iterations. Advanced each iteration
+     *  by the Injection Engine (`currentSkillId = graph.nextSkill(ctx)`) and
+     *  carried by the mount mappers; reset to `undefined` per turn at seed (each
+     *  turn re-enters via the entry router). `from`-gates the route triggers.
+     *  Undefined for agents without a skill graph. */
+    currentSkillId?: string;
+    /** The relevance ranking of entry candidates from an entry scorer (`.entryBy()` /
+     *  `.entryByRelevance()`) — written by the PickEntry stage once per turn (the
+     *  "Why this skill?" relevance %). `score` is the raw strategy score; `relevance`
+     *  the softmax share. Absent unless the graph used an entry scorer. */
+    entryScores?: ReadonlyArray<{
+        readonly id: string;
+        readonly score: number;
+        readonly relevance: number;
+    }>;
+    /** Name of the entry scorer that produced `entryScores` (`'keyword'` /
+     *  `'embedding'` / a custom scorer's name). */
+    entryScorer?: string;
+    /** Set when a `PermissionChecker` returns `{ result: 'halt', ... }`.
+     *  `Agent.run()` reads these at the API boundary and throws a typed
+     *  `PolicyHaltError` carrying the same context — the chart $break's
+     *  graceful termination becomes a runtime signal callers can catch
+     *  with `instanceof PolicyHaltError`. Telemetry tag from the rule. */
+    policyHaltReason?: string;
+    /** Content delivered to the LLM as the synthetic tool_result before
+     *  termination — also surfaces on `PolicyHaltError.tellLLM` for
+     *  audit / replay. */
+    policyHaltTellLLM?: string;
+    /** The proposed tool call that triggered the halt (NOT executed). */
+    policyHaltTarget?: string;
+    policyHaltArgs?: Readonly<Record<string, unknown>>;
+    /** ReAct iteration the halt fired on. */
+    policyHaltIteration?: number;
+    /** Identifier of the PermissionChecker that returned `'halt'`. */
+    policyHaltCheckerId?: string;
+    /** Provider-specific raw thinking data, set by callLLM after the
+     *  LLM response lands. The NormalizeThinking sub-subflow reads this
+     *  and feeds it to the configured `ThinkingHandler.normalize()`.
+     *  Undefined when the provider has no thinking content for this call. */
+    rawThinking?: unknown;
+    /** Normalized thinking blocks from the most recent LLM response.
+     *  Written by the NormalizeThinking sub-subflow; read by toolCalls.ts
+     *  + prepareFinal.ts when constructing the assistant message for
+     *  `scope.history` (ensures Anthropic signature round-trip). Empty
+     *  array when no thinking present. */
+    thinkingBlocks: readonly ThinkingBlock[];
+    /** Set when the rules-based reliability loop takes the fail-fast path.
+     *  `Agent.run()` reads these from the post-run snapshot and throws a
+     *  typed `ReliabilityFailFastError`. Mirrors `policyHalt*` — because the
+     *  loop stops the chart with `$break` (not a throw), durable scope is the
+     *  only courier of the structured fail context across the break to the
+     *  API boundary. (Telemetry ALSO fires via the `reliability.fail_fast`
+     *  emit event; these scope fields are the business-logic control signal.) */
+    reliabilityFailKind?: string;
+    reliabilityFailPayload?: ReliabilityScope['failPayload'];
+    reliabilityFailReason?: string;
+    /** Originating error message/name — stringified because Error objects
+     *  don't survive footprintjs's `structuredClone` of scope. */
+    reliabilityFailCauseMessage?: string;
+    reliabilityFailCauseName?: string;
+}

package/dist/esm/core/agent/validators.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Agent validators — pure helper functions extracted from Agent.ts.
+ *
+ * These run at Agent construction time (eagerly, so misconfiguration
+ * fails fast at `.build()`) and during stage execution (safeStringify
+ * for tool-result formatting).
+ *
+ * Pure functions, no class state — extracted for readability and
+ * isolated testability. The Agent class imports + invokes these in
+ * its constructor and stage handlers.
+ */
+import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { Injection } from '../../lib/injection-engine/types.js';
+import type { ToolRegistryEntry } from '../tools.js';
+/**
+ * Validate that every memory definition has a unique id. Each memory
+ * writes to its own scope key (`memoryInjection_${id}`); duplicates
+ * silently overwrite, leading to data loss that's hard to debug.
+ *
+ * Throws on collision so `Agent.build()` fails fast at construction.
+ */
+export declare function validateMemoryIdUniqueness(memories: readonly MemoryDefinition[]): void;
+/**
+ * Validate `maxIterations`. The historical silent clamp to 50 existed because
+ * footprintjs's recursive traversal hit its depth wall around iteration 71 —
+ * footprintjs 9.0.0's trampoline removed that wall (loops run on a flat
+ * stack), so the cap is gone. The lower bound (1) still prevents a
+ * 0-iteration agent; large values are the consumer's COST choice (each
+ * iteration is an LLM call) — a dev-mode warning flags budgets above 100.
+ * The Agent passes matching headroom to the engine's own loop-iteration
+ * limit so it can never fire below the agent's budget.
+ */
+export declare function clampIterations(n: number): number;
+/**
+ * Validate tool-name uniqueness across `.tool()`-registered tools +
+ * every Skill's `inject.tools[]`. The LLM dispatches by `tool.schema.name`
+ * (the wire format), so any collision silently shadows execution.
+ *
+ * Called eagerly in the Agent constructor so `Agent.build()` throws
+ * immediately, not on first `run()`.
+ *
+ * `read_skill` is reserved when ≥1 Skill is registered — collisions
+ * with consumer tools throw.
+ */
+export declare function validateToolNameUniqueness(registry: readonly ToolRegistryEntry[], injections: readonly Injection[]): void;
+/**
+ * JSON.stringify with circular-ref protection. Tool results are untrusted —
+ * a hostile/buggy tool returning a cyclic object must not crash the run.
+ * Falls back to '[unstringifiable: <reason>]' so the LLM still sees that
+ * the tool ran and produced something unusable.
+ */
+export declare function safeStringify(value: unknown): string;

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

@@ -0,0 +1,38 @@
+/**
+ * cost — shared cost-accounting helper emitted by LLMCall + Agent.
+ *
+ * Pattern: Strategy (PricingTable port) + Event emission (typedEmit).
+ * Role:    core/ layer. When a runner is configured with a PricingTable,
+ *          every LLM response drives a `cost.tick` event carrying per-call
+ *          tokens/USD plus cumulative run totals. When a `costBudget` is
+ *          also set, the first crossing emits `cost.limit_hit` with
+ *          `action: 'warn'` (library never auto-aborts; consumers decide).
+ * Emits:   agentfootprint.cost.tick
+ *          agentfootprint.cost.limit_hit
+ */
+import type { PricingTable } from '../adapters/types.js';
+export interface CostAccountingScope {
+    cumTokensInput: number;
+    cumTokensOutput: number;
+    cumEstimatedUsd: number;
+    costBudgetHit: boolean;
+}
+type Usage = {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+};
+/**
+ * Emit `cost.tick` for the just-completed LLM response and, if the
+ * consumer set a `costBudget`, emit a one-shot `cost.limit_hit` the first
+ * time cumulative USD crosses the budget. Does nothing when no
+ * `pricingTable` is configured — zero overhead on runs without costing.
+ *
+ * Scope must carry the running cumulative counters; callers seed them
+ * in their Seed stage.
+ */
+export declare function emitCostTick(scope: CostAccountingScope & {
+    $emit: (name: string, payload?: unknown) => void;
+}, pricingTable: PricingTable | undefined, costBudget: number | undefined, model: string, usage: Usage): void;
+export {};

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

@@ -0,0 +1,200 @@
+/**
+ * flowchartAsTool — wrap a footprintjs `FlowChart` as an Agent `Tool`.
+ *
+ * The Block A7 piece. footprintjs is the substrate; agentfootprint is
+ * the agent layer above it. When a multi-step procedure is already
+ * expressed as a footprintjs flowchart (intake validation, refund
+ * processing, claim adjudication — anything with branches, loops, or
+ * decision evidence), let the LLM call it as ONE tool. The flowchart's
+ * step-by-step recorders, narrative, and pause/resume continue to work
+ * exactly as they do outside the agent.
+ *
+ * Why this matters:
+ *
+ *   1. **Composition over re-write.** A team with a non-trivial
+ *      footprintjs flowchart shouldn't have to flatten it into N
+ *      separate tools to expose it to an agent. Wrap it once.
+ *
+ *   2. **Observability stays free.** Every flowchart stage emits typed
+ *      events. The Agent's recorders see the wrapping tool call;
+ *      footprintjs's recorders see everything inside. Two layers,
+ *      one observation tree. The `recorders` option bridges them:
+ *      attach agent-layer observers (the causal-evidence bridge,
+ *      `otel.decisionEvidenceRecorder()`, your own CombinedRecorder)
+ *      to the tool's INTERNAL executor so decide()/select() evidence
+ *      inside the flowchart reaches them too.
+ *
+ *   3. **Pause/resume composes.** A pausable handler inside the
+ *      flowchart pauses the inner executor; the outer agent treats
+ *      the pause as an unfinished tool call. Resume the agent and the
+ *      inner flowchart resumes from its checkpoint. (Today: surfaces
+ *      the pause as a thrown error with the checkpoint attached;
+ *      polished agent-side pause integration in v2.6.)
+ *
+ * Pattern: Adapter (GoF) over `FlowChartExecutor.run()`. Translates
+ *          `Tool.execute(args, ctx)` into `executor.run({ input: args,
+ *          env: { signal: ctx.signal } })` and the result back to a
+ *          string via `resultMapper` (or a default JSON stringify).
+ *
+ * Role:    Layer-6 (Agent) → Layer-1 (footprintjs) bridge. Pure
+ *          interop; no new abstraction in either layer.
+ *
+ * @example  Single-stage flowchart as a tool
+ *   import { flowChart } from 'footprintjs';
+ *   import { Agent, flowchartAsTool } from 'agentfootprint';
+ *
+ *   const refundChart = flowChart<{ refundId: string }>(
+ *     'RefundFlow',
+ *     async (scope) => {
+ *       const args = scope.$getArgs<{ orderId: string; reason: string }>();
+ *       scope.refundId = await refundService.process(args.orderId);
+ *     },
+ *     'refund-flow',
+ *   ).build();
+ *
+ *   const refundTool = flowchartAsTool({
+ *     name: 'process_refund',
+ *     description: 'Process a refund for an order. Returns refundId on success.',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: {
+ *         orderId: { type: 'string' },
+ *         reason: { type: 'string' },
+ *       },
+ *       required: ['orderId', 'reason'],
+ *     },
+ *     flowchart: refundChart,
+ *     resultMapper: (snapshot) =>
+ *       JSON.stringify({ refundId: snapshot.values.refundId, status: 'processed' }),
+ *   });
+ *
+ *   const agent = Agent.create({ provider }).tool(refundTool).build();
+ *
+ * @example  Multi-stage flowchart with decide() + recorders
+ *   const triageChart = flowChart<TriageState>('Triage', validateInput, 'validate')
+ *     .addDeciderFunction('Classify', classifyDecider, 'classify')
+ *       .addFunctionBranch('high', 'Escalate', escalate)
+ *       .addFunctionBranch('low', 'Auto-handle', autoHandle)
+ *       .end()
+ *     .build();
+ *
+ *   // decide() evidence inside the chart fires `onDecision` on each
+ *   // attached recorder — wire the agent's evidence consumers straight
+ *   // into the tool instead of hand-mounting the chart.
+ *   const evidence = causalEvidenceRecorder();
+ *
+ *   const triageTool = flowchartAsTool({
+ *     name: 'triage_request',
+ *     description: 'Triage an incoming request and return the decision.',
+ *     inputSchema: { ... },
+ *     flowchart: triageChart,
+ *     recorders: [evidence],
+ *   });
+ */
+import { type CombinedRecorder, type FlowChart } from 'footprintjs';
+import type { Tool } from './tools.js';
+/**
+ * Pruned snapshot view passed to `resultMapper`. We keep this minimal
+ * (the values bag + the chart's narrative entries) to avoid leaking
+ * internal scope plumbing. Consumers needing the full snapshot can
+ * pass a `passthrough` resultMapper that ignores the prune.
+ */
+export interface FlowchartToolSnapshot {
+    /**
+     * Final scope state — the merged result of every stage's writes.
+     * This is what `executor.getSnapshot().values` returns.
+     */
+    readonly values: Readonly<Record<string, unknown>>;
+    /**
+     * The flowchart's combined narrative entries (flow + data).
+     * Useful for resultMappers that want to extract specific commit
+     * artifacts or audit a decision path.
+     */
+    readonly narrative: readonly {
+        readonly type?: string;
+        readonly text?: string;
+    }[];
+}
+/**
+ * Optional result mapper. Receives the flowchart's final snapshot
+ * (pruned to `FlowchartToolSnapshot`) and returns the string the LLM
+ * sees as the tool result.
+ *
+ * If omitted, the default behavior is `JSON.stringify(snapshot.values)`.
+ *
+ * Errors thrown from the mapper become the tool result with a
+ * `[mapper-error: ...]` prefix so the LLM sees a useful diagnostic.
+ */
+export type FlowchartResultMapper = (snapshot: FlowchartToolSnapshot) => string;
+/**
+ * Options for `flowchartAsTool`.
+ */
+export interface FlowchartAsToolOptions {
+    /** Tool name the LLM dispatches by. Must be unique across the agent's tools. */
+    readonly name: string;
+    /** Tool description shown to the LLM. */
+    readonly description: string;
+    /**
+     * JSON Schema describing the input args the LLM must produce.
+     * Becomes `flowchart.run({ input: args })`. Default: `{ type: 'object', properties: {} }`.
+     */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /**
+     * The footprintjs flowchart to mount as the tool's body.
+     * The chart's stages receive args via `scope.$getArgs()`.
+     */
+    readonly flowchart: FlowChart;
+    /**
+     * Optional shaping function. Default: `JSON.stringify(snapshot.values)`.
+     * Errors throw into the tool's `[mapper-error: ...]` envelope.
+     */
+    readonly resultMapper?: FlowchartResultMapper;
+    /**
+     * Observers to attach to the tool's INTERNAL `FlowChartExecutor`
+     * before each run. This is the hook that lets decide()/select()
+     * evidence (and every other footprintjs event) inside a tool-mounted
+     * flowchart reach agent-layer evidence consumers — e.g. the causal
+     * `causalEvidenceRecorder()` bridge or `otel.decisionEvidenceRecorder()`.
+     * Without it, the internal executor is unobservable from outside.
+     *
+     * Each entry is a footprintjs `CombinedRecorder`, attached via
+     * `executor.attachCombinedRecorder` and routed by runtime
+     * method-shape detection — so ONE array covers all three observer
+     * channels (scope data-flow `onRead`/`onWrite`/`onCommit`/…,
+     * control-flow `onDecision`/`onSelected`/`onLoop`/…, and emit
+     * `onEmit`). Implement only the hooks you care about.
+     *
+     * **Per-invocation semantics:** the tool builds a FRESH executor per
+     * call (flowchart state never leaks between invocations) and attaches
+     * every recorder in this array to EACH invocation's executor before
+     * `run()`. The recorder INSTANCES are yours and are shared across
+     * invocations — a stateful recorder therefore accumulates events from
+     * EVERY invocation of the tool. Each invocation is a distinct run
+     * with a fresh `runId`; recorders needing per-invocation bookkeeping
+     * detect the boundary via `event.traversalContext.runId !== lastRunId`
+     * (Convention 4) rather than assuming one run per recorder lifetime.
+     */
+    readonly recorders?: ReadonlyArray<CombinedRecorder>;
+}
+/**
+ * Wrap a footprintjs `FlowChart` as a `Tool` the Agent's LLM can call.
+ *
+ * On execute:
+ *   1. Constructs a fresh `FlowChartExecutor(flowchart)` per call (so
+ *      consecutive invocations don't share state).
+ *   2. Attaches each `opts.recorders` entry via
+ *      `executor.attachCombinedRecorder` — the SAME recorder instances
+ *      attach to every invocation's fresh executor (see the option's
+ *      JSDoc for the shared-state / runId implications).
+ *   3. Calls `executor.run({ input: args, env: { signal } })` with the
+ *      LLM-supplied args + the agent's abort signal.
+ *   4. If the run paused, throws an Error with the checkpoint attached
+ *      (`error.checkpoint`) so the agent loop can surface it. Polished
+ *      agent-side pause integration is v2.6 work.
+ *   5. If the run completed, calls `resultMapper(snapshot)` (or the
+ *      default JSON.stringify) and returns the string.
+ *   6. If the run threw, the error propagates — the Agent's
+ *      tool-call handler converts it to a synthetic error string for
+ *      the LLM to see + recover from.
+ */
+export declare function flowchartAsTool(opts: FlowchartAsToolOptions): Tool;