agentfootprint 2.3.0 → 2.5.0

package/dist/esm/tool-providers/gatedTools.js

@@ -0,0 +1,52 @@
+/**
+ * gatedTools — wrap any ToolProvider with a per-tool gating predicate.
+ *
+ * The DECORATOR for tool providers. Filters the inner provider's
+ * output by running the predicate against each tool name. Composes
+ * freely:
+ *
+ *   gatedTools(
+ *     gatedTools(staticTools(allTools), readOnlyPredicate),
+ *     skillGatePredicate,
+ *   )
+ *
+ * Reads as: "static list of all tools, filtered by readonly policy,
+ * then further filtered by the active skill's tool set." Each gate
+ * is one concern; composition handles the rest.
+ *
+ * Pattern: Decorator (GoF) — wraps any ToolProvider with an additional
+ *          filter. Mirrors `withRetry` / `withFallback` over LLMProvider.
+ *
+ * @example  Read-only enforcement
+ *   const readOnly = gatedTools(
+ *     staticTools([read, write]),
+ *     (toolName) => toolName.startsWith('read_'),
+ *   );
+ *   readOnly.list(ctx); // → [read]
+ *
+ * @example  Skill-gated dispatch (autoActivate use case)
+ *   const skillGated = gatedTools(
+ *     staticTools(allTools),
+ *     (toolName, ctx) => ctx.activeSkillId
+ *       ? skillToolMap[ctx.activeSkillId].includes(toolName)
+ *       : alwaysVisible.includes(toolName),
+ *   );
+ */
+// #region gatedTools
+export function gatedTools(inner, predicate) {
+    return {
+        id: 'gated',
+        list(ctx) {
+            // Pull from the inner provider first; each recomputation sees
+            // the freshest state from any nested gates.
+            const innerTools = inner.list(ctx);
+            // Filter by predicate — tool name from `tool.schema.name`.
+            // Predicates throwing escape: a buggy predicate should crash
+            // loudly, not silently allow tools through. Per the
+            // permission-as-defense-in-depth principle.
+            return innerTools.filter((t) => predicate(t.schema.name, ctx));
+        },
+    };
+}
+// #endregion gatedTools
+//# sourceMappingURL=gatedTools.js.map

package/dist/esm/tool-providers/gatedTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatedTools.js","sourceRoot":"","sources":["../../../src/tool-providers/gatedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,qBAAqB;AACrB,MAAM,UAAU,UAAU,CAAC,KAAmB,EAAE,SAA4B;IAC1E,OAAO;QACL,EAAE,EAAE,OAAO;QACX,IAAI,CAAC,GAAwB;YAC3B,8DAA8D;YAC9D,4CAA4C;YAC5C,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnC,2DAA2D;YAC3D,6DAA6D;YAC7D,oDAAoD;YACpD,4CAA4C;YAC5C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC;AACD,wBAAwB"}

package/dist/esm/tool-providers/index.js

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

package/dist/esm/tool-providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,uEAAuE;AACvE,qEAAqE;AACrE,eAAe;AACf,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/esm/tool-providers/skillScopedTools.js

@@ -0,0 +1,63 @@
+/**
+ * skillScopedTools — ToolProvider that exposes a tool subset only when
+ * a specific Skill is active in the current iteration's context.
+ *
+ * The Block A5 piece. Pairs with `defineSkill({ autoActivate: 'currentSkill' })`
+ * to give the LLM a sharper choice space: when `billing` activates, the
+ * tool list flips from "all 25 agent tools" to "the 7 billing tools" +
+ * any baseline (always-on) tools the consumer composes alongside.
+ *
+ * Pattern: gated ToolProvider keyed by `ctx.activeSkillId`. Pure compute;
+ *          no Agent-runtime dependency. Composes freely with `staticTools`
+ *          for the always-on baseline.
+ *
+ * @example  One skill's tools, scoped by activation
+ *   const billingTools = skillScopedTools('billing', [refundTool, chargeTool]);
+ *   billingTools.list({ iteration: 1, activeSkillId: 'billing', identity: ... });
+ *   // → [refundTool, chargeTool]
+ *   billingTools.list({ iteration: 1, activeSkillId: 'refund', identity: ... });
+ *   // → [] (different skill active)
+ *   billingTools.list({ iteration: 1, identity: ... });
+ *   // → [] (no skill active)
+ *
+ * @example  Compose with baseline + multiple skills
+ *   const baseline   = staticTools([lookupOrderTool, listSkills, readSkill]);
+ *   const billingTbx = skillScopedTools('billing', [refundTool, chargeTool]);
+ *   const refundTbx  = skillScopedTools('refund',  [reverseTool]);
+ *
+ *   // Wrap each scope-provider in a gatedTools for downstream composition,
+ *   // OR build a small wrapper that concatenates list(ctx) outputs:
+ *   const provider: ToolProvider = {
+ *     id: 'composite',
+ *     list: (ctx) => [
+ *       ...baseline.list(ctx),
+ *       ...billingTbx.list(ctx),
+ *       ...refundTbx.list(ctx),
+ *     ],
+ *   };
+ *
+ * Note: the runtime that POPULATES `ctx.activeSkillId` from
+ * `scope.activatedInjectionIds` lands in Block C / v2.5+. Today,
+ * consumers can drive it manually for tests + design-time inspection.
+ */
+// #region skillScopedTools
+export function skillScopedTools(skillId, tools) {
+    if (!skillId || skillId.trim().length === 0) {
+        throw new Error('skillScopedTools: `skillId` is required and must be non-empty.');
+    }
+    // Capture the tool list once. `list()` returns a fresh array each
+    // call (matches the staticTools / gatedTools convention so the
+    // agent's reference-equality check always sees an update).
+    const captured = [...tools];
+    return {
+        id: `skill-scoped:${skillId}`,
+        list(ctx) {
+            // Empty list when the skill is not active.
+            if (ctx.activeSkillId !== skillId)
+                return [];
+            return [...captured];
+        },
+    };
+}
+// #endregion skillScopedTools
+//# sourceMappingURL=skillScopedTools.js.map

package/dist/esm/tool-providers/skillScopedTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillScopedTools.js","sourceRoot":"","sources":["../../../src/tool-providers/skillScopedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,2BAA2B;AAC3B,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,KAAsB;IACtE,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,kEAAkE;IAClE,+DAA+D;IAC/D,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC5B,OAAO;QACL,EAAE,EAAE,gBAAgB,OAAO,EAAE;QAC7B,IAAI,CAAC,GAAwB;YAC3B,2CAA2C;YAC3C,IAAI,GAAG,CAAC,aAAa,KAAK,OAAO;gBAAE,OAAO,EAAE,CAAC;YAC7C,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC;AACD,8BAA8B"}

package/dist/esm/tool-providers/staticTools.js

@@ -0,0 +1,33 @@
+/**
+ * staticTools — the simplest ToolProvider. Wraps a fixed Tool[] list.
+ *
+ * 90% case. What `agent.tools(arr)` does today, made composable.
+ * Equivalent to passing `arr` directly EXCEPT that `staticTools(arr)`
+ * is now a `ToolProvider` you can wrap with `gatedTools(...)` for
+ * permission filtering or per-skill gating.
+ *
+ * Pattern: identity ToolProvider — no filtering, just exposes the
+ *          underlying list verbatim.
+ *
+ * @example
+ *   const provider = staticTools([weatherTool, lookupTool]);
+ *   // Materialize the visible list and register via .tools(...).
+ *   // Direct .toolProvider(...) wiring on the builder lands in Block A5 / v2.5+.
+ *   const visible = provider.list({ iteration: 0, identity: { conversationId: '_' } });
+ *   const agent = Agent.create({ provider: llm, model }).tools(visible).build();
+ */
+// #region staticTools
+export function staticTools(tools) {
+    // Capture the input list once. `list()` returns a fresh array each
+    // call so the agent's reference-equality check always sees an update
+    // (matches the `gatedTools` decorator's per-call recomputation).
+    const captured = [...tools];
+    return {
+        id: 'static',
+        list(_ctx) {
+            return [...captured];
+        },
+    };
+}
+// #endregion staticTools
+//# sourceMappingURL=staticTools.js.map

package/dist/esm/tool-providers/staticTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticTools.js","sourceRoot":"","sources":["../../../src/tool-providers/staticTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,sBAAsB;AACtB,MAAM,UAAU,WAAW,CAAC,KAAsB;IAChD,mEAAmE;IACnE,qEAAqE;IACrE,iEAAiE;IACjE,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC5B,OAAO;QACL,EAAE,EAAE,QAAQ;QACZ,IAAI,CAAC,IAAyB;YAC5B,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC;AACD,yBAAyB"}

package/dist/esm/tool-providers/types.js

@@ -0,0 +1,53 @@
+/**
+ * ToolProvider — abstraction over tool dispatch.
+ *
+ * v2.4 shipped tools as a flat array on the agent (registered via
+ * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
+ * production agents need:
+ *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
+ *   2. Per-skill tool gating (only show the active skill's tools to
+ *      the LLM each turn)
+ *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
+ *      decorator over the base tool list)
+ *
+ * `ToolProvider` is the answer: a chainable abstraction over "what
+ * tools does the LLM see right now?". The agent asks the provider
+ * each iteration; the provider returns the visible tool set computed
+ * from whatever predicates / role gates / skill filters the consumer
+ * composed.
+ *
+ * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
+ *          "compute the visible tool list given current context".
+ *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
+ *          provider with an additional filter, mirroring how `withRetry`
+ *          / `withFallback` decorate `LLMProvider`.
+ * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
+ *          each iteration to compute the visible tool set.
+ * Emits:   N/A (pure compute; permission denials emit elsewhere via the
+ *          permission subsystem).
+ *
+ * @example  Static tool list (90% case — what `.tools(arr)` does today)
+ *   const provider = staticTools([weather, lookupOrder]);
+ *
+ * @example  Read-only enforcement (role-based gate)
+ *   const readOnlyProvider = gatedTools(
+ *     staticTools([weather, lookupOrder, processRefund]),
+ *     (toolName) => policy.isAllowed(toolName),
+ *   );
+ *
+ * @example  Skill-gated dispatch (only active skill's tools visible)
+ *   const skillGated = gatedTools(
+ *     staticTools(allTools),
+ *     (toolName, ctx) => ctx.activeSkillId
+ *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
+ *       : alwaysVisible.includes(toolName),
+ *   );
+ *
+ * @example  Stack: read-only over skill-gated
+ *   const provider = gatedTools(
+ *     gatedTools(staticTools(allTools), readOnlyPredicate),
+ *     skillGatePredicate,
+ *   );
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/tool-providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tool-providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG"}

package/dist/index.js

@@ -21,8 +21,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConditionalBuilder = exports.Conditional = exports.ParallelBuilder = exports.Parallel = exports.SequenceBuilder = exports.Sequence = exports.defineTool = exports.AgentBuilder = exports.Agent = exports.LLMCallBuilder = exports.LLMCall = exports.renderThinkingLine = exports.selectThinkingState = exports.defaultThinkingTemplates = exports.renderCommentary = exports.extractCommentaryVars = exports.selectCommentaryKey = exports.defaultCommentaryTemplates = exports.boundaryRecorder = exports.BoundaryRecorder = exports.attachFlowchart = exports.LoggingDomains = exports.attachLogging = exports.attachThinking = exports.isPaused = exports.isPauseRequest = exports.askHuman = exports.pauseHere = exports.makeRunId = exports.RunnerBase = exports.typedEmit = exports.skillRecorder = exports.memoryRecorder = exports.evalRecorder = exports.permissionRecorder = exports.costRecorder = exports.compositionRecorder = exports.agentRecorder = exports.streamRecorder = exports.EmitBridge = exports.ContextRecorder = exports.parseSubflowPath = exports.buildEventMeta = exports.COMPOSITION_KEYS = exports.isInjectionKey = exports.injectionKeyForSlot = exports.INJECTION_KEYS = exports.EventDispatcher = exports.ALL_EVENT_TYPES = exports.EVENT_NAMES = void 0;
-exports.mockMcpClient = exports.mcpClient = exports.indexDocuments = exports.defineRAG = exports.identityNamespace = exports.mockEmbedder = exports.InMemoryStore = exports.SNAPSHOT_PROJECTIONS = exports.MEMORY_TIMING = exports.MEMORY_STRATEGIES = exports.MEMORY_TYPES = exports.defineMemory = exports.llmFactExtractor = exports.patternFactExtractor = exports.llmExtractor = exports.heuristicExtractor = exports.autoPipeline = exports.semanticPipeline = exports.narrativePipeline = exports.factPipeline = exports.ephemeralPipeline = exports.defaultPipeline = exports.defineFact = exports.defineSteering = exports.defineSkill = exports.defineInstruction = exports.buildInjectionEngineSubflow = exports.evaluateInjections = exports.encodeSSE = exports.SSEFormatter = exports.toSSE = exports.createProvider = exports.BrowserOpenAIProvider = exports.browserOpenai = exports.BrowserAnthropicProvider = exports.browserAnthropic = exports.BedrockProvider = exports.bedrock = exports.ollama = exports.OpenAIProvider = exports.openai = exports.AnthropicProvider = exports.anthropic = exports.mock = exports.MockProvider = exports.LoopBuilder = exports.Loop = void 0;
+exports.applyOutputSchema = exports.OutputSchemaError = exports.AgentBuilder = exports.Agent = exports.LLMCallBuilder = exports.LLMCall = exports.renderThinkingLine = exports.selectThinkingState = exports.defaultThinkingTemplates = exports.renderCommentary = exports.extractCommentaryVars = exports.selectCommentaryKey = exports.defaultCommentaryTemplates = exports.boundaryRecorder = exports.BoundaryRecorder = exports.attachFlowchart = exports.LoggingDomains = exports.attachLogging = exports.attachThinking = exports.isPaused = exports.isPauseRequest = exports.askHuman = exports.pauseHere = exports.makeRunId = exports.RunnerBase = exports.typedEmit = exports.skillRecorder = exports.memoryRecorder = exports.evalRecorder = exports.permissionRecorder = exports.costRecorder = exports.compositionRecorder = exports.agentRecorder = exports.streamRecorder = exports.EmitBridge = exports.BASELINE_SOURCES = exports.ENGINEERED_SOURCES = exports.isBaselineSource = exports.isEngineeredSource = exports.contextEngineering = exports.ContextRecorder = exports.parseSubflowPath = exports.buildEventMeta = exports.COMPOSITION_KEYS = exports.isInjectionKey = exports.injectionKeyForSlot = exports.INJECTION_KEYS = exports.EventDispatcher = exports.ALL_EVENT_TYPES = exports.EVENT_NAMES = void 0;
+exports.identityNamespace = exports.mockEmbedder = exports.InMemoryStore = exports.SNAPSHOT_PROJECTIONS = exports.MEMORY_TIMING = exports.MEMORY_STRATEGIES = exports.MEMORY_TYPES = exports.defineMemory = exports.llmFactExtractor = exports.patternFactExtractor = exports.llmExtractor = exports.heuristicExtractor = exports.autoPipeline = exports.semanticPipeline = exports.narrativePipeline = exports.factPipeline = exports.ephemeralPipeline = exports.defaultPipeline = exports.defineFact = exports.defineSteering = exports.buildReadSkillTool = exports.buildListSkillsTool = exports.SkillRegistry = exports.resolveSurfaceMode = exports.defineSkill = exports.defineInstruction = exports.projectActiveInjection = exports.buildInjectionEngineSubflow = exports.evaluateInjections = exports.encodeSSE = exports.SSEFormatter = exports.toSSE = exports.createProvider = exports.BrowserOpenAIProvider = exports.browserOpenai = exports.BrowserAnthropicProvider = exports.browserAnthropic = exports.mock = exports.MockProvider = exports.LoopBuilder = exports.Loop = exports.ConditionalBuilder = exports.Conditional = exports.ParallelBuilder = exports.Parallel = exports.SequenceBuilder = exports.Sequence = exports.defineTool = exports.flowchartAsTool = exports.buildDefaultInstruction = void 0;
+exports.validateMessages = exports.composeMessages = exports.defaultThinkingMessages = exports.defaultCommentaryMessages = exports.PermissionPolicy = exports.skillScopedTools = exports.gatedTools = exports.staticTools = exports.mockMcpClient = exports.mcpClient = exports.indexDocuments = exports.defineRAG = void 0;
 // Events — registry, types, payloads
 __exportStar(require("./events/types.js"), exports);
 __exportStar(require("./events/payloads.js"), exports);
@@ -54,6 +55,12 @@ Object.defineProperty(exports, "parseSubflowPath", { enumerable: true, get: func
 // Core recorders
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
+var contextEngineering_js_1 = require("./recorders/core/contextEngineering.js");
+Object.defineProperty(exports, "contextEngineering", { enumerable: true, get: function () { return contextEngineering_js_1.contextEngineering; } });
+Object.defineProperty(exports, "isEngineeredSource", { enumerable: true, get: function () { return contextEngineering_js_1.isEngineeredSource; } });
+Object.defineProperty(exports, "isBaselineSource", { enumerable: true, get: function () { return contextEngineering_js_1.isBaselineSource; } });
+Object.defineProperty(exports, "ENGINEERED_SOURCES", { enumerable: true, get: function () { return contextEngineering_js_1.ENGINEERED_SOURCES; } });
+Object.defineProperty(exports, "BASELINE_SOURCES", { enumerable: true, get: function () { return contextEngineering_js_1.BASELINE_SOURCES; } });
 var EmitBridge_js_1 = require("./recorders/core/EmitBridge.js");
 Object.defineProperty(exports, "EmitBridge", { enumerable: true, get: function () { return EmitBridge_js_1.EmitBridge; } });
 var StreamRecorder_js_1 = require("./recorders/core/StreamRecorder.js");
@@ -123,6 +130,12 @@ Object.defineProperty(exports, "LLMCallBuilder", { enumerable: true, get: functi
 var Agent_js_1 = require("./core/Agent.js");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return Agent_js_1.Agent; } });
 Object.defineProperty(exports, "AgentBuilder", { enumerable: true, get: function () { return Agent_js_1.AgentBuilder; } });
+var outputSchema_js_1 = require("./core/outputSchema.js");
+Object.defineProperty(exports, "OutputSchemaError", { enumerable: true, get: function () { return outputSchema_js_1.OutputSchemaError; } });
+Object.defineProperty(exports, "applyOutputSchema", { enumerable: true, get: function () { return outputSchema_js_1.applyOutputSchema; } });
+Object.defineProperty(exports, "buildDefaultInstruction", { enumerable: true, get: function () { return outputSchema_js_1.buildDefaultInstruction; } });
+var flowchartAsTool_js_1 = require("./core/flowchartAsTool.js");
+Object.defineProperty(exports, "flowchartAsTool", { enumerable: true, get: function () { return flowchartAsTool_js_1.flowchartAsTool; } });
 var tools_js_1 = require("./core/tools.js");
 Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return tools_js_1.defineTool; } });
 // Slot subflow builders are intentionally NOT exported. They are
@@ -149,19 +162,24 @@ Object.defineProperty(exports, "LoopBuilder", { enumerable: true, get: function
 // Adapters — LLM providers
 // `mock(...)` is the lowercase factory equivalent to `new MockProvider(...)`.
 // `anthropic(...)` is the real Claude provider via `@anthropic-ai/sdk`.
+// Zero-peer-dep providers — safe to re-export from the main barrel
+// because bundlers walking these never touch optional peer-dep code.
+//
+// Vendor-SDK-backed providers (AnthropicProvider, OpenAIProvider,
+// BedrockProvider) live ONLY at `agentfootprint/llm-providers` (or
+// the legacy `agentfootprint/providers` alias). That subpath
+// segregation means bundlers walking from `agentfootprint` main
+// never see the lazy peer-dep requires for `@anthropic-ai/sdk`,
+// `openai`, `@aws-sdk/client-bedrock-runtime`, etc. — automatic
+// tree-shaking, no bundler-side workarounds.
+//
+// Migration (v2.4 → v2.5):
+//   import { AnthropicProvider } from 'agentfootprint';                  // ❌ removed
+//   import { AnthropicProvider } from 'agentfootprint/llm-providers';    // ✓ canonical
+//   import { AnthropicProvider } from 'agentfootprint/providers';        // ✓ legacy alias
 var MockProvider_js_1 = require("./adapters/llm/MockProvider.js");
 Object.defineProperty(exports, "MockProvider", { enumerable: true, get: function () { return MockProvider_js_1.MockProvider; } });
 Object.defineProperty(exports, "mock", { enumerable: true, get: function () { return MockProvider_js_1.mock; } });
-var AnthropicProvider_js_1 = require("./adapters/llm/AnthropicProvider.js");
-Object.defineProperty(exports, "anthropic", { enumerable: true, get: function () { return AnthropicProvider_js_1.anthropic; } });
-Object.defineProperty(exports, "AnthropicProvider", { enumerable: true, get: function () { return AnthropicProvider_js_1.AnthropicProvider; } });
-var OpenAIProvider_js_1 = require("./adapters/llm/OpenAIProvider.js");
-Object.defineProperty(exports, "openai", { enumerable: true, get: function () { return OpenAIProvider_js_1.openai; } });
-Object.defineProperty(exports, "OpenAIProvider", { enumerable: true, get: function () { return OpenAIProvider_js_1.OpenAIProvider; } });
-Object.defineProperty(exports, "ollama", { enumerable: true, get: function () { return OpenAIProvider_js_1.ollama; } });
-var BedrockProvider_js_1 = require("./adapters/llm/BedrockProvider.js");
-Object.defineProperty(exports, "bedrock", { enumerable: true, get: function () { return BedrockProvider_js_1.bedrock; } });
-Object.defineProperty(exports, "BedrockProvider", { enumerable: true, get: function () { return BedrockProvider_js_1.BedrockProvider; } });
 var BrowserAnthropicProvider_js_1 = require("./adapters/llm/BrowserAnthropicProvider.js");
 Object.defineProperty(exports, "browserAnthropic", { enumerable: true, get: function () { return BrowserAnthropicProvider_js_1.browserAnthropic; } });
 Object.defineProperty(exports, "BrowserAnthropicProvider", { enumerable: true, get: function () { return BrowserAnthropicProvider_js_1.BrowserAnthropicProvider; } });
@@ -181,9 +199,14 @@ var index_js_1 = require("./lib/injection-engine/index.js");
 // Engine
 Object.defineProperty(exports, "evaluateInjections", { enumerable: true, get: function () { return index_js_1.evaluateInjections; } });
 Object.defineProperty(exports, "buildInjectionEngineSubflow", { enumerable: true, get: function () { return index_js_1.buildInjectionEngineSubflow; } });
+Object.defineProperty(exports, "projectActiveInjection", { enumerable: true, get: function () { return index_js_1.projectActiveInjection; } });
 // Sugar factories — one per injection flavor
 Object.defineProperty(exports, "defineInstruction", { enumerable: true, get: function () { return index_js_1.defineInstruction; } });
 Object.defineProperty(exports, "defineSkill", { enumerable: true, get: function () { return index_js_1.defineSkill; } });
+Object.defineProperty(exports, "resolveSurfaceMode", { enumerable: true, get: function () { return index_js_1.resolveSurfaceMode; } });
+Object.defineProperty(exports, "SkillRegistry", { enumerable: true, get: function () { return index_js_1.SkillRegistry; } });
+Object.defineProperty(exports, "buildListSkillsTool", { enumerable: true, get: function () { return index_js_1.buildListSkillsTool; } });
+Object.defineProperty(exports, "buildReadSkillTool", { enumerable: true, get: function () { return index_js_1.buildReadSkillTool; } });
 Object.defineProperty(exports, "defineSteering", { enumerable: true, get: function () { return index_js_1.defineSteering; } });
 Object.defineProperty(exports, "defineFact", { enumerable: true, get: function () { return index_js_1.defineFact; } });
 // Patterns — factory functions composing primitives + core-flow into
@@ -236,4 +259,26 @@ Object.defineProperty(exports, "indexDocuments", { enumerable: true, get: functi
 var index_js_7 = require("./lib/mcp/index.js");
 Object.defineProperty(exports, "mcpClient", { enumerable: true, get: function () { return index_js_7.mcpClient; } });
 Object.defineProperty(exports, "mockMcpClient", { enumerable: true, get: function () { return index_js_7.mockMcpClient; } });
+// Tool dispatch primitives (v2.5+). New `agentfootprint/tool-providers`
+// subpath bundles tool sources (mcpClient / mockMcpClient) with tool
+// dispatch primitives (staticTools / gatedTools) so consumers find
+// "everything tool-related" in one place. Top-level barrel re-exports
+// the dispatch primitives too — `mcpClient` already re-exports above.
+var index_js_8 = require("./tool-providers/index.js");
+Object.defineProperty(exports, "staticTools", { enumerable: true, get: function () { return index_js_8.staticTools; } });
+Object.defineProperty(exports, "gatedTools", { enumerable: true, get: function () { return index_js_8.gatedTools; } });
+Object.defineProperty(exports, "skillScopedTools", { enumerable: true, get: function () { return index_js_8.skillScopedTools; } });
+// Cross-cutting authorization (v2.5+). `agentfootprint/security` is the
+// dedicated subpath; the root barrel also re-exports `PermissionPolicy`
+// so existing v2.4 consumers find it at the top level.
+var index_js_9 = require("./security/index.js");
+Object.defineProperty(exports, "PermissionPolicy", { enumerable: true, get: function () { return index_js_9.PermissionPolicy; } });
+// Message Catalog Pattern (v2.5+). `agentfootprint/locales` is the
+// dedicated subpath; the root barrel also re-exports the helpers so
+// existing v2.4 consumers find them at the top level.
+var index_js_10 = require("./locales/index.js");
+Object.defineProperty(exports, "defaultCommentaryMessages", { enumerable: true, get: function () { return index_js_10.defaultCommentaryMessages; } });
+Object.defineProperty(exports, "defaultThinkingMessages", { enumerable: true, get: function () { return index_js_10.defaultThinkingMessages; } });
+Object.defineProperty(exports, "composeMessages", { enumerable: true, get: function () { return index_js_10.composeMessages; } });
+Object.defineProperty(exports, "validateMessages", { enumerable: true, get: function () { return index_js_10.validateMessages; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;;;AAsCH,qCAAqC;AACrC,oDAAkC;AAClC,uDAAqC;AACrC,oDAM8B;AAL5B,0GAAA,WAAW,OAAA;AACX,8GAAA,eAAe,OAAA;AAMjB,aAAa;AACb,wDASgC;AAR9B,gHAAA,eAAe,OAAA;AAUjB,6BAA6B;AAC7B,sDAAoC;AAEpC,yEAAyE;AACzE,uDAAuD;AACvD,mDAK0B;AAJxB,gHAAA,cAAc,OAAA;AACd,qHAAA,mBAAmB,OAAA;AACnB,gHAAA,cAAc,OAAA;AAGhB,oEAAoE;AACpE,yEAAyE;AACzE,wEAAwE;AACxE,qEAAqE;AACrE,kDAAkD;AAClD,sDAOmC;AANjC,4GAAA,gBAAgB,OAAA;AAQlB,gBAAgB;AAChB,sDAA0F;AAAjF,8GAAA,cAAc,OAAA;AAAE,gHAAA,gBAAgB,OAAA;AAEzC,iBAAiB;AACjB,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,gFAUgD;AAT9C,2HAAA,kBAAkB,OAAA;AAClB,2HAAA,kBAAkB,OAAA;AAClB,yHAAA,gBAAgB,OAAA;AAChB,2HAAA,kBAAkB,OAAA;AAClB,yHAAA,gBAAgB,OAAA;AAMlB,gEAAoF;AAA3E,2GAAA,UAAU,OAAA;AACnB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,8DAA0D;AAAjD,yGAAA,SAAS,OAAA;AAIlB,sDAA6D;AAApD,2GAAA,UAAU,OAAA;AAAE,0GAAA,SAAS,OAAA;AAE9B,sEAAsE;AACtE,wEAAwE;AACxE,iEAAiE;AACjE,sEAAsE;AACtE,uEAAuE;AACvE,4CAMyB;AALvB,qGAAA,SAAS,OAAA;AACT,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,oGAAA,QAAQ,OAAA;AAIV,4CAA4C;AAC5C,qFAIuD;AAHrD,qHAAA,cAAc,OAAA;AAIhB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,uFAQwD;AAPtD,uHAAA,eAAe,OAAA;AAQjB,qFAgBuD;AAfrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAgBlB,qEAAqE;AACrE,kEAAkE;AAClE,kEAAkE;AAClE,sGAOqE;AANnE,oIAAA,0BAA0B,OAAA;AAC1B,6HAAA,mBAAmB,OAAA;AACnB,+HAAA,qBAAqB,OAAA;AACrB,0HAAA,gBAAgB,OAAA;AAKlB,kEAAkE;AAClE,mEAAmE;AACnE,8DAA8D;AAC9D,iEAAiE;AACjE,mEAAmE;AACnE,qEAAqE;AACrE,gGAQiE;AAP/D,gIAAA,wBAAwB,OAAA;AACxB,2HAAA,mBAAmB,OAAA;AACnB,0HAAA,kBAAkB,OAAA;AAOpB,qBAAqB;AACrB,gDAM2B;AALzB,qGAAA,OAAO,OAAA;AACP,4GAAA,cAAc,OAAA;AAKhB,4CAMyB;AALvB,iGAAA,KAAK,OAAA;AACL,wGAAA,YAAY,OAAA;AAKd,0DAMgC;AAL9B,oHAAA,iBAAiB,OAAA;AACjB,oHAAA,iBAAiB,OAAA;AACjB,0HAAA,uBAAuB,OAAA;AAIzB,gEAKmC;AAJjC,qHAAA,eAAe,OAAA;AAWjB,4CAA6C;AAApC,sGAAA,UAAU,OAAA;AAEnB,iEAAiE;AACjE,yDAAyD;AACzD,kEAAkE;AAClE,6DAA6D;AAC7D,wEAAwE;AACxE,kEAAkE;AAClE,2DAA2D;AAC3D,sEAAsE;AAEtE,4BAA4B;AAC5B,uDAMiC;AAL/B,uGAAA,QAAQ,OAAA;AACR,8GAAA,eAAe,OAAA;AAKjB,uDAUiC;AAT/B,uGAAA,QAAQ,OAAA;AACR,8GAAA,eAAe,OAAA;AASjB,6DAOoC;AANlC,6GAAA,WAAW,OAAA;AACX,oHAAA,kBAAkB,OAAA;AAMpB,+CAO6B;AAN3B,+FAAA,IAAI,OAAA;AACJ,sGAAA,WAAW,OAAA;AAOb,2BAA2B;AAC3B,8EAA8E;AAC9E,wEAAwE;AACxE,mEAAmE;AACnE,qEAAqE;AACrE,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,6DAA6D;AAC7D,gEAAgE;AAChE,gEAAgE;AAChE,gEAAgE;AAChE,6CAA6C;AAC7C,EAAE;AACF,2BAA2B;AAC3B,sFAAsF;AACtF,wFAAwF;AACxF,2FAA2F;AAC3F,kEAKwC;AAJtC,+GAAA,YAAY,OAAA;AACZ,uGAAA,IAAI,OAAA;AAIN,0FAIoD;AAHlD,+HAAA,gBAAgB,OAAA;AAChB,uIAAA,wBAAwB,OAAA;AAG1B,oFAIiD;AAH/C,yHAAA,aAAa,OAAA;AACb,iIAAA,qBAAqB,OAAA;AAGvB,sEAI0C;AAHxC,mHAAA,cAAc,OAAA;AAKhB,+DAA+D;AAC/D,yCAAgF;AAAvE,kGAAA,KAAK,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,sGAAA,SAAS,OAAA;AAEvC,oEAAoE;AACpE,gEAAgE;AAChE,4DA+ByC;AAxBvC,SAAS;AACT,8GAAA,kBAAkB,OAAA;AAClB,uHAAA,2BAA2B,OAAA;AAC3B,kHAAA,sBAAsB,OAAA;AAGtB,6CAA6C;AAC7C,6GAAA,iBAAiB,OAAA;AAEjB,uGAAA,WAAW,OAAA;AACX,8GAAA,kBAAkB,OAAA;AAClB,yGAAA,aAAa,OAAA;AAEb,+GAAA,mBAAmB,OAAA;AACnB,8GAAA,kBAAkB,OAAA;AAMlB,0GAAA,cAAc,OAAA;AAEd,sGAAA,UAAU,OAAA;AAIZ,qEAAqE;AACrE,0DAA0D;AAC1D,sDAAoC;AAEpC,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,sEAAsE;AACtE,8CAA8C;AAC9C,uDAQoC;AAPlC,YAAY;AACZ,2GAAA,eAAe,OAAA;AACf,6GAAA,iBAAiB,OAAA;AACjB,wGAAA,YAAY,OAAA;AACZ,6GAAA,iBAAiB,OAAA;AACjB,4GAAA,gBAAgB,OAAA;AAChB,wGAAA,YAAY,OAAA;AAEd,oDAIiC;AAH/B,kBAAkB;AAClB,8GAAA,kBAAkB,OAAA;AAClB,wGAAA,YAAY,OAAA;AAEd,oDAIiC;AAH/B,kBAAkB;AAClB,gHAAA,oBAAoB,OAAA;AACpB,4GAAA,gBAAgB,OAAA;AAElB,8CAsB2B;AArBzB,+DAA+D;AAC/D,wGAAA,YAAY,OAAA;AACZ,wGAAA,YAAY,OAAA;AACZ,6GAAA,iBAAiB,OAAA;AACjB,yGAAA,aAAa,OAAA;AACb,gHAAA,oBAAoB,OAAA;AAQpB,iEAAiE;AACjE,iEAAiE;AACjE,4BAA4B;AAC5B,yGAAA,aAAa,OAAA;AACb,wGAAA,YAAY,OAAA;AACZ,6GAAA,iBAAiB,OAAA;AAKnB,wEAAwE;AACxE,sEAAsE;AACtE,sEAAsE;AACtE,+CAM4B;AAL1B,qGAAA,SAAS,OAAA;AAET,0GAAA,cAAc,OAAA;AAKhB,kEAAkE;AAClE,sEAAsE;AACtE,sEAAsE;AACtE,6BAA6B;AAC7B,+CAW4B;AAV1B,qGAAA,SAAS,OAAA;AACT,yGAAA,aAAa,OAAA;AAWf,wEAAwE;AACxE,qEAAqE;AACrE,mEAAmE;AACnE,sEAAsE;AACtE,sEAAsE;AACtE,sDAOmC;AANjC,uGAAA,WAAW,OAAA;AACX,sGAAA,UAAU,OAAA;AACV,4GAAA,gBAAgB,OAAA;AAMlB,wEAAwE;AACxE,wEAAwE;AACxE,uDAAuD;AACvD,gDAI6B;AAH3B,4GAAA,gBAAgB,OAAA;AAKlB,mEAAmE;AACnE,oEAAoE;AACpE,sDAAsD;AACtD,gDAM4B;AAL1B,sHAAA,yBAAyB,OAAA;AACzB,oHAAA,uBAAuB,OAAA;AACvB,4GAAA,eAAe,OAAA;AACf,6GAAA,gBAAgB,OAAA"}

package/dist/lib/injection-engine/SkillRegistry.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * 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);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillRegistry = void 0;
+const skillTools_js_1 = require("./skillTools.js");
+const defineSkill_js_1 = require("./factories/defineSkill.js");
+class SkillRegistry {
+    skills = new Map();
+    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 = {}) {
+        this.opts = Object.freeze({ ...opts });
+    }
+    /** Registry-level default `surfaceMode`, or `undefined` if unset. */
+    get surfaceMode() {
+        return this.opts.surfaceMode;
+    }
+    /** Registry-level provider hint, or `undefined` if unset. */
+    get providerHint() {
+        return this.opts.providerHint;
+    }
+    /**
+     * 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) {
+        if (skill.flavor !== 'skill') {
+            throw new Error(`SkillRegistry.register: expected a Skill (flavor: 'skill'), got flavor: '${skill.flavor}' (id: '${skill.id}'). Use defineSkill(...) to construct.`);
+        }
+        if (this.skills.has(skill.id)) {
+            throw new Error(`SkillRegistry.register: skill '${skill.id}' is already registered. Use .replace('${skill.id}', skill) to overwrite.`);
+        }
+        this.skills.set(skill.id, skill);
+        return this;
+    }
+    /** Replace an existing skill by id. Throws if id is not registered. */
+    replace(id, skill) {
+        if (!this.skills.has(id)) {
+            throw new Error(`SkillRegistry.replace: no skill registered at '${id}'. Use .register(...) for new skills.`);
+        }
+        if (skill.flavor !== 'skill') {
+            throw new Error(`SkillRegistry.replace: expected a Skill (flavor: 'skill'), got '${skill.flavor}'.`);
+        }
+        if (skill.id !== id) {
+            throw new Error(`SkillRegistry.replace: skill.id ('${skill.id}') does not match the slot id ('${id}'). Either use .register(...) for the new id or pass a skill with the matching id.`);
+        }
+        this.skills.set(id, skill);
+        return this;
+    }
+    /** Remove a skill by id. No-op if not registered. */
+    unregister(id) {
+        this.skills.delete(id);
+        return this;
+    }
+    /** Look up by id. Returns undefined if not registered. */
+    get(id) {
+        return this.skills.get(id);
+    }
+    /** True iff a skill with the given id is registered. */
+    has(id) {
+        return this.skills.has(id);
+    }
+    /** All registered skills. Order matches registration order. */
+    list() {
+        return [...this.skills.values()];
+    }
+    /** Number of registered skills. */
+    get size() {
+        return this.skills.size;
+    }
+    /** Drop all registrations. */
+    clear() {
+        this.skills.clear();
+    }
+    /**
+     * 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() {
+        const skills = this.list();
+        return {
+            listSkills: (0, skillTools_js_1.buildListSkillsTool)(skills),
+            readSkill: (0, skillTools_js_1.buildReadSkillTool)(skills),
+        };
+    }
+    /**
+     * 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, provider, model) {
+        const skill = typeof skillOrId === 'string' ? this.get(skillOrId) : skillOrId;
+        if (!skill) {
+            const id = typeof skillOrId === 'string' ? skillOrId : skillOrId.id;
+            throw new Error(`SkillRegistry.resolveForSkill: no skill registered at id '${id}'.`);
+        }
+        if (skill.flavor !== 'skill') {
+            throw new Error(`SkillRegistry.resolveForSkill: '${skill.id}' has flavor '${skill.flavor}', expected 'skill'.`);
+        }
+        const meta = skill.metadata;
+        const skillMode = meta?.surfaceMode;
+        if (skillMode && skillMode !== 'auto')
+            return skillMode;
+        if (this.opts.surfaceMode && this.opts.surfaceMode !== 'auto') {
+            return this.opts.surfaceMode;
+        }
+        const effectiveProvider = provider ?? this.opts.providerHint ?? 'unknown';
+        return (0, defineSkill_js_1.resolveSurfaceMode)(effectiveProvider, model);
+    }
+}
+exports.SkillRegistry = SkillRegistry;
+//# sourceMappingURL=SkillRegistry.js.map

package/dist/lib/injection-engine/SkillRegistry.js.map

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