agentfootprint 2.3.0 → 2.5.0

package/dist/types/recorders/core/contextEngineering.d.ts

@@ -0,0 +1,137 @@
+/**
+ * contextEngineering(agent) — first-class handle on the engineered
+ * subset of `context.injected` events.
+ *
+ * The Block A8 piece. agentfootprint already emits `context.injected`
+ * for EVERY piece of content that lands in a slot — including the
+ * baseline flow (the user message, every tool result, the static
+ * system prompt). For a developer who wants to inspect what their
+ * RAG / Skills / Memory / Instructions / Steering / Facts ARE
+ * INJECTING (the actual context-engineering work), the baseline flow
+ * is noise.
+ *
+ * `contextEngineering(agent)` filters the stream to ONLY the
+ * engineered injections and gives consumers two cleaner subscriptions:
+ *
+ *   - `onEngineered(cb)` — fires for `source` ∈ {rag, skill, memory,
+ *     instructions, steering, fact, custom}. The actual
+ *     context-engineering work.
+ *   - `onBaseline(cb)` — fires for `source` ∈ {user, tool-result,
+ *     assistant, base, registry}. The baseline message-history flow.
+ *
+ * Use cases:
+ *   - **Lens UI**: render only engineered injections in the "context
+ *     bin"; show the baseline flow as edges between iterations.
+ *   - **Eval pipelines**: count how many RAG chunks vs Memory entries
+ *     vs Skill bodies entered the prompt for an eval-set query.
+ *   - **Cost attribution**: sum tokens by `source` to know what
+ *     fraction of spend is RAG vs Skills vs baseline.
+ *   - **Debug logging**: tail just the engineered signals to spot
+ *     surprising activations during dev.
+ *
+ * Pattern: Strategy + Filter (GoF) — pure classifier function over
+ *          the existing `context.injected` event payload, paired with
+ *          a thin subscription helper.
+ *
+ * Role:    Layer-2 (event taxonomy) consumer-side helper. Doesn't
+ *          emit new events; doesn't change the agent's flowchart.
+ *          Pure observation.
+ *
+ * @example
+ *   import { contextEngineering } from 'agentfootprint';
+ *
+ *   const ce = contextEngineering(agent);
+ *   ce.onEngineered((e) => {
+ *     console.log(`[${e.payload.source}] ${e.payload.contentSummary}`);
+ *   });
+ *   ce.onBaseline((e) => {
+ *     console.log(`[baseline:${e.payload.source}]`);
+ *   });
+ *
+ *   await agent.run({ message: 'help me' });
+ *   // ... runs; engineered + baseline streams fire separately
+ *
+ *   ce.detach();   // stops both subscriptions; the agent itself is fine
+ */
+import type { AgentfootprintEventMap } from '../../events/registry.js';
+import type { ContextSource } from '../../events/types.js';
+/**
+ * Public set of "engineered" sources — the context-engineering
+ * primitives that consumers configure (RAG, Skills, Memory,
+ * Instructions, Steering, Facts) plus user-defined `custom`.
+ *
+ * Frozen so consumers can `.has(value)` directly without copy.
+ */
+export declare const ENGINEERED_SOURCES: ReadonlySet<ContextSource>;
+/**
+ * Public set of "baseline" sources — the message-history flow that
+ * exists regardless of context engineering: user input, tool results,
+ * assistant outputs, the always-on system prompt anchor (`base`), and
+ * the agent's static tool registry advertisement (`registry`).
+ */
+export declare const BASELINE_SOURCES: ReadonlySet<ContextSource>;
+/**
+ * Pure classifier: given a `ContextSource`, is it engineered?
+ *
+ * Useful for ad-hoc filtering on a raw `agent.on('agentfootprint.context.injected', ...)`
+ * subscription when you don't need the wrapper helper.
+ */
+export declare function isEngineeredSource(source: ContextSource): boolean;
+/**
+ * Pure classifier: given a `ContextSource`, is it baseline?
+ */
+export declare function isBaselineSource(source: ContextSource): boolean;
+/**
+ * The shape of the event passed to `onEngineered` / `onBaseline`
+ * callbacks. Same as `agentfootprint.context.injected`'s envelope —
+ * we don't transform it, just route by source.
+ */
+export type ContextInjectedEvent = AgentfootprintEventMap['agentfootprint.context.injected'];
+/** Listener signature for the wrapper helper. */
+export type ContextInjectedListener = (event: ContextInjectedEvent) => void;
+/** Unsubscribe handle. */
+export type ContextEngineeringUnsubscribe = () => void;
+/**
+ * Minimal subset of the agent surface this helper depends on.
+ * Lets us accept any runner (Agent, LLMCall, Sequence, etc.) that
+ * implements the typed `on(type, cb)` subscription API.
+ */
+interface RunnerWithEvents {
+    on(type: 'agentfootprint.context.injected', listener: ContextInjectedListener): ContextEngineeringUnsubscribe;
+}
+/**
+ * Handle returned by `contextEngineering(agent)`. Lets consumers
+ * subscribe to engineered / baseline streams and detach cleanly.
+ */
+export interface ContextEngineeringHandle {
+    /**
+     * Fires for `context.injected` events whose source is in
+     * `ENGINEERED_SOURCES`. Returns an unsubscribe function.
+     */
+    onEngineered(listener: ContextInjectedListener): ContextEngineeringUnsubscribe;
+    /**
+     * Fires for `context.injected` events whose source is in
+     * `BASELINE_SOURCES`. Returns an unsubscribe function.
+     */
+    onBaseline(listener: ContextInjectedListener): ContextEngineeringUnsubscribe;
+    /**
+     * Detach all subscriptions registered through this handle. After
+     * calling, no further callbacks will fire. Idempotent (safe to
+     * call multiple times).
+     */
+    detach(): void;
+}
+/**
+ * Wrap a runner's `agentfootprint.context.injected` stream into two
+ * filtered subscriptions: engineered + baseline. Multiple listeners
+ * per stream are allowed; `detach()` removes all of them.
+ *
+ * The classifier inspects `event.payload.source`. Unknown sources
+ * (forward-compat: `ContextSource` is open-extensible) are routed
+ * to NEITHER stream — preferring under-firing over miscategorizing.
+ * Use `agent.on('agentfootprint.context.injected', ...)` directly
+ * if you need to observe sources that aren't (yet) classified.
+ */
+export declare function contextEngineering(agent: RunnerWithEvents): ContextEngineeringHandle;
+export {};
+//# sourceMappingURL=contextEngineering.d.ts.map

package/dist/types/recorders/core/contextEngineering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextEngineering.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/contextEngineering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,aAAa,CAQxD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,aAAa,CAMtD,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAEjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE/D;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,CAAC,iCAAiC,CAAC,CAAC;AAE7F,iDAAiD;AACjD,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE5E,0BAA0B;AAC1B,MAAM,MAAM,6BAA6B,GAAG,MAAM,IAAI,CAAC;AAEvD;;;;GAIG;AACH,UAAU,gBAAgB;IACxB,EAAE,CACA,IAAI,EAAE,iCAAiC,EACvC,QAAQ,EAAE,uBAAuB,GAChC,6BAA6B,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,uBAAuB,GAAG,6BAA6B,CAAC;IAC/E;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,uBAAuB,GAAG,6BAA6B,CAAC;IAC7E;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,wBAAwB,CA0CpF"}

package/dist/types/recorders/observability/commentary/commentaryTemplates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBAmDxC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA8EzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}
+{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBAyDxC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA8EzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}

package/dist/types/security/PermissionPolicy.d.ts

@@ -0,0 +1,125 @@
+/**
+ * PermissionPolicy — data-driven role-based authorization for tool dispatch.
+ *
+ * Closes Neo gap #2 (of 8). Permissions are CROSS-CUTTING — they're not
+ * context engineering, they're a guard ON context-engineering operations
+ * (tool dispatch, skill activation, memory writes, output emission).
+ * That's why this lives in `agentfootprint/security`, parallel to the
+ * provider subpaths.
+ *
+ * Two surfaces, one primitive:
+ *   1. `PermissionPolicy.fromRoles({...}, activeRole)` — declarative,
+ *      data-driven, auditable. Production governance.
+ *   2. The PermissionPolicy instance satisfies BOTH:
+ *      - `PermissionChecker` interface (async check; consumed by Agent
+ *        constructor's `permissionChecker` field)
+ *      - sync `isAllowed(toolId)` method (consumed by `gatedTools(...)`
+ *        from `agentfootprint/tool-providers`)
+ *
+ * Pattern: Strategy (GoF) for the role-allowlist policy + Adapter
+ *          (matches `PermissionChecker` interface so it composes with
+ *          existing v2.4 Agent constructor).
+ *
+ * Role: Layer-3 cross-cutting guard. Not Injection. Not provider.
+ *       Lives in its own subpath (`agentfootprint/security`).
+ *
+ * @example  Read-only role for a support agent
+ *   const policy = PermissionPolicy.fromRoles(
+ *     {
+ *       readonly: ['lookup_order', 'get_status', 'list_skills', 'read_skill'],
+ *       support: ['lookup_order', 'get_status', 'process_refund', 'list_skills', 'read_skill'],
+ *     },
+ *     'readonly',
+ *   );
+ *
+ *   policy.isAllowed('lookup_order');     // → true
+ *   policy.isAllowed('process_refund');   // → false (not in readonly role)
+ *
+ *   // As a tool-dispatch gate (composes with gatedTools)
+ *   const provider = gatedTools(staticTools(allTools), (name) => policy.isAllowed(name));
+ *
+ *   // As an Agent permissionChecker (the v2.4 surface)
+ *   const agent = Agent.create({ provider, model, permissionChecker: policy }).build();
+ *
+ * @example  Per-identity role switching at runtime
+ *   const policy = PermissionPolicy.fromRoles({
+ *     readonly: [...],
+ *     admin: [...],
+ *   }, 'readonly');
+ *
+ *   const adminPolicy = policy.withActiveRole('admin');
+ *   // Same allowlist data; different active role.
+ */
+import type { PermissionChecker, PermissionRequest, PermissionDecision } from '../adapters/types.js';
+/**
+ * Map of role name → list of tool ids that role is allowed to invoke.
+ * The shape consumers extend over time as new tools / roles arrive.
+ */
+export type RoleAllowlist = Readonly<Record<string, readonly string[]>>;
+export interface PermissionPolicyOptions {
+    /**
+     * The role allowlist. Each role maps to the tool ids it can invoke.
+     * Tool ids match the `name` field of `Tool.schema.name` exactly.
+     */
+    readonly roles: RoleAllowlist;
+    /**
+     * Which role is active for this policy instance. Calls to
+     * `.isAllowed(toolId)` check against this role's allowlist.
+     * Use `.withActiveRole(name)` to derive a sibling policy with a
+     * different active role.
+     */
+    readonly activeRole: string;
+}
+/**
+ * Data-driven role-based permission policy. Satisfies the v2.4
+ * `PermissionChecker` interface AND exposes a sync `isAllowed` method
+ * for use with `gatedTools` from `agentfootprint/tool-providers`.
+ */
+export declare class PermissionPolicy implements PermissionChecker {
+    private readonly opts;
+    readonly name = "PermissionPolicy";
+    private constructor();
+    /**
+     * Factory: build a role-based policy from a role → tool-ids map and
+     * the role active for this instance.
+     *
+     * Throws if `activeRole` isn't a key in `roles` — fail loud at
+     * config time, not at first denied call.
+     */
+    static fromRoles(roles: RoleAllowlist, activeRole: string): PermissionPolicy;
+    /**
+     * Sync allowlist check. Use as a predicate with `gatedTools`:
+     *
+     *   gatedTools(staticTools(allTools), (toolId) => policy.isAllowed(toolId))
+     *
+     * Returns true iff `toolId` is in the active role's allowlist.
+     * Closes-fail by design: missing role membership = denied.
+     */
+    isAllowed(toolId: string): boolean;
+    /**
+     * Async check matching the `PermissionChecker` interface — consumed
+     * by `Agent.create({ permissionChecker })`. Wraps `isAllowed` with
+     * the structured `PermissionDecision` envelope (allow / deny + a
+     * `policyRuleId` so observability can trace which role decided).
+     *
+     * Today the policy only checks the tool name (request.target).
+     * Future work: also gate by capability ('memory_write', etc.) when
+     * the role allowlist is widened to capability-by-id.
+     */
+    check(request: PermissionRequest): Promise<PermissionDecision>;
+    /**
+     * Derive a sibling policy with a different active role. Same role
+     * map; different active role. Useful for per-identity routing
+     * (one policy instance per request, varying active role per caller).
+     *
+     * Returns a NEW PermissionPolicy — original is unchanged.
+     */
+    withActiveRole(activeRole: string): PermissionPolicy;
+    /** The role name currently active. Useful for observability. */
+    get activeRole(): string;
+    /** All defined role names. Stable order = registration order. */
+    get roles(): readonly string[];
+    /** All tool ids allowed under the current active role. */
+    allowedToolIds(): readonly string[];
+}
+//# sourceMappingURL=PermissionPolicy.d.ts.map

package/dist/types/security/PermissionPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionPolicy.d.ts","sourceRoot":"","sources":["../../../src/security/PermissionPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IAGpC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFzC,QAAQ,CAAC,IAAI,sBAAsB;IAEnC,OAAO;IAUP;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB;IAI5E;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;;;;;OASG;IACG,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAepE;;;;;;OAMG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;IAIpD,gEAAgE;IAChE,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,iEAAiE;IACjE,IAAI,KAAK,IAAI,SAAS,MAAM,EAAE,CAE7B;IAED,0DAA0D;IAC1D,cAAc,IAAI,SAAS,MAAM,EAAE;CAGpC"}

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

@@ -0,0 +1,40 @@
+/**
+ * agentfootprint/security — cross-cutting authorization + governance.
+ *
+ * Permissions are NOT context engineering — they're a guard ON
+ * context-engineering operations (tool dispatch, skill activation,
+ * memory writes, output emission). That's why this lives in its own
+ * subpath, parallel to `agentfootprint/tool-providers` and the
+ * `agentfootprint/memory-*` and `agentfootprint/providers` subpaths.
+ *
+ * Today's surface is small and data-driven on purpose: one role
+ * allowlist primitive that satisfies BOTH the v2.4 `PermissionChecker`
+ * interface AND a sync `isAllowed(toolId)` predicate for use with
+ * `gatedTools` from `agentfootprint/tool-providers`.
+ *
+ * Future additions (capability gating, gate_open flows, audit logs)
+ * land here without expanding the public root barrel.
+ *
+ * @example
+ *   import { PermissionPolicy } from 'agentfootprint/security';
+ *   import { gatedTools, staticTools } from 'agentfootprint/tool-providers';
+ *
+ *   const policy = PermissionPolicy.fromRoles(
+ *     {
+ *       readonly: ['lookup', 'list_skills', 'read_skill'],
+ *       admin:    ['lookup', 'list_skills', 'read_skill', 'write', 'delete'],
+ *     },
+ *     'readonly',
+ *   );
+ *
+ *   const provider = gatedTools(
+ *     staticTools(allTools),
+ *     (name) => policy.isAllowed(name),
+ *   );
+ *
+ *   const agent = Agent.create({ provider, model, permissionChecker: policy }).build();
+ */
+export { PermissionPolicy } from './PermissionPolicy.js';
+export type { RoleAllowlist, PermissionPolicyOptions } from './PermissionPolicy.js';
+export type { PermissionChecker, PermissionRequest, PermissionDecision, } from '../adapters/types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAMpF,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC"}

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

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

package/dist/types/tool-providers/gatedTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatedTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/gatedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAuB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGvF,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,GAAG,YAAY,CAc1F"}

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

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

package/dist/types/tool-providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","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;AACzD,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKvF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,GACZ,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import type { Tool } from '../core/tools.js';
+import type { ToolProvider } from './types.js';
+export declare function skillScopedTools(skillId: string, tools: readonly Tool[]): ToolProvider;
+//# sourceMappingURL=skillScopedTools.d.ts.map

package/dist/types/tool-providers/skillScopedTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillScopedTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/skillScopedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAGpE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAgBtF"}

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

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

package/dist/types/tool-providers/staticTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/staticTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAGpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAWhE"}

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

@@ -0,0 +1,103 @@
+/**
+ * ToolProvider — abstraction over tool dispatch.
+ *
+ * v2.4 shipped tools as a flat array on the agent (registered via
+ * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
+ * production agents need:
+ *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
+ *   2. Per-skill tool gating (only show the active skill's tools to
+ *      the LLM each turn)
+ *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
+ *      decorator over the base tool list)
+ *
+ * `ToolProvider` is the answer: a chainable abstraction over "what
+ * tools does the LLM see right now?". The agent asks the provider
+ * each iteration; the provider returns the visible tool set computed
+ * from whatever predicates / role gates / skill filters the consumer
+ * composed.
+ *
+ * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
+ *          "compute the visible tool list given current context".
+ *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
+ *          provider with an additional filter, mirroring how `withRetry`
+ *          / `withFallback` decorate `LLMProvider`.
+ * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
+ *          each iteration to compute the visible tool set.
+ * Emits:   N/A (pure compute; permission denials emit elsewhere via the
+ *          permission subsystem).
+ *
+ * @example  Static tool list (90% case — what `.tools(arr)` does today)
+ *   const provider = staticTools([weather, lookupOrder]);
+ *
+ * @example  Read-only enforcement (role-based gate)
+ *   const readOnlyProvider = gatedTools(
+ *     staticTools([weather, lookupOrder, processRefund]),
+ *     (toolName) => policy.isAllowed(toolName),
+ *   );
+ *
+ * @example  Skill-gated dispatch (only active skill's tools visible)
+ *   const skillGated = gatedTools(
+ *     staticTools(allTools),
+ *     (toolName, ctx) => ctx.activeSkillId
+ *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
+ *       : alwaysVisible.includes(toolName),
+ *   );
+ *
+ * @example  Stack: read-only over skill-gated
+ *   const provider = gatedTools(
+ *     gatedTools(staticTools(allTools), readOnlyPredicate),
+ *     skillGatePredicate,
+ *   );
+ */
+import type { Tool } from '../core/tools.js';
+/**
+ * Read-only context the provider receives each iteration. Pure data
+ * — providers MUST NOT mutate. Used by gating predicates to inspect
+ * the current activation state.
+ */
+export interface ToolDispatchContext {
+    /** Current ReAct iteration (1-based). */
+    readonly iteration: number;
+    /**
+     * The id of the currently-activated Skill, if any.
+     * Set by `read_skill(id)` activation; cleared between turns.
+     * Used by `autoActivate`-driven per-skill tool gating.
+     */
+    readonly activeSkillId?: string;
+    /**
+     * Caller identity tuple — passed through from `agent.run({ identity })`.
+     * Permission predicates can role-check based on `identity.principal`
+     * or `identity.tenant`.
+     */
+    readonly identity?: {
+        readonly tenant?: string;
+        readonly principal?: string;
+        readonly conversationId: string;
+    };
+}
+/**
+ * The provider interface. A `ToolProvider` answers ONE question per
+ * iteration: "what tools should the LLM see right now?"
+ *
+ * Implementations are PURE — given the same context, return the same
+ * tool list. No async (the answer is needed synchronously each
+ * iteration; if you need async filtering, precompute upstream).
+ */
+export interface ToolProvider {
+    /**
+     * Return the tool list visible to the LLM for the current iteration.
+     * The returned array MUST be a NEW reference each call (the agent
+     * compares for change detection). Order is preserved — the LLM may
+     * use position as a hint when tool descriptions are ambiguous.
+     */
+    list(ctx: ToolDispatchContext): readonly Tool[];
+    /**
+     * Optional: stable id for observability / debugging. Defaults to
+     * `'static'` for `staticTools`, `'gated'` for `gatedTools`. Custom
+     * implementations should set their own id.
+     */
+    readonly id?: string;
+}
+/** Predicate for `gatedTools` — runs per tool, per iteration. */
+export type ToolGatePredicate = (toolName: string, ctx: ToolDispatchContext) => boolean;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,IAAI,EAAE,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC"}