agentfootprint 6.43.0 → 6.45.0

package/dist/esm/strategies/defaults/noopLens.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `noopLens()` — default LensStrategy.
+ *
+ * Pattern: Strategy. Wildcard fallback. Same role as `NoOpCacheStrategy`.
+ * Role:    Drops every update. Used when no Lens vendor strategy is
+ *          configured AND the consumer hasn't supplied a callback.
+ *          Keeps `enable.lens()` callable without args without
+ *          throwing — important for the zero-arg HelloWorld pattern.
+ *
+ * Use when:
+ *   - You want the agent to run without a Lens UI (production
+ *     server-side, headless eval, batch jobs)
+ *   - Tier-1 of compose chains where you want the chain to compile
+ *     even if the real Lens strategy is conditional
+ *
+ * Don't use when: you actually want to see the StepGraph. Use
+ * `lens-browser`, `lens-cli`, or `lens-jsonExport` from the
+ * vendor-strategy subpaths once they ship in v2.12+.
+ */
+import type { LensStrategy, LensUpdate } from '../types.js';
+export interface NoopLensOptions {
+    /**
+     * Optional callback called per update — useful for tests that want
+     * to verify the strategy was wired without actually rendering.
+     */
+    readonly onUpdate?: (update: LensUpdate) => void;
+}
+export declare function noopLens(opts?: NoopLensOptions): LensStrategy;

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

@@ -0,0 +1,36 @@
+/**
+ * `agentfootprint/strategies` — typed strategy interfaces + default
+ * sinks for the v2.8 grouped-enabler architecture.
+ *
+ * See:
+ *   - `docs/inspiration/strategy-everywhere.md` — design memo + AWS-first roadmap
+ *   - `types.ts` — typed interfaces (Observability, Cost, LiveStatus, Lens)
+ *   - `defaults/` — the 4 in-core default strategies
+ *
+ * Vendor strategies ship under three GROUPED subpaths (matching the
+ * parallel-providers pattern v2.5 established for `llm-providers` /
+ * `tool-providers` / `memory-providers`). Each subpath holds N
+ * vendor-named factories — adding a vendor never adds a new subpath:
+ *
+ *   - `agentfootprint/observability-providers`
+ *       agentcoreObservability (v2.8.1)
+ *       cloudwatchObservability (v2.8.2)
+ *       xrayObservability (v2.8.3)
+ *       otelObservability (v2.9.x)
+ *       datadogObservability (v2.9.x)
+ *
+ *   - `agentfootprint/cost-providers`
+ *       stripeCost (v2.10.x)
+ *
+ *   - `agentfootprint/lens-providers`
+ *       browserLens / cliLens (v2.12.x)
+ *
+ * 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`.
+ */
+export * from './types.js';
+export * from './defaults/index.js';
+export { composeObservability, composeCost, composeLiveStatus, composeLens } from './compose.js';
+export { attachObservabilityStrategy, attachCostStrategy, attachLiveStatusStrategy, type ObservabilityEnableOptions, type CostEnableOptions, type LiveStatusEnableOptions, } from './attach.js';

package/dist/esm/strategies/registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Strategy registry — name → factory for each of the 4 groups.
+ *
+ * Mirrors `src/cache/strategyRegistry.ts` exactly: maps a string name
+ * to a factory function that takes vendor-specific config and returns
+ * a typed strategy instance. Vendor adapter subpaths self-register on
+ * import via side-effect.
+ *
+ * Two ways consumers wire a strategy:
+ *
+ *   1. By NAME (registry lookup) — the recommended path for vendor
+ *      adapters:
+ *        ```ts
+ *        import 'agentfootprint/observability-datadog';  // self-registers 'datadog'
+ *        agent.enable.observability({ vendor: 'datadog', config: { apiKey } });
+ *        ```
+ *
+ *   2. By INSTANCE (explicit pass) — for custom in-house strategies
+ *      or test mocks:
+ *        ```ts
+ *        agent.enable.observability({ strategy: myCustomStrategy });
+ *        ```
+ *
+ * The two paths are mutually exclusive in `EnableOptions` — the type
+ * union enforces that consumers pick one.
+ *
+ * Lookup is exact-match by name (case-insensitive fallback). Unknown
+ * names return `undefined`; the consumer's `enable.X` then no-ops
+ * (per "do nothing if not configured" rule).
+ */
+import type { ObservabilityStrategy, CostStrategy, LiveStatusStrategy, LensStrategy } from './types.js';
+/** Vendor adapter subpaths register a factory keyed by their vendor
+ *  name. Config shape is vendor-specific — type-erased at the registry
+ *  boundary; consumer's responsibility to pass the right shape. */
+export type ObservabilityFactory = (config?: unknown) => ObservabilityStrategy;
+export type CostFactory = (config?: unknown) => CostStrategy;
+export type LiveStatusFactory = (config?: unknown) => LiveStatusStrategy;
+export type LensFactory = (config?: unknown) => LensStrategy;
+/**
+ * Register a vendor observability strategy by name. Called from the
+ * vendor's subpath at module load (side-effect import):
+ *
+ *   ```ts
+ *   // agentfootprint/observability-datadog/index.ts
+ *   import { registerObservabilityStrategy } from 'agentfootprint/strategies';
+ *   registerObservabilityStrategy('datadog', (config) => datadogObservability(config));
+ *   ```
+ *
+ * Replacing an existing registration is allowed — most-recent wins.
+ * Useful for test mocks.
+ */
+export declare function registerObservabilityStrategy(name: string, factory: ObservabilityFactory): void;
+/** Look up an observability factory by vendor name. Case-insensitive
+ *  fallback. Returns `undefined` when the name is unknown — caller
+ *  decides to noop or throw. */
+export declare function getObservabilityStrategy(name: string): ObservabilityFactory | undefined;
+/** Diagnostic — list all registered vendor names. */
+export declare function listObservabilityStrategies(): readonly string[];
+export declare function registerCostStrategy(name: string, factory: CostFactory): void;
+export declare function getCostStrategy(name: string): CostFactory | undefined;
+export declare function listCostStrategies(): readonly string[];
+export declare function registerLiveStatusStrategy(name: string, factory: LiveStatusFactory): void;
+export declare function getLiveStatusStrategy(name: string): LiveStatusFactory | undefined;
+export declare function listLiveStatusStrategies(): readonly string[];
+export declare function registerLensStrategy(name: string, factory: LensFactory): void;
+export declare function getLensStrategy(name: string): LensFactory | undefined;
+export declare function listLensStrategies(): readonly string[];
+/** Reset every registry to empty. Tests only — not in the public
+ *  barrel. */
+export declare function _resetRegistriesForTests(): void;

package/dist/esm/strategies/types.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Strategy interface types for the v2.8 grouped-enabler architecture.
+ *
+ * Pattern: Strategy + Bridge + Hexagonal port. See the design memo
+ *          `docs/inspiration/strategy-everywhere.md`.
+ *
+ * Four groups, four typed strategy interfaces. Each follows the same
+ * shape (one canonical contract, locked at the type level):
+ *
+ *   1. `name: string`            — registry key for auto-registration
+ *   2. `capabilities: {...}`     — what this strategy supports
+ *   3. `onEvent(...)`            — hot path; sync, side-effect-only
+ *   4. `flush?(): Promise<void>` — optional batch flushing
+ *   5. `stop?(): void`           — optional teardown
+ *
+ * Design constraints (from the panel review):
+ *   - **PASSIVE / non-blocking by construction.** Strategies are
+ *     observers — they NEVER block the agent loop. Async work
+ *     (HTTP shipment, disk I/O, batching) is the STRATEGY's internal
+ *     concern: buffer in `onEvent` (sync), drain in `flush()` (async
+ *     OK). The dispatcher never awaits a strategy's `onEvent`.
+ *   - `onEvent` MUST be sync `void`. MUST NOT throw. Errors caught +
+ *     routed to `_onError` at the dispatch layer; one bad strategy
+ *     never breaks the agent loop.
+ *   - Idempotent registration — registering the same `name` twice
+ *     replaces, doesn't double-fire.
+ *   - `stop()` is idempotent — halts everything that strategy enabled,
+ *     nothing else, calling twice is a no-op.
+ *   - `flush()` is optional, may be sync OR async — strategies that
+ *     don't batch can omit it. Consumer's `agent.run()` lifecycle
+ *     calls flush at boundary points (turn end, run end) so batched
+ *     strategies don't lose tail events. Flush is the ONLY async
+ *     path; the hot path is always sync.
+ */
+import type { AgentfootprintEvent, AgentfootprintEventType } from '../events/registry.js';
+import type { StepGraph } from '../recorders/observability/FlowchartRecorder.js';
+import type { StatusState } from '../recorders/observability/status/statusTemplates.js';
+/**
+ * Common base every strategy carries. Per-group strategies extend this
+ * with their typed `onEvent` signature + capability shape.
+ */
+export interface BaseStrategy {
+    /** Registry key. Conventionally lowercase-kebab: `'datadog'`,
+     *  `'agentcore'`, `'cloudwatch'`. Used to look up the strategy from
+     *  config + de-dupe registrations. */
+    readonly name: string;
+    /** Optional batch flush. Returns `void` for sync sinks (Pino-style)
+     *  OR `Promise<void>` for async sinks (Datadog HTTP batch, OTel
+     *  BatchSpanProcessor). Called before `agent.run()` resolves so
+     *  batched exporters don't lose tail events. */
+    flush?(): void | Promise<void>;
+    /** Optional teardown. Called on `stop()` returned by `enable.X`.
+     *  Idempotent — calling twice is a no-op. Strategies that open no
+     *  external resources can omit this. */
+    stop?(): void;
+    /**
+     * Optional event-type filter. When set, the dispatcher only forwards
+     * events whose `type` is in this set — saves the strategy from
+     * filtering itself + reduces hot-path allocations.
+     *
+     * Per AWS CloudWatch panel review: storage cost scales with size,
+     * strategies need to declare what they consume so the framework
+     * doesn't force them to inspect everything.
+     */
+    readonly relevantEventTypes?: readonly AgentfootprintEventType[];
+    /**
+     * Optional config validator. Called ONCE at registration time —
+     * throws if the strategy's options are invalid (wrong API key shape,
+     * missing peer dep, unreachable endpoint). Saves customer-support
+     * "why is my dashboard empty?" tickets.
+     *
+     * Per New Relic panel review.
+     */
+    validate?(): void;
+    /**
+     * Optional error sink. Called when this strategy itself errors —
+     * e.g., HTTP 401 from Datadog, malformed config in pino. Default
+     * dispatcher behavior is to swallow + log to console (so one bad
+     * exporter doesn't kill the agent loop). Consumers wire this when
+     * they want to surface vendor errors in their own tooling.
+     *
+     * Per New Relic panel review.
+     */
+    _onError?(error: Error, event?: AgentfootprintEvent): void;
+}
+/**
+ * Capabilities a strategy declares — matches OTel's 4-signal model
+ * (events / logs / traces / metrics). A strategy can opt into any
+ * subset. `compose([...])` ORs the children's capabilities.
+ *
+ *   - `events: true`   → wide structured events (Honeycomb / OTel
+ *                        events / Datadog wide events). agentfootprint
+ *                        events are this shape natively — most
+ *                        strategies should default to `events: true`.
+ *   - `logs: true`     → flat log records (pino, console, CloudWatch
+ *                        Logs). The strategy reduces a wide event to
+ *                        a single log line.
+ *   - `traces: true`   → strategy maps events to spans (parent/child
+ *                        via `runtimeStageId`).
+ *   - `metrics: true`  → strategy aggregates counters / gauges
+ *                        (CloudWatch metrics, Mimir, Prometheus).
+ */
+export interface ObservabilityCapabilities {
+    readonly events?: boolean;
+    readonly logs?: boolean;
+    readonly traces?: boolean;
+    readonly metrics?: boolean;
+}
+/**
+ * The single hot-path entry every observability strategy implements.
+ * Receives every typed agent event. MUST be sync + side-effect-only +
+ * non-throwing.
+ *
+ * Strategies that batch should buffer in `onEvent` and drain in
+ * `flush()`.
+ */
+export interface ObservabilityStrategy extends BaseStrategy {
+    readonly capabilities: ObservabilityCapabilities;
+    /**
+     * Translate the typed agentfootprint event into the vendor's wire
+     * format and ship it to the destination (Datadog API, OTel exporter,
+     * pino stream, CloudWatch PutLogEvents, etc.).
+     *
+     * MUST be sync `void`. Buffer internally; drain in `flush()`.
+     */
+    exportEvent(event: AgentfootprintEvent): void;
+}
+/**
+ * What a cost strategy receives every time the cost recorder fires.
+ * Carries enough info for the strategy to decide whether to ship to
+ * billing, log a warning, trigger a circuit breaker, etc.
+ */
+export interface CostTick {
+    readonly cumulativeInputTokens: number;
+    readonly cumulativeOutputTokens: number;
+    readonly cumulativeCostUsd: number;
+    readonly recentInputTokens: number;
+    readonly recentOutputTokens: number;
+    readonly recentCostUsd: number;
+    readonly model: string;
+    readonly iteration?: number;
+    readonly runtimeStageId?: string;
+}
+export interface CostCapabilities {
+    /** Strategy supports per-tick streaming. `false` for batch-only sinks. */
+    readonly streaming?: boolean;
+    /** Strategy supports budget enforcement (will throw / break the loop
+     *  when budget exceeded). Most strategies are observe-only. */
+    readonly enforcement?: boolean;
+}
+export interface CostStrategy extends BaseStrategy {
+    readonly capabilities: CostCapabilities;
+    /**
+     * Translate the cost tick into the vendor's wire format and ship it
+     * (Stripe billing API, accounting webhook, internal metrics sink).
+     *
+     * MUST be sync `void`. Buffer internally; drain in `flush()`.
+     */
+    recordCost(tick: CostTick): void;
+}
+/**
+ * What a status strategy receives every time `selectStatus`
+ * returns a new state. The renderer has already resolved templates to
+ * a final string; strategies decide where to send it.
+ */
+export interface StatusUpdate {
+    /** Rendered status line (already template-resolved). */
+    readonly line: string;
+    /** Underlying state for strategies that want to format their own
+     *  view (e.g., emit different colors per state in a TUI). */
+    readonly state: StatusState;
+}
+export interface LiveStatusCapabilities {
+    /** Strategy supports streaming partial tokens (vs only state
+     *  transitions). */
+    readonly streaming?: boolean;
+}
+export interface LiveStatusStrategy extends BaseStrategy {
+    readonly capabilities: LiveStatusCapabilities;
+    /**
+     * Render the rendered status line to the strategy's destination
+     * (chat bubble callback, stdout, webhook).
+     *
+     * MUST be sync `void`.
+     */
+    renderStatus(update: StatusUpdate): void;
+}
+/**
+ * What a Lens strategy receives — the live StepGraph each time the
+ * boundary recorder fires an event that changes the visible structure.
+ * Strategies decide how to render: DOM (browser), TUI (CLI), JSON
+ * (capture for replay).
+ */
+export interface LensUpdate {
+    readonly graph: StepGraph;
+    /** Whether this is the FINAL update (run finished). Strategies that
+     *  buffer for animation can flush here. */
+    readonly final: boolean;
+}
+export interface LensCapabilities {
+    /** Strategy renders to a UI (browser DOM, TUI). */
+    readonly interactive?: boolean;
+    /** Strategy serializes for replay / export. */
+    readonly serializable?: boolean;
+}
+export interface LensStrategy extends BaseStrategy {
+    readonly capabilities: LensCapabilities;
+    /**
+     * Render the live StepGraph to the strategy's destination (DOM,
+     * TUI, JSON serializer).
+     *
+     * MUST be sync `void`.
+     */
+    renderGraph(update: LensUpdate): void;
+}
+/**
+ * Discriminated union for the `compose([...])` combinator and the
+ * registry. Lets the registry hold one Map<name, AnyStrategy> while
+ * preserving type narrowing per-group via the `kind` discriminator.
+ */
+export type AnyStrategy = ({
+    readonly kind: 'observability';
+} & ObservabilityStrategy) | ({
+    readonly kind: 'cost';
+} & CostStrategy) | ({
+    readonly kind: 'liveStatus';
+} & LiveStatusStrategy) | ({
+    readonly kind: 'lens';
+} & LensStrategy);
+export type StrategyKind = AnyStrategy['kind'];
+/**
+ * Cost-of-on knob (per Datadog panel review). Each tier is a soft
+ * suggestion — strategies decide what to do per tier (e.g., a
+ * `pino` strategy might gzip on `firehose`, an OTel strategy might
+ * raise its `BatchSpanProcessor` interval).
+ */
+export type ObservabilityTier = 'minimal' | 'standard' | 'firehose';
+/**
+ * Detach mode — controls whether the strategy's hot-path call
+ * (e.g. `exportEvent`) runs sync inside the agent loop or is deferred
+ * onto a `footprintjs/detach` driver so the loop never blocks.
+ *
+ * Three semantics:
+ *
+ *   - `'forget'`  — `detachAndForget`. Discard the handle. Pure
+ *                   fire-and-forget telemetry. Errors land on the
+ *                   (discarded) handle and go silent unless the
+ *                   strategy's own `_onError` surfaces them. Use for
+ *                   high-volume exports where dropping a single event
+ *                   is acceptable.
+ *
+ *   - `'join-later'` — `detachAndJoinLater`. The driver returns a
+ *                      `DetachHandle`; we deliver it to your
+ *                      `onHandle` callback so you can `await` later
+ *                      (graceful shutdown, tests, backpressure).
+ *
+ *   - omitted (default sync) — strategy hot-path runs inline, same as
+ *                              every release before v2.8.
+ *
+ * For graceful shutdown — call `flushAllDetached()` (from
+ * `'footprintjs/detach'`) in your SIGTERM handler. Drains every
+ * in-flight detached handle process-wide.
+ */
+export interface DetachOptions {
+    /** The driver to schedule on. Required — there is no library
+     *  default. Pick by environment: `microtaskBatchDriver` (cross-
+     *  runtime, default for in-process), `setImmediateDriver` (Node),
+     *  `setTimeoutDriver` (cross-runtime, configurable delay),
+     *  `sendBeaconDriver` (browser, survives page-unload), etc. */
+    readonly driver: import('footprintjs/detach').DetachDriver;
+    /** `'forget'` discards the handle (pure telemetry). `'join-later'`
+     *  delivers the handle to `onHandle` for later awaiting. Default
+     *  `'forget'`. */
+    readonly mode?: 'forget' | 'join-later';
+    /** Required when `mode === 'join-later'`. Receives every minted
+     *  handle. Push to a closure-local array if you want
+     *  `Promise.all(handles.map(h => h.wait()))` later, or keep a
+     *  rolling window for backpressure. */
+    readonly onHandle?: (handle: import('footprintjs/detach').DetachHandle) => void;
+}
+/**
+ * Common options every group accepts. Per-group enablers extend with
+ * their own keys (e.g., `templates` for liveStatus, `budget` for cost).
+ */
+export interface CommonStrategyOptions {
+    /**
+     * Strategy implementation. Defaults differ per group:
+     *   - observability → `console()`
+     *   - cost          → `inMemorySink()`
+     *   - liveStatus    → consumer-provided callback
+     *   - lens          → `browser()` (when in DOM) / `noop()` (else)
+     */
+    readonly strategy?: BaseStrategy;
+    /** 0..1 — fraction of events to forward. 1.0 = all, 0 = none.
+     *  Per-Datadog panel review: every observability enabler accepts
+     *  this. */
+    readonly sampleRate?: number;
+    /** Opt-in detach. When set, the strategy's hot-path call (e.g.
+     *  `exportEvent`) is scheduled on the given driver instead of
+     *  running inline — agent loop never blocks on slow exporters.
+     *  See `DetachOptions` for the three semantics. */
+    readonly detach?: DetachOptions;
+}

package/dist/esm/stream.d.ts

@@ -0,0 +1,82 @@
+/**
+ * agentfootprint/stream — agent events → Server-Sent Events helpers.
+ *
+ * Pattern: Adapter (event stream → SSE wire format).
+ * Role:    Outer ring. Subscribes to a `Runner`'s `EventDispatcher`
+ *          and yields SSE-formatted strings. Drop into any HTTP
+ *          framework that accepts an async iterable response body
+ *          (Fetch Response, Express res.write, Hono streaming, etc.).
+ * Emits:   N/A — observes only.
+ */
+import type { AgentfootprintEvent } from './events/registry.js';
+import type { RunnerBase } from './core/RunnerBase.js';
+/**
+ * Hand the runner this iterable's caller before calling `runner.run()`.
+ * Yields SSE-formatted strings until the run finishes (success, error,
+ * or pause). Each event becomes:
+ *
+ *   event: <event name>
+ *   data: <JSON payload>
+ *   <blank line>
+ *
+ * @example
+ *   // Express
+ *   app.post('/agent', async (req, res) => {
+ *     res.setHeader('content-type', 'text/event-stream');
+ *     for await (const chunk of toSSE(agent)) {
+ *       res.write(chunk);
+ *     }
+ *     res.end();
+ *     // (in parallel: await agent.run(req.body))
+ *   });
+ */
+export interface ToSSEOptions {
+    /**
+     * Filter predicate — return false to skip an event. Default: all events.
+     * Common: `event => event.type.startsWith('agentfootprint.stream.')`
+     * for a token-only feed.
+     */
+    readonly filter?: (event: AgentfootprintEvent) => boolean;
+    /**
+     * Output shape:
+     *   - 'full' (default) — each event is JSON-serialized verbatim.
+     *   - 'text' — only `agentfootprint.stream.token.content` is yielded,
+     *     in plain text form (no event/data prefix). Useful for piping
+     *     directly into a chat UI.
+     */
+    readonly format?: 'full' | 'text';
+    /**
+     * Custom event name extractor. By default `event.type` is used.
+     * Useful for SSE consumers that want their own naming.
+     */
+    readonly eventName?: (event: AgentfootprintEvent) => string;
+    /**
+     * Heartbeat interval in ms. SSE connections through proxies/load
+     * balancers often die after ~30s of silence; emit `: ping` comments
+     * at this interval. Default 0 (disabled).
+     */
+    readonly heartbeatMs?: number;
+}
+/**
+ * Subscribe to a runner's `EventDispatcher` and yield SSE-formatted
+ * strings until the run completes.
+ */
+export declare function toSSE<TIn, TOut>(runner: RunnerBase<TIn, TOut>, options?: ToSSEOptions): AsyncIterable<string>;
+/**
+ * Class form for consumers who prefer `new SSEFormatter(runner).stream()`.
+ * Identical behavior to `toSSE(runner)` — pick by preference.
+ */
+export declare class SSEFormatter<TIn = unknown, TOut = unknown> {
+    private readonly runner;
+    private readonly options;
+    constructor(runner: RunnerBase<TIn, TOut>, options?: ToSSEOptions);
+    /** Async iterable of SSE chunks. Consume with `for await`. */
+    stream(): AsyncIterable<string>;
+}
+/**
+ * Format any JSON-able payload as a single SSE event chunk.
+ *
+ * Useful for app-level events outside the runner's typed registry
+ * (auth/error frames, app-state echoes). Most consumers won't need this.
+ */
+export declare function encodeSSE(eventName: string, payload: unknown): string;

package/dist/esm/thinking/AnthropicThinkingHandler.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AnthropicThinkingHandler — normalizes Anthropic's extended-thinking
+ * response shape into the framework's `ThinkingBlock[]` contract.
+ *
+ * Anthropic emits thinking via blocks in `response.content`:
+ *
+ *   ```ts
+ *   { type: 'thinking',          thinking: 'reasoning text', signature: 'opaque-base64' }
+ *   { type: 'redacted_thinking',                              signature: 'opaque-base64' }
+ *   { type: 'text',              text: 'visible content' }
+ *   { type: 'tool_use',          id, name, input }
+ *   ```
+ *
+ * The handler filters for `'thinking'` + `'redacted_thinking'` blocks,
+ * preserves the `signature` field BYTE-EXACT (Anthropic validates
+ * signatures server-side on the next turn — any modification = HTTP 400),
+ * and ignores other block types (visible text + tool calls flow through
+ * the existing `LLMResponse.content` / `LLMResponse.toolCalls` paths).
+ *
+ * **Critical invariant:** signature pass-through is byte-exact. The
+ * handler MUST NOT trim, normalize encoding, JSON-roundtrip, or
+ * otherwise touch the signature string. Tests verify this explicitly.
+ *
+ * **Three input shapes** Anthropic produces (per Phase 4a panel review):
+ *   1. Non-streaming response: full `response.content` array
+ *   2. Streaming aggregated:   AnthropicProvider accumulates chunks +
+ *                              calls handler with the same array shape
+ *   3. Bedrock-via-Anthropic:  deferred to Phase 5+ (separate handler
+ *                              or extension of this one)
+ *
+ * Streaming + non-streaming converge on shape #1 because the provider
+ * handles the distinction — handler only sees the assembled content
+ * array.
+ *
+ * **`parseChunk` is OPTIONAL** — Phase 3's framework path populates
+ * `LLMChunk.thinkingDelta` from inside AnthropicProvider's `stream()`
+ * directly, bypassing handler.parseChunk. We still implement it for
+ * consumer integrations that want to use the handler on raw Anthropic
+ * chunks directly (e.g., custom transports).
+ */
+import type { ThinkingHandler } from './types.js';
+export declare const anthropicThinkingHandler: ThinkingHandler;

package/dist/esm/thinking/MockThinkingHandler.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MockThinkingHandler — canonical example for the v2.14 ThinkingHandler
+ * contract. Used by:
+ *
+ *   1. Tests — drives the shared contract test (every shipped handler
+ *      MUST satisfy the same invariants this mock demonstrates).
+ *   2. Future provider authors — reference implementation showing how
+ *      to handle BOTH Anthropic-shape inputs (signed blocks, possibly
+ *      redacted) and OpenAI-shape inputs (multi-block summary). The
+ *      pattern of "discriminate by shape, normalize each branch" is
+ *      reusable across providers.
+ *   3. The MockProvider for end-to-end tests of the framework wiring
+ *      without depending on a real LLM SDK.
+ *
+ * Defaults are deliberately sensitive-data-free — no fake PII, no
+ * fake-signature material that could be confused for real cryptography,
+ * no internal-looking IDs. Sets the example for consumer-authored
+ * handlers.
+ */
+import type { ThinkingHandler } from './types.js';
+/** Shape the mock recognizes for Anthropic-style raw inputs. */
+interface MockAnthropicRaw {
+    readonly kind: 'anthropic';
+    readonly blocks: ReadonlyArray<{
+        readonly type: 'thinking' | 'redacted_thinking';
+        readonly thinking?: string;
+        readonly signature?: string;
+    }>;
+}
+/** Shape the mock recognizes for OpenAI-style raw inputs. */
+interface MockOpenAIRaw {
+    readonly kind: 'openai';
+    readonly summarySteps: readonly string[];
+}
+/**
+ * Build an Anthropic-style raw input for tests. Signature is a marker
+ * string — real Anthropic signatures are opaque base64.
+ */
+export declare function mockAnthropicRaw(blocks: readonly {
+    content: string;
+    signature?: string;
+    redacted?: boolean;
+}[]): MockAnthropicRaw;
+/**
+ * Build an OpenAI-style raw input for tests — one summary step per
+ * string. Each step becomes a separate ThinkingBlock with `summary: true`.
+ */
+export declare function mockOpenAIRaw(summarySteps: readonly string[]): MockOpenAIRaw;
+export declare const mockThinkingHandler: ThinkingHandler;
+export {};

package/dist/esm/thinking/OpenAIThinkingHandler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OpenAIThinkingHandler — normalizes OpenAI's o1/o3 reasoning_summary
+ * structured output into the framework's `ThinkingBlock[]` contract.
+ *
+ * OpenAI's reasoning_summary shape varies by model + API version:
+ *
+ *   1. Older o1 format — simple string:
+ *        "I worked through the problem by first..."
+ *
+ *   2. Newer o3+ structured — array of summary items:
+ *        [
+ *          { type: 'summary_text', text: 'Identify the user request' },
+ *          { type: 'summary_text', text: 'Choose appropriate tool' },
+ *        ]
+ *
+ *   3. Missing entirely — most calls (gpt-4o, or o1/o3 without
+ *      reasoning_summary param requested) → undefined raw input
+ *
+ * Handler dispatches on shape; output is `ThinkingBlock[]` with
+ * `summary: true` per Phase 1 contract — distinguishes structured-
+ * summary blocks from raw thinking content (Anthropic's shape).
+ *
+ * **No signature** — OpenAI doesn't sign reasoning. The output's
+ * `signature` field stays undefined. No round-trip integrity invariant
+ * (unlike Anthropic).
+ *
+ * **No `parseChunk`** — OpenAI doesn't stream reasoning content as of
+ * early 2026. Reasoning arrives only on the terminal response. Per
+ * Phase 1 design, `parseChunk` is optional; we omit entirely.
+ *
+ * **No `usage.thinking` computation** — reasoning_tokens lives on
+ * `response.usage.completion_tokens_details.reasoning_tokens` and is
+ * the OpenAIProvider's job to surface (deferred). Handler doesn't
+ * compute token counts.
+ */
+import type { ThinkingHandler } from './types.js';
+export declare const openAIThinkingHandler: ThinkingHandler;