agentfootprint 2.4.0 → 2.5.0

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

@@ -0,0 +1,31 @@
+/**
+ * agentfootprint/llm-providers — LLM provider adapters (canonical subpath).
+ *
+ * The Block B canonical name. Mirrors the parallel structure shipped in
+ * v2.5:
+ *
+ *   agentfootprint/llm-providers     ← LLM provider adapters (this file)
+ *   agentfootprint/tool-providers    ← tool dispatch + tool sources
+ *   agentfootprint/memory-providers  ← memory store adapters
+ *   agentfootprint/security          ← cross-cutting authorization
+ *
+ * The legacy `agentfootprint/providers` subpath stays available as an
+ * alias through the v2.x line — it points at the same exports. New
+ * code SHOULD import from `agentfootprint/llm-providers` for clarity:
+ * grep'ing for "llm-providers" finds every LLM-side import in one
+ * shot, parallel to "tool-providers" and "memory-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
+ *          knows nothing about vendor specifics.
+ *
+ * @example
+ *   // New canonical import
+ *   import { mock, AnthropicProvider } from 'agentfootprint/llm-providers';
+ *
+ *   // Legacy alias (still works through v2.x)
+ *   import { mock, AnthropicProvider } from 'agentfootprint/providers';
+ */
+export * from './providers.js';
+//# sourceMappingURL=llm-providers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm-providers.d.ts","sourceRoot":"","sources":["../../src/llm-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,gBAAgB,CAAC"}

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

@@ -0,0 +1,133 @@
+/**
+ * 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
+ */
+export type { CommentaryTemplates as MessageCatalog } from '../recorders/observability/commentary/commentaryTemplates.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 declare const defaultCommentaryMessages: Readonly<Record<string, string>>;
+/**
+ * Canonical English thinking bundle. Alias of v2.4's
+ * `defaultThinkingTemplates`.
+ *
+ * Keys mirror agentfootprint event types; values may contain
+ * `{{var}}` placeholders for runtime substitution.
+ */
+export declare const defaultThinkingMessages: Readonly<Record<string, string>>;
+/**
+ * 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 declare function composeMessages<T extends Readonly<Record<string, string>>>(defaults: T, overrides?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * Validation options for `validateMessages`.
+ */
+export interface ValidateMessagesOptions {
+    /**
+     * Optional label for the error message (e.g., `'es-MX commentary'`).
+     * Defaults to `'message catalog'`.
+     */
+    readonly label?: string;
+    /**
+     * When `true`, empty-string values FAIL validation (treated like a
+     * missing key). When `false` (default), empty strings are valid —
+     * the framework's default catalogs intentionally use empty values
+     * for events the consumer should skip rendering for.
+     */
+    readonly forbidEmpty?: boolean;
+}
+/**
+ * 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 declare function validateMessages(catalog: Readonly<Record<string, string>>, requiredKeys: readonly string[], opts?: ValidateMessagesOptions | string): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/locales/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAKH,YAAY,EAAE,mBAAmB,IAAI,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAE1H;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,kCAA6B,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,kCAA2B,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxE,QAAQ,EAAE,CAAC,EACX,SAAS,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC/C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAElC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACzC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,IAAI,GAAE,uBAAuB,GAAG,MAAW,GAC1C,IAAI,CAwBN"}

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

@@ -0,0 +1,41 @@
+/**
+ * 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';
+ */
+export { RedisStore, type RedisStoreOptions, type RedisLikeClient, type RedisLikePipeline, } from './adapters/memory/redis.js';
+export { AgentCoreStore, type AgentCoreStoreOptions, type AgentCoreLikeClient, } from './adapters/memory/agentcore.js';
+//# sourceMappingURL=memory-providers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-providers.d.ts","sourceRoot":"","sources":["../../src/memory-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,gCAAgC,CAAC"}

package/dist/types/providers.d.ts

@@ -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/types/providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,UAAU,EACV,aAAa,GACd,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,UAAU,EACV,aAAa,GACd,MAAM,qBAAqB,CAAC"}

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