agentfootprint 2.12.1 → 2.14.0

package/dist/types/thinking/MockThinkingHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockThinkingHandler.d.ts","sourceRoot":"","sources":["../../../src/thinking/MockThinkingHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,gEAAgE;AAChE,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,mBAAmB,CAAC;QAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC,CAAC;CACJ;AAED,6DAA6D;AAC7D,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAiBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GAC7E,gBAAgB,CASlB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAE5E;AAED,eAAO,MAAM,mBAAmB,EAAE,eA0CjC,CAAC"}

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

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

package/dist/types/thinking/OpenAIThinkingHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAIThinkingHandler.d.ts","sourceRoot":"","sources":["../../../src/thinking/OpenAIThinkingHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAcjE,eAAO,MAAM,qBAAqB,EAAE,eAoCnC,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * 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 type { ThinkingBlock, ThinkingHandler } from './types.js';
+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.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/thinking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,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/types/thinking/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { ThinkingHandler } from './types.js';
+/**
+ * All thinking handlers shipped with the library. Append in alphabetical
+ * order (by `id`) so diffs stay readable as new handlers land.
+ */
+export declare const SHIPPED_THINKING_HANDLERS: readonly ThinkingHandler[];
+/**
+ * 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 declare function findThinkingHandler(providerName: string): ThinkingHandler | undefined;
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/thinking/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/thinking/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,eAAe,EAI/D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAKrF"}

package/dist/types/thinking/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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.
+ */
+/**
+ * One thinking block from an LLM response, normalized into a provider-
+ * agnostic shape. A response may contain multiple blocks (e.g. OpenAI's
+ * structured reasoning_summary emits one block per summary step).
+ *
+ * Discriminator `type`:
+ *   - `'thinking'`            — content is the model's reasoning
+ *   - `'redacted_thinking'`   — Anthropic emits this when reasoning
+ *                               trips a safety filter; content is
+ *                               EMPTY but `signature` is still required
+ *                               for round-trip on the next turn
+ */
+export interface ThinkingBlock {
+    /**
+     * Block type discriminator. Required so consumers can distinguish
+     * normal thinking blocks from server-redacted ones (Anthropic-only
+     * today; other providers may produce only `'thinking'`).
+     */
+    readonly type: 'thinking' | 'redacted_thinking';
+    /**
+     * Reasoning content as plain text. EMPTY string when `type ===
+     * 'redacted_thinking'` (the model's reasoning was redacted by the
+     * provider's safety layer; only the signature remains).
+     */
+    readonly content: string;
+    /**
+     * Provider cryptographic signature for round-trip integrity.
+     *
+     * **Anthropic:** REQUIRED for any block emitted in a response that
+     * also contained tool_use. The signed block MUST be echoed
+     * byte-exact in the assistant message of subsequent tool_result
+     * turns — Anthropic validates the signature server-side and rejects
+     * (HTTP 400) requests where signed blocks are missing or modified.
+     *
+     * **OpenAI:** not used (their reasoning_summary doesn't sign blocks).
+     *
+     * **Future providers:** opaque to the framework; preserved as-is.
+     *
+     * The framework persists this field in `scope.history` so the
+     * provider's serialization layer (Phase 4b) can echo it back on the
+     * next request.
+     */
+    readonly signature?: string;
+    /**
+     * `true` when this block is a structured-summary step rather than
+     * raw thinking content. Set by `OpenAIThinkingHandler` for each step
+     * of `reasoning_summary`; never set by Anthropic. Consumers
+     * displaying thinking can render summary blocks differently
+     * (e.g. as numbered steps) from raw blocks (continuous prose).
+     */
+    readonly summary?: boolean;
+    /**
+     * Provider-specific metadata escape hatch for fields the normalized
+     * shape doesn't model.
+     *
+     * **ANTI-PATTERN:** providers MUST NOT include sensitive raw data
+     * here (PII, internal IDs, request tokens, customer data). Use the
+     * dedicated `signature` field for cryptographic material; nothing
+     * else identity-bearing. The framework excludes `providerMeta` from
+     * `getNarrative()` by default to avoid accidental audit-log leakage.
+     */
+    readonly providerMeta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The consumer-facing contract for thinking normalization. Provider
+ * authors and custom-LLM consumers implement this shape; the framework
+ * auto-wraps each handler in a real footprintjs subflow at chart build
+ * time so the trace shows it as a discrete `runtimeStageId` (e.g.
+ * `sf-call-llm/thinking-{id}#5`).
+ *
+ * The framework matches handlers to providers by `providerNames` —
+ * the first handler whose `providerNames` includes the active
+ * `provider.name` is auto-wired. Override per-agent via
+ * `.thinkingHandler(customHandler)` (Phase 3 wiring).
+ */
+export interface ThinkingHandler {
+    /**
+     * Stable identifier used for `runtimeStageId`, telemetry, narrative
+     * entries, and the `agentfootprint.agent.thinking_parse_failed` event
+     * payload's `subflowId` field. Convention: lowercase + dash, e.g.
+     * `'anthropic'`, `'openai'`, `'mock'`.
+     */
+    readonly id: string;
+    /**
+     * Provider names this handler matches for auto-wire. The framework
+     * scans `SHIPPED_THINKING_HANDLERS` at chart build time and selects
+     * the first handler whose `providerNames` contains the active
+     * `provider.name`. Most handlers list one name; Bedrock-via-Anthropic
+     * style handlers may list multiple.
+     */
+    readonly providerNames: readonly string[];
+    /**
+     * Pure: raw provider data → normalized blocks.
+     *
+     * The framework wraps this call in a try/catch — throwing from
+     * `normalize()` does NOT abort the agent run. Instead the framework
+     * emits `agentfootprint.agent.thinking_parse_failed`, drops the
+     * thinking blocks (LLMMessage.thinkingBlocks remains undefined),
+     * and continues. Same graceful-failure pattern as v2.11.6
+     * `tools.discovery_failed`.
+     *
+     * Sync only in v2.14. Future widening to Promise return is a
+     * separate decision once a real consumer needs network-backed
+     * normalization.
+     *
+     * @param raw Provider-specific raw data — typically pulled from
+     *            `LLMResponse.providerRef`. Handler is responsible for
+     *            shape-checking; framework passes whatever the provider
+     *            stashed.
+     * @returns Normalized blocks in the order they appeared in the
+     *          response. Empty array when no thinking is present
+     *          (preferred over `undefined` for type stability).
+     */
+    normalize(raw: unknown): readonly ThinkingBlock[];
+    /**
+     * Optional streaming hot-path. When provided AND the provider streams,
+     * the framework calls `parseChunk(chunk)` per provider chunk and
+     * emits `agentfootprint.stream.thinking_delta` events for any
+     * `thinkingDelta` returned. Handlers without streaming support omit
+     * this field; the framework still calls `normalize()` on the
+     * response's terminal `LLMResponse.providerRef`.
+     *
+     * @param chunk Provider-specific chunk shape (Anthropic emits
+     *              `content_block_delta` events; OpenAI doesn't yet
+     *              stream reasoning content).
+     * @returns Object with optional `thinkingDelta` text — when set,
+     *          framework fires `stream.thinking_delta` event with the
+     *          content. Return `{}` (or omit) for chunks that contain
+     *          no thinking content.
+     */
+    parseChunk?(chunk: unknown): {
+        thinkingDelta?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/thinking/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,mBAAmB,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,aAAa,EAAE,CAAC;IAElD;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.12.1",
+  "version": "2.14.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -159,6 +159,11 @@
       "import": "./dist/esm/reliability/index.js",
       "require": "./dist/reliability/index.js"
     },
+    "./thinking": {
+      "types": "./dist/types/thinking/index.d.ts",
+      "import": "./dist/esm/thinking/index.js",
+      "require": "./dist/thinking/index.js"
+    },
     "./locales": {
       "types": "./dist/types/locales/index.d.ts",
       "import": "./dist/esm/locales/index.js",