agentfootprint 2.4.0 → 2.5.0

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, resolveSurfaceMode, SkillRegistry, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, 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

@@ -24,8 +24,51 @@
  *   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(...)`
@@ -46,5 +89,60 @@ export declare class SkillRegistry {
     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

@@ -1 +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;AAE5C,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IAEvD;;;;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;CAGd"}
+{"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"}

package/dist/types/lib/injection-engine/factories/defineSkill.d.ts

@@ -43,12 +43,13 @@ import type { Tool } from '../../../core/tools.js';
  * - `'auto'` — the library picks per provider via `resolveSurfaceMode`.
  *   `'both'` on Claude ≥ 3.5; `'tool-only'` everywhere else.
  *
- * **Today's behavior:** all four modes route through the recency-first
- * path the essay describes as cross-provider-correct (the activation +
- * next-iteration injection pattern). Full per-mode routing diversity
- * (suppress system-prompt for `'tool-only'`, e.g.) is a v2.5 polish.
- * Consumers express intent today; runtime behavior tightens later
- * without API change.
+ * **v2.5 runtime dispatch (Block C):** modes now route differently:
+ *   - `'system-prompt'` → body in system slot, tool result is confirmation
+ *   - `'tool-only'`     → body SUPPRESSED from system slot, tool result IS the body
+ *   - `'both'`          → body in system slot AND in tool result
+ *   - `'auto'`          → keeps v2.4 behavior (body in system slot, tool result is confirmation)
+ *     The Block A4 cascade resolves `'auto'` against provider/model context
+ *     at a future runtime layer (Claude ≥ 3.5 → `'both'`; else `'tool-only'`).
  */
 export type SurfaceMode = 'auto' | 'system-prompt' | 'tool-only' | 'both';
 /**
@@ -101,7 +102,33 @@ export interface DefineSkillOptions {
      * long-context attention decay. Default: undefined (no refresh).
      */
     readonly refreshPolicy?: RefreshPolicy;
+    /**
+     * Per-skill tool gating intent. Block A5 / v2.5.
+     *
+     * - `'currentSkill'` — when this Skill is the only active one, the
+     *   agent's tool list should narrow to this Skill's `tools` (plus
+     *   the consumer-composed baseline). Used with
+     *   `skillScopedTools(id, tools)` from `agentfootprint/tool-providers`
+     *   to materialize the gate. Block C wires this into the runtime
+     *   automatically.
+     * - `undefined` (default) — current additive behavior: this Skill's
+     *   tools are added to the agent's registry on activation, alongside
+     *   every other tool already registered.
+     *
+     * The field is a forward-compat marker today: the metadata stores
+     * it; consumers can read `skill.metadata.autoActivate` to drive
+     * their own ToolProvider composition. v2.5 runtime wiring builds
+     * on this contract without API change.
+     */
+    readonly autoActivate?: AutoActivateMode;
 }
+/**
+ * Per-skill tool gating mode. See `DefineSkillOptions.autoActivate`.
+ *
+ * Reserved future values: `'always'` (always show this Skill's tools
+ * regardless of activation), `'group'` (gate by a named skill group).
+ */
+export type AutoActivateMode = 'currentSkill';
 /**
  * Resolve `surfaceMode: 'auto'` to a concrete mode based on provider
  * + model. The defaults match the per-provider attention profile

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

@@ -1 +1 @@
-{"version":3,"file":"defineSkill.d.ts","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAahF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,CAiC/D"}
+{"version":3,"file":"defineSkill.d.ts","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAahF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,CAkC/D"}

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

@@ -5,12 +5,14 @@
  * One `Injection` type. One `InjectionEngine` subflow. N typed sugar
  * factories. See `README.md` in this folder for the full concept.
  */
-export type { Injection, InjectionTrigger, InjectionContent, InjectionContext, InjectionEvaluation, } from './types.js';
+export type { Injection, InjectionTrigger, InjectionContent, InjectionContext, InjectionEvaluation, ActiveInjection, } from './types.js';
+export { projectActiveInjection } from './types.js';
 export { evaluateInjections } from './evaluator.js';
 export { buildInjectionEngineSubflow, type InjectionEngineConfig, } from './buildInjectionEngineSubflow.js';
 export { defineInstruction, type DefineInstructionOptions } from './factories/defineInstruction.js';
-export { defineSkill, resolveSurfaceMode, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, } from './factories/defineSkill.js';
-export { SkillRegistry } from './SkillRegistry.js';
+export { defineSkill, resolveSurfaceMode, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, type AutoActivateMode, } from './factories/defineSkill.js';
+export { SkillRegistry, type SkillRegistryOptions } from './SkillRegistry.js';
+export { buildListSkillsTool, buildReadSkillTool, type SkillToolPair } from './skillTools.js';
 export { defineSteering, type DefineSteeringOptions } from './factories/defineSteering.js';
 export { defineFact, type DefineFactOptions } from './factories/defineFact.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAM9E,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE9F,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,73 @@
+/**
+ * Skill-tool builders — shared source of truth for `list_skills` and
+ * `read_skill` tools used by the Agent's auto-attach path AND by
+ * `SkillRegistry.toTools()` (explicit composition path).
+ *
+ * Both tools work over the SAME catalog (a list of `Injection` skills).
+ * Pulling them out of `core/Agent.ts` removes the v2.4 duplication
+ * risk: the Agent auto-attaches its own `read_skill`, the registry
+ * builds a sibling — they MUST agree on schema + execute semantics.
+ *
+ * Pattern: pure builder functions over an `Injection[]` catalog.
+ *          Tool execute is identity-style (returns confirmation
+ *          string); the agent's tool-calls subflow inspects the
+ *          tool name + args and updates `scope.activatedInjectionIds`
+ *          so the next iteration's InjectionEngine sees the new
+ *          activation.
+ *
+ * Closes Neo gap #3 (of 8) by making the LLM-facing skill discovery
+ * surface composable — consumers can plug `listSkills` / `readSkill`
+ * into their own ToolProvider chain (e.g., gatedTools → permission
+ * filter → static + skill-tools).
+ */
+import type { Tool } from '../../core/tools.js';
+import type { Injection } from './types.js';
+/**
+ * Build the `list_skills` tool — a no-arg tool that returns the
+ * registered skills as `{ id, description }[]`. Lets the LLM discover
+ * skills without paying the prompt-token cost of embedding the
+ * catalog into every system prompt.
+ *
+ * Pairs with `read_skill` (which actually activates a skill by id).
+ *
+ * Returns `undefined` when there are no skills — callers should
+ * guard or filter undefined out of their tool list.
+ */
+export declare function buildListSkillsTool(skills: readonly Injection[]): Tool | undefined;
+/**
+ * Build the `read_skill` tool — activates a skill for the next
+ * iteration. The LLM picks WHICH skill via the `id` argument.
+ *
+ * Tool execute() returns a confirmation string. The actual bookkeeping
+ * (appending the requested skill id to `scope.activatedInjectionIds`)
+ * is handled by the Agent's tool-calls subflow, which inspects every
+ * `read_skill` tool call by name. The next iteration's InjectionEngine
+ * matches Skills with `trigger.kind: 'llm-activated'` by id and
+ * includes them in the active set; slot subflows then inject the body
+ * + tools.
+ *
+ * The tool's description lists each Skill's `id` + `description` so
+ * the LLM can choose meaningfully without first calling `list_skills`
+ * (a perf trade-off — small registries can afford the inline catalog;
+ * large ones should use `list_skills` for discovery and rely on the
+ * shorter `read_skill` description.) See `surfaceMode` (Block A4) for
+ * tunable trade-offs.
+ *
+ * Returns `undefined` when there are no skills — callers should
+ * guard or filter undefined out of their tool list.
+ */
+export declare function buildReadSkillTool(skills: readonly Injection[]): Tool | undefined;
+/**
+ * The pair returned by `SkillRegistry.toTools()`. Either entry may be
+ * undefined when the registry is empty. Consumers typically destructure:
+ *
+ *   const { listSkills, readSkill } = registry.toTools();
+ *   const tools = [listSkills, readSkill, ...other].filter(Boolean) as Tool[];
+ */
+export interface SkillToolPair {
+    /** The `list_skills` tool, or `undefined` if registry is empty. */
+    readonly listSkills: Tool | undefined;
+    /** The `read_skill` tool, or `undefined` if registry is empty. */
+    readonly readSkill: Tool | undefined;
+}
+//# sourceMappingURL=skillTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skillTools.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,CAqBlF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,CAwDjF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,SAAS,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,SAAS,CAAC;CACtC"}

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

@@ -167,6 +167,24 @@ export interface ActiveInjection {
     readonly id: string;
     readonly flavor: import('../../events/types.js').ContextSource;
     readonly description?: string;
+    /**
+     * Resolved surfaceMode (Skill flavor only). Drives Block C runtime
+     * dispatch — slot subflows skip system-slot injection when this is
+     * `'tool-only'`; the read_skill tool delivers the body in its
+     * result for `'tool-only'` and `'both'`.
+     *
+     * `'auto'` and absent both mean "keep v2.4 behavior" (body in
+     * system slot, tool result is confirmation only). The Block A4
+     * cascade resolves 'auto' against provider/model context at a
+     * later layer; this projection stays declarative.
+     */
+    readonly surfaceMode?: 'auto' | 'system-prompt' | 'tool-only' | 'both';
+    /**
+     * Per-skill tool gating intent (Skill flavor only). Reserved for
+     * Block C+ runtime auto-wiring of `skillScopedTools`. Today
+     * consumers wire this manually via `agentfootprint/tool-providers`.
+     */
+    readonly autoActivate?: 'currentSkill';
     readonly inject: {
         readonly systemPrompt?: string;
         readonly messages?: ReadonlyArray<{

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

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

package/dist/types/lib/lazyRequire.d.ts

@@ -0,0 +1,30 @@
+/**
+ * lazyRequire — module-path-indirect `require()` wrapper for lazy
+ * peer-dep loading.
+ *
+ * Why a wrapper: bundlers (Vite, esbuild, webpack, Rollup) statically
+ * analyze `require('literal-string')` calls and try to resolve the
+ * dependency at BUILD time — even when the function is never called
+ * at runtime. For optional peer-deps (`@modelcontextprotocol/sdk`,
+ * `@anthropic-ai/sdk`, `ioredis`, `@aws-sdk/client-bedrock-*`), this
+ * means consumers who never instantiate the matching adapter still
+ * get a build error if the peer-dep isn't installed.
+ *
+ * Wrapping the call in a function with a string PARAMETER hides the
+ * specifier from static analysis. At runtime this is exactly the
+ * same as inline `require()`, including the throwing behavior when
+ * the peer-dep isn't installed.
+ *
+ * Pattern: indirect require — used by Node's `createRequire`-style
+ *          fallbacks for the same reason.
+ *
+ * @example
+ *   try {
+ *     const mod = lazyRequire<typeof import('ioredis')>('ioredis');
+ *     this._client = new mod.default(...);
+ *   } catch {
+ *     throw new Error('install ioredis to use RedisStore');
+ *   }
+ */
+export declare function lazyRequire<T = unknown>(specifier: string): T;
+//# sourceMappingURL=lazyRequire.d.ts.map

package/dist/types/lib/lazyRequire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazyRequire.d.ts","sourceRoot":"","sources":["../../../src/lib/lazyRequire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC,CAG7D"}

package/dist/types/lib/mcp/mcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAA8B,MAAM,YAAY,CAAC;AAU1F;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAyC1E"}
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAA8B,MAAM,YAAY,CAAC;AAW1F;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAyC1E"}