agentfootprint 6.43.0 → 6.45.0

package/dist/esm/core/runner.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Runner — consumer-facing interface for every primitive/composition/pattern.
+ *
+ * Pattern: Facade (GoF) over the footprintjs FlowChart + EventDispatcher.
+ * Role:    The one object consumers hold. Exposes:
+ *            - `.run()` (execute)
+ *            - `.getSpec()` (the design-time FlowChart blueprint —
+ *              same value footprintjs's `addSubFlowChart*` accepts)
+ *            - `.on() / .off() / .once()` (listener subscription)
+ *            - `.attach()` (attach custom CombinedRecorder)
+ *            - `.emit()` (consumer-defined custom events on the same
+ *              dispatcher, matches DOM CustomEvent)
+ * Emits:   N/A — this file defines the INTERFACE. Concrete runners
+ *          (LLMCall, Agent, Sequence, etc.) implement it.
+ */
+import type { CombinedRecorder, FlowChart, FlowchartCheckpoint, RunOptions } from 'footprintjs';
+import type { RunnerPauseOutcome } from './pause.js';
+import type { EventListener, ListenOptions, Unsubscribe, WildcardListener, WildcardSubscription } from '../events/dispatcher.js';
+import type { AgentfootprintEvent, AgentfootprintEventType } from '../events/registry.js';
+import type { FlowchartHandle, FlowchartOptions } from '../recorders/observability/FlowchartRecorder.js';
+import type { LocalObservabilityHandle, LocalObservabilityOptions } from '../recorders/observability/localObservability.js';
+import type { ObservabilityEnableOptions, CostEnableOptions, LiveStatusEnableOptions } from '../strategies/attach.js';
+/**
+ * High-level feature-enable methods. Each attaches a pre-built observability
+ * recorder and returns an Unsubscribe function. Additional methods land in
+ * Phase 5 (lens, tracing, cost, guardrails, ...).
+ */
+export interface EnableNamespace {
+    /**
+     * Live composition graph — subflow / fork-branch / decision-branch
+     * nodes accumulate as execution unfolds. Hook into any graph renderer
+     * (React Flow, Cytoscape, D3) without touching footprintjs internals.
+     *
+     * Returns a handle with `getSnapshot()` so the UI can query the graph
+     * at any time (not just via onUpdate).
+     */
+    flowchart(opts?: FlowchartOptions): FlowchartHandle;
+    /**
+     * Tier-3 / Debug — RETAIN a live run model: render it live via
+     * `<Lens recorder={handle} />` (the handle's `onUpdate` drives the UI) AND
+     * snapshot it for OFFLINE replay via `handle.getTrace()` / `onComplete`.
+     *
+     * Contrast `observability({ strategy })` below (Tier-4 / Monitor), which
+     * ships each event to a vendor and forgets. `localObservability` keeps the
+     * model so you can look at it — locally, with full content. The serialized
+     * `Trace` is redactable at the serialize boundary (`redact` / `getTrace`).
+     */
+    localObservability(opts?: LocalObservabilityOptions): LocalObservabilityHandle;
+    /**
+     * v2.8+ — grouped strategy enabler for observability. Pipes every
+     * typed event into a vendor strategy (Datadog, OTel, AgentCore,
+     * CloudWatch, …) or the default `consoleObservability()`. See
+     * `agentfootprint/strategies` + `docs/inspiration/strategy-everywhere.md`.
+     */
+    observability(opts?: ObservabilityEnableOptions): Unsubscribe;
+    /**
+     * v2.8+ — grouped strategy enabler for cost. Subscribes the strategy
+     * to `cost.tick` events; defaults to `inMemorySinkCost()` for
+     * read-back / test inspection.
+     */
+    cost(opts?: CostEnableOptions): Unsubscribe;
+    /**
+     * v2.8+ — grouped strategy enabler for chat-bubble live status.
+     * Maintains the thinking-state machine; calls strategy.renderStatus
+     * each time the rendered line changes (deduped — not on every token).
+     * Strategy is required (consumer must wire UI).
+     */
+    liveStatus(opts: LiveStatusEnableOptions): Unsubscribe;
+}
+/**
+ * Every primitive (LLMCall, Agent), every composition (Sequence, Parallel,
+ * Conditional, Loop), and every pattern factory result implements Runner.
+ * That makes them freely nestable: any runner can be a child of any
+ * composition.
+ */
+export interface Runner<TIn = unknown, TOut = unknown> {
+    /**
+     * Return the footprintjs FlowChart for this runner — the canonical
+     * design-time blueprint. Stable across calls. Pairs with the run-time
+     * accessors (`getLastSnapshot`, `getCommitCount`) and matches
+     * `ExplainableShell.spec` + `specToReactFlow(spec, ...)` consumer
+     * conventions.
+     *
+     * Subflow mounting (footprintjs `addSubFlowChart*`) accepts the
+     * `FlowChart` value directly:
+     *
+     *   parent.addSubFlowChartNext('sf-agent', child.getSpec(), 'Agent')
+     */
+    getSpec(): FlowChart;
+    /**
+     * Return the consumer-shaped UI group for this runner — produced by
+     * invoking the `groupTranslator` (if one was attached at constructor
+     * time) with this composition's metadata. Returns `undefined` when no
+     * translator was attached.
+     *
+     * Companion of `getSpec()`: `getSpec()` is the canonical (UI-
+     * agnostic) blueprint; `getUIGroup()` is the consumer-shaped view.
+     * Both are stable post-construction.
+     *
+     * See `core/translator.ts` for the `GroupTranslator` /
+     * `GroupMetadata` types.
+     */
+    getUIGroup<T = unknown>(): T | undefined;
+    /**
+     * Translate this runner's group metadata with a CALLER-SUPPLIED
+     * translator that OVERRIDES whatever translator (if any) the runner
+     * was constructed with. Used by parent compositions to apply
+     * per-method translator overrides (e.g.,
+     * `Parallel.create(...).branch('special', runner, { groupTranslator: ... })`
+     * — for the `'special'` branch only, this `override` runs against
+     * `runner`'s own `GroupMetadata` instead of the runner's default
+     * translator).
+     *
+     * NOT cached at the runner level. The caller invokes this exactly
+     * once per build (parent's `buildUIGroupMetadata`) and caches the
+     * resulting `uiGroup` via the parent's `RunnerBase.uiGroupCache`.
+     *
+     * Returns `undefined` when this runner has no group metadata to
+     * translate (i.e., `buildUIGroupMetadata()` returned `undefined`).
+     */
+    getUIGroupWith<T = unknown>(override: import('./translator.js').GroupTranslator): T | undefined;
+    /**
+     * Execute the runner. On happy-path completion, resolves with `TOut`.
+     * If any stage (Agent tool via `pauseHere`, nested runner, or consumer
+     * scope code) called `scope.$pause()`, resolves with a `RunnerPauseOutcome`
+     * carrying the serializable checkpoint. Discriminate with `isPaused()`.
+     */
+    run(input: TIn, options?: RunOptions): Promise<TOut | RunnerPauseOutcome>;
+    /**
+     * Resume a previously-paused execution from its checkpoint. `input` is
+     * delivered to the paused stage's resume handler. The same return shape
+     * as `run()`: `TOut` on completion, `RunnerPauseOutcome` if execution
+     * pauses again (e.g., a multi-step approval flow).
+     */
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<TOut | RunnerPauseOutcome>;
+    /**
+     * Subscribe a typed listener. Returns unsubscribe.
+     *
+     * Lifecycle: the subscription lives until you call the returned
+     * Unsubscribe, the `{ signal }` you passed aborts, or
+     * `removeAllListeners()` runs. Nothing auto-expires per-run — pass a
+     * per-run AbortSignal for request-scoped listeners on long-lived
+     * runners (servers).
+     */
+    on<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>, options?: ListenOptions): Unsubscribe;
+    /** Subscribe to a domain wildcard (e.g. 'agentfootprint.context.*') or '*'. */
+    on(type: WildcardSubscription, listener: WildcardListener, options?: ListenOptions): Unsubscribe;
+    /** Unsubscribe a previously-registered listener. */
+    off<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>): void;
+    off(type: WildcardSubscription, listener: WildcardListener): void;
+    /** Subscribe a one-shot listener (fires once then auto-removes). Accepts `{ signal }`. */
+    once<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>, options?: Omit<ListenOptions, 'once'>): Unsubscribe;
+    once(type: WildcardSubscription, listener: WildcardListener, options?: Omit<ListenOptions, 'once'>): Unsubscribe;
+    /**
+     * Drop every event listener on this runner in one call (typed,
+     * domain-wildcard, and `'*'`). Lifecycle escape hatch for server
+     * consumers that can't keep Unsubscribe handles. Also removes
+     * listeners wired by `enable.*` strategies; does NOT detach recorders
+     * added via `attach()`.
+     */
+    removeAllListeners(): void;
+    /**
+     * Diagnostic — listeners currently retained. No argument = total
+     * (the leak-detection number); with a subscription key = that exact
+     * bucket only (wildcards not folded in — use the dispatcher's
+     * `hasListenersFor` semantics for "would anything fire").
+     */
+    listenerCount(type?: AgentfootprintEventType | WildcardSubscription): number;
+    /**
+     * Attach a footprintjs CombinedRecorder to observe the execution.
+     * Returns an unsubscribe function — call it to detach the recorder
+     * from future runs. (Already-running executions continue using it.)
+     *
+     * Recorders live for the RUNNER's lifetime: nothing auto-expires
+     * per-run, and `removeAllListeners()` does not touch them. The caller
+     * owns cleanup via the returned Unsubscribe.
+     */
+    attach(recorder: CombinedRecorder): Unsubscribe;
+    /**
+     * Enable-namespace for high-level observability features. Each method
+     * attaches a pre-built CombinedRecorder and returns an unsubscribe
+     * function. Consumers write ONE line to enable rich observability,
+     * instead of N `.on()` subscriptions.
+     */
+    readonly enable: EnableNamespace;
+    /**
+     * Emit a consumer-defined custom event through the same dispatcher.
+     *
+     * Matches DOM CustomEvent. Useful for domain-specific events outside
+     * the 47-event registry (e.g. `myapp.billing.checkpoint`). Library
+     * events are reserved under the `agentfootprint.*` namespace.
+     */
+    emit(name: string, payload: Record<string, unknown>): void;
+}
+/** Kept for convenience — mirrors the RunOptions export from footprintjs. */
+export type { RunOptions };
+/**
+ * Union used in emit() for the `AgentfootprintEvent` type constraint. A
+ * consumer emitting a custom event passes a plain object payload; the
+ * dispatcher wraps it as AgentfootprintEvent only when the name is a
+ * registered type. Otherwise it flows through as an opaque custom event.
+ */
+export type EmittedEvent = AgentfootprintEvent;

package/dist/esm/core/slots/buildMessagesSlot.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Messages slot subflow builder
+ *
+ * Pattern: Builder (returns a FlowChart mountable via addSubFlowChartNext).
+ * Role:    Layer-3 context engineering. Produces InjectionRecord[] from
+ *          the current conversation history. For LLMCall, that's one
+ *          user message. For Agent, it's user + assistant + tool-result
+ *          messages accumulated over iterations.
+ * Emits:   None directly; ContextRecorder sees the writes.
+ *
+ * Minimal scope for Phase 3e: pass-through of an input message history
+ * array. Full MessageStrategy (windowing, summarizing) arrives in Phase 5.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { ContextRole } from '../../events/types.js';
+/**
+ * A single message supplied by the caller. Structurally matches the
+ * LLMMessage adapter type but local-aliased to keep this file free of
+ * adapter-layer coupling.
+ */
+export interface InputMessage {
+    readonly role: ContextRole;
+    readonly content: string;
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+}
+export interface MessagesSlotConfig {
+    /** Budget cap (chars). Default: 10000. */
+    readonly budgetCap?: number;
+}
+/**
+ * Build the Messages slot subflow.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(SUBFLOW_IDS.MESSAGES, buildMessagesSlot(cfg), 'Messages', {
+ *     inputMapper: (parent) => ({ messages: parent.messages, iteration: parent.iteration }),
+ *     outputMapper: (sf) => ({ messagesInjections: sf.messagesInjections }),
+ *   })
+ */
+export declare function buildMessagesSlot(config?: MessagesSlotConfig): FlowChart;

package/dist/esm/core/slots/buildSystemPromptSlot.d.ts

@@ -0,0 +1,41 @@
+/**
+ * System-Prompt slot subflow builder
+ *
+ * Pattern: Builder (returns a FlowChart mountable via addSubFlowChartNext).
+ * Role:    Layer-3 context engineering; inside Layer-5 primitives
+ *          (LLMCall, Agent). Ported from v1's buildSystemPromptSubflow
+ *          to InjectionRecord + SlotComposition shape.
+ * Emits:   None directly. Writes to conventional scope keys; ContextRecorder
+ *          observes and emits context.* events.
+ *
+ * Minimal scope for Phase 3e: static prompt string OR a dynamic function
+ * of the input. Full SystemPromptProvider / Skill / RAG integration
+ * arrives in Phase 5.
+ */
+import type { FlowChart } from 'footprintjs';
+/**
+ * Function that produces the system prompt string given runtime scope
+ * context. Receives the subflow's $getArgs() payload.
+ */
+export type SystemPromptFn = (args: {
+    readonly userMessage?: string;
+    readonly iteration?: number;
+}) => string | Promise<string>;
+export interface SystemPromptSlotConfig {
+    /** Static string OR a function. Empty string → no injection, empty slot. */
+    readonly prompt: string | SystemPromptFn;
+    /** Budget cap (chars). Default: 4000. */
+    readonly budgetCap?: number;
+    /** Optional description — where this prompt originated (e.g. "agent.system()"). */
+    readonly reason?: string;
+}
+/**
+ * Build the System-Prompt slot subflow.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(SUBFLOW_IDS.SYSTEM_PROMPT, buildSystemPromptSlot(cfg), 'System Prompt', {
+ *     inputMapper: (parent) => ({ userMessage: parent.userMessage, iteration: parent.iteration }),
+ *     outputMapper: (sf) => ({ systemPromptInjections: sf.systemPromptInjections }),
+ *   })
+ */
+export declare function buildSystemPromptSlot(config: SystemPromptSlotConfig): FlowChart;

package/dist/esm/core/slots/buildThinkingSubflow.d.ts

@@ -0,0 +1,40 @@
+/**
+ * NormalizeThinking sub-subflow — wraps a consumer's `ThinkingHandler`
+ * (function-pair contract) in a real footprintjs subflow at chart
+ * build time. Mounted as a stage AFTER CallLLM inside `sf-call-llm`
+ * when (and only when) a handler is configured.
+ *
+ * runtimeStageId format: `sf-call-llm/thinking-{handler.id}#N`
+ *
+ * Two-layer architecture (per Phase 1 panel decision):
+ *   - CONSUMER-FACING:    `ThinkingHandler` — simple function-pair
+ *                          (id, providerNames, normalize, parseChunk?)
+ *   - FRAMEWORK-INTERNAL: this file wraps each handler in a real
+ *                         footprintjs subflow with own runtimeStageId,
+ *                         narrative entry, and InOutRecorder boundary.
+ *
+ * Failure isolation: handler `normalize()` throws are caught here.
+ * Framework emits `agentfootprint.agent.thinking_parse_failed`, sets
+ * `scope.thinkingBlocks` to empty, and the subflow exits cleanly. The
+ * agent run continues; the assistant message simply has no thinking
+ * blocks attached. Same graceful pattern as v2.11.6 `tools.discovery_failed`.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { ThinkingHandler } from '../../thinking/types.js';
+/**
+ * Build a thinking-normalization sub-subflow for a configured handler.
+ * Mounted as a single-stage subflow inside `sf-call-llm` AFTER CallLLM.
+ *
+ * The subflow:
+ *   1. Reads `scope.rawThinking` (set by CallLLM from `LLMResponse.rawThinking`)
+ *   2. If rawThinking is undefined → write empty array, exit (early-return)
+ *   3. Calls `handler.normalize(rawThinking)`
+ *   4. On success: writes `scope.thinkingBlocks` + emits `stream.thinking_end`
+ *   5. On throw: writes empty array + emits `agent.thinking_parse_failed`
+ *
+ * The result on `scope.thinkingBlocks` is read by toolCalls.ts and
+ * prepareFinal.ts when constructing the assistant message for
+ * `scope.history` — that's where the Anthropic signature round-trip
+ * actually flows from.
+ */
+export declare function buildThinkingSubflow(handler: ThinkingHandler): FlowChart;

package/dist/esm/core/slots/buildToolsSlot.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tools slot subflow builder
+ *
+ * Pattern: Builder (returns a FlowChart mountable via addSubFlowChartNext).
+ * Role:    Layer-3 context engineering. Resolves the tools list the LLM
+ *          sees on this iteration — one InjectionRecord per exposed tool.
+ * Emits:   None directly; ContextRecorder sees the writes.
+ *
+ * Minimal scope for Phase 3e: static tool registry, all exposed every
+ * iteration. Full permission gating / skill activation / context-aware
+ * tool filtering arrives in Phase 5.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { LLMToolSchema } from '../../adapters/types.js';
+import type { Tool } from '../tools.js';
+import type { ToolProvider } from '../../tool-providers/types.js';
+/**
+ * Mutable cache shared between `buildToolsSlot` (writer) and
+ * `buildToolCallsHandler` (reader) within ONE run. The Tools slot
+ * resolves the provider's tools each iteration and stashes the
+ * Tool[] here; the toolCalls handler reads on dispatch — so async
+ * providers pay the discovery cost once, not twice. Scoped to the
+ * chart build so concurrent `agent.run()` calls each get their own
+ * cache.
+ */
+export interface ProviderToolCache {
+    current: readonly Tool[];
+}
+export interface ToolsSlotConfig {
+    /** Tool registry exposed to the LLM. Empty → empty slot (LLMCall case). */
+    readonly tools: readonly LLMToolSchema[];
+    /**
+     * Optional `ToolProvider` consulted PER-ITERATION (Block A5 follow-up).
+     * When set, the slot calls `provider.list(ctx)` each iteration with
+     * the current `{ iteration, activeSkillId, identity, signal }`.
+     * Provider-supplied tool schemas are MERGED with the static `tools`
+     * registry — both flow to the LLM. This is what makes Dynamic ReAct's
+     * tool list reshape per iteration.
+     */
+    readonly toolProvider?: ToolProvider;
+    /**
+     * Mutable cache the slot writes to after resolving `toolProvider.list(ctx)`.
+     * The same cache reference is passed to `buildToolCallsHandler` so
+     * dispatch reads from this iteration's resolved Tool[] instead of
+     * calling `list()` a second time. Required when `toolProvider` is set.
+     */
+    readonly providerToolCache?: ProviderToolCache;
+    /** Budget cap (chars). Default: 2000. */
+    readonly budgetCap?: number;
+}
+/**
+ * Build the Tools slot subflow.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(SUBFLOW_IDS.TOOLS, buildToolsSlot(cfg), 'Tools', {
+ *     inputMapper: (parent) => ({ iteration: parent.iteration }),
+ *     outputMapper: (sf) => ({ toolsInjections: sf.toolsInjections, toolSchemas: sf.toolSchemas }),
+ *   })
+ */
+export declare function buildToolsSlot(config: ToolsSlotConfig): FlowChart;

package/dist/esm/core/slots/helpers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared helpers for slot subflow builders.
+ *
+ * Pattern: utility module.
+ * Role:    Tiny pure functions the slot builders share — hash, truncate,
+ *          breakdown. Kept co-located to avoid cross-package import churn.
+ */
+import type { ContextSource, ContextSlot } from '../../events/types.js';
+import type { InjectionRecord, SlotComposition } from '../../recorders/core/types.js';
+/** Non-cryptographic stable hash — sufficient for InjectionRecord dedup. */
+export declare function fnv1a(input: string): string;
+/** Truncate with ellipsis for contentSummary fields. */
+export declare function truncate(s: string, n: number): string;
+/** Aggregate injection chars/count per source — payload for SlotComposition. */
+export declare function breakdown(injections: readonly InjectionRecord[]): Readonly<Partial<Record<ContextSource, {
+    chars: number;
+    count: number;
+}>>>;
+/**
+ * Build a SlotComposition summary record from injections + budget cap.
+ * Drop tracking is opt-in — pass `dropped` when the slot actually
+ * evicted anything during composition.
+ */
+export declare function composeSlot(slot: ContextSlot, iteration: number, injections: readonly InjectionRecord[], budgetCap: number, orderingStrategy?: string, dropped?: {
+    count: number;
+    summaries: readonly string[];
+}): SlotComposition;

package/dist/esm/core/toolContract.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Agent ↔ tool-server contract check (proposal 009, the server-boundary extension).
+ *
+ * When an agent's tools call a remote tool-server (an MCP-ish sidecar, a function
+ * gateway), the agent's `inputSchema` and the server's real contract can drift —
+ * and the model then calls a tool that 404s, or omits an arg the server REQUIRES and
+ * gets a 501/400 "doesn't work." The server usually publishes its own catalog
+ * (e.g. `GET /tools` → `[{ name, inputSchema }]`), so the drift is checkable.
+ *
+ * `toolContractCheckup(agentTools, serverCatalog)` is a PURE diff (no I/O — the
+ * consumer fetches the catalog and passes it). It mirrors the `graph.checkup()`
+ * shape so both feed the same reporting.
+ */
+import type { Tool } from './tools.js';
+export type ToolContractCode = 'missing-on-server' | 'dead-endpoint' | 'required-divergence' | 'arg-divergence' | 'optional-drift';
+/** One contract issue. `kind: 'error'` fails `ok`. */
+export interface ToolContractProblem {
+    readonly kind: 'error' | 'warning';
+    readonly code: ToolContractCode;
+    readonly tool: string;
+    readonly message: string;
+}
+export interface ToolContractCheckup {
+    readonly ok: boolean;
+    readonly problems: readonly ToolContractProblem[];
+}
+/** A server-catalog entry — the shape of one item from `GET /tools`. */
+export interface ServerToolEntry {
+    readonly name: string;
+    readonly inputSchema?: {
+        readonly required?: readonly string[];
+        readonly properties?: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Diff an agent's tools against a server's tool catalog. Pure + deterministic.
+ *
+ * @param agentTools     the agent's tools (`Tool[]` or `{name, inputSchema}[]`)
+ * @param serverCatalog  the server's catalog (e.g. `await (await fetch('/tools')).json()`)
+ */
+export declare function toolContractCheckup(agentTools: ReadonlyArray<Tool | ServerToolEntry>, serverCatalog: ReadonlyArray<ServerToolEntry>): ToolContractCheckup;
+/** Format a contract check-up for a thrown error / console warning. */
+export declare function formatToolContractCheckup(checkup: ToolContractCheckup): string;

package/dist/esm/core/tools.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Tool types — Agent's tool-call contract.
+ *
+ * Pattern: Strategy (GoF) — each Tool is a strategy for "how to execute
+ *          this named operation given these args".
+ * Role:    Consumer-facing shape. Agent.tool(...) accepts these.
+ * Emits:   N/A (types only).
+ */
+import type { LLMToolSchema } from '../adapters/types.js';
+import type { Credential, CredentialNeed, CredentialProvider } from '../identity/types.js';
+/**
+ * One executable tool the Agent can call.
+ *
+ * - `schema` is what the LLM sees (name, description, JSON schema).
+ * - `execute` runs when the LLM requests this tool with the given args.
+ *   Returns anything JSON-serializable; the framework forwards it back
+ *   to the LLM as the tool result.
+ */
+export interface Tool<TArgs = Record<string, unknown>, TResult = unknown> {
+    readonly schema: LLMToolSchema;
+    /** Declare-and-push: a credential this tool needs. The framework resolves it
+     *  BEFORE invoking and injects `ctx.credential`; it is NOT in `schema`, so the
+     *  LLM never sees or fills it. */
+    readonly needs?: CredentialNeed;
+    execute(args: TArgs, ctx: ToolExecutionContext): Promise<TResult> | TResult;
+}
+/** Runtime context passed to tool.execute(). */
+export interface ToolExecutionContext {
+    /** Unique id of THIS tool invocation (matches stream.tool_start.toolCallId). */
+    readonly toolCallId: string;
+    /** Current iteration number of the ReAct loop. */
+    readonly iteration: number;
+    /** Abort signal propagated from run({ env: { signal } }). */
+    readonly signal?: AbortSignal;
+    /**
+     * The bound credential provider — the PULL escape hatch for dynamic needs.
+     * Always present: when none is attached it's a fail-closed provider that
+     * THROWS, so it never silently no-ops via optional chaining. Prefer the
+     * declarative `needs` + `ctx.credential` for the common case.
+     */
+    readonly credentials: CredentialProvider;
+    /** True when a real provider is attached. Branch on this for intentional
+     *  degraded (no-credential) mode instead of relying on `undefined`. */
+    readonly hasCredentials: boolean;
+    /** The credential resolved for this tool's declared `needs` (declare-and-push).
+     *  Present only when the tool declared a need and it resolved successfully. */
+    readonly credential?: Credential;
+}
+/**
+ * Internal: registry entry keyed by tool name.
+ * Consumer never sees this shape.
+ */
+export interface ToolRegistryEntry {
+    readonly name: string;
+    readonly tool: Tool;
+}
+/**
+ * Convenience input for `defineTool` — flatter than `Tool` itself.
+ * Consumers describe the tool inline; the helper assembles `schema`.
+ *
+ * `inputSchema` is a JSON Schema object (the same one the LLM will
+ * see). For tools that take no arguments, pass `{ type: 'object',
+ * properties: {} }` or omit and we'll default to that.
+ */
+export interface DefineToolOptions<TArgs, TResult> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /** Declare a credential this tool needs (declare-and-push). Resolved by the
+     *  framework before `execute` and injected as `ctx.credential`. */
+    readonly needs?: CredentialNeed;
+    execute(args: TArgs, ctx: ToolExecutionContext): Promise<TResult> | TResult;
+}
+/**
+ * STRICT validation — throws a clear, actionable error if a tool name can't be
+ * sent to an LLM. Exposed for consumers who want to fail hard (e.g. in a build
+ * step or a test). The library itself only WARNS (see `warnIfInvalidToolName`),
+ * because a name is provider-specific: a mock or a name-sanitizing custom provider
+ * may accept dotted/namespaced names that OpenAI/Anthropic reject.
+ */
+export declare function assertValidToolName(name: unknown): asserts name is string;
+/**
+ * DEV-MODE heads-up (never throws): warns once-per-call if a tool name will be
+ * rejected by OpenAI/Anthropic. Production and non-dev runs pay nothing. This is
+ * the library's default guard (Convention: dev diagnostics warn, they don't throw)
+ * — keeping mock/custom-provider + namespaced-name setups working. Reach for
+ * `assertValidToolName` when you want a hard failure.
+ */
+export declare function warnIfInvalidToolName(name: unknown): void;
+export declare function defineTool<TArgs = Record<string, unknown>, TResult = unknown>(options: DefineToolOptions<TArgs, TResult>): Tool<TArgs, TResult>;

package/dist/esm/core/translator.d.ts

@@ -0,0 +1,94 @@
+/**
+ * GroupTranslator — UI-agnostic composition-level translator hook.
+ *
+ * Pattern: Visitor (GoF) at the composition boundary. Consumer supplies
+ *          a translator function; each agentfootprint composition
+ *          (Parallel, Sequence, Loop, Conditional, Agent, LLMCall)
+ *          invokes it with composition-level metadata to produce a
+ *          consumer-shaped UI output.
+ * Role:    The per-COMPOSITION hook alongside footprintjs's per-NODE
+ *          `StructureRecorder`. The two are independent — a consumer
+ *          can attach either, both, or neither.
+ *
+ *          - StructureRecorder observes ONE spec node at a time (record).
+ *          - GroupTranslator sees the WHOLE composition (compose).
+ *
+ *          For Lens's compound rendering (Parallel-as-container,
+ *          Agent-as-drillable-card, LLMCall-as-card-with-slots),
+ *          this is the right granularity: the translator knows the
+ *          composition KIND and its full member list at once, so it
+ *          can emit a single group-level shape with children pre-laid.
+ *
+ * Cascade: each composition that runs nested compositions exposes its
+ *          members' OWN translated outputs via `GroupMember.uiGroup`.
+ *          The consumer threads the same translator through every
+ *          composition's construction (or per-method override via
+ *          L1c) to get end-to-end coverage. No automatic propagation
+ *          — propagation requires footprintjs-level changes which
+ *          we're not making for this hook.
+ */
+import type { Runner } from './runner.js';
+/**
+ * The composition KIND a translator sees in `GroupMetadata.kind`.
+ * Closed union — every agentfootprint composition declares exactly
+ * one of these via the literal string baked into its `buildChart()`
+ * description prefix and surfaced here in `GroupMetadata`.
+ */
+export type GroupKind = 'Parallel' | 'Sequence' | 'Loop' | 'Conditional' | 'Agent' | 'LLMCall';
+/**
+ * One member of a composition. Shape is uniform across composition
+ * kinds — Parallel branches, Sequence steps, Loop body, Conditional
+ * branches, Agent tools/slots, LLMCall slots all map to this.
+ *
+ * `memberId` is the stable id the composition assigned (e.g. `legal`
+ * for a Parallel branch, `step-classify` for a Sequence step,
+ * `body` for a Loop). Consumers can correlate this with the
+ * SpecNode's `subflowId` / `id` to drill in.
+ *
+ * `runner` is the underlying `Runner` instance — useful for the
+ * consumer to call `member.runner.getSpec()` for the nested chart or
+ * `member.runner.getUIGroup()` for the nested translation result
+ * (when the same translator was threaded through that runner's
+ * construction).
+ *
+ * `uiGroup` is the member's already-translated output. Populated
+ * when the consumer threaded the same `groupTranslator` reference
+ * into each member's construction; `undefined` otherwise.
+ */
+export interface GroupMember {
+    readonly memberId: string;
+    readonly runner: Runner;
+    readonly uiGroup?: unknown;
+}
+/**
+ * What a composition hands to its `groupTranslator` at build time.
+ * All composition kinds emit the same shape — the `kind` discriminator
+ * + the `extra` bag carry per-composition specifics.
+ */
+export interface GroupMetadata {
+    readonly kind: GroupKind;
+    readonly id: string;
+    readonly name: string;
+    readonly members: ReadonlyArray<GroupMember>;
+    /**
+     * Composition-specific extras. Carried verbatim from the
+     * composition's own state — `Parallel` puts the merge strategy
+     * here, `Loop` puts iteration budgets, `Conditional` puts the
+     * fallback branch id, etc. Closed enough per kind that consumers
+     * can switch on `kind` to read it safely.
+     */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The consumer-supplied translator. Pure function — no async, no
+ * side effects expected. Runs ONCE per composition at the moment
+ * `getUIGroup()` is first called (memoised behaviour is per
+ * composition's discretion).
+ *
+ * Output type `T` is whatever the consumer wants — a React Flow
+ * group node, a Mermaid string, a domain-specific layout object,
+ * anything. agentfootprint stays UI-agnostic.
+ */
+export interface GroupTranslator<T = unknown> {
+    (group: GroupMetadata): T;
+}