agentfootprint 2.4.0 → 2.5.0

package/dist/esm/locales/index.js

@@ -0,0 +1,144 @@
+/**
+ * agentfootprint/locales — Message Catalog Pattern.
+ *
+ * The Block D piece. agentfootprint emits user-facing prose at two
+ * audience levels:
+ *
+ *   - **Commentary** — third-person prose for the bottom panel of any
+ *     viewer (Lens, CLI tail, log files). "The agent dispatched the
+ *     refund tool, which returned successfully."
+ *   - **Thinking** — first-person status for chat-bubble UIs.
+ *     "Looking up your order…"
+ *
+ * v2.4 shipped these as `defaultCommentaryTemplates` and
+ * `defaultThinkingTemplates` (flat `Record<string, string>` maps with
+ * `{{var}}` substitution). The names worked but the framing was
+ * generic — "templates" collides with TypeScript / templating-engine
+ * terminology, and there was no first-class place to ship locale
+ * packs.
+ *
+ * **Block D formalizes this as the Message Catalog Pattern:**
+ *
+ *   - `defaultCommentaryMessages` / `defaultThinkingMessages` —
+ *     canonical English bundles. Aliases of the v2.4 names; symbol
+ *     identity preserved (`defaultCommentaryMessages ===
+ *     defaultCommentaryTemplates`).
+ *   - `composeMessages(defaults, overrides)` — spread overrides on
+ *     top of defaults; missing keys fall back to the default bundle.
+ *   - `validateMessages(catalog, requiredKeys)` — assert every
+ *     required key is present (and non-empty). Catches drift between
+ *     a consumer's locale pack and the framework's required key set.
+ *
+ * The natural consumer pattern is to ship locale packs alongside the
+ * agent code:
+ *
+ *   import { defaultCommentaryMessages, composeMessages } from 'agentfootprint/locales';
+ *   import { esCommentaryMessages } from './locales/es.js';
+ *
+ *   const merged = composeMessages(defaultCommentaryMessages, esCommentaryMessages);
+ *
+ *   const agent = Agent.create({...})
+ *     .commentaryTemplates(merged)
+ *     .build();
+ *
+ * Pattern: i18n locale resolution (Resource Bundle, Fowler 2002) +
+ *          plain object merge for overrides. No catalog inheritance
+ *          chain — overrides win OR fall back to defaults.
+ *
+ * @example  Locale pack drop-in
+ *   const esThinking = composeMessages(defaultThinkingMessages, {
+ *     'stream.llm_start.iter1':   '{{appName}} está pensando...',
+ *     'stream.tool_start':        'Llamando a {{toolName}}...',
+ *   });
+ *   const agent = Agent.create({...}).thinkingTemplates(esThinking).build();
+ *
+ * @example  Validate a locale pack against the framework's required keys
+ *   import { defaultCommentaryMessages, validateMessages } from 'agentfootprint/locales';
+ *
+ *   const myCatalog = composeMessages(defaultCommentaryMessages, customOverrides);
+ *   validateMessages(myCatalog, Object.keys(defaultCommentaryMessages));
+ *   // throws on first missing OR empty key — fail-fast at boot
+ */
+import { defaultCommentaryTemplates } from '../recorders/observability/commentary/commentaryTemplates.js';
+import { defaultThinkingTemplates } from '../recorders/observability/thinking/thinkingTemplates.js';
+/**
+ * Canonical English commentary bundle. Alias of v2.4's
+ * `defaultCommentaryTemplates` — same symbol, friendlier framing.
+ *
+ * Keys mirror agentfootprint event types; values may contain
+ * `{{var}}` placeholders for runtime substitution.
+ */
+export const defaultCommentaryMessages = defaultCommentaryTemplates;
+/**
+ * Canonical English thinking bundle. Alias of v2.4's
+ * `defaultThinkingTemplates`.
+ *
+ * Keys mirror agentfootprint event types; values may contain
+ * `{{var}}` placeholders for runtime substitution.
+ */
+export const defaultThinkingMessages = defaultThinkingTemplates;
+/**
+ * Spread `overrides` on top of `defaults` so every key in `defaults`
+ * has a value (the override or the original). The result is a fresh
+ * object — neither input is mutated.
+ *
+ * Missing override keys fall back to the default; extra override
+ * keys are preserved (forward-compat for consumer-defined keys).
+ *
+ * @example
+ *   const merged = composeMessages(defaultCommentaryMessages, {
+ *     'stream.llm_start.iter1': 'My custom thinking line',
+ *   });
+ */
+export function composeMessages(defaults, overrides = {}) {
+    return Object.freeze({ ...defaults, ...overrides });
+}
+/**
+ * Assert that every key in `requiredKeys` is present in `catalog`.
+ * Throws an Error listing every missing key — batched so consumers
+ * fix all at once instead of error-by-error.
+ *
+ * Useful at boot to catch drift between a consumer's locale pack and
+ * the framework's required key set.
+ *
+ * Empty-string values are VALID by default — the framework's default
+ * catalogs use `''` to signal "render nothing for this event."
+ * Pass `{ forbidEmpty: true }` to also reject empty values.
+ *
+ * @param catalog       The (composed) message catalog to validate.
+ * @param requiredKeys  The keys consumers must define. Typically
+ *                      `Object.keys(defaultCommentaryMessages)` or
+ *                      `Object.keys(defaultThinkingMessages)`.
+ * @param opts          Optional `{ label, forbidEmpty }` (or a bare
+ *                      string label for back-compat with simple use).
+ *
+ * @throws Error when any required key is missing (or empty under
+ *               `forbidEmpty`).
+ */
+export function validateMessages(catalog, requiredKeys, opts = {}) {
+    const resolved = typeof opts === 'string' ? { label: opts } : opts;
+    const label = resolved.label ?? 'message catalog';
+    const forbidEmpty = resolved.forbidEmpty ?? false;
+    const missing = [];
+    const empty = [];
+    for (const key of requiredKeys) {
+        const value = catalog[key];
+        if (value === undefined) {
+            missing.push(key);
+        }
+        else if (forbidEmpty && value.length === 0) {
+            empty.push(key);
+        }
+    }
+    if (missing.length === 0 && empty.length === 0)
+        return;
+    const parts = [];
+    if (missing.length > 0) {
+        parts.push(`missing keys: ${missing.join(', ')}`);
+    }
+    if (empty.length > 0) {
+        parts.push(`empty values: ${empty.join(', ')}`);
+    }
+    throw new Error(`validateMessages(${label}): ${parts.join('; ')}.`);
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/locales/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/locales/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,8DAA8D,CAAC;AAC1G,OAAO,EAAE,wBAAwB,EAAE,MAAM,0DAA0D,CAAC;AAIpG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAW,EACX,YAA8C,EAAE;IAEhD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AACtD,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyC,EACzC,YAA+B,EAC/B,OAAyC,EAAE;IAE3C,MAAM,QAAQ,GAA4B,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5F,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,iBAAiB,CAAC;IAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,IAAI,KAAK,CAAC;IAElD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC"}

package/dist/esm/memory-providers.js

@@ -0,0 +1,44 @@
+/**
+ * agentfootprint/memory-providers — memory store adapters (canonical subpath).
+ *
+ * The Block B canonical name. Mirrors the parallel structure shipped in
+ * v2.5:
+ *
+ *   agentfootprint/llm-providers     ← LLM provider adapters
+ *   agentfootprint/tool-providers    ← tool dispatch + tool sources
+ *   agentfootprint/memory-providers  ← memory store adapters (this file)
+ *   agentfootprint/security          ← cross-cutting authorization
+ *
+ * One subpath that grows — RedisStore, AgentCoreStore, and future
+ * stores (DynamoDB, Postgres, Pinecone, …) all live here. No more
+ * adding `agentfootprint/memory-<vendor>` per-adapter subpath each
+ * time a new store ships.
+ *
+ * Per-adapter aliases (`agentfootprint/memory-redis`,
+ * `agentfootprint/memory-agentcore`) stay available through the v2.x
+ * line — they point at the same files. New code SHOULD import from
+ * `agentfootprint/memory-providers`:
+ *
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ *
+ * Pattern: Adapter (GoF) — each store translates the `MemoryStore`
+ *          interface onto a specific backend (Redis, DynamoDB-style
+ *          AWS Bedrock AgentCore Memory, etc.).
+ * Role:    Outer ring (Hexagonal). All store adapters lazy-require
+ *          their vendor SDKs at construction time, so importing this
+ *          barrel costs ZERO peer-dep load — only the stores you
+ *          actually instantiate pull their SDK in.
+ *
+ * @example
+ *   // New canonical import
+ *   import { RedisStore } from 'agentfootprint/memory-providers';
+ *
+ *   // Legacy per-adapter alias (still works through v2.x)
+ *   import { RedisStore } from 'agentfootprint/memory-redis';
+ */
+// Lazy-required peer-dep stores. Both adapters defer their vendor SDK
+// `require()` to constructor time; importing this barrel doesn't load
+// `ioredis` or `@aws-sdk/client-bedrock-agent-runtime`.
+export { RedisStore, } from './adapters/memory/redis.js';
+export { AgentCoreStore, } from './adapters/memory/agentcore.js';
+//# sourceMappingURL=memory-providers.js.map

package/dist/esm/memory-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../../src/memory-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,OAAO,EACL,UAAU,GAIX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,GAGf,MAAM,gCAAgC,CAAC"}

package/dist/esm/providers.js

@@ -1,6 +1,17 @@
 /**
  * agentfootprint/providers — LLM provider adapters.
  *
+ * **DEPRECATION NOTICE (v2.5):** This subpath is now the legacy alias.
+ * The canonical name in v2.5+ is `agentfootprint/llm-providers`,
+ * matching the parallel structure (`tool-providers` /
+ * `memory-providers` / `security`). Existing imports keep working
+ * unchanged through the v2.x line; the alias is removed in v3.0.
+ *
+ *   // Old (still works through v2.x):
+ *   import { mock } from 'agentfootprint/providers';
+ *   // New canonical:
+ *   import { mock } from 'agentfootprint/llm-providers';
+ *
  * Pattern: Adapter (GoF) — concrete `LLMProvider` implementations that
  *          translate the agentfootprint port to a specific vendor SDK.
  * Role:    Outer ring (Hexagonal). Swappable at runtime; the Agent

package/dist/esm/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,GAGL,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,GAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,GAEP,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAEzB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,GAEtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,GAGL,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,GAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,GAEP,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAEzB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,GAEtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC"}

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

@@ -0,0 +1,155 @@
+/**
+ * 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
+ */
+/**
+ * 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 const 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`).
+ */
+export const 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.
+ */
+export function isEngineeredSource(source) {
+    return ENGINEERED_SOURCES.has(source);
+}
+/**
+ * Pure classifier: given a `ContextSource`, is it baseline?
+ */
+export function isBaselineSource(source) {
+    return BASELINE_SOURCES.has(source);
+}
+/**
+ * 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 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 };
+}
+//# sourceMappingURL=contextEngineering.js.map

package/dist/esm/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;AACH,MAAM,CAAC,MAAM,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;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA+B,IAAI,GAAG,CAAgB;IACjF,MAAM;IACN,aAAa;IACb,WAAW;IACX,MAAM;IACN,UAAU;CACX,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,OAAO,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,OAAO,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAkDD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,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"}

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

@@ -70,7 +70,12 @@ export const 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/esm/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":"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"}

package/dist/esm/security/PermissionPolicy.js

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+/**
+ * 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 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] ?? [])];
+    }
+}
+//# sourceMappingURL=PermissionPolicy.js.map

package/dist/esm/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,MAAM,OAAO,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"}

package/dist/esm/security/index.js

@@ -0,0 +1,38 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/esm/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

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"}