agentfootprint 2.3.0 → 2.5.0

package/dist/types/core/flowchartAsTool.d.ts

@@ -0,0 +1,161 @@
+/**
+ * flowchartAsTool — wrap a footprintjs `FlowChart` as an Agent `Tool`.
+ *
+ * The Block A7 piece. footprintjs is the substrate; agentfootprint is
+ * the agent layer above it. When a multi-step procedure is already
+ * expressed as a footprintjs flowchart (intake validation, refund
+ * processing, claim adjudication — anything with branches, loops, or
+ * decision evidence), let the LLM call it as ONE tool. The flowchart's
+ * step-by-step recorders, narrative, and pause/resume continue to work
+ * exactly as they do outside the agent.
+ *
+ * Why this matters:
+ *
+ *   1. **Composition over re-write.** A team with a non-trivial
+ *      footprintjs flowchart shouldn't have to flatten it into N
+ *      separate tools to expose it to an agent. Wrap it once.
+ *
+ *   2. **Observability stays free.** Every flowchart stage emits typed
+ *      events. The Agent's recorders see the wrapping tool call;
+ *      footprintjs's recorders see everything inside. Two layers,
+ *      one observation tree.
+ *
+ *   3. **Pause/resume composes.** A pausable handler inside the
+ *      flowchart pauses the inner executor; the outer agent treats
+ *      the pause as an unfinished tool call. Resume the agent and the
+ *      inner flowchart resumes from its checkpoint. (Today: surfaces
+ *      the pause as a thrown error with the checkpoint attached;
+ *      polished agent-side pause integration in v2.6.)
+ *
+ * Pattern: Adapter (GoF) over `FlowChartExecutor.run()`. Translates
+ *          `Tool.execute(args, ctx)` into `executor.run({ input: args,
+ *          env: { signal: ctx.signal } })` and the result back to a
+ *          string via `resultMapper` (or a default JSON stringify).
+ *
+ * Role:    Layer-6 (Agent) → Layer-1 (footprintjs) bridge. Pure
+ *          interop; no new abstraction in either layer.
+ *
+ * @example  Single-stage flowchart as a tool
+ *   import { flowChart } from 'footprintjs';
+ *   import { flowchartAsTool } from 'agentfootprint';
+ *
+ *   const refundChart = flowChart<{ orderId: string; reason: string }>(
+ *     'RefundFlow',
+ *     async (scope) => {
+ *       const refundId = await refundService.process(scope.$getArgs().orderId);
+ *       scope.refundId = refundId;
+ *     },
+ *     'refund-flow',
+ *   ).build();
+ *
+ *   const refundTool = flowchartAsTool({
+ *     name: 'process_refund',
+ *     description: 'Process a refund for an order. Returns refundId on success.',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: {
+ *         orderId: { type: 'string' },
+ *         reason: { type: 'string' },
+ *       },
+ *       required: ['orderId', 'reason'],
+ *     },
+ *     flowchart: refundChart,
+ *     resultMapper: (snapshot) =>
+ *       JSON.stringify({ refundId: snapshot.values.refundId, status: 'processed' }),
+ *   });
+ *
+ *   agent.tool(refundTool);
+ *
+ * @example  Multi-stage flowchart with decide() + recorders
+ *   const triageChart = flowChart<TriageState>('Triage', validateInput, 'validate')
+ *     .addDeciderFunction('Classify', classifyDecider, 'classify')
+ *       .addFunctionBranch('high', 'Escalate', escalate)
+ *       .addFunctionBranch('low', 'Auto-handle', autoHandle)
+ *       .end()
+ *     .build();
+ *
+ *   const triageTool = flowchartAsTool({
+ *     name: 'triage_request',
+ *     description: 'Triage an incoming request and return the decision.',
+ *     inputSchema: { ... },
+ *     flowchart: triageChart,
+ *   });
+ */
+import { type FlowChart } from 'footprintjs';
+import type { Tool } from './tools.js';
+/**
+ * Pruned snapshot view passed to `resultMapper`. We keep this minimal
+ * (the values bag + the chart's narrative entries) to avoid leaking
+ * internal scope plumbing. Consumers needing the full snapshot can
+ * pass a `passthrough` resultMapper that ignores the prune.
+ */
+export interface FlowchartToolSnapshot {
+    /**
+     * Final scope state — the merged result of every stage's writes.
+     * This is what `executor.getSnapshot().values` returns.
+     */
+    readonly values: Readonly<Record<string, unknown>>;
+    /**
+     * The flowchart's combined narrative entries (flow + data).
+     * Useful for resultMappers that want to extract specific commit
+     * artifacts or audit a decision path.
+     */
+    readonly narrative: readonly {
+        readonly type?: string;
+        readonly text?: string;
+    }[];
+}
+/**
+ * Optional result mapper. Receives the flowchart's final snapshot
+ * (pruned to `FlowchartToolSnapshot`) and returns the string the LLM
+ * sees as the tool result.
+ *
+ * If omitted, the default behavior is `JSON.stringify(snapshot.values)`.
+ *
+ * Errors thrown from the mapper become the tool result with a
+ * `[mapper-error: ...]` prefix so the LLM sees a useful diagnostic.
+ */
+export type FlowchartResultMapper = (snapshot: FlowchartToolSnapshot) => string;
+/**
+ * Options for `flowchartAsTool`.
+ */
+export interface FlowchartAsToolOptions {
+    /** Tool name the LLM dispatches by. Must be unique across the agent's tools. */
+    readonly name: string;
+    /** Tool description shown to the LLM. */
+    readonly description: string;
+    /**
+     * JSON Schema describing the input args the LLM must produce.
+     * Becomes `flowchart.run({ input: args })`. Default: `{ type: 'object', properties: {} }`.
+     */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /**
+     * The footprintjs flowchart to mount as the tool's body.
+     * The chart's stages receive args via `scope.$getArgs()`.
+     */
+    readonly flowchart: FlowChart;
+    /**
+     * Optional shaping function. Default: `JSON.stringify(snapshot.values)`.
+     * Errors throw into the tool's `[mapper-error: ...]` envelope.
+     */
+    readonly resultMapper?: FlowchartResultMapper;
+}
+/**
+ * Wrap a footprintjs `FlowChart` as a `Tool` the Agent's LLM can call.
+ *
+ * On execute:
+ *   1. Constructs a fresh `FlowChartExecutor(flowchart)` per call (so
+ *      consecutive invocations don't share state).
+ *   2. Calls `executor.run({ input: args, env: { signal } })` with the
+ *      LLM-supplied args + the agent's abort signal.
+ *   3. If the run paused, throws an Error with the checkpoint attached
+ *      (`error.checkpoint`) so the agent loop can surface it. Polished
+ *      agent-side pause integration is v2.6 work.
+ *   4. If the run completed, calls `resultMapper(snapshot)` (or the
+ *      default JSON.stringify) and returns the string.
+ *   5. If the run threw, the error propagates — the Agent's
+ *      tool-call handler converts it to a synthetic error string for
+ *      the LLM to see + recover from.
+ */
+export declare function flowchartAsTool(opts: FlowchartAsToolOptions): Tool;
+//# sourceMappingURL=flowchartAsTool.d.ts.map

package/dist/types/core/flowchartAsTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowchartAsTool.d.ts","sourceRoot":"","sources":["../../../src/core/flowchartAsTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,IAAI,EAAwB,MAAM,YAAY,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAsDlE"}

package/dist/types/core/outputSchema.d.ts

@@ -0,0 +1,128 @@
+/**
+ * outputSchema — declarative terminal contract for an Agent's final answer.
+ *
+ * The Block A6 piece. Lets a consumer say:
+ *
+ *   "Whatever this agent says at the end of a run, it MUST be JSON
+ *    matching this Zod (or Zod-like) schema. Auto-instruct the LLM,
+ *    parse + validate the final answer for me."
+ *
+ * Why a typed contract matters: agentic code that calls an LLM and
+ * then JSON.parses the string answer is brittle. The schema serves
+ * three jobs at once:
+ *
+ *   1. **Instruction**: a system-prompt sentence telling the LLM the
+ *      output shape (auto-generated from `schema.description` /
+ *      JSON-schema introspection where available, or from a consumer-
+ *      supplied `instruction` override).
+ *
+ *   2. **Validation**: a `parser.parse(rawString)` step on the run's
+ *      final answer, throwing `OutputSchemaError` on parse / shape
+ *      failure rather than returning malformed data.
+ *
+ *   3. **Type narrowing**: `agent.runTyped({...})` returns the inferred
+ *      shape `T` instead of `string`, so callers stop reaching for
+ *      `as MyType` casts.
+ *
+ * Pattern: Strategy (GoF) over the parser interface; structural
+ *          duck-typing (Zod / Valibot / ArkType / hand-written —
+ *          anything with a `parse(unknown): T` method satisfies it).
+ *
+ * Role:    Layer-6 (Agent) — terminal contract on the run output.
+ *          NOT a context-engineering Injection per se, but composes
+ *          with the InjectionEngine (auto-injects an Instruction).
+ *
+ * @example  zod schema
+ *   import { z } from 'zod';
+ *   const Output = z.object({ status: z.enum(['ok', 'err']), items: z.array(z.string()) });
+ *
+ *   const agent = Agent.create({ ... })
+ *     .system('You answer support tickets.')
+ *     .outputSchema(Output)
+ *     .build();
+ *
+ *   const typed = await agent.runTyped({ message: 'list pending tickets' });
+ *   typed.status; // narrowed to 'ok' | 'err'
+ *
+ * @example  valibot / arktype / hand-written parser
+ *   const Output = { parse(v: unknown): MyType { ... } };
+ *   const agent = Agent.create({...}).outputSchema(Output, { instruction: '...' }).build();
+ */
+/**
+ * Minimum shape any validation library must expose to satisfy
+ * `outputSchema`. Covers Zod (`schema.parse`), Valibot
+ * (`v.parse(schema, value)` — pass `{ parse: v => v.parse(schema, v) }`),
+ * ArkType (`type.assert`), and hand-written parsers.
+ *
+ * Implementations MUST throw on validation failure (the runtime
+ * catches the throw, wraps it in `OutputSchemaError`, and emits the
+ * diagnostic event).
+ */
+export interface OutputSchemaParser<T> {
+    parse(value: unknown): T;
+    /**
+     * Human-readable description of the output shape. Used by
+     * `outputSchema` to auto-build the system-prompt instruction when
+     * `opts.instruction` is not provided. Zod schemas expose this via
+     * `.describe('...')`; consumers can attach the field directly on
+     * hand-written parsers.
+     */
+    readonly description?: string;
+}
+/**
+ * Optional configuration for `outputSchema`.
+ */
+export interface OutputSchemaOptions {
+    /**
+     * Injection id for the auto-generated "respond with this shape"
+     * instruction. Defaults to `'output-schema'`. Override when you
+     * have multiple agents with different schemas in one process and
+     * want the diagnostic events to disambiguate.
+     */
+    readonly name?: string;
+    /**
+     * Custom system-prompt instruction text. Defaults to a generic
+     * "Respond with valid JSON matching the output schema. Do not
+     * include prose." sentence (extended with `parser.description`
+     * when present). Override when the LLM benefits from a
+     * domain-specific framing.
+     */
+    readonly instruction?: string;
+}
+/**
+ * Thrown by `agent.parseOutput(...)` / `agent.runTyped(...)` when the
+ * agent's final answer fails JSON parsing OR schema validation.
+ *
+ * `cause` carries the underlying parse error (Zod's ZodError, etc.).
+ * `rawOutput` carries the agent's untyped string output so callers
+ * can log / persist the failed response for triage.
+ */
+export declare class OutputSchemaError extends Error {
+    readonly rawOutput: string;
+    readonly stage: 'json-parse' | 'schema-validate';
+    readonly cause?: unknown;
+    constructor(message: string, opts: {
+        rawOutput: string;
+        stage: 'json-parse' | 'schema-validate';
+        cause?: unknown;
+    });
+}
+/**
+ * Default instruction template — used when `opts.instruction` is not
+ * provided. Concatenates the parser's `.description` (if present) so
+ * Zod schemas authored with `.describe('...')` propagate naturally.
+ */
+export declare function buildDefaultInstruction(parser: OutputSchemaParser<unknown>): string;
+/**
+ * Parse + validate a raw string answer against a parser. Used by
+ * `agent.parseOutput()` / `agent.runTyped()`. Centralized here so
+ * both call sites share identical error-mapping behavior.
+ *
+ * Two-stage error reporting:
+ *   - JSON parse failure → `stage: 'json-parse'` (LLM emitted prose
+ *     or malformed JSON)
+ *   - Schema validation failure → `stage: 'schema-validate'` (JSON
+ *     was valid but didn't match the contracted shape)
+ */
+export declare function applyOutputSchema<T>(raw: string, parser: OutputSchemaParser<T>): T;
+//# sourceMappingURL=outputSchema.d.ts.map

package/dist/types/core/outputSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputSchema.d.ts","sourceRoot":"","sources":["../../../src/core/outputSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAAC;IACjD,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQxF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG,MAAM,CAOnF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAmBlF"}

package/dist/types/core/slots/buildSystemPromptSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildSystemPromptSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildSystemPromptSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAOzD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAWD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CA8D/E"}
+{"version":3,"file":"buildSystemPromptSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildSystemPromptSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAOzD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAWD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CAqE/E"}

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

@@ -12,9 +12,19 @@
  */
 import type { FlowChart } from 'footprintjs';
 import type { LLMToolSchema } from '../../adapters/types.js';
+import type { ToolProvider } from '../../tool-providers/types.js';
 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 }`. 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;
     /** Budget cap (chars). Default: 2000. */
     readonly budgetCap?: number;
 }

package/dist/types/core/slots/buildToolsSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildToolsSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildToolsSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAO7D,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAmEjE"}
+{"version":3,"file":"buildToolsSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildToolsSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7D,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,+BAA+B,CAAC;AAGvF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA+HjE"}

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@
  * Role:    Single entry point consumers import from.
  * Emits:   N/A.
  */
+export type { CombinedRecorder, Recorder, FlowRecorder, EmitRecorder, WriteEvent, ReadEvent, CommitEvent, StageEvent, ErrorEvent, FlowStageEvent, FlowNextEvent, FlowDecisionEvent, FlowForkEvent, FlowSelectedEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, FlowLoopEvent, FlowBreakEvent, FlowErrorEvent, TraversalContext, EmitEvent, RedactionPolicy, RedactionReport, } from 'footprintjs';
 export * from './events/types.js';
 export * from './events/payloads.js';
 export { EVENT_NAMES, ALL_EVENT_TYPES, type AgentfootprintEvent, type AgentfootprintEventMap, type AgentfootprintEventType, } from './events/registry.js';
@@ -14,6 +15,7 @@ export { INJECTION_KEYS, injectionKeyForSlot, isInjectionKey, type InjectionKey,
 export { COMPOSITION_KEYS, type BudgetPressureRecord, type CompositionKey, type EvictionRecord, type InjectionRecord, type SlotComposition, } from './recorders/core/types.js';
 export { buildEventMeta, parseSubflowPath, type RunContext } from './bridge/eventMeta.js';
 export { ContextRecorder, type ContextRecorderOptions } from './recorders/core/ContextRecorder.js';
+export { contextEngineering, isEngineeredSource, isBaselineSource, ENGINEERED_SOURCES, BASELINE_SOURCES, type ContextEngineeringHandle, type ContextEngineeringUnsubscribe, type ContextInjectedEvent, type ContextInjectedListener, } from './recorders/core/contextEngineering.js';
 export { EmitBridge, type EmitBridgeOptions } from './recorders/core/EmitBridge.js';
 export { streamRecorder, type StreamRecorderOptions } from './recorders/core/StreamRecorder.js';
 export { agentRecorder, type AgentRecorderOptions } from './recorders/core/AgentRecorder.js';
@@ -35,6 +37,8 @@ export { defaultCommentaryTemplates, selectCommentaryKey, extractCommentaryVars,
 export { defaultThinkingTemplates, selectThinkingState, renderThinkingLine, type ThinkingContext, type ThinkingState, type ThinkingStateKind, type ThinkingTemplates, } from './recorders/observability/thinking/thinkingTemplates.js';
 export { LLMCall, LLMCallBuilder, type LLMCallInput, type LLMCallOptions, type LLMCallOutput, } from './core/LLMCall.js';
 export { Agent, AgentBuilder, type AgentInput, type AgentOptions, type AgentOutput, } from './core/Agent.js';
+export { OutputSchemaError, applyOutputSchema, buildDefaultInstruction, type OutputSchemaParser, type OutputSchemaOptions, } from './core/outputSchema.js';
+export { flowchartAsTool, type FlowchartAsToolOptions, type FlowchartResultMapper, type FlowchartToolSnapshot, } from './core/flowchartAsTool.js';
 export type { Tool, ToolExecutionContext, ToolRegistryEntry, DefineToolOptions, } from './core/tools.js';
 export { defineTool } from './core/tools.js';
 export { Sequence, SequenceBuilder, type SequenceInput, type SequenceOptions, type SequenceOutput, } from './core-flow/Sequence.js';
@@ -42,14 +46,11 @@ export { Parallel, ParallelBuilder, type BranchOutcome, type MergeFn, type Merge
 export { Conditional, ConditionalBuilder, type ConditionalInput, type ConditionalOptions, type ConditionalOutput, type Predicate, } from './core-flow/Conditional.js';
 export { Loop, LoopBuilder, type LoopInput, type LoopOptions, type LoopOutput, type UntilGuard, } from './core-flow/Loop.js';
 export { MockProvider, mock, type MockProviderOptions, type MockReply, } from './adapters/llm/MockProvider.js';
-export { anthropic, AnthropicProvider, type AnthropicProviderOptions, } from './adapters/llm/AnthropicProvider.js';
-export { openai, OpenAIProvider, ollama, type OpenAIProviderOptions, } from './adapters/llm/OpenAIProvider.js';
-export { bedrock, BedrockProvider, type BedrockProviderOptions, } from './adapters/llm/BedrockProvider.js';
 export { browserAnthropic, BrowserAnthropicProvider, type BrowserAnthropicProviderOptions, } from './adapters/llm/BrowserAnthropicProvider.js';
 export { browserOpenai, BrowserOpenAIProvider, type BrowserOpenAIProviderOptions, } from './adapters/llm/BrowserOpenAIProvider.js';
 export { createProvider, type ProviderKind, type CreateProviderOptions, } from './adapters/llm/createProvider.js';
 export { toSSE, SSEFormatter, encodeSSE, type ToSSEOptions } from './stream.js';
-export { type Injection, type InjectionTrigger, type InjectionContent, type InjectionContext, type InjectionEvaluation, evaluateInjections, buildInjectionEngineSubflow, type InjectionEngineConfig, defineInstruction, type DefineInstructionOptions, defineSkill, type DefineSkillOptions, defineSteering, type DefineSteeringOptions, defineFact, type DefineFactOptions, } from './lib/injection-engine/index.js';
+export { type Injection, type InjectionTrigger, type InjectionContent, type InjectionContext, type InjectionEvaluation, evaluateInjections, buildInjectionEngineSubflow, projectActiveInjection, type InjectionEngineConfig, type ActiveInjection, defineInstruction, type DefineInstructionOptions, defineSkill, resolveSurfaceMode, SkillRegistry, type SkillRegistryOptions, buildListSkillsTool, buildReadSkillTool, type SkillToolPair, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, type AutoActivateMode, defineSteering, type DefineSteeringOptions, defineFact, type DefineFactOptions, } from './lib/injection-engine/index.js';
 export * from './patterns/index.js';
 export { defaultPipeline, ephemeralPipeline, factPipeline, narrativePipeline, semanticPipeline, autoPipeline, } from './memory/pipeline/index.js';
 export { heuristicExtractor, llmExtractor, } from './memory/beats/index.js';
@@ -57,4 +58,7 @@ export { patternFactExtractor, llmFactExtractor, } from './memory/facts/index.js
 export { defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryDefinition, type DefineMemoryOptions, InMemoryStore, mockEmbedder, identityNamespace, type MemoryIdentity, type Embedder, } from './memory/index.js';
 export { defineRAG, type DefineRAGOptions, indexDocuments, type IndexDocumentsOptions, type RagDocument, } from './lib/rag/index.js';
 export { mcpClient, mockMcpClient, type McpClient, type McpClientOptions, type McpHttpTransport, type McpStdioTransport, type McpTransport, type McpSdkClient, type MockMcpClientOptions, type MockMcpTool, } from './lib/mcp/index.js';
+export { staticTools, gatedTools, skillScopedTools, type ToolProvider, type ToolDispatchContext, type ToolGatePredicate, } from './tool-providers/index.js';
+export { PermissionPolicy, type RoleAllowlist, type PermissionPolicyOptions, } from './security/index.js';
+export { defaultCommentaryMessages, defaultThinkingMessages, composeMessages, validateMessages, type MessageCatalog, } from './locales/index.js';
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/types/lib/injection-engine/SkillRegistry.d.ts

@@ -0,0 +1,148 @@
+/**
+ * SkillRegistry — centralized governance for Skills across one or
+ * more Agents.
+ *
+ * Most apps register Skills directly on the Agent via `.skill(s)`.
+ * Once you have multiple Agents that share a common skill catalog
+ * (a customer-support pool, a research team, a multi-step workflow
+ * where each step uses different overlapping skills), hand-syncing
+ * `.skill()` calls per Agent gets fragile.
+ *
+ * `SkillRegistry` is the answer: register once, attach to many
+ * Agents via `.skills(registry)`. Add a Skill to the registry and
+ * every consumer Agent picks it up at next build.
+ *
+ * @example
+ *   const registry = new SkillRegistry();
+ *   registry.register(billingSkill);
+ *   registry.register(refundSkill);
+ *
+ *   const supportAgent = Agent.create({ provider }).skills(registry).build();
+ *   const escalationAgent = Agent.create({ provider }).skills(registry).build();
+ *
+ *   // Add a new skill — both agents pick it up at next build.
+ *   registry.register(complianceSkill);
+ */
+import type { Injection } from './types.js';
+import { type SkillToolPair } from './skillTools.js';
+import { type SurfaceMode } from './factories/defineSkill.js';
+/**
+ * Options for `new SkillRegistry({...})`. All fields are optional;
+ * the empty-object form (`new SkillRegistry()`) is the v2.4 surface.
+ *
+ * @see SkillRegistry.resolveForSkill — applies the cascade
+ */
+export interface SkillRegistryOptions {
+    /**
+     * Registry-level default `surfaceMode`. Applies to skills whose own
+     * `surfaceMode` is `'auto'` (the `defineSkill` default). Per-skill
+     * `surfaceMode` always wins; this is the fallback BEFORE the global
+     * `resolveSurfaceMode(provider, model)` rule.
+     *
+     * Use case: a registry shared across agents pointed at the same
+     * provider can lock surfaceMode here once instead of repeating it
+     * on every `defineSkill`.
+     */
+    readonly surfaceMode?: SurfaceMode;
+    /**
+     * Provider name used as a hint when resolving `surfaceMode: 'auto'`
+     * inside this registry. Most consumers don't set this — runtime code
+     * passes the provider name into `resolveForSkill(skill, provider, model)`
+     * directly. This field is for cases where the registry is composed
+     * far from the agent (test fixtures, design-time inspectors).
+     *
+     * Match the provider's `name` field — `'anthropic'`, `'openai'`,
+     * `'mock'`, etc.
+     */
+    readonly providerHint?: string;
+}
+export declare class SkillRegistry {
+    private readonly skills;
+    private readonly opts;
+    /**
+     * Construct an empty registry. Optional `{ surfaceMode, providerHint }`
+     * fields set registry-level defaults; absent both, the registry is a
+     * pure container (the v2.4 surface).
+     */
+    constructor(opts?: SkillRegistryOptions);
+    /** Registry-level default `surfaceMode`, or `undefined` if unset. */
+    get surfaceMode(): SurfaceMode | undefined;
+    /** Registry-level provider hint, or `undefined` if unset. */
+    get providerHint(): string | undefined;
+    /**
+     * Register a skill. Throws if `skill.flavor !== 'skill'` or if a
+     * skill with the same id is already registered (use `.replace(...)`
+     * to overwrite intentionally).
+     */
+    register(skill: Injection): this;
+    /** Replace an existing skill by id. Throws if id is not registered. */
+    replace(id: string, skill: Injection): this;
+    /** Remove a skill by id. No-op if not registered. */
+    unregister(id: string): this;
+    /** Look up by id. Returns undefined if not registered. */
+    get(id: string): Injection | undefined;
+    /** True iff a skill with the given id is registered. */
+    has(id: string): boolean;
+    /** All registered skills. Order matches registration order. */
+    list(): readonly Injection[];
+    /** Number of registered skills. */
+    get size(): number;
+    /** Drop all registrations. */
+    clear(): void;
+    /**
+     * Materialize the LLM-facing skill discovery tools from the current
+     * registry contents. Returns `{ listSkills, readSkill }`:
+     *
+     *   - `list_skills` — no-arg tool the LLM calls to enumerate
+     *     `{ id, description }` for every registered skill. Lets the
+     *     LLM discover skills without paying the prompt-token cost of
+     *     a static catalog in the system prompt.
+     *
+     *   - `read_skill({ id })` — activates the named skill for the
+     *     NEXT iteration. The Agent's tool-calls subflow inspects this
+     *     tool call by name and updates `scope.activatedInjectionIds`
+     *     so the InjectionEngine on iter N+1 includes the skill in the
+     *     active set (body lands in the system slot; gated tools land
+     *     in the tools slot).
+     *
+     * Both entries are `undefined` when the registry is empty — filter
+     * before adding to a tool list:
+     *
+     *   const { listSkills, readSkill } = registry.toTools();
+     *   const tools = [listSkills, readSkill, ...other].filter(Boolean) as Tool[];
+     *
+     * Composes with `gatedTools` from `agentfootprint/tool-providers`
+     * so PermissionPolicy can scope which roles see the skill discovery
+     * surface.
+     *
+     * @returns A `SkillToolPair` (`{ listSkills, readSkill }`).
+     */
+    toTools(): SkillToolPair;
+    /**
+     * Resolve the effective `surfaceMode` for a skill, applying the
+     * cascade:
+     *
+     *   1. If the skill's own `metadata.surfaceMode` is concrete
+     *      (`'system-prompt'` / `'tool-only'` / `'both'`), return it.
+     *      Per-skill explicit choice always wins.
+     *   2. Else if the registry was constructed with a concrete
+     *      `surfaceMode`, return that.
+     *   3. Else delegate to `resolveSurfaceMode(provider, model)` using
+     *      the explicit `provider` arg (or `this.providerHint` if
+     *      omitted). Falls back to `'tool-only'` when no provider is
+     *      known.
+     *
+     * Forward-compat for Block C / v2.5 per-mode runtime routing: the
+     * runtime calls this with the agent's provider + model to decide
+     * how to materialize the skill's body into slots.
+     *
+     * Throws if the skill is not registered (catches typos at the
+     * caller site rather than silently resolving against a stranger).
+     *
+     * @param skillOrId  A registered Skill `Injection` OR its `id`.
+     * @param provider   Provider name override (wins over `providerHint`).
+     * @param model      Model name for the per-provider attention rule.
+     */
+    resolveForSkill(skillOrId: Injection | string, provider?: string, model?: string): Exclude<SurfaceMode, 'auto'>;
+}
+//# sourceMappingURL=SkillRegistry.d.ts.map

package/dist/types/lib/injection-engine/SkillRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillRegistry.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/SkillRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAA2C,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAElF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAEnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAE5C;;;;OAIG;gBACS,IAAI,GAAE,oBAAyB;IAI3C,qEAAqE;IACrE,IAAI,WAAW,IAAI,WAAW,GAAG,SAAS,CAEzC;IAED,6DAA6D;IAC7D,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAehC,uEAAuE;IACvE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAoB3C,qDAAqD;IACrD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAK5B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAItC,wDAAwD;IACxD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,+DAA+D;IAC/D,IAAI,IAAI,SAAS,SAAS,EAAE;IAI5B,mCAAmC;IACnC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,IAAI,aAAa;IAQxB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,CACb,SAAS,EAAE,SAAS,GAAG,MAAM,EAC7B,QAAQ,CAAC,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC;CAuBhC"}