agentfootprint 9.3.0 → 9.5.0

package/dist/types/memory/strategies.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Named memory strategies — what each one does, which TYPES accept it, and
+ * what the host must supply before it can run.
+ *
+ * `MEMORY_STRATEGIES` is a const of seven bare strings. A string is enough to
+ * WRITE `strategy: { kind: … }` and not nearly enough to OFFER the choice: a
+ * host rendering a strategy picker off that const offers seven options, and
+ * learns which of them this deployment can actually run by calling
+ * `defineMemory` and reading the exception. That is a selector that discovers
+ * its own capabilities by failing.
+ *
+ * So each strategy declares itself, and `listMemoryStrategies()` enumerates
+ * the declarations. The shape mirrors the influence exemplar in this same
+ * package (`listInfluenceStrategies()` → `{ name, description, requirements,
+ * scorer }`), with two deliberate differences:
+ *
+ *   • the id is `kind`, not `name` — it is the value the caller writes into
+ *     `strategy.kind`, so a picker's option value IS the id;
+ *   • there is no `scorer`, because a memory strategy is not a function the
+ *     host calls; what it needs instead is `types` — the memory TYPES that
+ *     accept it, which is the other half of "can I offer this?" (`decay` on a
+ *     SEMANTIC store is refused however good the host's credentials are).
+ *
+ * `requirements` is what a host must SUPPLY (an embedder, an LLM, a store
+ * that can search). Empty means the strategy runs anywhere, at $0.
+ *
+ * Pattern: declared capability descriptors + a guard that enforces them.
+ * Role:    memory/ layer-1, beside the const it describes.
+ * Emits:   N/A — build-time only.
+ *
+ * @see ./define.types.ts  for `MEMORY_STRATEGIES` and the strategy union
+ * @see ../lib/influence-core/strategies.ts  for the exemplar this follows
+ */
+import { type DefineMemoryOptions, type MemoryStrategyKind, type MemoryType } from './define.types.js';
+/**
+ * What a strategy needs the host to supply before it can run. A picker greys
+ * out (or refuses to offer) strategies whose requirements it cannot meet.
+ *
+ * Three well-known values ship; the type stays open so a consumer's own
+ * strategy descriptor can name something else:
+ *
+ *   - `'embedder'`     — an `Embedder` that turns text into a vector.
+ *   - `'vector-store'` — a store that implements `search()`. Not the same
+ *                        requirement as an embedder: the embedder makes the
+ *                        query vector, the store is what ranks against it,
+ *                        and a deployment can easily have one without the
+ *                        other (`RedisStore` is a full memory store with no
+ *                        `search()` at all).
+ *   - `'llm'`          — a chat provider the strategy calls on the host's
+ *                        behalf.
+ */
+export type MemoryStrategyRequirement = 'embedder' | 'vector-store' | 'llm' | (string & Record<never, never>);
+/**
+ * A memory strategy, described: enough for a host to render it in a picker
+ * and know, before it offers the option, whether this deployment can run it.
+ */
+export interface MemoryStrategyInfo {
+    /** The value written as `strategy.kind` — a member of `MEMORY_STRATEGIES`. */
+    readonly kind: MemoryStrategyKind;
+    /** One-or-two-sentence plain description, current-truth caveats included. */
+    readonly description: string;
+    /** What the host must supply. Empty = runs anywhere, no dependency, $0. */
+    readonly requirements: readonly MemoryStrategyRequirement[];
+    /** The memory TYPES that accept this strategy. Any other pair is refused. */
+    readonly types: readonly MemoryType[];
+}
+/**
+ * Every memory strategy, described — cheapest first, in the order the docs
+ * teach them. Frozen: a host renders its picker straight off this.
+ *
+ * @example Offer only what this deployment can actually run
+ * ```ts
+ * import { listMemoryStrategies } from 'agentfootprint/memory';
+ *
+ * const available = new Set(embedder ? ['embedder', 'vector-store'] : []);
+ * const offerable = listMemoryStrategies().filter(
+ *   (s) => s.types.includes('episodic') && s.requirements.every((r) => available.has(r)),
+ * );
+ * // → window, budget, decay, hybrid — the four that cost nothing to run.
+ * ```
+ */
+export declare function listMemoryStrategies(): readonly MemoryStrategyInfo[];
+/**
+ * One strategy's description by `kind`, or `undefined` for a string that is
+ * not a strategy at all.
+ */
+export declare function memoryStrategyInfo(kind: string): MemoryStrategyInfo | undefined;
+/**
+ * Refuse a config whose strategy declares a requirement the caller did not
+ * supply — by name, at BUILD, with the fix in the message.
+ *
+ * WHY it runs LAST, after the pipeline dispatch rather than before it: the
+ * dispatch's own refusals know more than this one does. `defineMemory`'s
+ * TOP_K arm knows about the `ranksBy: 'server-text'` exemption AND about the
+ * write half it takes away; the CAUSAL arm knows that exemption does not
+ * apply to it; the EXTRACT arm knows the `llm` matters only for
+ * `extractor: 'llm'`. Speaking first would replace those messages with a
+ * blunter one. This is the BACKSTOP: it says something only when nothing
+ * better already did, and its job is that no declared requirement can go
+ * unchecked — the failure it exists to prevent is a missing dependency
+ * surfacing as a `TypeError` from five frames inside a stage, halfway
+ * through a paid run.
+ *
+ * @param options the config as written by the caller.
+ * @param site    the call to name in the message, e.g. `defineMemory[chat]`.
+ */
+export declare function assertStrategyRequirements(options: DefineMemoryOptions, site: string): void;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/types/memory/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/memory/strategies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAEhB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,cAAc,GACd,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAsFD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,SAAS,kBAAkB,EAAE,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE/E;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3F"}

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

@@ -0,0 +1,31 @@
+/**
+ * CredentialRecorder — forwards `agentfootprint.credential.*` emits to the
+ * dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges the declare-and-push credential lifecycle — requested,
+ *          acquired, authorization_required, failed — so consumers observe it
+ *          via `agent.on('agentfootprint.credential.failed', …)` and
+ *          `agent.on('agentfootprint.credential.*', …)`.
+ * Emits:   agentfootprint.credential.{requested,acquired,authorization_required,failed}
+ *
+ * ── Why this did not exist until 9.4.0, and what it cost ────────────────────
+ * The credential domain has had payload types, registry entries and real
+ * `typedEmit` call sites since 6.11.0 — and NO BRIDGE. Every one of those
+ * events was raised onto footprintjs's emit channel and stopped there: a raw
+ * `agent.attach()` recorder saw them, and `agent.on(...)` never did. So the
+ * documented way to watch for credential failures observed nothing, and an AWS
+ * identity adapter that failed 100% of its calls for two minor versions did so
+ * in a silence that read exactly like health.
+ *
+ * This is the law CLAUDE.md states for a new event DOMAIN — payload + registry
+ * entry + `DomainWildcard` arm + a bridge attach — with the fourth part
+ * missing. Zero-cost when nothing fires: `EmitBridge` drops an event with no
+ * listener before building any meta.
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type CredentialRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function credentialRecorder(options: CredentialRecorderOptions): EmitBridge;
+//# sourceMappingURL=CredentialRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/CredentialRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IACjF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,UAAU,CAOjF"}

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

@@ -10,8 +10,12 @@
  * 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/providers` — plus
- * `agentCorePolicy()`, the same port answered by a remote policy store.
+ * `gatedTools` from `agentfootprint/providers`.
+ *
+ * There is no shipped REMOTE policy engine. `agentCorePolicy()` was one
+ * through 9.3.0 and is retired in 9.4.0 — see the note beside its export
+ * below. The port stays open: a remote checker is an object with a
+ * `check()` method, and anybody can write one.
  *
  * A local allowlist and a remote policy engine differ in one way that
  * matters here: the local one can answer synchronously, so it doubles
@@ -49,6 +53,6 @@ export type { PolicyHaltContext } from './PolicyHaltError.js';
 export { extractSequence, SYNTHETIC_DENY_PREFIX } from './extractSequence.js';
 export type { ExtractSequenceOptions } from './extractSequence.js';
 export { redactThinkingBlocks, REDACTED_PLACEHOLDER } from './thinkingRedaction.js';
-export { agentCorePolicy, type AgentCorePolicyOptions, type AgentCorePolicyClientLike, type AgentCorePolicyEvaluation, type AgentCorePolicyUnavailable, type BedrockAgentCorePolicySdkModule, } from '../adapters/security/agentcore.js';
+export { agentCorePolicy, AgentCorePolicyRetiredError, type AgentCorePolicyOptions, type AgentCorePolicyClientLike, type AgentCorePolicyEvaluation, type AgentCorePolicyUnavailable, type BedrockAgentCorePolicySdkModule, } from '../adapters/security/agentcore.js';
 export type { PermissionChecker, PermissionRequest, PermissionDecision, ToolCallEntry, ToolResultContent, } from '../adapters/types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAMpF,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,+BAA+B,GACrC,MAAM,mCAAmC,CAAC;AAM3C,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAOpF,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,+BAA+B,GACrC,MAAM,mCAAmC,CAAC;AAM3C,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "9.3.0",
+  "version": "9.5.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",