agentfootprint 6.44.0 → 7.0.0

package/dist/esm/memory/wire/mountMemoryPipeline.d.ts

@@ -0,0 +1,108 @@
+/**
+ * mountMemoryPipeline — mount a MemoryPipeline's read + write subflows
+ * into an arbitrary agent flowchart.
+ *
+ * Given:
+ *   - a `FlowChartBuilder<AgentState>` the caller has been assembling,
+ *   - a `MemoryPipeline { read, write }` (typically from a preset),
+ *   - identity + turn + budget inputs sourced from agent scope,
+ *   - mount points (which stage id to insert the read subflow before),
+ *
+ * returns the builder with:
+ *   1. the `read` subflow mounted BEFORE the given anchor stage, with an
+ *      inputMapper that reads identity/turn/budget from agent scope and
+ *      an outputMapper that writes `formatted` messages back,
+ *   2. the `write` subflow (if present) appended AT THE END, with an
+ *      inputMapper that reads `newMessages` from agent scope.
+ *
+ * The agent's existing stages are responsible for:
+ *   - populating `identity`, `turnNumber`, `contextTokensRemaining`,
+ *     `newMessages` in scope BEFORE the relevant memory subflow runs,
+ *   - consuming the injected `formatted` messages (merge into the
+ *     agent's outgoing LLM prompt).
+ *
+ * This helper does NOT own any of those concerns — it owns only the
+ * mechanical subflow mounting. Consumer-facing API
+ * (`AgentBuilder.memoryPipeline()`) is layered on top.
+ *
+ * Why a standalone helper, not a direct `AgentBuilder` patch?
+ *   - Lets us test the wire mechanism end-to-end in isolation (Layer 6)
+ *     without changing the existing AgentRunner path (100+ tests).
+ *   - The wire is a small, reviewable unit; the AgentBuilder refactor is
+ *     a larger concern that can ship separately.
+ *   - Future non-Agent concepts (Swarm, Parallel) can use the same helper
+ *     — memory isn't tied to Agent conceptually.
+ */
+import type { FlowChartBuilder } from 'footprintjs';
+import type { MemoryPipeline } from '../pipeline/types.js';
+/**
+ * Keys this helper reads from / writes to on the parent agent scope.
+ * Kept as fields on the config so consumers with non-standard field names
+ * can override without renaming scope properties.
+ */
+export interface MountMemoryPipelineConfig<ParentState> {
+    /** The compiled read + write subflows from a pipeline preset. */
+    readonly pipeline: MemoryPipeline;
+    /**
+     * Scope field name the read subflow reads identity from. Default
+     * `'identity'` — matches `MemoryState.identity`. Override when the
+     * host flowchart uses a different name.
+     */
+    readonly identityKey?: keyof ParentState & string;
+    /** Scope field name for the turn counter. Default `'turnNumber'`. */
+    readonly turnNumberKey?: keyof ParentState & string;
+    /**
+     * Scope field name for the context-tokens-remaining signal.
+     * Default `'contextTokensRemaining'`.
+     */
+    readonly contextTokensKey?: keyof ParentState & string;
+    /**
+     * Scope field the read subflow writes its `formatted` output to.
+     * Default `'memoryInjection'` — agent stages consume this to prepend
+     * to the LLM prompt. Distinct from the pipeline's own `formatted`
+     * field so there's no ambiguity between subflow-local and parent scope.
+     */
+    readonly injectionKey?: keyof ParentState & string;
+    /**
+     * Scope field the write subflow reads messages to persist from.
+     * Default `'newMessages'` — populated by the agent at turn end.
+     */
+    readonly newMessagesKey?: keyof ParentState & string;
+    /** Subflow id for the read mount. Default `'sf-memory-read'`. */
+    readonly readSubflowId?: string;
+    /** Subflow id for the write mount. Default `'sf-memory-write'`. */
+    readonly writeSubflowId?: string;
+    /**
+     * Evidence source for CAUSAL pipelines (the evidence bridge, backlog #5).
+     * Called by the write mount's inputMapper at write time; its result lands on
+     * `MemoryState.runEvidence` so `writeSnapshot` persists real decisions /
+     * tool calls / iterations / duration / token usage instead of zeros. The
+     * Agent threads `causalEvidenceRecorder().collect` here automatically when a
+     * CAUSAL memory is mounted. Omit for non-causal pipelines.
+     */
+    readonly evidenceSource?: () => import('../causal/evidenceRecorder.js').RunEvidence;
+}
+/**
+ * Mount only the READ subflow. Appends at the current builder tail, so
+ * callers typically invoke this BEFORE their LLM-call stage:
+ *
+ *   let b = flowChart('Seed', seedFn, 'seed');
+ *   b = mountMemoryRead(b, { pipeline });
+ *   b = b.addFunction('CallLLM', llmStage, 'call-llm');   // reads memoryInjection
+ *   b = mountMemoryWrite(b, { pipeline });                // persists newMessages
+ *
+ * Returns the same builder reference (fluent).
+ */
+export declare function mountMemoryRead<ParentState>(builder: FlowChartBuilder<ParentState>, config: MountMemoryPipelineConfig<ParentState>): FlowChartBuilder<ParentState>;
+/**
+ * Mount only the WRITE subflow. No-op when the pipeline has no `write`
+ * (e.g., ephemeral pipelines) — returns the builder unchanged.
+ */
+export declare function mountMemoryWrite<ParentState>(builder: FlowChartBuilder<ParentState>, config: MountMemoryPipelineConfig<ParentState>): FlowChartBuilder<ParentState>;
+/**
+ * Convenience: mount both read and write subflows back-to-back.
+ * Appropriate ONLY when the host flowchart has no stages between memory
+ * read and memory write (rare — most agents have the LLM call between).
+ * Prefer `mountMemoryRead` + stages + `mountMemoryWrite` for typical agents.
+ */
+export declare function mountMemoryPipeline<ParentState>(builder: FlowChartBuilder<ParentState>, config: MountMemoryPipelineConfig<ParentState>): FlowChartBuilder<ParentState>;

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

@@ -0,0 +1,37 @@
+/**
+ * agentfootprint/memory-providers — memory store adapters (canonical subpath).
+ *
+ * The Block B canonical name. Mirrors the parallel structure shipped in
+ * v2.5:
+ *
+ *   agentfootprint/llm-providers     ← LLM provider adapters
+ *   agentfootprint/tool-providers    ← tool dispatch + tool sources
+ *   agentfootprint/memory-providers  ← memory store adapters (this file)
+ *   agentfootprint/security          ← cross-cutting authorization
+ *
+ * One subpath that grows — RedisStore, AgentCoreStore, and future
+ * stores (DynamoDB, Postgres, Pinecone, …) all live here. No more
+ * adding `agentfootprint/memory-<vendor>` per-adapter subpath each
+ * time a new store ships.
+ *
+ * Per-adapter aliases (`agentfootprint/memory-redis`,
+ * `agentfootprint/memory-agentcore`) stay available through the v2.x
+ * line — they point at the same files. New code SHOULD import from
+ * `agentfootprint/memory-providers`:
+ *
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ *
+ * Pattern: Adapter (GoF) — each store translates the `MemoryStore`
+ *          interface onto a specific backend (Redis, DynamoDB-style
+ *          AWS Bedrock AgentCore Memory, etc.).
+ * Role:    Outer ring (Hexagonal). All store adapters lazy-require
+ *          their vendor SDKs at construction time, so importing this
+ *          barrel costs ZERO peer-dep load — only the stores you
+ *          actually instantiate pull their SDK in.
+ *
+ * @example
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ */
+export { RedisStore, type RedisStoreOptions, type RedisLikeClient, type RedisLikePipeline, } from './adapters/memory/redis.js';
+export { AgentCoreStore, type AgentCoreStoreOptions, type AgentCoreLikeClient, } from './adapters/memory/agentcore.js';
+export { BedrockAgentMemory, type BedrockAgentMemoryOptions, type BedrockAgentMemoryLikeClient, type BedrockAgentSummary, } from './adapters/memory/bedrockAgentMemory.js';

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

@@ -0,0 +1,19 @@
+/**
+ * compareFinders — run several finders on the same case and collect their answers
+ * side by side (a leaderboard row per finder). PARAMETRIC: you pass the finders to
+ * compare, so nothing is auto-discovered or retained — unused finders stay
+ * tree-shakeable.
+ */
+import type { Finder, FindInput, FindResult } from './types.js';
+/** One finder's result in a comparison (or the error it threw). */
+export interface CompareRow {
+    readonly finder: string;
+    readonly result: FindResult | null;
+    readonly error?: string;
+}
+/**
+ * Run each finder on `input`; a finder that throws (e.g. missing a dep it needs)
+ * becomes a row with `result: null` and `error` set, so one finder cannot abort
+ * the comparison.
+ */
+export declare function compareFinders(finders: readonly Finder[], input: FindInput): Promise<CompareRow[]>;

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

@@ -0,0 +1,22 @@
+/**
+ * observability / contextError / finders — pluggable context-bug localization.
+ *
+ * "Which piece of context made the agent's answer wrong?" Pick a finder and call
+ * `find(input)`. Each finder is a thin, self-explaining 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.
+ *
+ *   import { rankSuspects } from 'agentfootprint/observability/contextError/finders';
+ *   const r = await rankSuspects.find(input);   // r.lead, r.evidence ('guessed'|'proven')
+ *
+ * Tree-shakeable: one finder = one file = one named export. Importing one finder does
+ * not pull the others (or the heavy ablation path behind removeAndRetry). This barrel
+ * is re-export-only — no runtime code, no registry.
+ */
+export type { ContextPiece, Evidence, Finder, FinderMeta, FindInput, FindResult, Granularity, ScoredSuspect, StepInput, } from './types.js';
+export { rankSuspects } from './rankSuspects.js';
+export { removeAndRetry } from './removeAndRetry.js';
+export { traceSteps } from './traceSteps.js';
+export { testManyCombos } from './testManyCombos.js';
+export { shrinkToCause } from './shrinkToCause.js';
+export { compareFinders, type CompareRow } from './compareFinders.js';

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

@@ -0,0 +1,2 @@
+import type { Finder } from './types.js';
+export declare const rankSuspects: Finder;

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

@@ -0,0 +1,11 @@
+/**
+ * removeAndRetry — the thorough finder. Removes each context piece, re-runs the
+ * agent, and a piece is the cause iff its removal flips the outcome back. No
+ * embedder, no heuristic: pure counterfactual. Exact, but pays one re-run per
+ * piece (`checks`), and on multi-loop runs it can over-attribute (several pieces
+ * each flip) — narrow with a slice first when that happens.
+ *
+ * Method: leave-one-out ablation (counterfactual necessity).
+ */
+import type { Finder } from './types.js';
+export declare const removeAndRetry: Finder;

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

@@ -0,0 +1,11 @@
+/**
+ * shrinkToCause — keeps cutting the suspect set down until the smallest subset whose
+ * removal still fixes the answer. For a single dominant cause it converges in fewer
+ * re-runs than leave-one-out (delta-debugging minimization); for co-necessary causes it
+ * still returns the minimal recovering set, but may cost more probes than leave-one-out.
+ * The returned set is verified to recover by construction.
+ *
+ * Method: delta-debugging minimization (ddmin) over the removal set that recovers.
+ */
+import type { Finder } from './types.js';
+export declare const shrinkToCause: Finder;

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

@@ -0,0 +1,11 @@
+/**
+ * testManyCombos — turns context pieces on and off in many combinations, re-runs each,
+ * and learns which pieces drive the wrong answer (a linear-surrogate attribution), then
+ * confirms the top candidate with one clean ablation. The sampling one: it estimates an
+ * influence weight per piece from counterfactual data rather than ranking by similarity.
+ *
+ * Method: random-subset ablation + linear-surrogate attribution. Deterministic
+ * pseudo-random masking (a reproducible reimplementation of ContextCite's random subsets).
+ */
+import type { Finder } from './types.js';
+export declare const testManyCombos: Finder;

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

@@ -0,0 +1,2 @@
+import type { Finder } from './types.js';
+export declare const traceSteps: Finder;

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,57 @@
+/**
+ * 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 * from "./debug.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/observe.js

@@ -64,42 +64,13 @@ export { toolLineageRecorder, } from './recorders/observability/ToolLineageRecor
 export { agentThinkingTrace, } from './recorders/observability/AgentThinkingTraceRecorder.js';
 // Emit primitive — used by every Tier-3 source-domain.
 export { typedEmit } from './recorders/core/typedEmit.js';
-// influence-core — the ONE embedding-based scoring engine (RFC-002/003
-// block D6). Not a recorder: pure, embedder-injected scoring functions
-// + the shared bounded embedding cache. Future /observe features build
-// on it (RFC-002 C1 catalog lint, C4/C5 margin recorder, RFC-003 D7
-// edge weigher). Honest claim: every score is an embedding-geometry
-// PROXY — semantic alignment, never model internals, never causal
-// attribution.
-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, } from './lib/influence-core/index.js';
-// Introspection toolpack (RFC-003 Part C) — footprintjs trace evidence
-// exposed as TOOLS a debugging LLM calls over a COMPLETED run's artifacts.
-// Bounded, honest (⚠ markers), redaction-respecting, id-navigable.
-export { callTraceTool, lazyTraceToolpack, NO_COMPLETED_RUN_MESSAGE, TOOLPACK_HARD_CAPS, traceToolpack, } from './lib/trace-toolpack/index.js';
-// The two conversational doors over the toolpack: a DEDICATED debugger
-// agent (separate session, any provider — cheap models welcome), and the
-// in-conversation `.selfExplain()` builder option's types. Same evidence,
-// same honesty discipline as the UI doors (BacktrackView / Lens).
-export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding, traceDebugAgent, } from './lib/trace-toolpack/index.js';
-// Contextual-bug localizer (RFC-003 Part B, D7–D9) — "git bisect for
-// context". Assembly: footprintjs causal DAG (control edges + honesty
-// markers + EdgeWeigher) × influence-core scoring (D6) × consumer-run
-// counterfactual ablation. §B2 claim tiers: scores/weights are
-// embedding-geometry PROXIES; ablation verdicts are the ONLY causal
-// claims; slice completeness is bounded by tracking — and says so.
-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, } from './lib/context-bisect/index.js';
-// BacktrackTrace serializer — feeds agentThinkingUI's <BacktrackView>
-// (the "why?" board) straight off a localizer report. Pure mapping, no
-// UI dependency; the interfaces mirror agentthinkingui's contract.
-export { toBacktrackTrace, } from './lib/context-bisect/index.js';
-// Tool-catalog confusability lint (RFC-002 tier 1, C1–C3) — build-time,
-// CI-gateable, framework-agnostic: plain { name, description?, inputSchema? }
-// tools in (OpenAI/Anthropic/MCP lists coerce via coerceCatalog; the
-// library's Tool[] via catalogFromTools), a report with a gateable `ok`
-// out. Pluggable structural rule pack; thresholds + embedder consumer-
-// injected with our defaults. Bin: `agentfootprint-lint-tools`.
-// Front door: docs/guides/tool-catalog-lint.md.
-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, } from './lib/tool-lint/index.js';
+// ── DEPRECATED (moved to agentfootprint/debug) ─────────────────
+// The diagnosis tools (influence-core, trace-toolpack, context-bisect,
+// tool-lint) moved to `agentfootprint/debug` in the surface cleanup, so the
+// import path matches the Debug docs category. They are re-exported here for
+// ONE transition version — import them from `agentfootprint/debug` instead.
+// They will be removed from `agentfootprint/observe` in the next major.
+export * from "./debug.js";
 // Tool-choice margin recorder (RFC-002 tier 2, C4–C6) — per LLM call,
 // ranks the OFFERED catalog against the choice context (user message +
 // latest assistant reasoning) via influence-core scoreMargin; embeds

package/dist/esm/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAgBjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAQhB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,EACd,wBAAwB,GAQzB,MAAM,gDAAgD,CAAC;AAExD,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,OAAO,EACL,cAAc,EACd,aAAa,EACb,gBAAgB,GAKjB,MAAM,oCAAoC,CAAC;AAE5C,mFAAmF;AACnF,OAAO,EACL,wBAAwB,GAGzB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,GAKrB,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,GAEzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,GAGb,MAAM,6CAA6C,CAAC;AACrD,4EAA4E;AAC5E,gFAAgF;AAChF,OAAO,EACL,mBAAmB,GAMpB,MAAM,kDAAkD,CAAC;AAC1D,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EACL,kBAAkB,GAQnB,MAAM,yDAAyD,CAAC;AAEjE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,cAAc,YAAY,CAAC;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAOnB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,aAAa,EACb,cAAc,GAOf,MAAM,4CAA4C,CAAC"}

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>;