agentfootprint 6.44.0 → 6.45.0

package/dist/esm/observability/contextError/finders/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Context-error finders — the plain, pluggable public surface for context-bug
+ * localization. A `Finder` answers one question: "which piece of context made the
+ * agent's answer wrong?" Each finder is a thin, named adapter over the engines in
+ * `src/lib/context-bisect` + `src/lib/influence-core`; the academic method + citation
+ * live in `meta`, never in the import name.
+ *
+ * Taxonomy (area / category / thing): observability / contextError / finders.
+ * Tree-shakeable: one finder = one file = one named export; import only what you use.
+ */
+import type { Embedder } from '../../../lib/influence-core/index.js';
+/** How sure the finder is. `guessed` = ranked by a similarity proxy only;
+ *  `proven` = a removal/re-run actually flipped the outcome (counterfactual). */
+export type Evidence = 'guessed' | 'proven';
+/** What the finder points at. `piece` = a context element; `step` = an agent step. */
+export type Granularity = 'piece' | 'step';
+/** A removable piece of context the finder can suspect. */
+export interface ContextPiece {
+    readonly id: string;
+    readonly text: string;
+}
+/** One agent step (a tool-call), for finders that work at step granularity. */
+export interface StepInput {
+    readonly id: string;
+    /** Human-readable label, e.g. `get_promo@L1`. */
+    readonly label: string;
+    readonly text: string;
+}
+/** Everything a finder may need. Light finders use `embedder`; counterfactual
+ *  finders use `rerun`; step finders use `steps`. A finder throws if a field it
+ *  needs is missing. */
+export interface FindInput {
+    /** The removable context pieces to consider. */
+    readonly suspects: readonly ContextPiece[];
+    /** The wrong answer to explain. */
+    readonly wrongOutput: string;
+    /** Embedder for similarity-ranking finders. */
+    readonly embedder?: Embedder;
+    /** Re-run with the given pieces removed; `recovered` = the outcome flipped back. */
+    readonly rerun?: (removedIds: readonly string[]) => Promise<{
+        recovered: boolean;
+        outcome?: string;
+    }>;
+    /** The agent's steps, for step-granularity finders. */
+    readonly steps?: readonly StepInput[];
+    /** For testManyCombos: how many on/off combinations to sample (default ~4×#suspects). */
+    readonly samples?: number;
+}
+/** One suspect in the finder's ranked output. */
+export interface ScoredSuspect {
+    readonly id: string;
+    /** Higher = more suspicious. Absent for finders that don't score. */
+    readonly score?: number;
+}
+/** What a finder returns. Plain fields, namespace-independent. */
+export interface FindResult {
+    /** Which finder produced this. */
+    readonly finder: string;
+    /** Suspects, most-to-least suspicious. */
+    readonly suspects: readonly ScoredSuspect[];
+    /** The single top suspect, if any. */
+    readonly lead?: string;
+    /** The small set worth confirming when there is no clear single winner. */
+    readonly shortlist: readonly string[];
+    /** `guessed` (proxy) vs `proven` (counterfactual). */
+    readonly evidence: Evidence;
+    /** `piece` vs `step`. */
+    readonly granularity: Granularity;
+    /** How many times the finder re-ran the agent (the honest cost). 0 = free. */
+    readonly checks: number;
+    /** A self-explaining narrative of how the finder reached its answer. */
+    readonly explanation: string;
+}
+/** Attribution — kept off the import name, surfaced in docs / leaderboards. */
+export interface FinderMeta {
+    /** Plain one-liner for a leaderboard row. */
+    readonly label: string;
+    /** The precise technique, for experts. */
+    readonly method: string;
+    /** Citation, if the finder reimplements a published method. */
+    readonly paper?: string;
+}
+/** A pluggable context-error finder. */
+export interface Finder {
+    readonly name: string;
+    readonly meta: FinderMeta;
+    find(input: FindInput): Promise<FindResult>;
+}

package/dist/esm/observability-providers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * agentfootprint/observability-providers — vendor observability strategies.
+ *
+ * Grouped subpath following the parallel-providers pattern v2.5
+ * established for `llm-providers` / `tool-providers` /
+ * `memory-providers`. Adding a new vendor adds an export here, NOT
+ * a new subpath — keeps `package.json#exports` from sprawling.
+ *
+ * Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
+ * so consumers who never call a particular factory don't have to
+ * install that SDK. Peer-deps are declared in package.json with
+ * `peerDependenciesMeta.{name}.optional = true`.
+ *
+ * @example
+ * ```ts
+ * import { agentcoreObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: agentcoreObservability({
+ *     region: 'us-east-1',
+ *     logGroupName: '/agentfootprint/my-agent',
+ *   }),
+ *   // Recommended — keeps the agent loop unblocked by network latency.
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * Roadmap:
+ *   - agentcoreObservability   ← v2.8.1
+ *   - cloudwatchObservability  ← v2.8.2
+ *   - xrayObservability        ← v2.8.3
+ *   - otelObservability        ← v2.9.0 (this release)
+ *
+ * Note: `datadogObservability` was on the v2.9 roadmap, but Datadog
+ * APM accepts OTLP — point your OTel SDK at Datadog's OTLP endpoint
+ * and `otelObservability` covers the Datadog use case. We'll ship a
+ * dedicated `dd-trace`-based adapter only if real-world feedback
+ * demands the native Datadog APM client.
+ */
+export { agentcoreObservability, type AgentcoreObservabilityOptions, } from './adapters/observability/agentcore.js';
+export { cloudwatchObservability, type CloudwatchObservabilityOptions, } from './adapters/observability/cloudwatch.js';
+export { xrayObservability, type XrayObservabilityOptions, type XRayLikeClient, } from './adapters/observability/xray.js';
+export { otelObservability, type OtelObservabilityOptions, type OtelObservabilityStrategy, type OtelDecisionEvidenceRecorder, type OtelTracerLike, type OtelSpanLike, type OtelSpanOptions, type OtelAttributeValue, } from './adapters/observability/otel.js';
+export { auditExport, verifyAuditBundle, AUDIT_BUNDLE_FORMAT, AUDIT_GENESIS_EVENT_TYPE, AUDIT_ZERO_HASH, type AuditBundle, type AuditBundleHeader, type AuditExportOptions, type AuditExportStrategy, type AuditRecord, type AuditVerifyResult, } from './adapters/observability/audit.js';
+export { canonicalJson, CANONICAL_JSON_VERSION } from './lib/canonicalJson.js';

package/dist/esm/observe.d.ts

@@ -0,0 +1,62 @@
+/**
+ * agentfootprint/observe — observability recorders.
+ *
+ * Pattern: Observer (GoF) — pluggable, fire-and-forget event listeners
+ *          for the agent's typed event stream.
+ * Role:    Outer ring (Hexagonal). Attach via `runner.attachScopeRecorder()`;
+ *          the runner emits events, recorders accumulate state.
+ *
+ * Three tiers (progressive disclosure):
+ *
+ *   Tier 1 — context + stream                                (the core)
+ *     • ContextRecorder      — every slot composition
+ *     • StreamRecorder       — token-level LLM streaming
+ *
+ *   Tier 2 — composition + agent                       (structural nav)
+ *     • CompositionRecorder  — Sequence/Parallel/Conditional/Loop entries
+ *     • AgentRecorder        — agent-loop iterations, tool calls
+ *     • BoundaryRecorder     — domain-tagged subflow entry/exit
+ *     • FlowchartRecorder    — StepGraph projection (Lens-friendly)
+ *
+ *   Tier 3 — domain dashboards                              (attach on demand)
+ *     • CostRecorder         — token/USD spend
+ *     • EvalRecorder         — eval scores from `runner.emit('eval.*', ...)`
+ *     • MemoryRecorder       — memory injections + writes
+ *     • PermissionRecorder   — permission decisions + denials
+ *     • SkillRecorder        — skill activations
+ *     • LoggingRecorder      — structured log lines per event
+ *     • StatusRecorder     — chat-bubble first-person status
+ *
+ * Domain-flavored consumers (Lens, Grafana, Datadog) compose Tier 1+2
+ * directly; Tier 3 dashboards are opt-in.
+ */
+export { ContextRecorder, type ContextRecorderOptions } from './recorders/core/ContextRecorder.js';
+export { streamRecorder, type StreamRecorderOptions } from './recorders/core/StreamRecorder.js';
+export { compositionRecorder, type CompositionRecorderOptions, } from './recorders/core/CompositionRecorder.js';
+export { agentRecorder, type AgentRecorderOptions } from './recorders/core/AgentRecorder.js';
+export { boundaryRecorder, BoundaryRecorder, type ActorArrow, type BoundaryAggregate, type BoundaryRecorderOptions, type BoundaryRangeLabel, type DomainContextInjectedEvent, type DomainDecisionBranchEvent, type DomainEvent, type DomainForkBranchEvent, type DomainLLMEndEvent, type DomainLLMStartEvent, type DomainLoopIterationEvent, type DomainRunEvent, type DomainSubflowEvent, type DomainToolStartEvent, type DomainToolEndEvent, } from './recorders/observability/BoundaryRecorder.js';
+export { buildRunSteps, RunStepRecorder, runStepRecorder, type BuildRunStepsOptions, type RunStep, type RunStepGraph, type RunStepKind, type RunStepMeta, type RunStepRecorderOptions, type RunStepTransition, } from './recorders/observability/RunStepRecorder.js';
+export { attachFlowchart, buildStepGraph, buildStepGraphFromEvents, type StepGraph, type StepNode, type StepEdge, type SlotBoundary, type ContextInjection, type FlowchartOptions, type FlowchartHandle, } from './recorders/observability/FlowchartRecorder.js';
+export { serializeTrace, redactContent, traceToStepGraph, type Trace, type TraceSummary, type TraceRedaction, type SerializeTraceOptions, } from './recorders/observability/trace.js';
+export { attachLocalObservability, type LocalObservabilityHandle, type LocalObservabilityOptions, } from './recorders/observability/localObservability.js';
+export { liveStateRecorder, LiveStateRecorder, LiveLLMTracker, LiveToolTracker, LiveAgentTurnTracker, type LLMLiveState, type ToolLiveState, type AgentTurnLiveState, type LiveStateRunnerLike, } from './recorders/observability/LiveStateRecorder.js';
+export { costRecorder, type CostRecorderOptions } from './recorders/core/CostRecorder.js';
+export { toolsRecorder, type ToolsRecorderOptions } from './recorders/core/ToolsRecorder.js';
+export { contextEvaluatedRecorder, type ContextEvaluatedRecorderOptions, } from './recorders/core/ContextEvaluatedRecorder.js';
+export { evalRecorder, type EvalRecorderOptions } from './recorders/core/EvalRecorder.js';
+export { memoryRecorder, type MemoryRecorderOptions } from './recorders/core/MemoryRecorder.js';
+export { permissionRecorder, type PermissionRecorderOptions, } from './recorders/core/PermissionRecorder.js';
+export { skillRecorder, type SkillRecorderOptions } from './recorders/core/SkillRecorder.js';
+export { attachLogging, LoggingDomains, type LoggingLogger, type LoggingDomain, type LoggingOptions, } from './recorders/observability/LoggingRecorder.js';
+export { attachStatus, type StatusEvent, type StatusOptions, } from './recorders/observability/StatusRecorder.js';
+export { toolLineageRecorder, type ToolLineageRecorderHandle, type ToolLineageOptions, type ToolLineageGraph, type ToolLineageEdge, type ToolCallRef, } from './recorders/observability/ToolLineageRecorder.js';
+export { agentThinkingTrace, type AgentThinkingTraceHandle, type AgentThinkingTraceOptions, type AttTrace, type AttStep, type AttCost, type AttAnswer, type AttToolSeen, } from './recorders/observability/AgentThinkingTraceRecorder.js';
+export { typedEmit } from './recorders/core/typedEmit.js';
+export { adaptWeights, averageRelevancy, compositeScore, contentHash, DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, DEFAULT_SHORTLIST_BAND, EmbeddingCache, embeddingCache, finalAnswerSimilarity, marginStrategy, pairwiseSimilarity, persistence, rankingConfidence, ratioStrategy, scoreContrastiveInfluence, scoreInfluence, scoreMargin, structuralProximity, type CandidateScore, type ConfidenceStrategy, type Embedder, type EmbeddingCacheOptions, type EmbeddingCacheStats, type EvidenceInput, type InfluenceScore, type InfluenceScorer, type InfluenceWeights, type MarginCandidate, type MarginResult, type PairwiseSimilarityArgs, type PairwiseSimilarityResult, type RankingConfidence, type RankingConfidenceOptions, type ScoreContrastiveInfluenceArgs, type ScoreInfluenceArgs, type ScoreMarginArgs, type SignalScores, type SimilarityItem, type SimilarityPair, } from './lib/influence-core/index.js';
+export { callTraceTool, lazyTraceToolpack, NO_COMPLETED_RUN_MESSAGE, TOOLPACK_HARD_CAPS, traceToolpack, type TraceToolpackArtifacts, type TraceToolpackOptions, } from './lib/trace-toolpack/index.js';
+export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding, traceDebugAgent, type SelfExplainOptions, type TraceDebugAgentOptions, } from './lib/trace-toolpack/index.js';
+export { ablationForSuspect, applyAblations, assembleTrajectory, assignCostVerdicts, bisectCulprits, bucketByAnchors, shortlistEarlyCulprits, walkToRoot, walkTrajectory, buildWriterFrameIndex, DEFAULT_RECENCY_DECAY, classifySuspect, findLoopHeads, CONTEXT_BISECT_DEFAULTS, defaultOutcomeComparator, defaultSuspectClassifier, findDroppedContext, formatContextBugReport, llmCallIdsFromEvents, llmEdgeWeigher, localizeContextBug, probeFlipped, runAblationProbe, runRestorationProbe, stepOutputText, suspectLabel, verdictFor, type AblationRerun, type AblationRunner, type AblationRunStats, type AblationSpec, type AblationTargets, type AblationVerdict, type AblationVerdictKind, type AnchorBucket, type AssembleTrajectoryOptions, type LoopCandidate, type LoopRecallShortlist, type ShortlistEarlyCulpritsOptions, type RootCauseHop, type RootCauseNote, type RootCausePath, type WalkToRootOptions, type BisectCulpritsOptions, type BisectionProbe, type BisectionResult, type CapturedEventLike, type ClassifyContext, type ContextBugArtifacts, type ContextBugReport, type ContextSource, type ContextUnit, type CostRange, type CostStats, type CostVerdict, type DroppedUnit, type EdgePathStep, type LoopFrame, type HonestyFlag, type HonestyFlagKind, type LlmEdgeWeigherHandle, type LlmEdgeWeigherOptions, type LocalizeContextBugOptions, type MissingContextResult, type OutcomeComparator, type QualityTriggerLookup, type RankedParentEdge, type RestorationProbeConfig, type RestorationRerun, type RestorationRunner, type RestoredCandidate, type RunCost, type SimilarityStats, type SliceStats, type Suspect, type SuspectClass, type SuspectClassifier, type SuspectDetail, type SuspectKind, type SuspectSeed, type SyntheticQuestionNode, type Trajectory, } from './lib/context-bisect/index.js';
+export { toBacktrackTrace, type BacktrackCustodyHop, type BacktrackHop, type BacktrackSuspectCard, type BacktrackTrace, type BacktrackTrail, type ToBacktrackTraceOptions, } from './lib/context-bisect/index.js';
+export { analyzeToolCatalog, catalogFromTools, coerceCatalog, confusabilityText, DEFAULT_CONFUSABILITY_THRESHOLD, DEFAULT_OMISSION_CUES, DEFAULT_WATCH_BAND, DEFAULT_WHEN_CUES, defaultStructuralRules, descriptionRule, differentiationHint, enumInProseRule, formatToolCatalogReport, MOCK_EMBEDDER_CALIBRATION, optionalParamRule, runToolLintCli, saysWhatNotWhenRule, type AnalyzeToolCatalogOptions, type CatalogTool, type ConfusablePairFinding, type DescriptionRuleOptions, type FormatReportOptions, type LintRule, type LintSeverity, type OptionalParamRuleOptions, type PairVerdict, type SaysWhatNotWhenRuleOptions, type SimilarityReport, type StructuralFinding, type ToolCatalogReport, type ToolLintCliIO, } from './lib/tool-lint/index.js';
+export { buildChoiceContext, toolChoiceRecorder, type OfferedTool, type ToolChoiceCall, type ToolChoiceRecorderHandle, type ToolChoiceRecorderOptions, type ToolChoiceSkipReason, type ToolChoiceSummary, } from './recorders/observability/ToolChoiceRecorder.js';
+export { routeRecorder, formatRouteHop, type RouteRecorderHandle, type RouteRecorderOptions, type RouteHop, type RouteOutcome, type RouteTrip, type RouteTripKind, } from './recorders/observability/RouteRecorder.js';

package/dist/esm/patterns/Debate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Debate — two agents alternate proposing + critiquing, a judge decides.
+ *
+ * Paper: "Improving Factuality and Reasoning in Language Models through
+ *        Multiagent Debate" — Du et al., 2023
+ *        (https://arxiv.org/abs/2305.14325).
+ *
+ * Pattern: Factory → produces a `Runner` built from
+ *          `Sequence(Proposer → Critic → Judge)` by default, or an
+ *          iterated `Loop(Sequence(…))` when `rounds > 1`.
+ * Role:    patterns/ layer.
+ * Emits:   Everything Sequence + Loop + LLMCall emit.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface DebateOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** Proposer persona — asserts a position given the question. */
+    readonly proposerPrompt: string;
+    /** Critic persona — argues against the proposer's position. */
+    readonly criticPrompt: string;
+    /** Judge persona — reads the debate transcript, returns the verdict. */
+    readonly judgePrompt: string;
+    /** Rounds of propose+critique before the judge weighs in. Default 1. */
+    readonly rounds?: number;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a Debate Runner. One debate "round" = Proposer → Critic. After
+ * N rounds, the Judge sees the final exchange and renders the verdict.
+ * The Judge's output is the Runner's return value.
+ */
+export declare function debate(opts: DebateOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/MapReduce.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MapReduce — fan-out N LLMCalls over deterministic input shards, reduce.
+ *
+ * Origin: classic map-reduce (Dean & Ghemawat, 2004) applied to
+ *         LLM context-window constraints. Seen in long-document
+ *         summarization: split → summarize each → combine.
+ *
+ * Pattern: Factory → produces a Runner composing `Parallel` of N
+ *          shard-aware branches. Each branch is an LLMCall wrapped so it
+ *          extracts its shard index from the input by position.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *
+ * Shard count is fixed at build time — consumer supplies `shardCount`
+ * and a `split(input, shardCount)` function that MUST return exactly
+ * `shardCount` strings. The extracted strings are packed into one
+ * `message` at run time (delimiter `\u001F`) so each branch can pick
+ * its own index. For run-time-variable shard counts, factor MapReduce
+ * inside a wrapping Runner that rebuilds the Parallel per call.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+import type { MergeFn, MergeWithLLMOptions } from '../core-flow/Parallel.js';
+export interface MapReduceOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** System prompt applied to every shard's LLMCall. */
+    readonly mapPrompt: string;
+    /**
+     * Number of shards to fan out. Must be >= 2 (for one-shard, use
+     * `LLMCall` directly). Fixed at build time.
+     */
+    readonly shardCount: number;
+    /**
+     * Splitter invoked at run time with `(input, shardCount)`. MUST return
+     * exactly `shardCount` strings. If it returns fewer, remaining shards
+     * receive empty strings; more are truncated.
+     */
+    readonly split: (input: string, shardCount: number) => readonly string[];
+    /**
+     * Reducer — either a pure fn combining the N shard outputs, OR an LLM
+     * synthesizer.
+     */
+    readonly reduce: {
+        readonly kind: 'fn';
+        readonly fn: MergeFn;
+    } | {
+        readonly kind: 'llm';
+        readonly opts: MergeWithLLMOptions;
+    };
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a MapReduce Runner. At run time:
+ *   1. The splitter runs the consumer's `split(input, shardCount)` and
+ *      packs the resulting N shards into a delimited string.
+ *   2. Parallel fans out to N branches. Each branch's wrapper extracts
+ *      its own shard from the packed input and feeds it to the shared
+ *      LLMCall.
+ *   3. The reducer combines the N branch outputs into the final string.
+ */
+export declare function mapReduce(opts: MapReduceOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/Reflection.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reflection — iterative self-refinement via critic + revise.
+ *
+ * Paper: "Self-Refine: Iterative Refinement with Self-Feedback" —
+ *        Madaan et al., 2023 (https://arxiv.org/abs/2303.17651).
+ *
+ * Pattern: Factory (GoF) → produces a `Runner` built from a `Loop`
+ *          whose body is `Sequence(Propose → Critique → Revise)`.
+ * Role:    patterns/ layer. Pure composition — no new abstractions.
+ * Emits:   Loop's composition.iteration_start / iteration_exit plus
+ *          every inner LLMCall's stream.llm_start/end.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface ReflectionOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** System prompt for the initial / revision proposer. */
+    readonly proposerPrompt: string;
+    /**
+     * System prompt for the critic. Should instruct the critic to return
+     * "DONE" (or a consumer-chosen sentinel) when the proposal is good
+     * enough — that string is checked by `untilCritiqueContains` to stop
+     * the refinement loop.
+     */
+    readonly criticPrompt: string;
+    /**
+     * Stop string the critic should emit when satisfied. When the critic's
+     * response contains this substring, the loop exits and the last
+     * proposal is returned. Default: 'DONE'.
+     */
+    readonly untilCritiqueContains?: string;
+    /** Max refinement iterations. Default 3. */
+    readonly maxIterations?: number;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a Reflection Runner. Each iteration:
+ *   1. Propose — LLMCall writes a candidate answer based on the input
+ *   2. Critique — LLMCall judges the candidate; exit marker stops loop
+ *   3. Revise — next iteration's propose sees the previous critique
+ *
+ * Each iteration's output (the candidate proposal) becomes the next
+ * iteration's input. The final iteration's proposal is returned.
+ */
+export declare function reflection(opts: ReflectionOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/SelfConsistency.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SelfConsistency — sample N answers, pick the majority.
+ *
+ * Paper: "Self-Consistency Improves Chain of Thought Reasoning in
+ * Language Models" — Wang et al., 2022 (https://arxiv.org/abs/2203.11171).
+ *
+ * Pattern: Factory (GoF) → produces a `Runner` that composes `Parallel`
+ *          of N `LLMCall` branches with a majority-vote merge function.
+ * Role:    patterns/ layer. Pure composition of core primitives +
+ *          core-flow compositions — no new abstractions.
+ * Emits:   Everything `Parallel` + `LLMCall` emit (stream / composition /
+ *          context). No pattern-specific event domain needed; consumers
+ *          observe via the standard typed listeners.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface SelfConsistencyOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly systemPrompt: string;
+    /** Number of parallel samples. 3 / 5 are typical; paper uses up to 40. */
+    readonly samples: number;
+    /** Sampling temperature. Defaults to a higher value (0.7) to get diverse samples. */
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    /**
+     * Consumer-provided extractor: given a full LLM response, return the
+     * "vote token" (e.g., the final answer stripped of the chain-of-thought
+     * preamble). Defaults to returning the trimmed string.
+     */
+    readonly extract?: (response: string) => string;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a SelfConsistency Runner. Given a system prompt, the Runner
+ * runs `samples` parallel LLMCalls with the same input, extracts each
+ * response's vote token, then returns the most-frequent token. Ties
+ * are broken by the first response's extract.
+ */
+export declare function selfConsistency(opts: SelfConsistencyOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/Swarm.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Swarm — multi-agent handoff. At each step, an LLM-driven routing
+ * decision picks which agent handles the next turn.
+ *
+ * Origin: OpenAI Swarm experiment (2024). Useful for specialist
+ *         routing — each agent has a narrow role + its own tools.
+ *
+ * Pattern: Factory → produces a `Runner` built from
+ *          `Loop(Conditional(route-to-agent))`.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *          Agent roster is FIXED at build time; the routing decision
+ *          is made at runtime by a consumer-supplied `route(input)`
+ *          function (sync — pure over `{ message }`).
+ *
+ * For LLM-driven routing (the classic Swarm style), the consumer
+ * composes a "router" LLMCall as the first step of each iteration and
+ * parses its response in their `route()` function.
+ */
+import type { Runner } from '../core/runner.js';
+export interface SwarmAgent {
+    /** Stable id used in events + routing decisions. */
+    readonly id: string;
+    /** Display name for topology / narrative. */
+    readonly name?: string;
+    /** The runner that handles a turn when selected. */
+    readonly runner: Runner<{
+        message: string;
+    }, string>;
+}
+export interface SwarmOptions {
+    /**
+     * The fixed agent roster. Must contain >= 2 agents. The order doesn't
+     * matter — the `route` function selects by id.
+     */
+    readonly agents: readonly SwarmAgent[];
+    /**
+     * Routing function — receives the current message and returns the
+     * selected agent's id. Pure sync; evaluated before each iteration's
+     * chosen agent runs. Return `undefined` or an unknown id to halt
+     * the swarm (the loop's `until` guard fires).
+     */
+    readonly route: (input: {
+        readonly message: string;
+    }) => string | undefined;
+    /** Max hand-offs before the loop halts. Default 10. */
+    readonly maxHandoffs?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a Swarm Runner. Each iteration:
+ *   1. Router evaluates `route(input)` to pick an agent id.
+ *   2. Conditional dispatches to that agent's runner.
+ *   3. Agent's output becomes the next iteration's input.
+ * Loop halts when `route` returns a halt-sentinel id (or unknown id
+ * falling to the `done` branch) OR when `maxHandoffs` is reached.
+ */
+export declare function swarm(opts: SwarmOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/ToT.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ToT — Tree of Thoughts: breadth-first iterative expansion + pruning.
+ *
+ * Paper: "Tree of Thoughts: Deliberate Problem Solving with Large
+ *        Language Models" — Yao et al., 2023
+ *        (https://arxiv.org/abs/2305.10601).
+ *
+ * Pattern: Factory → produces a `Runner` built from `Loop(depth times,
+ *          Parallel(K thought branches) + prune-to-top-M)`.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *          Build-time-fixed depth + branching factor; runtime frontier
+ *          is pruned to `beamWidth` per level via a consumer-supplied
+ *          scorer.
+ *
+ * Tradeoff vs. full DFS: this shipped variant is BFS with constant
+ * width. True DFS with backtracking or adaptive branching factor would
+ * need runtime-variable Parallel (DynamicParallel) or recursion.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface ToTOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** System prompt for the thought-generation LLMCall. */
+    readonly thoughtPrompt: string;
+    /** Depth of the tree (number of expansion iterations). */
+    readonly depth: number;
+    /** Branching factor — K thoughts generated per frontier node per iteration. */
+    readonly branchingFactor: number;
+    /**
+     * Scorer: given a thought, return a numeric score. Higher is better.
+     * The top `beamWidth` thoughts survive each level; the rest are pruned.
+     * Synchronous so pruning is deterministic.
+     */
+    readonly score: (thought: string) => number;
+    /** Beam width — how many thoughts survive after each level. Default 1 (greedy). */
+    readonly beamWidth?: number;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a ToT Runner. At run time:
+ *   1. Seed — treat the input message as the initial frontier of 1 thought.
+ *   2. For each of `depth` iterations:
+ *      a. Parallel fan-out: generate `branchingFactor` new thoughts.
+ *      b. Score all new thoughts, keep top `beamWidth`, pass to next iteration.
+ *   3. Return the single best-scoring thought from the final frontier.
+ */
+export declare function tot(opts: ToTOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * patterns/ — factory functions that compose primitives + core-flow
+ * into well-known agent patterns from the research literature.
+ *
+ * Each pattern is:
+ *   - A factory function returning a `Runner` — drops into any
+ *     `Sequence.step()`, `Parallel.branch()`, etc.
+ *   - Purely composed — no new primitives, no state machinery beyond
+ *     what the underlying compositions provide.
+ *   - Documented with the canonical paper reference.
+ *
+ * Build-time-fixed cardinality: all patterns take a FIXED
+ * shard/branch/agent count at build time. Run-time-variable branching
+ * is a separate (not-yet-shipped) feature and would need a
+ * `DynamicParallel` primitive.
+ */
+export { selfConsistency, type SelfConsistencyOptions } from './SelfConsistency.js';
+export { reflection, type ReflectionOptions } from './Reflection.js';
+export { debate, type DebateOptions } from './Debate.js';
+export { mapReduce, type MapReduceOptions } from './MapReduce.js';
+export { tot, type ToTOptions } from './ToT.js';
+export { swarm, type SwarmOptions, type SwarmAgent } from './Swarm.js';

package/dist/esm/providers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * LLM provider adapters — implementation behind the `agentfootprint/llm-providers`
+ * subpath (which re-exports this file).
+ *
+ * The standalone `agentfootprint/providers` subpath alias was removed in 4.0.0.
+ * Import from the canonical subpath:
+ *
+ *   import { mock, anthropic, openai } from 'agentfootprint/llm-providers';
+ *
+ * Pattern: Adapter (GoF) — concrete `LLMProvider` implementations that
+ *          translate the agentfootprint port to a specific vendor SDK.
+ * Role:    Outer ring (Hexagonal). Swappable at runtime; the Agent
+ *          knows nothing about vendor specifics.
+ *
+ * What's here today:
+ *   • `mock` / `MockProvider` — deterministic + realistic-mode mock
+ *   • `anthropic` / `AnthropicProvider` — real provider (Claude)
+ *   • `openai` / `OpenAIProvider` — real provider (GPT)
+ *
+ * Bring your own (BYO):
+ *   For Bedrock / Ollama / Cohere / on-prem / fine-tuned models,
+ *   implement the `LLMProvider` interface (see `LLMProvider` exported
+ *   from the main barrel) — `complete()` is required, `stream()` is
+ *   optional. The `MockProvider` source is the canonical reference.
+ */
+export { MockProvider, mock, type MockProviderOptions, type LatencyMs, } from './adapters/llm/MockProvider.js';
+export { anthropic, AnthropicProvider, type AnthropicProviderOptions, } from './adapters/llm/AnthropicProvider.js';
+export { openai, OpenAIProvider, ollama, azureOpenai, type OpenAIProviderOptions, type AzureOpenAIProviderOptions, } from './adapters/llm/OpenAIProvider.js';
+export { bedrock, BedrockProvider, type BedrockProviderOptions, } from './adapters/llm/BedrockProvider.js';
+export { browserAnthropic, BrowserAnthropicProvider, type BrowserAnthropicProviderOptions, } from './adapters/llm/BrowserAnthropicProvider.js';
+export { browserOpenai, BrowserOpenAIProvider, type BrowserOpenAIProviderOptions, } from './adapters/llm/BrowserOpenAIProvider.js';
+export { createProvider, type ProviderKind, type CreateProviderOptions, } from './adapters/llm/createProvider.js';
+export type { LLMProvider, LLMRequest, LLMResponse, LLMChunk, LLMMessage, LLMToolSchema, } from './adapters/types.js';

package/dist/esm/recorders/core/AgentRecorder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AgentRecorder — forwards `agentfootprint.agent.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the agent-lifecycle bridge recorder.
+ *          Same mechanics as StreamRecorder, scoped to agent.* events
+ *          (turns + iterations + route decisions + handoffs).
+ * Emits:   agentfootprint.agent.turn_start / turn_end / iteration_start /
+ *          iteration_end / route_decided / handoff
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type AgentRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function agentRecorder(options: AgentRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/CompositionRecorder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CompositionRecorder — forwards `agentfootprint.composition.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the composition-domain bridge recorder.
+ *          Compositions (Sequence, Parallel, Conditional, Loop) typedEmit
+ *          composition.enter/exit/fork_start/branch_complete/merge_end/
+ *          route_decided/iteration_start/iteration_exit from their internal
+ *          stages; this recorder observes via footprintjs's EmitRecorder
+ *          channel and re-dispatches with typed payloads + meta.
+ * Emits:   agentfootprint.composition.*
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type CompositionRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function compositionRecorder(options: CompositionRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ContextEvaluatedRecorder.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ContextEvaluatedRecorder — forwards the `agentfootprint.context.evaluated`
+ * emit to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    The InjectionEngine `typedEmit`s `context.evaluated` (the
+ *          "what was considered / active / skipped + why" summary). Unlike the
+ *          other `context.*` events — which `ContextRecorder` DISPATCHES by
+ *          observing scope writes — this one is emitted complete by the stage,
+ *          so it just needs forwarding (the EmitBridge pass-through pattern,
+ *          same as StreamRecorder / AgentRecorder).
+ * Why a full-name prefix: scoped to EXACTLY `agentfootprint.context.evaluated`
+ *          (not the whole `context.*` domain) so it never double-dispatches
+ *          `context.slot_composed`, which IS `typedEmit`'d in the viz chart
+ *          (`buildMessageApiChart`) while ALSO being dispatched by
+ *          `ContextRecorder` from writes in the runtime charts.
+ * Emits:   agentfootprint.context.evaluated
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ContextEvaluatedRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function contextEvaluatedRecorder(options: ContextEvaluatedRecorderOptions): EmitBridge;