agentfootprint 2.13.0 → 2.14.1

package/dist/thinking/AnthropicThinkingHandler.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anthropicThinkingHandler = void 0;
+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;
+}
+exports.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/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;AAEY,QAAA,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/thinking/MockThinkingHandler.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockThinkingHandler = exports.mockOpenAIRaw = exports.mockAnthropicRaw = void 0;
+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.
+ */
+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 }),
+        })),
+    };
+}
+exports.mockAnthropicRaw = mockAnthropicRaw;
+/**
+ * Build an OpenAI-style raw input for tests — one summary step per
+ * string. Each step becomes a separate ThinkingBlock with `summary: true`.
+ */
+function mockOpenAIRaw(summarySteps) {
+    return { kind: 'openai', summarySteps };
+}
+exports.mockOpenAIRaw = mockOpenAIRaw;
+exports.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/thinking/MockThinkingHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockThinkingHandler.js","sourceRoot":"","sources":["../../src/thinking/MockThinkingHandler.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAuBH,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,CAAC,GAAG,GAAmE,CAAC;IAC9E,wEAAwE;IACxE,uEAAuE;IACvE,+DAA+D;IAC/D,+CAA+C;IAC/C,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAC9B,MAA8E;IAE9E,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAE,mBAA6B,CAAC,CAAC,CAAE,UAAoB;YACzE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YAC9C,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;SAC7D,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAXD,4CAWC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,YAA+B;IAC3D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AAC1C,CAAC;AAFD,sCAEC;AAEY,QAAA,mBAAmB,GAAoB;IAClD,EAAE,EAAE,MAAM;IACV,6DAA6D;IAC7D,oCAAoC;IACpC,aAAa,EAAE,CAAC,MAAM,CAAC;IAEvB,SAAS,CAAC,GAAY;QACpB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAE/B,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC7B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAiB,EAAE;gBACzC,IAAI,CAAC,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;oBACnC,OAAO;wBACL,IAAI,EAAE,mBAAmB;wBACzB,OAAO,EAAE,EAAE;wBACX,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;qBAC7D,CAAC;gBACJ,CAAC;gBACD,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,OAAO,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;oBACzB,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;iBAC7D,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,sEAAsE;QACtE,OAAO,GAAG,CAAC,YAAY,CAAC,GAAG,CACzB,CAAC,OAAO,EAAiB,EAAE,CAAC,CAAC;YAC3B,IAAI,EAAE,UAAU;YAChB,OAAO;YACP,OAAO,EAAE,IAAI;SACd,CAAC,CACH,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,KAAc;QACvB,4DAA4D;QAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QAC3D,MAAM,CAAC,GAAG,KAAoC,CAAC;QAC/C,OAAO,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,CAAC;CACF,CAAC"}

package/dist/thinking/OpenAIThinkingHandler.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAIThinkingHandler = void 0;
+function isOpenAIStructuredArray(raw) {
+    return Array.isArray(raw);
+}
+exports.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/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;AAEY,QAAA,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/thinking/index.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findThinkingHandler = exports.SHIPPED_THINKING_HANDLERS = exports.openAIThinkingHandler = exports.anthropicThinkingHandler = exports.mockOpenAIRaw = exports.mockAnthropicRaw = exports.mockThinkingHandler = void 0;
+var MockThinkingHandler_js_1 = require("./MockThinkingHandler.js");
+Object.defineProperty(exports, "mockThinkingHandler", { enumerable: true, get: function () { return MockThinkingHandler_js_1.mockThinkingHandler; } });
+Object.defineProperty(exports, "mockAnthropicRaw", { enumerable: true, get: function () { return MockThinkingHandler_js_1.mockAnthropicRaw; } });
+Object.defineProperty(exports, "mockOpenAIRaw", { enumerable: true, get: function () { return MockThinkingHandler_js_1.mockOpenAIRaw; } });
+var AnthropicThinkingHandler_js_1 = require("./AnthropicThinkingHandler.js");
+Object.defineProperty(exports, "anthropicThinkingHandler", { enumerable: true, get: function () { return AnthropicThinkingHandler_js_1.anthropicThinkingHandler; } });
+var OpenAIThinkingHandler_js_1 = require("./OpenAIThinkingHandler.js");
+Object.defineProperty(exports, "openAIThinkingHandler", { enumerable: true, get: function () { return OpenAIThinkingHandler_js_1.openAIThinkingHandler; } });
+var registry_js_1 = require("./registry.js");
+Object.defineProperty(exports, "SHIPPED_THINKING_HANDLERS", { enumerable: true, get: function () { return registry_js_1.SHIPPED_THINKING_HANDLERS; } });
+Object.defineProperty(exports, "findThinkingHandler", { enumerable: true, get: function () { return registry_js_1.findThinkingHandler; } });
+//# sourceMappingURL=index.js.map

package/dist/thinking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/thinking/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;;;AAIH,mEAAgG;AAAvF,6HAAA,mBAAmB,OAAA;AAAE,0HAAA,gBAAgB,OAAA;AAAE,uHAAA,aAAa,OAAA;AAE7D,6EAAyE;AAAhE,uIAAA,wBAAwB,OAAA;AAEjC,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAE9B,6CAA+E;AAAtE,wHAAA,yBAAyB,OAAA;AAAE,kHAAA,mBAAmB,OAAA"}

package/dist/thinking/registry.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findThinkingHandler = exports.SHIPPED_THINKING_HANDLERS = void 0;
+const AnthropicThinkingHandler_js_1 = require("./AnthropicThinkingHandler.js");
+const MockThinkingHandler_js_1 = require("./MockThinkingHandler.js");
+const OpenAIThinkingHandler_js_1 = require("./OpenAIThinkingHandler.js");
+/**
+ * All thinking handlers shipped with the library. Append in alphabetical
+ * order (by `id`) so diffs stay readable as new handlers land.
+ */
+exports.SHIPPED_THINKING_HANDLERS = [
+    AnthropicThinkingHandler_js_1.anthropicThinkingHandler,
+    MockThinkingHandler_js_1.mockThinkingHandler,
+    OpenAIThinkingHandler_js_1.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
+ */
+function findThinkingHandler(providerName) {
+    for (const handler of exports.SHIPPED_THINKING_HANDLERS) {
+        if (handler.providerNames.includes(providerName))
+            return handler;
+    }
+    return undefined;
+}
+exports.findThinkingHandler = findThinkingHandler;
+//# sourceMappingURL=registry.js.map

package/dist/thinking/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/thinking/registry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,+EAAyE;AACzE,qEAA+D;AAC/D,yEAAmE;AAGnE;;;GAGG;AACU,QAAA,yBAAyB,GAA+B;IACnE,sDAAwB;IACxB,4CAAmB;IACnB,gDAAqB;CACtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,YAAoB;IACtD,KAAK,MAAM,OAAO,IAAI,iCAAyB,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,OAAO,CAAC;IACnE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AALD,kDAKC"}

package/dist/thinking/types.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/thinking/types.js.map

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

package/dist/types/adapters/llm/AnthropicProvider.d.ts

@@ -31,6 +31,10 @@ interface AnthropicCreateParams {
     tools?: AnthropicTool[];
     temperature?: number;
     stop_sequences?: string[];
+    thinking?: {
+        type: 'enabled';
+        budget_tokens: number;
+    };
 }
 interface AnthropicMessageParam {
     role: 'user' | 'assistant';
@@ -49,6 +53,13 @@ type AnthropicContentBlock = {
     tool_use_id: string;
     content: string;
     is_error?: boolean;
+} | {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+} | {
+    type: 'redacted_thinking';
+    signature?: string;
 };
 interface AnthropicTool {
     name: string;

package/dist/types/adapters/llm/AnthropicProvider.d.ts.map

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

package/dist/types/adapters/llm/BrowserAnthropicProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BrowserAnthropicProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/BrowserAnthropicProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,UAAU,EACV,WAAW,EAEZ,MAAM,aAAa,CAAC;AA6CrB,MAAM,WAAW,+BAA+B;IAC9C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;CAChC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,+BAA+B,GAAG,WAAW,CAwKtF;AAED,qBAAa,wBAAyB,YAAW,WAAW;IAC1D,QAAQ,CAAC,IAAI,uBAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,OAAO,EAAE,+BAA+B;IAIpD,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC;CAIjD"}
+{"version":3,"file":"BrowserAnthropicProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/BrowserAnthropicProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,UAAU,EACV,WAAW,EAEZ,MAAM,aAAa,CAAC;AAsDrB,MAAM,WAAW,+BAA+B;IAC9C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;CAChC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,+BAA+B,GAAG,WAAW,CAsPtF;AAED,qBAAa,wBAAyB,YAAW,WAAW;IAC1D,QAAQ,CAAC,IAAI,uBAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,OAAO,EAAE,+BAA+B;IAIpD,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC;CAIjD"}

package/dist/types/adapters/types.d.ts

@@ -13,6 +13,7 @@
  * these interfaces — never on concrete adapters.
  */
 import type { ContextRole, ContextSlot, ContextSource } from '../events/types.js';
+import type { ThinkingBlock } from '../thinking/types.js';
 export interface LLMMessage {
     readonly role: ContextRole;
     readonly content: string;
@@ -33,6 +34,26 @@ export interface LLMMessage {
         readonly name: string;
         readonly args: Readonly<Record<string, unknown>>;
     }[];
+    /**
+     * v2.14 — Thinking blocks emitted by the LLM on assistant turns.
+     *
+     * Required for Anthropic extended-thinking + tool-use flows: signed
+     * blocks MUST be echoed BYTE-EXACT in subsequent assistant turns or
+     * Anthropic's API rejects with 400. The framework persists blocks
+     * here so the AnthropicProvider's serializer (Phase 4b) can restore
+     * them on the next request.
+     *
+     * **Persistence model — DIFFERENT from `ephemeral`:**
+     *   - `ephemeral` messages: NOT persisted to scope.history
+     *   - `thinkingBlocks`: PERSISTED (required for signature round-trip)
+     *
+     * Visible to recorders + audit by default. Use
+     * `RedactionPolicy.thinkingPatterns` (Phase 3) to scrub sensitive
+     * reasoning content before audit-log adapters fire.
+     *
+     * Empty array OR undefined when no thinking is present (most calls).
+     */
+    readonly thinkingBlocks?: readonly ThinkingBlock[];
     /**
      * v2.13 — PERSISTENCE flag (NOT a visibility flag). When `true`:
      *   • The message IS sent to the LLM as part of the next request
@@ -83,6 +104,32 @@ export interface LLMRequest {
      * cache support (OpenAI auto-cache, Mock, NoOp) ignore it.
      */
     readonly cacheMarkers?: readonly import('../cache/types.js').CacheMarker[];
+    /**
+     * v2.14 — request the LLM emit reasoning/thinking content on this call.
+     *
+     * Activation: presence of this field tells the provider to ASK for
+     * thinking. Anthropic translates to `thinking: { type: 'enabled',
+     * budget_tokens: budget }` on the wire. OpenAI ignores (o1/o3
+     * thinking is selected at the model id level, not per-request).
+     *
+     * `budget` is the maximum reasoning tokens the model may spend.
+     * Anthropic requires it; recommended range 1024-32000 for
+     * claude-sonnet-4-5 / opus-4-5. Models that don't support extended
+     * thinking will reject the request with HTTP 400 — pick a supported
+     * model when setting this field.
+     *
+     * Independent from `LLMMessage.thinkingBlocks` (the response side):
+     *   - `request.thinking` = activation (consumer ASKS for thinking)
+     *   - `message.thinkingBlocks` = round-trip (consumer ECHOES prior
+     *     assistant turn's signed blocks back to the model)
+     *
+     * Set via `AgentBuilder.thinking({ budget })` — applied to every
+     * LLM call the agent makes. Leave undefined to call without thinking
+     * (the v2.13 default).
+     */
+    readonly thinking?: {
+        readonly budget: number;
+    };
 }
 export interface LLMResponse {
     readonly content: string;
@@ -96,9 +143,43 @@ export interface LLMResponse {
         readonly output: number;
         readonly cacheRead?: number;
         readonly cacheWrite?: number;
+        /**
+         * v2.14 — count of reasoning/thinking tokens used by the model.
+         * Distinct from `output` (which is visible-content tokens).
+         *
+         * Semantics:
+         *   - `undefined` — provider doesn't expose / no thinking enabled
+         *                   on this call / call without extended thinking
+         *   - `0`         — thinking enabled but model produced no
+         *                   thinking tokens this call
+         *   - `>0`        — actual reasoning token count (billing-relevant
+         *                   for both Anthropic extended thinking and
+         *                   OpenAI o1/o3 reasoning_tokens)
+         *
+         * Cost dashboards reading `cost.tick` events should track this
+         * separately from `output` — pricing differs (Anthropic charges
+         * extended thinking at output rates; OpenAI o1/o3 reasoning tokens
+         * are billed as a separate line item).
+         */
+        readonly thinking?: number;
     };
     readonly stopReason: string;
     readonly providerRef?: string;
+    /**
+     * v2.14 — Provider-specific raw thinking data, opaque to the
+     * framework. Providers that support extended thinking populate this
+     * with their native shape (Anthropic: array of `{type, thinking,
+     * signature}` blocks; OpenAI: `reasoning_summary` value; custom:
+     * whatever the provider emits). The framework hands this to a
+     * configured `ThinkingHandler.normalize(rawThinking)` to produce
+     * the normalized `ThinkingBlock[]` that lands on
+     * `LLMMessage.thinkingBlocks`.
+     *
+     * Undefined when the provider has no thinking content for this call
+     * — most calls (gpt-4o, claude without extended thinking enabled,
+     * etc.). The thinking subflow's stage early-returns in this case.
+     */
+    readonly rawThinking?: unknown;
 }
 export interface LLMChunk {
     readonly tokenIndex: number;
@@ -119,6 +200,22 @@ export interface LLMChunk {
      * authoritative payload in that case.
      */
     readonly response?: LLMResponse;
+    /**
+     * v2.14 — streaming thinking-content tokens. Parallel to `content`
+     * but for the model's reasoning chain rather than visible output.
+     * Set on chunks that carry thinking deltas (Anthropic emits these
+     * via `content_block_delta` events with `delta.type === 'thinking_delta'`);
+     * undefined or empty on chunks that carry only visible-content tokens.
+     *
+     * Frameworks: this field drives `agentfootprint.stream.thinking_delta`
+     * events when a `ThinkingHandler.parseChunk()` returns one. Consumers
+     * who want to render thinking-as-it-streams subscribe to that event.
+     *
+     * Default consumer behavior: thinking tokens are NOT shown to end
+     * users via `enable.thinking({ stream: false })` (the default).
+     * Consumers explicitly opt in with `enable.thinking({ stream: true })`.
+     */
+    readonly thinkingDelta?: string;
 }
 export interface LLMProvider {
     readonly name: string;