agentfootprint 2.13.0 → 2.14.0

package/dist/esm/security/thinkingRedaction.js

@@ -0,0 +1,66 @@
+/**
+ * thinkingRedaction — content scrubbing for ThinkingBlock[] before
+ * persistence + audit-log adapters fire.
+ *
+ * Pattern: Pure function. Same shape as the v2.4 RedactionPolicy.scope-
+ * patterns / emit-patterns helpers — regex match + replace.
+ *
+ * Mental model — TWO-LAYER persistence:
+ *   - LLMMessage.thinkingBlocks IS persisted to scope.history (required
+ *     for Anthropic signature round-trip).
+ *   - Audit-log adapters (CloudWatch, Datadog OTel, etc.) read from
+ *     scope.history. Sensitive reasoning (PII in chain-of-thought,
+ *     internal IDs the model worked through) lands there too.
+ *   - This helper scrubs content patterns BEFORE the assistant message
+ *     pushes to scope.history, so the audit-log surface only sees
+ *     redacted content while the LLM still sees the unredacted reasoning
+ *     for round-trip integrity.
+ *
+ * The signature field is NEVER touched by redaction — Anthropic's
+ * server-side signature is bound to the original content; modifying
+ * content here would invalidate the signature. Resolution: signature
+ * survives byte-exact, content gets scrubbed. This means the Anthropic
+ * API will reject the next turn IF the consumer wired thinkingPatterns
+ * AND uses Anthropic with extended-thinking-plus-tools. Document.
+ *
+ * Recommended use:
+ *   - DON'T wire thinkingPatterns when using Anthropic extended thinking
+ *     + tool calls (signature breaks).
+ *   - DO wire thinkingPatterns when using OpenAI o1/o3 (no signature,
+ *     no round-trip requirement) or for offline log scrubbing.
+ *   - For Anthropic + sensitive reasoning, prefer audit-log-side
+ *     redaction (filter in your CloudWatch / Datadog adapter rather
+ *     than the framework's persistence point).
+ */
+/** Sentinel string used in place of redacted content. */
+export const REDACTED_PLACEHOLDER = '[REDACTED]';
+/**
+ * Return a copy of `blocks` with each block's `content` field scrubbed
+ * by every pattern in `patterns`. Returns the input array unchanged
+ * when `patterns` is undefined, empty, or no block content matches.
+ *
+ * Signature + summary + providerMeta fields are preserved BYTE-EXACT
+ * — only `content` is touched.
+ *
+ * Anthropic signature warning: scrubbing content invalidates the
+ * Anthropic server-side signature. Round-trip will fail with HTTP 400
+ * on the next turn. Document this in the consumer recipe.
+ */
+export function redactThinkingBlocks(blocks, patterns) {
+    if (!patterns || patterns.length === 0)
+        return blocks;
+    if (blocks.length === 0)
+        return blocks;
+    let anyChanged = false;
+    const out = blocks.map((b) => {
+        const scrubbed = patterns.reduce((c, re) => c.replace(re, REDACTED_PLACEHOLDER), b.content);
+        if (scrubbed === b.content)
+            return b;
+        anyChanged = true;
+        return { ...b, content: scrubbed };
+    });
+    // Return the original array reference when nothing changed —
+    // downstream reference-equality checks (cache markers) stay stable.
+    return anyChanged ? out : blocks;
+}
+//# sourceMappingURL=thinkingRedaction.js.map

package/dist/esm/security/thinkingRedaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinkingRedaction.js","sourceRoot":"","sources":["../../../src/security/thinkingRedaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAgC,EAChC,QAAuC;IAEvC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAEvC,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC3B,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,oBAAoB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;QAC5F,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC;QACrC,UAAU,GAAG,IAAI,CAAC;QAClB,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,6DAA6D;IAC7D,oEAAoE;IACpE,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACnC,CAAC"}

package/dist/esm/thinking/AnthropicThinkingHandler.js

@@ -0,0 +1,111 @@
+/**
+ * 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).
+ */
+function isAnthropicContentArray(raw) {
+    return Array.isArray(raw);
+}
+function isThinkingBlock(b) {
+    return b.type === 'thinking';
+}
+function isRedactedThinkingBlock(b) {
+    return b.type === 'redacted_thinking';
+}
+function isAnthropicChunk(chunk) {
+    return typeof chunk === 'object' && chunk !== null;
+}
+export const anthropicThinkingHandler = {
+    id: 'anthropic',
+    // 'browser-anthropic' shares the same response shape (raw Anthropic
+    // wire format) — both providers route through fromAnthropicResponse
+    // which sets `rawThinking` to `message.content`. Bedrock Claude
+    // would also fit here but ships as a separate handler if/when its
+    // shape diverges.
+    providerNames: ['anthropic', 'browser-anthropic'],
+    normalize(raw) {
+        if (!isAnthropicContentArray(raw))
+            return [];
+        const out = [];
+        for (const block of raw) {
+            if (isThinkingBlock(block)) {
+                // Byte-exact signature preservation: pass through as-is.
+                // No String() coercion that could normalize encoding; if
+                // Anthropic ever emits a non-string signature it would be a
+                // wire-protocol violation we want to surface, not silently
+                // coerce.
+                out.push({
+                    type: 'thinking',
+                    // Don't touch content — pass through. Anthropic guarantees
+                    // it's a string when the field is present.
+                    content: block.thinking,
+                    ...(block.signature !== undefined && { signature: block.signature }),
+                });
+            }
+            else if (isRedactedThinkingBlock(block)) {
+                // Redacted blocks have no readable content but the signature
+                // is still REQUIRED for round-trip. Empty content is the
+                // contract (per Phase 1 ThinkingBlock JSDoc).
+                out.push({
+                    type: 'redacted_thinking',
+                    content: '',
+                    ...(block.signature !== undefined && { signature: block.signature }),
+                });
+            }
+            // Other block types (text, tool_use, etc.) flow through the
+            // existing LLMResponse paths — ignore here.
+        }
+        return out;
+    },
+    parseChunk(chunk) {
+        // Optional escape hatch — framework path doesn't call this
+        // (AnthropicProvider populates LLMChunk.thinkingDelta directly).
+        // Provided for consumer integrations using the handler on raw
+        // Anthropic chunks directly.
+        if (!isAnthropicChunk(chunk))
+            return {};
+        const delta = chunk.delta;
+        if (!delta)
+            return {};
+        if (delta.type === 'thinking_delta' && typeof delta.thinking === 'string') {
+            return { thinkingDelta: delta.thinking };
+        }
+        return {};
+    },
+};
+//# sourceMappingURL=AnthropicThinkingHandler.js.map

package/dist/esm/thinking/AnthropicThinkingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnthropicThinkingHandler.js","sourceRoot":"","sources":["../../../src/thinking/AnthropicThinkingHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAuCH,SAAS,uBAAuB,CAAC,GAAY;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,eAAe,CAAC,CAAwB;IAC/C,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;AAC/B,CAAC;AAED,SAAS,uBAAuB,CAAC,CAAwB;IACvD,OAAO,CAAC,CAAC,IAAI,KAAK,mBAAmB,CAAC;AACxC,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,EAAE,EAAE,WAAW;IACf,oEAAoE;IACpE,oEAAoE;IACpE,gEAAgE;IAChE,kEAAkE;IAClE,kBAAkB;IAClB,aAAa,EAAE,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAEjD,SAAS,CAAC,GAAY;QACpB,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAE7C,MAAM,GAAG,GAAoB,EAAE,CAAC;QAChC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YACxB,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,yDAAyD;gBACzD,yDAAyD;gBACzD,4DAA4D;gBAC5D,2DAA2D;gBAC3D,UAAU;gBACV,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,UAAU;oBAChB,2DAA2D;oBAC3D,2CAA2C;oBAC3C,OAAO,EAAE,KAAK,CAAC,QAAQ;oBACvB,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;iBACrE,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1C,6DAA6D;gBAC7D,yDAAyD;gBACzD,8CAA8C;gBAC9C,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EAAE,EAAE;oBACX,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;iBACrE,CAAC,CAAC;YACL,CAAC;YACD,4DAA4D;YAC5D,4CAA4C;QAC9C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,UAAU,CAAC,KAAc;QACvB,2DAA2D;QAC3D,iEAAiE;QACjE,8DAA8D;QAC9D,6BAA6B;QAC7B,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;CACF,CAAC"}

package/dist/esm/thinking/MockThinkingHandler.js

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+function isMockRaw(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return false;
+    const r = raw;
+    // Accept only well-formed shapes — protects against {kind: 'anthropic'}
+    // missing blocks (would crash .map). The framework's failure-isolation
+    // would catch the throw, but defending here keeps the contract
+    // "normalize never throws on garbage" tighter.
+    if (r.kind === 'anthropic')
+        return Array.isArray(r.blocks);
+    if (r.kind === 'openai')
+        return Array.isArray(r.summarySteps);
+    return false;
+}
+/**
+ * Build an Anthropic-style raw input for tests. Signature is a marker
+ * string — real Anthropic signatures are opaque base64.
+ */
+export function mockAnthropicRaw(blocks) {
+    return {
+        kind: 'anthropic',
+        blocks: blocks.map((b) => ({
+            type: b.redacted ? 'redacted_thinking' : 'thinking',
+            ...(b.redacted ? {} : { thinking: b.content }),
+            ...(b.signature !== undefined && { signature: b.signature }),
+        })),
+    };
+}
+/**
+ * Build an OpenAI-style raw input for tests — one summary step per
+ * string. Each step becomes a separate ThinkingBlock with `summary: true`.
+ */
+export function mockOpenAIRaw(summarySteps) {
+    return { kind: 'openai', summarySteps };
+}
+export const mockThinkingHandler = {
+    id: 'mock',
+    // Matches the MockProvider's name; framework auto-wires when
+    // Agent uses MockProvider in tests.
+    providerNames: ['mock'],
+    normalize(raw) {
+        if (!isMockRaw(raw))
+            return [];
+        if (raw.kind === 'anthropic') {
+            return raw.blocks.map((b) => {
+                if (b.type === 'redacted_thinking') {
+                    return {
+                        type: 'redacted_thinking',
+                        content: '',
+                        ...(b.signature !== undefined && { signature: b.signature }),
+                    };
+                }
+                return {
+                    type: 'thinking',
+                    content: b.thinking ?? '',
+                    ...(b.signature !== undefined && { signature: b.signature }),
+                };
+            });
+        }
+        // OpenAI-style: one block per summary step, all marked summary: true.
+        return raw.summarySteps.map((content) => ({
+            type: 'thinking',
+            content,
+            summary: true,
+        }));
+    },
+    parseChunk(chunk) {
+        // Mock streams thinking via { thinkingDelta: '...' } shape.
+        if (typeof chunk !== 'object' || chunk === null)
+            return {};
+        const c = chunk;
+        return typeof c.thinkingDelta === 'string' ? { thinkingDelta: c.thinkingDelta } : {};
+    },
+};
+//# sourceMappingURL=MockThinkingHandler.js.map

package/dist/esm/thinking/MockThinkingHandler.js.map

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

package/dist/esm/thinking/OpenAIThinkingHandler.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+function isOpenAIStructuredArray(raw) {
+    return Array.isArray(raw);
+}
+export const openAIThinkingHandler = {
+    id: 'openai',
+    providerNames: ['openai'],
+    normalize(raw) {
+        if (raw === undefined || raw === null)
+            return [];
+        // Shape 1: simple string (older o1 format).
+        if (typeof raw === 'string') {
+            return raw.length > 0 ? [{ type: 'thinking', content: raw, summary: true }] : [];
+        }
+        // Shape 2: structured array of summary items (newer o3+ format).
+        if (isOpenAIStructuredArray(raw)) {
+            const out = [];
+            for (const item of raw) {
+                // Tolerate items missing `text` (defensive — wire format may
+                // evolve). Skip entries without usable content.
+                if (typeof item.text === 'string' && item.text.length > 0) {
+                    out.push({
+                        type: 'thinking',
+                        content: item.text,
+                        summary: true,
+                    });
+                }
+            }
+            return out;
+        }
+        // Unknown shape — return empty rather than throw. The framework
+        // catches throws and emits parse_failed; here we choose graceful
+        // empty for unknown OpenAI evolutions (forward-compat).
+        return [];
+    },
+    // No parseChunk — OpenAI doesn't stream reasoning content.
+};
+//# sourceMappingURL=OpenAIThinkingHandler.js.map

package/dist/esm/thinking/OpenAIThinkingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAIThinkingHandler.js","sourceRoot":"","sources":["../../../src/thinking/OpenAIThinkingHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAYH,SAAS,uBAAuB,CAAC,GAAY;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAoB;IACpD,EAAE,EAAE,QAAQ;IACZ,aAAa,EAAE,CAAC,QAAQ,CAAC;IAEzB,SAAS,CAAC,GAAY;QACpB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QAEjD,4CAA4C;QAC5C,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,CAAC;QAED,iEAAiE;QACjE,IAAI,uBAAuB,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,GAAG,GAAoB,EAAE,CAAC;YAChC,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;gBACvB,6DAA6D;gBAC7D,gDAAgD;gBAChD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC1D,GAAG,CAAC,IAAI,CAAC;wBACP,IAAI,EAAE,UAAU;wBAChB,OAAO,EAAE,IAAI,CAAC,IAAI;wBAClB,OAAO,EAAE,IAAI;qBACd,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QAED,gEAAgE;QAChE,iEAAiE;QACjE,wDAAwD;QACxD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,2DAA2D;CAC5D,CAAC"}

package/dist/esm/thinking/index.js

@@ -0,0 +1,51 @@
+/**
+ * agentfootprint/thinking — extended-thinking subsystem (v2.14+).
+ *
+ * **Two-layer architecture:**
+ *
+ *   • CONSUMER-FACING:    `ThinkingHandler` — simple function-pair
+ *                          implemented by provider authors.
+ *   • FRAMEWORK-INTERNAL: each handler is auto-wrapped in a real
+ *                         footprintjs subflow at chart build time;
+ *                         shows in trace as own runtimeStageId.
+ *
+ * **Auto-wire by provider name:**
+ *
+ *   ```ts
+ *   import { Agent } from 'agentfootprint';
+ *
+ *   // Library scans SHIPPED_THINKING_HANDLERS, finds the handler
+ *   // whose providerNames includes provider.name. Mounted as a
+ *   // sub-subflow of sf-call-llm.
+ *   const agent = Agent.create({ provider: anthropic({...}), model: '...' })
+ *     .build();
+ *
+ *   // Opt out:
+ *   //   .thinkingHandler(undefined)
+ *   // Override with a custom handler:
+ *   //   .thinkingHandler(myCustomHandler)
+ *   ```
+ *
+ * **Custom handlers:**
+ *
+ *   ```ts
+ *   import { type ThinkingHandler } from 'agentfootprint/thinking';
+ *
+ *   export const geminiThinkingHandler: ThinkingHandler = {
+ *     id: 'gemini',
+ *     providerNames: ['gemini'],
+ *     normalize(raw) { ... },
+ *     parseChunk(chunk) { ... },  // optional
+ *   };
+ *   ```
+ *
+ * Failure isolation: handler `normalize()` throws are caught by the
+ * framework — emit `agentfootprint.agent.thinking_parse_failed`, drop
+ * the blocks, continue. Same graceful pattern as v2.11.6
+ * `tools.discovery_failed`.
+ */
+export { mockThinkingHandler, mockAnthropicRaw, mockOpenAIRaw } from './MockThinkingHandler.js';
+export { anthropicThinkingHandler } from './AnthropicThinkingHandler.js';
+export { openAIThinkingHandler } from './OpenAIThinkingHandler.js';
+export { SHIPPED_THINKING_HANDLERS, findThinkingHandler } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/thinking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/thinking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/thinking/registry.js

@@ -0,0 +1,46 @@
+/**
+ * Registry — single source of truth for the framework's auto-wire
+ * logic AND the shared contract test.
+ *
+ * Phase 3 wiring scans this array at chart build time and selects the
+ * first handler whose `providerNames` includes the active
+ * `provider.name`. Phase 4a adds AnthropicThinkingHandler; Phase 5
+ * adds OpenAIThinkingHandler — append-only as new providers ship.
+ *
+ * Future provider authors:
+ *   • Implement `ThinkingHandler` for your provider
+ *   • Append to this array
+ *   • The shared contract test in `test/thinking/contract.test.ts`
+ *     verifies your handler honors the framework's invariants
+ */
+import { anthropicThinkingHandler } from './AnthropicThinkingHandler.js';
+import { mockThinkingHandler } from './MockThinkingHandler.js';
+import { openAIThinkingHandler } from './OpenAIThinkingHandler.js';
+/**
+ * All thinking handlers shipped with the library. Append in alphabetical
+ * order (by `id`) so diffs stay readable as new handlers land.
+ */
+export const SHIPPED_THINKING_HANDLERS = [
+    anthropicThinkingHandler,
+    mockThinkingHandler,
+    openAIThinkingHandler,
+];
+/**
+ * Look up a handler by `provider.name`. Returns the first match in
+ * `SHIPPED_THINKING_HANDLERS`. Returns `undefined` when no handler
+ * matches — framework treats this as "no thinking support for this
+ * provider", which is the correct default for providers that don't
+ * emit thinking content (gpt-3.5, mistral, etc.).
+ *
+ * Used by:
+ *   • Phase 3 framework auto-wire (chart build time)
+ *   • Tests verifying registry lookup
+ */
+export function findThinkingHandler(providerName) {
+    for (const handler of SHIPPED_THINKING_HANDLERS) {
+        if (handler.providerNames.includes(providerName))
+            return handler;
+    }
+    return undefined;
+}
+//# sourceMappingURL=registry.js.map

package/dist/esm/thinking/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/thinking/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGnE;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAA+B;IACnE,wBAAwB;IACxB,mBAAmB;IACnB,qBAAqB;CACtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,KAAK,MAAM,OAAO,IAAI,yBAAyB,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,OAAO,CAAC;IACnE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/esm/thinking/types.js

@@ -0,0 +1,30 @@
+/**
+ * Thinking — public types for the v2.14 extended-thinking subsystem.
+ *
+ * Mental model — TWO-LAYER architecture:
+ *
+ *   • CONSUMER-FACING:   `ThinkingHandler` — a simple function-pair
+ *                        (id, providerNames, normalize, parseChunk?).
+ *                        Provider authors and custom-LLM consumers
+ *                        implement THIS shape.
+ *
+ *   • FRAMEWORK-INTERNAL: each `ThinkingHandler` is auto-wrapped in a
+ *                         real footprintjs subflow at chart build time.
+ *                         The subflow gets its own `runtimeStageId`,
+ *                         narrative entry, and InOutRecorder boundary
+ *                         — full trace observability for free without
+ *                         the consumer writing flowchart code.
+ *
+ * Same pattern as how consumers write a `Tool` and the framework wraps
+ * dispatch in a tool-call subflow, or how consumers write a
+ * `ToolProvider` and the framework wraps `list()` in the Tools slot
+ * subflow.
+ *
+ * @see SHIPPED_THINKING_HANDLERS for the registry the framework uses
+ *      to auto-wire by `provider.name` (Phase 3 wiring).
+ * @see MockThinkingHandler for the canonical example demonstrating
+ *      both Anthropic-shape (signed blocks) and OpenAI-shape (multi-
+ *      block summary) inputs.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/thinking/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/thinking/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/dist/events/registry.js

@@ -38,6 +38,7 @@ exports.EVENT_NAMES = {
         routeDecided: 'agentfootprint.agent.route_decided',
         handoff: 'agentfootprint.agent.handoff',
         outputSchemaValidationFailed: 'agentfootprint.agent.output_schema_validation_failed',
+        thinkingParseFailed: 'agentfootprint.agent.thinking_parse_failed',
     },
     stream: {
         llmStart: 'agentfootprint.stream.llm_start',
@@ -45,6 +46,8 @@ exports.EVENT_NAMES = {
         token: 'agentfootprint.stream.token',
         toolStart: 'agentfootprint.stream.tool_start',
         toolEnd: 'agentfootprint.stream.tool_end',
+        thinkingDelta: 'agentfootprint.stream.thinking_delta',
+        thinkingEnd: 'agentfootprint.stream.thinking_end',
     },
     context: {
         injected: 'agentfootprint.context.injected',
@@ -123,11 +126,14 @@ exports.ALL_EVENT_TYPES = [
     'agentfootprint.agent.route_decided',
     'agentfootprint.agent.handoff',
     'agentfootprint.agent.output_schema_validation_failed',
+    'agentfootprint.agent.thinking_parse_failed',
     'agentfootprint.stream.llm_start',
     'agentfootprint.stream.llm_end',
     'agentfootprint.stream.token',
     'agentfootprint.stream.tool_start',
     'agentfootprint.stream.tool_end',
+    'agentfootprint.stream.thinking_delta',
+    'agentfootprint.stream.thinking_end',
     'agentfootprint.context.injected',
     'agentfootprint.context.evicted',
     'agentfootprint.context.slot_composed',

package/dist/events/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/events/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/events/registry.ts"],"names":[],"mappings":"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"}

package/dist/security/index.js

@@ -36,7 +36,7 @@
  *   const agent = Agent.create({ provider, model, permissionChecker: policy }).build();
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SYNTHETIC_DENY_PREFIX = exports.extractSequence = exports.PolicyHaltError = exports.PermissionPolicy = void 0;
+exports.REDACTED_PLACEHOLDER = exports.redactThinkingBlocks = exports.SYNTHETIC_DENY_PREFIX = exports.extractSequence = exports.PolicyHaltError = exports.PermissionPolicy = void 0;
 var PermissionPolicy_js_1 = require("./PermissionPolicy.js");
 Object.defineProperty(exports, "PermissionPolicy", { enumerable: true, get: function () { return PermissionPolicy_js_1.PermissionPolicy; } });
 var PolicyHaltError_js_1 = require("./PolicyHaltError.js");
@@ -44,4 +44,7 @@ Object.defineProperty(exports, "PolicyHaltError", { enumerable: true, get: funct
 var extractSequence_js_1 = require("./extractSequence.js");
 Object.defineProperty(exports, "extractSequence", { enumerable: true, get: function () { return extractSequence_js_1.extractSequence; } });
 Object.defineProperty(exports, "SYNTHETIC_DENY_PREFIX", { enumerable: true, get: function () { return extractSequence_js_1.SYNTHETIC_DENY_PREFIX; } });
+var thinkingRedaction_js_1 = require("./thinkingRedaction.js");
+Object.defineProperty(exports, "redactThinkingBlocks", { enumerable: true, get: function () { return thinkingRedaction_js_1.redactThinkingBlocks; } });
+Object.defineProperty(exports, "REDACTED_PLACEHOLDER", { enumerable: true, get: function () { return thinkingRedaction_js_1.REDACTED_PLACEHOLDER; } });
 //# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;;AAEH,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AAGzB,2DAAuD;AAA9C,qHAAA,eAAe,OAAA;AAGxB,2DAA8E;AAArE,qHAAA,eAAe,OAAA;AAAE,2HAAA,qBAAqB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;;AAEH,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AAGzB,2DAAuD;AAA9C,qHAAA,eAAe,OAAA;AAGxB,2DAA8E;AAArE,qHAAA,eAAe,OAAA;AAAE,2HAAA,qBAAqB,OAAA;AAG/C,+DAAoF;AAA3E,4HAAA,oBAAoB,OAAA;AAAE,4HAAA,oBAAoB,OAAA"}

package/dist/security/thinkingRedaction.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * thinkingRedaction — content scrubbing for ThinkingBlock[] before
+ * persistence + audit-log adapters fire.
+ *
+ * Pattern: Pure function. Same shape as the v2.4 RedactionPolicy.scope-
+ * patterns / emit-patterns helpers — regex match + replace.
+ *
+ * Mental model — TWO-LAYER persistence:
+ *   - LLMMessage.thinkingBlocks IS persisted to scope.history (required
+ *     for Anthropic signature round-trip).
+ *   - Audit-log adapters (CloudWatch, Datadog OTel, etc.) read from
+ *     scope.history. Sensitive reasoning (PII in chain-of-thought,
+ *     internal IDs the model worked through) lands there too.
+ *   - This helper scrubs content patterns BEFORE the assistant message
+ *     pushes to scope.history, so the audit-log surface only sees
+ *     redacted content while the LLM still sees the unredacted reasoning
+ *     for round-trip integrity.
+ *
+ * The signature field is NEVER touched by redaction — Anthropic's
+ * server-side signature is bound to the original content; modifying
+ * content here would invalidate the signature. Resolution: signature
+ * survives byte-exact, content gets scrubbed. This means the Anthropic
+ * API will reject the next turn IF the consumer wired thinkingPatterns
+ * AND uses Anthropic with extended-thinking-plus-tools. Document.
+ *
+ * Recommended use:
+ *   - DON'T wire thinkingPatterns when using Anthropic extended thinking
+ *     + tool calls (signature breaks).
+ *   - DO wire thinkingPatterns when using OpenAI o1/o3 (no signature,
+ *     no round-trip requirement) or for offline log scrubbing.
+ *   - For Anthropic + sensitive reasoning, prefer audit-log-side
+ *     redaction (filter in your CloudWatch / Datadog adapter rather
+ *     than the framework's persistence point).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactThinkingBlocks = exports.REDACTED_PLACEHOLDER = void 0;
+/** Sentinel string used in place of redacted content. */
+exports.REDACTED_PLACEHOLDER = '[REDACTED]';
+/**
+ * Return a copy of `blocks` with each block's `content` field scrubbed
+ * by every pattern in `patterns`. Returns the input array unchanged
+ * when `patterns` is undefined, empty, or no block content matches.
+ *
+ * Signature + summary + providerMeta fields are preserved BYTE-EXACT
+ * — only `content` is touched.
+ *
+ * Anthropic signature warning: scrubbing content invalidates the
+ * Anthropic server-side signature. Round-trip will fail with HTTP 400
+ * on the next turn. Document this in the consumer recipe.
+ */
+function redactThinkingBlocks(blocks, patterns) {
+    if (!patterns || patterns.length === 0)
+        return blocks;
+    if (blocks.length === 0)
+        return blocks;
+    let anyChanged = false;
+    const out = blocks.map((b) => {
+        const scrubbed = patterns.reduce((c, re) => c.replace(re, exports.REDACTED_PLACEHOLDER), b.content);
+        if (scrubbed === b.content)
+            return b;
+        anyChanged = true;
+        return { ...b, content: scrubbed };
+    });
+    // Return the original array reference when nothing changed —
+    // downstream reference-equality checks (cache markers) stay stable.
+    return anyChanged ? out : blocks;
+}
+exports.redactThinkingBlocks = redactThinkingBlocks;
+//# sourceMappingURL=thinkingRedaction.js.map