agentfootprint 6.44.0 → 7.0.0

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;

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

@@ -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 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';

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

@@ -0,0 +1,33 @@
+/**
+ * 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;

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

@@ -0,0 +1,162 @@
+/**
+ * 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;
+    };
+}

package/dist/esm/tool-providers/gatedTools.d.ts

@@ -0,0 +1,36 @@
+/**
+ * gatedTools — wrap any ToolProvider with a per-tool gating predicate.
+ *
+ * The DECORATOR for tool providers. Filters the inner provider's
+ * output by running the predicate against each tool name. Composes
+ * freely:
+ *
+ *   gatedTools(
+ *     gatedTools(staticTools(allTools), readOnlyPredicate),
+ *     skillGatePredicate,
+ *   )
+ *
+ * Reads as: "static list of all tools, filtered by readonly policy,
+ * then further filtered by the active skill's tool set." Each gate
+ * is one concern; composition handles the rest.
+ *
+ * Pattern: Decorator (GoF) — wraps any ToolProvider with an additional
+ *          filter. Mirrors `withRetry` / `withFallback` over LLMProvider.
+ *
+ * @example  Read-only enforcement
+ *   const readOnly = gatedTools(
+ *     staticTools([read, write]),
+ *     (toolName) => toolName.startsWith('read_'),
+ *   );
+ *   readOnly.list(ctx); // → [read]
+ *
+ * @example  Skill-gated dispatch (autoActivate use case)
+ *   const skillGated = gatedTools(
+ *     staticTools(allTools),
+ *     (toolName, ctx) => ctx.activeSkillId
+ *       ? skillToolMap[ctx.activeSkillId].includes(toolName)
+ *       : alwaysVisible.includes(toolName),
+ *   );
+ */
+import type { ToolProvider, ToolGatePredicate } from './types.js';
+export declare function gatedTools(inner: ToolProvider, predicate: ToolGatePredicate): ToolProvider;

package/dist/esm/tool-providers/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * agentfootprint/tool-providers — chainable tool dispatch + tool sources.
+ *
+ * Two layers under one subpath:
+ *
+ * 1. Tool dispatch (this folder)
+ *    - `staticTools(arr)` — wrap a flat tool list
+ *    - `gatedTools(inner, predicate)` — decorator that filters
+ *    - `ToolProvider` interface — the contract
+ *    - `ToolDispatchContext` — read-only context per iteration
+ *
+ * 2. Tool sources (re-exported from existing modules)
+ *    - `mcpClient(opts)` — connect to an MCP server (real)
+ *    - `mockMcpClient({ tools })` — in-memory MCP source for dev / tests
+ *
+ * Compose freely. The dispatch layer is decorator-shaped (mirroring
+ * `withRetry` / `withFallback` over LLMProvider). Tool sources produce
+ * `Tool[]` that flow into a `staticTools(arr)` provider, which can
+ * then be wrapped by `gatedTools(...)` for permission gating or
+ * per-skill filtering.
+ *
+ * @example  Static (90% case — what `agent.tools(arr)` does today)
+ *   const provider = staticTools([weatherTool, lookupTool]);
+ *
+ * @example  Read-only enforcement
+ *   const readOnly = gatedTools(
+ *     staticTools(allTools),
+ *     (name) => policy.isAllowed(name),
+ *   );
+ *
+ * @example  MCP source + permission gate
+ *   const slack = await mcpClient({ transport: ... });
+ *   const slackTools = await slack.tools();
+ *   const provider = gatedTools(staticTools(slackTools), (name) => allowed(name));
+ */
+export { staticTools } from './staticTools.js';
+export { gatedTools } from './gatedTools.js';
+export { skillScopedTools } from './skillScopedTools.js';
+export type { ToolProvider, ToolDispatchContext, ToolGatePredicate } from './types.js';
+export { mcpClient, mockMcpClient } from '../lib/mcp/index.js';
+export type { McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, MockMcpClientOptions, MockMcpTool, } from '../lib/mcp/index.js';

package/dist/esm/tool-providers/skillScopedTools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * skillScopedTools — ToolProvider that exposes a tool subset only when
+ * a specific Skill is active in the current iteration's context.
+ *
+ * The Block A5 piece. Pairs with `defineSkill({ autoActivate: 'currentSkill' })`
+ * to give the LLM a sharper choice space: when `billing` activates, the
+ * tool list flips from "all 25 agent tools" to "the 7 billing tools" +
+ * any baseline (always-on) tools the consumer composes alongside.
+ *
+ * Pattern: gated ToolProvider keyed by `ctx.activeSkillId`. Pure compute;
+ *          no Agent-runtime dependency. Composes freely with `staticTools`
+ *          for the always-on baseline.
+ *
+ * @example  One skill's tools, scoped by activation
+ *   const billingTools = skillScopedTools('billing', [refundTool, chargeTool]);
+ *   billingTools.list({ iteration: 1, activeSkillId: 'billing' });
+ *   // → [refundTool, chargeTool]
+ *   billingTools.list({ iteration: 1, activeSkillId: 'refund' });
+ *   // → [] (different skill active)
+ *   billingTools.list({ iteration: 1 });
+ *   // → [] (no skill active)
+ *
+ * @example  Compose with baseline + multiple skills
+ *   const baseline   = staticTools([lookupOrderTool, listSkills, readSkill]);
+ *   const billingTbx = skillScopedTools('billing', [refundTool, chargeTool]);
+ *   const refundTbx  = skillScopedTools('refund',  [reverseTool]);
+ *
+ *   // Wrap each scope-provider in a gatedTools for downstream composition,
+ *   // OR build a small wrapper that concatenates list(ctx) outputs:
+ *   const provider: ToolProvider = {
+ *     id: 'composite',
+ *     list: (ctx) => [
+ *       ...baseline.list(ctx),
+ *       ...billingTbx.list(ctx),
+ *       ...refundTbx.list(ctx),
+ *     ],
+ *   };
+ *
+ * Note: the runtime that POPULATES `ctx.activeSkillId` from
+ * `scope.activatedInjectionIds` lands in Block C / v2.5+. Today,
+ * consumers can drive it manually for tests + design-time inspection.
+ */
+import type { Tool } from '../core/tools.js';
+import type { ToolProvider } from './types.js';
+export declare function skillScopedTools(skillId: string, tools: readonly Tool[]): ToolProvider;

package/dist/esm/tool-providers/staticTools.d.ts

@@ -0,0 +1,21 @@
+/**
+ * staticTools — the simplest ToolProvider. Wraps a fixed Tool[] list.
+ *
+ * 90% case. What `agent.tools(arr)` does today, made composable.
+ * Equivalent to passing `arr` directly EXCEPT that `staticTools(arr)`
+ * is now a `ToolProvider` you can wrap with `gatedTools(...)` for
+ * permission filtering or per-skill gating.
+ *
+ * Pattern: identity ToolProvider — no filtering, just exposes the
+ *          underlying list verbatim.
+ *
+ * @example
+ *   const provider = staticTools([weatherTool, lookupTool]);
+ *   // Materialize the visible list and register via .tools(...).
+ *   // Direct .toolProvider(...) wiring on the builder lands in Block A5 / v2.5+.
+ *   const visible = provider.list({ iteration: 0, identity: { conversationId: '_' } });
+ *   const agent = Agent.create({ provider: llm, model }).tools(visible).build();
+ */
+import type { Tool } from '../core/tools.js';
+import type { ToolProvider } from './types.js';
+export declare function staticTools(tools: readonly Tool[]): ToolProvider;

package/dist/esm/tool-providers/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * ToolProvider — abstraction over tool dispatch.
+ *
+ * v2.4 shipped tools as a flat array on the agent (registered via
+ * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
+ * production agents need:
+ *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
+ *   2. Per-skill tool gating (only show the active skill's tools to
+ *      the LLM each turn)
+ *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
+ *      decorator over the base tool list)
+ *
+ * `ToolProvider` is the answer: a chainable abstraction over "what
+ * tools does the LLM see right now?". The agent asks the provider
+ * each iteration; the provider returns the visible tool set computed
+ * from whatever predicates / role gates / skill filters the consumer
+ * composed.
+ *
+ * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
+ *          "compute the visible tool list given current context".
+ *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
+ *          provider with an additional filter, mirroring how `withRetry`
+ *          / `withFallback` decorate `LLMProvider`.
+ * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
+ *          each iteration to compute the visible tool set.
+ * Emits:   N/A (pure compute; permission denials emit elsewhere via the
+ *          permission subsystem).
+ *
+ * @example  Static tool list (90% case — what `.tools(arr)` does today)
+ *   const provider = staticTools([weather, lookupOrder]);
+ *
+ * @example  Read-only enforcement (role-based gate)
+ *   const readOnlyProvider = gatedTools(
+ *     staticTools([weather, lookupOrder, processRefund]),
+ *     (toolName) => policy.isAllowed(toolName),
+ *   );
+ *
+ * @example  Skill-gated dispatch (only active skill's tools visible)
+ *   const skillGated = gatedTools(
+ *     staticTools(allTools),
+ *     (toolName, ctx) => ctx.activeSkillId
+ *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
+ *       : alwaysVisible.includes(toolName),
+ *   );
+ *
+ * @example  Stack: read-only over skill-gated
+ *   const provider = gatedTools(
+ *     gatedTools(staticTools(allTools), readOnlyPredicate),
+ *     skillGatePredicate,
+ *   );
+ */
+import type { Tool } from '../core/tools.js';
+/**
+ * Read-only context the provider receives each iteration. Pure data
+ * — providers MUST NOT mutate. Used by gating predicates to inspect
+ * the current activation state.
+ */
+export interface ToolDispatchContext {
+    /** Current ReAct iteration (1-based). */
+    readonly iteration: number;
+    /**
+     * The id of the currently-activated Skill, if any.
+     * Set by `read_skill(id)` activation; cleared between turns.
+     * Used by `autoActivate`-driven per-skill tool gating.
+     */
+    readonly activeSkillId?: string;
+    /**
+     * Caller identity tuple — passed through from `agent.run({ identity })`.
+     * Permission predicates can role-check based on `identity.principal`
+     * or `identity.tenant`.
+     */
+    readonly identity?: {
+        readonly tenant?: string;
+        readonly principal?: string;
+        readonly conversationId: string;
+    };
+    /**
+     * Optional abort signal propagated from the agent's `run({ env })` /
+     * AbortController. Async providers (network discovery, MCP catalog
+     * fetch, registry pull) MUST honor this — abandon the in-flight
+     * request when the agent is cancelled mid-discovery, otherwise the
+     * provider holds the run open past abort. Sync providers can ignore
+     * it.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * The provider interface. A `ToolProvider` answers ONE question per
+ * iteration: "what tools should the LLM see right now?"
+ *
+ * Implementations are PURE — given the same context, return the same
+ * tool list (no observable mutation; reentrant; safe under concurrent
+ * calls).
+ *
+ * **Sync vs async.** Most providers (`staticTools`, `gatedTools`,
+ * `skillScopedTools`) compute the answer synchronously and return
+ * `readonly Tool[]` — the agent's hot path skips the await microtask
+ * entirely via a runtime `instanceof Promise` check. Discovery-style
+ * providers (MCP catalog fetch, registry pull, dynamic skill resolution)
+ * may return `Promise<readonly Tool[]>`; the agent awaits only when
+ * the value is actually a Promise. Sync providers pay zero overhead.
+ *
+ * **Caching.** The agent calls `list(ctx)` once per iteration. For
+ * expensive lookups (network calls, hub queries), the provider is
+ * responsible for caching — typically TTL- or iteration-keyed. The
+ * framework deliberately does NOT cache for you because the cache
+ * key depends on which fields of `ctx` matter to your provider
+ * (e.g., per-skill vs per-tenant vs per-iteration).
+ *
+ * **Errors.** A throwing or rejecting provider emits
+ * `agentfootprint.tools.discovery_failed` and aborts the iteration —
+ * the run continues only if a configured `reliability` rule routes
+ * the error (`fail-fast`, `retry`, etc.). Discovery failure is loud
+ * by design; silently dropping tools mid-conversation produces
+ * non-deterministic agent behavior that's harder to debug than a
+ * crash.
+ */
+export interface ToolProvider {
+    /**
+     * Return the tool list visible to the LLM for the current iteration.
+     * Sync return is the fast path; Promise return is supported for
+     * discovery-style providers. The returned array MUST be a NEW
+     * reference each call (the agent compares for change detection).
+     * Order is preserved — the LLM may use position as a hint when tool
+     * descriptions are ambiguous.
+     */
+    list(ctx: ToolDispatchContext): readonly Tool[] | Promise<readonly Tool[]>;
+    /**
+     * Optional: stable id for observability / debugging. Defaults to
+     * `'static'` for `staticTools`, `'gated'` for `gatedTools`. Custom
+     * implementations should set their own id — surfaces on
+     * `agentfootprint.tools.discovery_failed.providerId` so consumers
+     * can route alerts to the right hub adapter.
+     */
+    readonly id?: string;
+}
+/** Predicate for `gatedTools` — runs per tool, per iteration. */
+export type ToolGatePredicate = (toolName: string, ctx: ToolDispatchContext) => boolean;

package/dist/events.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * agentfootprint/events — the typed event system.
+ *
+ * Every agentfootprint run emits a single, strongly-typed event stream:
+ * the registry (`EVENT_NAMES`, `AgentfootprintEventMap`, `AgentfootprintEvent`),
+ * the dispatcher (`EventDispatcher` + listener/wildcard types), the shared
+ * context/composition types, and the ~60 typed payload shapes (grouped
+ * under the `Payloads` namespace).
+ *
+ * This is observability infrastructure, not core agent API, so in v7 it
+ * lives on its own subpath — consistent with `/observe`, `/memory`, etc.
+ * Recorders (`agentfootprint/observe`) and viewer libraries consume it;
+ * the `Agent` builder wires it for you.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventDispatcher = exports.ALL_EVENT_TYPES = exports.EVENT_NAMES = void 0;
+// Shared event/context/composition types.
+__exportStar(require("./events/types.js"), exports);
+// Registry — the event-name set + the typed map/union/discriminant.
+var registry_js_1 = require("./events/registry.js");
+Object.defineProperty(exports, "EVENT_NAMES", { enumerable: true, get: function () { return registry_js_1.EVENT_NAMES; } });
+Object.defineProperty(exports, "ALL_EVENT_TYPES", { enumerable: true, get: function () { return registry_js_1.ALL_EVENT_TYPES; } });
+// Dispatcher — subscribe to the stream (`.on(type, listener)`), wildcard
+// subscriptions, and the unsubscribe handle.
+var dispatcher_js_1 = require("./events/dispatcher.js");
+Object.defineProperty(exports, "EventDispatcher", { enumerable: true, get: function () { return dispatcher_js_1.EventDispatcher; } });
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;AAEH,0CAA0C;AAC1C,oDAAkC;AAQlC,oEAAoE;AACpE,oDAM8B;AAL5B,0GAAA,WAAW,OAAA;AACX,8GAAA,eAAe,OAAA;AAMjB,yEAAyE;AACzE,6CAA6C;AAC7C,wDASgC;AAR9B,gHAAA,eAAe,OAAA"}