agentfootprint 1.23.0 → 2.1.0

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

@@ -1,22 +1,23 @@
 /**
- * agentfootprint/patterns — canonical agent composition patterns.
+ * patterns/ — factory functions that compose primitives + core-flow
+ * into well-known agent patterns from the research literature.
  *
- * Each pattern is a thin factory over the existing concepts (`FlowChart`,
- * `Parallel`, `Conditional`, `Agent`, `LLMCall`, `RAG`, `Swarm`). No new
- * primitives. The source of each file shows the composition — read it to
- * learn how to build your own.
+ * 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.
  *
- * @example
- * ```ts
- * import { treeOfThoughts, reflexion, planExecute, mapReduce } from 'agentfootprint/patterns';
- * ```
+ * 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 { planExecute } from './planExecute';
-export type { PlanExecuteOptions } from './planExecute';
-export { mapReduce } from './mapReduce';
-export type { MapReduceOptions, MapReduceMapper, MapReduceReduceConfig } from './mapReduce';
-export { treeOfThoughts } from './treeOfThoughts';
-export type { TreeOfThoughtsOptions } from './treeOfThoughts';
-export { reflexion } from './reflexion';
-export type { ReflexionOptions } from './reflexion';
+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';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/patterns/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/providers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * agentfootprint/providers — LLM provider adapters.
+ *
+ * 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, type OpenAIProviderOptions, } 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';
+//# sourceMappingURL=providers.d.ts.map

package/dist/types/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,UAAU,EACV,aAAa,GACd,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,16 @@
+/**
+ * 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;
+//# sourceMappingURL=AgentRecorder.d.ts.map

package/dist/types/recorders/core/AgentRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/AgentRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC5E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAOvE"}

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

@@ -0,0 +1,18 @@
+/**
+ * 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;
+//# sourceMappingURL=CompositionRecorder.d.ts.map

package/dist/types/recorders/core/CompositionRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/CompositionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAClF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,UAAU,CAOnF"}

package/dist/types/recorders/core/ContextRecorder.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ContextRecorder — observes footprintjs subflow + scope events, emits
+ * grouped `context.*` domain events via the EventDispatcher.
+ *
+ * Pattern: Observer (GoF) + Pipes & Filters (Hohpe & Woolf, 2003).
+ * Role:    Core semantic grouping layer for the 3-slot model. Watches
+ *          slot subflows (sf-system-prompt / sf-messages / sf-tools) and
+ *          translates raw writes into context.injected / evicted /
+ *          slot_composed / budget_pressure events.
+ * Emits:   agentfootprint.context.injected
+ *          agentfootprint.context.evicted
+ *          agentfootprint.context.slot_composed
+ *          agentfootprint.context.budget_pressure
+ */
+import type { CombinedRecorder, FlowSubflowEvent, WriteEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+/**
+ * Supplies the recorder with run-level context. Passed at construction
+ * time (static fields) OR updated via `updateRunContext` between runs
+ * when reusing one recorder across multiple executor runs.
+ */
+export interface ContextRecorderOptions {
+    readonly dispatcher: EventDispatcher;
+    readonly id?: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class ContextRecorder implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly getRunContext;
+    private readonly slotStack;
+    private readonly seenInjections;
+    constructor(options: ContextRecorderOptions);
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onWrite(event: WriteEvent): void;
+    private currentSlot;
+    private handleInjectionsWrite;
+    private handleSlotComposedWrite;
+    private handleEvictionsWrite;
+    private handleBudgetPressureWrite;
+    private emitInjected;
+    private dispatch;
+    private asInjectionArray;
+    private asSlotComposition;
+    private asEvictionArray;
+    private asPressureArray;
+}
+//# sourceMappingURL=ContextRecorder.d.ts.map

package/dist/types/recorders/core/ContextRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/ContextRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAIlE,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAS5E;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,UAAU,CAAC;CAC1C;AAED,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAIjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAI/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;gBAErD,OAAO,EAAE,sBAAsB;IAQ3C,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAQ7C,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAa5C,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAyChC,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,uBAAuB;IAM/B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,eAAe;CAUxB"}

package/dist/types/recorders/core/CostRecorder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CostRecorder — forwards `agentfootprint.cost.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Bridges `cost.tick` + `cost.limit_hit` emits from LLMCall / Agent
+ *          stages (via `emitCostTick`) to the EventDispatcher so typed
+ *          consumer listeners fire.
+ * Emits:   agentfootprint.cost.tick / cost.limit_hit
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type CostRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function costRecorder(options: CostRecorderOptions): EmitBridge;
+//# sourceMappingURL=CostRecorder.d.ts.map

package/dist/types/recorders/core/CostRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CostRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC3E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,UAAU,CAOrE"}

package/dist/types/recorders/core/EmitBridge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * EmitBridge — forwards footprintjs emits whose name starts with a given
+ * prefix to the EventDispatcher, enriched with EventMeta.
+ *
+ * Pattern: Adapter (GoF) + Pipes & Filters (Hohpe & Woolf, 2003).
+ * Role:    Single reusable translation layer for every "pass-through"
+ *          prefix recorder (StreamRecorder, AgentRecorder, and any
+ *          future domain whose events are emitted via typedEmit()).
+ * Emits:   Any event whose name matches `prefix` — type derived from the
+ *          emit name and validated by the consumer's EventMap subscription.
+ */
+import type { CombinedRecorder, EmitEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+export interface EmitBridgeOptions {
+    readonly dispatcher: EventDispatcher;
+    /** Recorder id — must be unique among attached recorders. */
+    readonly id: string;
+    /** Event-name prefix this bridge forwards (e.g. 'agentfootprint.stream.'). */
+    readonly prefix: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class EmitBridge implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly prefix;
+    private readonly getRunContext;
+    constructor(options: EmitBridgeOptions);
+    onEmit(event: EmitEvent): void;
+}
+//# sourceMappingURL=EmitBridge.d.ts.map

package/dist/types/recorders/core/EmitBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmitBridge.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/EmitBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,UAAU,CAAC;CAC1C;AAED,qBAAa,UAAW,YAAW,gBAAgB;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;gBAErC,OAAO,EAAE,iBAAiB;IAOtC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;CAkB/B"}

package/dist/types/recorders/core/EvalRecorder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * EvalRecorder — forwards `agentfootprint.eval.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges consumer-emitted `eval.score` + `eval.threshold_crossed`
+ *          events to typed listeners. Evaluation is a consumer concern
+ *          (LLM-based grading, heuristic checks, reference-output diffs),
+ *          so the library only provides transport — not any built-in
+ *          evaluators.
+ * Emits:   agentfootprint.eval.score / eval.threshold_crossed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type EvalRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function evalRecorder(options: EvalRecorderOptions): EmitBridge;
+//# sourceMappingURL=EvalRecorder.d.ts.map

package/dist/types/recorders/core/EvalRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EvalRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/EvalRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC3E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,UAAU,CAOrE"}

package/dist/types/recorders/core/MemoryRecorder.d.ts

@@ -0,0 +1,18 @@
+/**
+ * MemoryRecorder — forwards `agentfootprint.memory.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges memory-layer events (strategy_applied, attached,
+ *          detached, written) emitted by consumer memory adapters.
+ *          The library does not ship a memory implementation; consumers
+ *          plug in their own store and emit these events where relevant
+ *          (e.g., before/after sliding-window summarization).
+ * Emits:   agentfootprint.memory.strategy_applied / attached /
+ *          detached / written
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type MemoryRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function memoryRecorder(options: MemoryRecorderOptions): EmitBridge;
+//# sourceMappingURL=MemoryRecorder.d.ts.map

package/dist/types/recorders/core/MemoryRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/MemoryRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAOzE"}

package/dist/types/recorders/core/PermissionRecorder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PermissionRecorder — forwards `agentfootprint.permission.*` emits
+ * to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges permission.check, permission.gate_opened, and
+ *          permission.gate_closed emits into the typed dispatcher so
+ *          consumer `.on('agentfootprint.permission.check', ...)`
+ *          listeners fire.
+ * Emits:   agentfootprint.permission.check / gate_opened / gate_closed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type PermissionRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function permissionRecorder(options: PermissionRecorderOptions): EmitBridge;
+//# sourceMappingURL=PermissionRecorder.d.ts.map

package/dist/types/recorders/core/PermissionRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/PermissionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IACjF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,UAAU,CAOjF"}

package/dist/types/recorders/core/SkillRecorder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SkillRecorder — forwards `agentfootprint.skill.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges skill lifecycle events (activated, deactivated) emitted
+ *          by consumer skill-management code. Skills are a consumer-owned
+ *          context-engineering concern; the library only provides transport.
+ * Emits:   agentfootprint.skill.activated / skill.deactivated
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type SkillRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function skillRecorder(options: SkillRecorderOptions): EmitBridge;
+//# sourceMappingURL=SkillRecorder.d.ts.map

package/dist/types/recorders/core/SkillRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/SkillRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC5E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAOvE"}

package/dist/types/recorders/core/StreamRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * StreamRecorder — forwards `agentfootprint.stream.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the stream-domain bridge recorder.
+ *          Stage code in LLMCall/Agent calls `typedEmit(scope, 'agentfootprint.stream.llm_start', {...})`;
+ *          this recorder observes via footprintjs's EmitRecorder channel
+ *          and re-dispatches with typed payloads + enriched meta.
+ * Emits:   agentfootprint.stream.llm_start / llm_end / token / tool_start / tool_end
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type StreamRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function streamRecorder(options: StreamRecorderOptions): EmitBridge;
+//# sourceMappingURL=StreamRecorder.d.ts.map

package/dist/types/recorders/core/StreamRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/StreamRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAOzE"}

package/dist/types/recorders/core/typedEmit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * typedEmit — typed facade over footprintjs's `scope.$emit(name, payload)`.
+ *
+ * Pattern: Facade (GoF) over an untyped API.
+ * Role:    Stage code inside LLMCall/Agent/slot subflows calls this helper
+ *          to emit events. The EventMap + TS generics reject typos and
+ *          payload drift at compile time; the runtime call is identical
+ *          to footprintjs's `$emit`.
+ * Emits:   Whatever `T` is — the consumer passes the type and payload.
+ */
+import type { AgentfootprintEventMap, AgentfootprintEventType } from '../../events/registry.js';
+/**
+ * Minimal scope surface we need to emit — structurally compatible with
+ * footprintjs's `TypedScope<T>`, whose `$emit(name, payload?: unknown)` is
+ * wider than this.
+ */
+interface EmitableScope {
+    $emit(name: string, payload?: unknown): void;
+}
+/**
+ * Emit a typed event from inside stage code.
+ *
+ * @example
+ *   typedEmit(scope, 'agentfootprint.stream.llm_start', {
+ *     iteration: 1,
+ *     provider: 'anthropic',
+ *     model: 'claude-opus-4-7',
+ *     systemPromptChars: 800,
+ *     messagesCount: 2,
+ *     toolsCount: 0,
+ *   });
+ */
+export declare function typedEmit<K extends AgentfootprintEventType>(scope: EmitableScope, type: K, payload: AgentfootprintEventMap[K]['payload']): void;
+export {};
+//# sourceMappingURL=typedEmit.d.ts.map

package/dist/types/recorders/core/typedEmit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedEmit.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/typedEmit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEhG;;;;GAIG;AACH,UAAU,aAAa;IACrB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,uBAAuB,EACzD,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAC5C,IAAI,CAEN"}

package/dist/types/recorders/core/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Recorder-layer types — shapes builders use to communicate with recorders.
+ *
+ * Pattern: Data Transfer Object (Fowler, PoEAA).
+ * Role:    Shared vocabulary between builders (which WRITE injections) and
+ *          recorders (which OBSERVE those writes and emit grouped events).
+ */
+import type { ContextLifetime, ContextRecency, ContextRole, ContextSlot, ContextSource } from '../../events/types.js';
+/**
+ * An injection record written by a slot subflow into `scope[INJECTION_KEYS[slot]]`.
+ * ContextRecorder reads this to construct the corresponding event payload.
+ *
+ * Builders write arrays of these; recorders diff old-vs-new to detect NEW
+ * injections.
+ */
+export interface InjectionRecord {
+    /** Short human-readable content summary. */
+    readonly contentSummary: string;
+    /** Full content (may be redacted downstream). Optional. */
+    readonly rawContent?: string;
+    /** Stable hash of the content — enables duplicate detection. */
+    readonly contentHash: string;
+    /** The 3-slot target (sanity-checked against the subflow ID). */
+    readonly slot: ContextSlot;
+    /** Where this content came from. */
+    readonly source: ContextSource;
+    /** Optional source-specific identifier (retriever id, skill id, ...). */
+    readonly sourceId?: string;
+    /** Upstream event reference (runtimeStageId that produced the content). */
+    readonly upstreamRef?: string;
+    /** Why this was injected. */
+    readonly reason: string;
+    /** Role, when injecting into messages slot. */
+    readonly asRole?: ContextRole;
+    /** Recency, when injecting into messages slot. */
+    readonly asRecency?: ContextRecency;
+    /** Position within the slot (messages index, system-prompt section order). */
+    readonly position?: number;
+    /** Section tag for structured system prompts (e.g. "<skill>", "<retrieved>"). */
+    readonly sectionTag?: string;
+    /** Retrieval / ranking evidence. */
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    readonly threshold?: number;
+    readonly budgetSpent?: {
+        readonly tokens: number;
+        readonly fractionOfCap: number;
+    };
+    /** How long this injection is expected to persist. */
+    readonly expiresAfter?: ContextLifetime;
+}
+/**
+ * Slot composition summary — written by a slot subflow at the END of its
+ * composition pass. ContextRecorder emits one `context.slot_composed`
+ * event per slot exit, built from this record.
+ */
+export interface SlotComposition {
+    readonly slot: ContextSlot;
+    readonly iteration: number;
+    readonly budget: {
+        readonly cap: number;
+        readonly used: number;
+        readonly headroomChars: number;
+    };
+    readonly sourceBreakdown: Readonly<Partial<Record<ContextSource, {
+        readonly chars: number;
+        readonly count: number;
+    }>>>;
+    readonly orderingStrategy?: string;
+    readonly droppedCount: number;
+    readonly droppedSummaries: readonly string[];
+}
+/**
+ * Eviction record — a piece that was removed from a slot under pressure.
+ */
+export interface EvictionRecord {
+    readonly slot: ContextSlot;
+    readonly contentHash: string;
+    readonly reason: 'budget' | 'stale' | 'low_score' | 'policy' | 'user_revoked';
+    readonly survivalMs: number;
+}
+/**
+ * Budget-pressure warning — emitted before evictions fire.
+ */
+export interface BudgetPressureRecord {
+    readonly slot: ContextSlot;
+    readonly capTokens: number;
+    readonly projectedTokens: number;
+    readonly overflowBy: number;
+    readonly planAction: 'evict' | 'summarize' | 'abort';
+}
+export declare const COMPOSITION_KEYS: {
+    readonly SLOT_COMPOSED: "slotCompositions";
+    readonly EVICTED: "slotEvictions";
+    readonly BUDGET_PRESSURE: "slotBudgetPressures";
+};
+export type CompositionKey = (typeof COMPOSITION_KEYS)[keyof typeof COMPOSITION_KEYS];
+//# sourceMappingURL=types.d.ts.map

package/dist/types/recorders/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/types.ts"],"names":[],"mappings":"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"}