agentfootprint 2.4.0 → 2.5.0

package/dist/recorders/core/contextEngineering.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextEngineering = exports.isBaselineSource = exports.isEngineeredSource = exports.BASELINE_SOURCES = exports.ENGINEERED_SOURCES = void 0;
+/**
+ * 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.
+ */
+exports.ENGINEERED_SOURCES = new Set([
+    'rag',
+    'skill',
+    'memory',
+    'instructions',
+    'steering',
+    'fact',
+    'custom',
+]);
+/**
+ * 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`).
+ */
+exports.BASELINE_SOURCES = new Set([
+    'user',
+    'tool-result',
+    'assistant',
+    'base',
+    'registry',
+]);
+/**
+ * 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.
+ */
+function isEngineeredSource(source) {
+    return exports.ENGINEERED_SOURCES.has(source);
+}
+exports.isEngineeredSource = isEngineeredSource;
+/**
+ * Pure classifier: given a `ContextSource`, is it baseline?
+ */
+function isBaselineSource(source) {
+    return exports.BASELINE_SOURCES.has(source);
+}
+exports.isBaselineSource = isBaselineSource;
+/**
+ * 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.
+ */
+function contextEngineering(agent) {
+    const unsubscribers = [];
+    function onEngineered(listener) {
+        const wrapped = (e) => {
+            if (isEngineeredSource(e.payload.source))
+                listener(e);
+        };
+        const unsub = agent.on('agentfootprint.context.injected', wrapped);
+        unsubscribers.push(unsub);
+        return () => {
+            unsub();
+            const idx = unsubscribers.indexOf(unsub);
+            if (idx >= 0)
+                unsubscribers.splice(idx, 1);
+        };
+    }
+    function onBaseline(listener) {
+        const wrapped = (e) => {
+            if (isBaselineSource(e.payload.source))
+                listener(e);
+        };
+        const unsub = agent.on('agentfootprint.context.injected', wrapped);
+        unsubscribers.push(unsub);
+        return () => {
+            unsub();
+            const idx = unsubscribers.indexOf(unsub);
+            if (idx >= 0)
+                unsubscribers.splice(idx, 1);
+        };
+    }
+    function detach() {
+        for (const unsub of unsubscribers) {
+            try {
+                unsub();
+            }
+            catch {
+                // Defensive: a misbehaving subscription's throw should not
+                // prevent detaching the rest.
+            }
+        }
+        unsubscribers.length = 0;
+    }
+    return { onEngineered, onBaseline, detach };
+}
+exports.contextEngineering = contextEngineering;
+//# sourceMappingURL=contextEngineering.js.map

package/dist/recorders/core/contextEngineering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextEngineering.js","sourceRoot":"","sources":["../../../src/recorders/core/contextEngineering.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;;;AAKH;;;;;;GAMG;AACU,QAAA,kBAAkB,GAA+B,IAAI,GAAG,CAAgB;IACnF,KAAK;IACL,OAAO;IACP,QAAQ;IACR,cAAc;IACd,UAAU;IACV,MAAM;IACN,QAAQ;CACT,CAAC,CAAC;AAEH;;;;;GAKG;AACU,QAAA,gBAAgB,GAA+B,IAAI,GAAG,CAAgB;IACjF,MAAM;IACN,aAAa;IACb,WAAW;IACX,MAAM;IACN,UAAU;CACX,CAAC,CAAC;AAEH;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,MAAqB;IACtD,OAAO,0BAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAFD,gDAEC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,MAAqB;IACpD,OAAO,wBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAFD,4CAEC;AAkDD;;;;;;;;;;GAUG;AACH,SAAgB,kBAAkB,CAAC,KAAuB;IACxD,MAAM,aAAa,GAAoC,EAAE,CAAC;IAE1D,SAAS,YAAY,CAAC,QAAiC;QACrD,MAAM,OAAO,GAA4B,CAAC,CAAC,EAAE,EAAE;YAC7C,IAAI,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,iCAAiC,EAAE,OAAO,CAAC,CAAC;QACnE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,GAAG,EAAE;YACV,KAAK,EAAE,CAAC;YACR,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACzC,IAAI,GAAG,IAAI,CAAC;gBAAE,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC;IACJ,CAAC;IAED,SAAS,UAAU,CAAC,QAAiC;QACnD,MAAM,OAAO,GAA4B,CAAC,CAAC,EAAE,EAAE;YAC7C,IAAI,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,iCAAiC,EAAE,OAAO,CAAC,CAAC;QACnE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,GAAG,EAAE;YACV,KAAK,EAAE,CAAC;YACR,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACzC,IAAI,GAAG,IAAI,CAAC;gBAAE,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC;IACJ,CAAC;IAED,SAAS,MAAM;QACb,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,KAAK,EAAE,CAAC;YACV,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;gBAC3D,8BAA8B;YAChC,CAAC;QACH,CAAC;QACD,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AA1CD,gDA0CC"}

package/dist/recorders/observability/commentary/commentaryTemplates.js

@@ -73,7 +73,12 @@ exports.defaultCommentaryTemplates = {
     'context.injected.rag': '{{appName}} retrieved relevant content and added it to the conversation.',
     'context.injected.skill': '{{appName}} activated a skill — its body went into the system prompt, and its tools became available to the LLM.',
     'context.injected.memory': '{{appName}} pulled prior content from memory and added it to the conversation.',
-    'context.injected.instructions': '{{appName}} added a tool-specific instruction to the system prompt after that tool returned.',
+    // Generic — fits always-on rules + on-tool-return predicates uniformly.
+    // Specialized variants below disambiguate when the trigger metadata
+    // is available on the event.
+    'context.injected.instructions': '{{appName}} added a rule to the system prompt: {{descClause}}.',
+    'context.injected.instructions.onToolReturn': '{{appName}} added a tool-specific reminder after `{{lastToolName}}` returned: {{descClause}}.',
+    'context.injected.instructions.alwaysOn': '{{appName}} added an always-on rule to the system prompt: {{descClause}}.',
     'context.injected.custom': '{{appName}} injected a custom piece of context.',
     'skill.activated': '{{appName}} turned on a skill — its tools and instructions are now available.',
     'skill.deactivated': '{{appName}} turned off a skill.',

package/dist/recorders/observability/commentary/commentaryTemplates.js.map

@@ -1 +1 @@
-{"version":3,"file":"commentaryTemplates.js","sourceRoot":"","sources":["../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commentaryTemplates.js","sourceRoot":"","sources":["../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;;;AAUH;;;;GAIG;AACU,QAAA,0BAA0B,GAAwB;IAC7D,kBAAkB,EAAE,2CAA2C;IAE/D,wBAAwB,EAAE,2CAA2C;IACrE,wBAAwB,EAAE,8DAA8D;IAExF,sBAAsB,EAAE,qEAAqE;IAC7F,yBAAyB,EAAE,qEAAqE;IAEhG,mEAAmE;IACnE,iEAAiE;IACjE,iEAAiE;IACjE,8DAA8D;IAC9D,gDAAgD;IAChD,mEAAmE;IACnE,iDAAiD;IACjD,6DAA6D;IAC7D,6CAA6C;IAC7C,iEAAiE;IACjE,iEAAiE;IACjE,iBAAiB,EAAE,0BAA0B;IAC7C,sBAAsB,EAAE,wCAAwC;IAEhE,mBAAmB,EACjB,+IAA+I;IACjJ,wBAAwB,EAAE,6BAA6B;IACvD,0BAA0B,EAAE,EAAE;IAE9B,iBAAiB,EAAE,4EAA4E;IAE/F,sBAAsB,EACpB,0EAA0E;IAC5E,wBAAwB,EACtB,kHAAkH;IACpH,yBAAyB,EACvB,gFAAgF;IAClF,wEAAwE;IACxE,oEAAoE;IACpE,6BAA6B;IAC7B,+BAA+B,EAAE,gEAAgE;IACjG,4CAA4C,EAC1C,+FAA+F;IACjG,wCAAwC,EACtC,2EAA2E;IAC7E,yBAAyB,EAAE,iDAAiD;IAE5E,iBAAiB,EACf,+EAA+E;IACjF,mBAAmB,EAAE,iCAAiC;IAEtD,wBAAwB,EAAE,gDAAgD;IAC1E,uBAAuB,EAAE,yDAAyD;IAElF,eAAe,EAAE,yEAAyE;IAC1F,cAAc,EAAE,sBAAsB;IAEtC,gBAAgB,EAAE,2CAA2C;CAC9D,CAAC;AAgBF;;;;;;;GAOG;AACH,SAAgB,mBAAmB,CAAC,KAA0B;IAC5D,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,iCAAiC;YACpC,OAAO,kBAAkB,CAAC;QAC5B,KAAK,+BAA+B;YAClC,OAAO,IAAI,CAAC;QAEd,KAAK,iCAAiC;YACpC,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,wBAAwB,CAAC;QAE7F,KAAK,+BAA+B;YAClC,OAAO,KAAK,CAAC,OAAO,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,yBAAyB,CAAC;QAE9F,KAAK,kCAAkC;YACrC,OAAO,mBAAmB,CAAC;QAC7B,KAAK,gCAAgC;YACnC,OAAO,iBAAiB,CAAC;QAE3B,KAAK,iCAAiC;YACpC,QAAQ,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC7B,KAAK,KAAK;oBACR,OAAO,sBAAsB,CAAC;gBAChC,KAAK,OAAO;oBACV,OAAO,wBAAwB,CAAC;gBAClC,KAAK,QAAQ;oBACX,OAAO,yBAAyB,CAAC;gBACnC,KAAK,cAAc;oBACjB,OAAO,+BAA+B,CAAC;gBACzC,KAAK,QAAQ;oBACX,OAAO,yBAAyB,CAAC;gBACnC,wDAAwD;gBACxD,+BAA+B;gBAC/B,KAAK,MAAM,CAAC;gBACZ,KAAK,aAAa,CAAC;gBACnB,KAAK,WAAW,CAAC;gBACjB,KAAK,MAAM,CAAC;gBACZ,KAAK,UAAU;oBACb,OAAO,IAAI,CAAC;gBACd;oBACE,OAAO,yBAAyB,CAAC;YACrC,CAAC;QAEH,KAAK,gCAAgC;YACnC,OAAO,iBAAiB,CAAC;QAC3B,KAAK,kCAAkC;YACrC,OAAO,mBAAmB,CAAC;QAE7B,KAAK,sCAAsC,CAAC;QAC5C,KAAK,oCAAoC,CAAC;QAC1C,KAAK,oCAAoC;YACvC,OAAO,IAAI,CAAC,CAAC,kDAAkD;QAEjE,KAAK,uCAAuC;YAC1C,OAAO,wBAAwB,CAAC;QAClC,KAAK,sCAAsC;YACzC,OAAO,uBAAuB,CAAC;QAEjC,KAAK,8BAA8B;YACjC,OAAO,eAAe,CAAC;QACzB,KAAK,6BAA6B;YAChC,OAAO,cAAc,CAAC;QAExB,KAAK,+BAA+B;YAClC,OAAO,gBAAgB,CAAC;QAE1B,0DAA0D;QAC1D,mEAAmE;QACnE,kEAAkE;QAClE,gEAAgE;QAChE,YAAY;QACZ,KAAK,sCAAsC,CAAC;QAC5C,KAAK,gCAAgC,CAAC;QACtC,KAAK,wCAAwC;YAC3C,OAAO,IAAI,CAAC;QAEd;YACE,OAAO,SAAS,CAAC,CAAC,eAAe;IACrC,CAAC;AACH,CAAC;AA9ED,kDA8EC;AAED;;;;;;;;GAQG;AACH,SAAgB,qBAAqB,CACnC,KAA0B,EAC1B,GAAsB,EACtB,YAAiC,kCAA0B;IAE3D,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IAEtC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,iCAAiC;YACpC,OAAO,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAE3D,KAAK,kCAAkC,CAAC,CAAC,CAAC;YACxC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YACxC,MAAM,IAAI,GAAG,GAAG,CAAC,kBAAkB,EAAE,CAAC,QAAQ,CAAC,CAAC;YAChD,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;YACnE,+DAA+D;YAC/D,gEAAgE;YAChE,MAAM,UAAU,GAAG,OAAO;gBACxB,CAAC,CAAC,gBAAgB,CAAC,SAAS,CAAC,wBAAwB,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAK,EAAE,CAAC;gBAC9E,CAAC,CAAC,SAAS,CAAC,0BAA0B,CAAC,IAAI,EAAE,CAAC;YAChD,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;QAC3C,CAAC;QAED,kEAAkE;QAClE,0DAA0D;QAC1D;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AA5BD,sDA4BC;AAED;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAAC,QAAgB,EAAE,IAA4B;IAC7E,OAAO,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3E,CAAC;AAFD,4CAEC"}

package/dist/security/PermissionPolicy.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionPolicy = void 0;
+/**
+ * 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`.
+ */
+class PermissionPolicy {
+    opts;
+    name = 'PermissionPolicy';
+    constructor(opts) {
+        this.opts = opts;
+        if (!opts.roles[opts.activeRole]) {
+            throw new Error(`PermissionPolicy: activeRole '${opts.activeRole}' is not defined in roles. Available: ${Object.keys(opts.roles).join(', ') || '(none)'}`);
+        }
+    }
+    /**
+     * 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, activeRole) {
+        return new PermissionPolicy({ roles, activeRole });
+    }
+    /**
+     * 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) {
+        return (this.opts.roles[this.opts.activeRole] ?? []).includes(toolId);
+    }
+    /**
+     * 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.
+     */
+    async check(request) {
+        const toolId = request.target ?? request.capability;
+        if (this.isAllowed(toolId)) {
+            return {
+                result: 'allow',
+                policyRuleId: `${this.opts.activeRole}.allowlist`,
+            };
+        }
+        return {
+            result: 'deny',
+            policyRuleId: `${this.opts.activeRole}.allowlist.miss`,
+            rationale: `Tool '${toolId}' is not in the '${this.opts.activeRole}' role allowlist.`,
+        };
+    }
+    /**
+     * 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) {
+        return new PermissionPolicy({ roles: this.opts.roles, activeRole });
+    }
+    /** The role name currently active. Useful for observability. */
+    get activeRole() {
+        return this.opts.activeRole;
+    }
+    /** All defined role names. Stable order = registration order. */
+    get roles() {
+        return Object.keys(this.opts.roles);
+    }
+    /** All tool ids allowed under the current active role. */
+    allowedToolIds() {
+        return [...(this.opts.roles[this.opts.activeRole] ?? [])];
+    }
+}
+exports.PermissionPolicy = PermissionPolicy;
+//# sourceMappingURL=PermissionPolicy.js.map

package/dist/security/PermissionPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionPolicy.js","sourceRoot":"","sources":["../../src/security/PermissionPolicy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;;;AA6BH;;;;GAIG;AACH,MAAa,gBAAgB;IAGU;IAF5B,IAAI,GAAG,kBAAkB,CAAC;IAEnC,YAAqC,IAA6B;QAA7B,SAAI,GAAJ,IAAI,CAAyB;QAChE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,iCAAiC,IAAI,CAAC,UAAU,yCAC9C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QACxC,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,KAAoB,EAAE,UAAkB;QACvD,OAAO,IAAI,gBAAgB,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,MAAc;QACtB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,OAA0B;QACpC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC;QACpD,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,MAAM,EAAE,OAAO;gBACf,YAAY,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,YAAY;aAClD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,MAAM;YACd,YAAY,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,iBAAiB;YACtD,SAAS,EAAE,SAAS,MAAM,oBAAoB,IAAI,CAAC,IAAI,CAAC,UAAU,mBAAmB;SACtF,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,UAAkB;QAC/B,OAAO,IAAI,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,gEAAgE;IAChE,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;IAC9B,CAAC;IAED,iEAAiE;IACjE,IAAI,KAAK;QACP,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,0DAA0D;IAC1D,cAAc;QACZ,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5D,CAAC;CACF;AAtFD,4CAsFC"}

package/dist/security/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * 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();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionPolicy = void 0;
+var PermissionPolicy_js_1 = require("./PermissionPolicy.js");
+Object.defineProperty(exports, "PermissionPolicy", { enumerable: true, get: function () { return PermissionPolicy_js_1.PermissionPolicy; } });
+//# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;;AAEH,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA"}

package/dist/tool-providers/gatedTools.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * 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),
+ *   );
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatedTools = void 0;
+// #region gatedTools
+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));
+        },
+    };
+}
+exports.gatedTools = gatedTools;
+// #endregion gatedTools
+//# sourceMappingURL=gatedTools.js.map

package/dist/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,SAAgB,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;AAdD,gCAcC;AACD,wBAAwB"}

package/dist/tool-providers/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 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));
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockMcpClient = exports.mcpClient = exports.skillScopedTools = exports.gatedTools = exports.staticTools = void 0;
+var staticTools_js_1 = require("./staticTools.js");
+Object.defineProperty(exports, "staticTools", { enumerable: true, get: function () { return staticTools_js_1.staticTools; } });
+var gatedTools_js_1 = require("./gatedTools.js");
+Object.defineProperty(exports, "gatedTools", { enumerable: true, get: function () { return gatedTools_js_1.gatedTools; } });
+var skillScopedTools_js_1 = require("./skillScopedTools.js");
+Object.defineProperty(exports, "skillScopedTools", { enumerable: true, get: function () { return skillScopedTools_js_1.skillScopedTools; } });
+// 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.
+var index_js_1 = require("../lib/mcp/index.js");
+Object.defineProperty(exports, "mcpClient", { enumerable: true, get: function () { return index_js_1.mcpClient; } });
+Object.defineProperty(exports, "mockMcpClient", { enumerable: true, get: function () { return index_js_1.mockMcpClient; } });
+//# sourceMappingURL=index.js.map

package/dist/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,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AAGzB,uEAAuE;AACvE,qEAAqE;AACrE,eAAe;AACf,gDAA+D;AAAtD,qGAAA,SAAS,OAAA;AAAE,yGAAA,aAAa,OAAA"}

package/dist/tool-providers/skillScopedTools.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillScopedTools = void 0;
+// #region skillScopedTools
+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];
+        },
+    };
+}
+exports.skillScopedTools = skillScopedTools;
+// #endregion skillScopedTools
+//# sourceMappingURL=skillScopedTools.js.map

package/dist/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,SAAgB,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;AAhBD,4CAgBC;AACD,8BAA8B"}

package/dist/tool-providers/staticTools.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * 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();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staticTools = void 0;
+// #region staticTools
+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];
+        },
+    };
+}
+exports.staticTools = staticTools;
+// #endregion staticTools
+//# sourceMappingURL=staticTools.js.map

package/dist/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,SAAgB,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;AAXD,kCAWC;AACD,yBAAyB"}