agentfootprint 6.40.0 → 6.42.0

package/dist/types/adapters/memory/agentcore.d.ts

@@ -1,121 +1,100 @@
 /**
- * AgentCoreStore — AWS Bedrock AgentCore Memory adapter (peer-dep
- * `@aws-sdk/client-bedrock-agent-runtime`).
- *
- * Import from the canonical subpath (the `agentfootprint/memory-agentcore`
- * alias was removed in 4.0.0):
+ * AgentCoreStore — AWS Bedrock **AgentCore Memory** adapter
+ * (peer-dep `@aws-sdk/client-bedrock-agentcore`).
  *
  *   import { AgentCoreStore } from 'agentfootprint/memory-providers';
  *
  *   const store = new AgentCoreStore({
- *     memoryId: 'arn:aws:bedrock:us-east-1:...:memory/my-mem',
- *     region: 'us-east-1',
+ *     memoryId: 'arn:aws:bedrock-agentcore:us-west-2:...:memory/my-mem',
+ *     region: 'us-west-2',
  *   });
  *
- * Pattern: Adapter (GoF) — translates the `MemoryStore` interface onto
- *          AgentCore Memory's session/event model:
- *            MemoryIdentity     ↔  AgentCore session (sessionId derived
- *                                  from the identity tuple)
- *            MemoryEntry        ↔  AgentCore event payload (JSON
- *                                  envelope keyed by entry id)
- *            putIfVersion       ↔  unsupported by AgentCore natively;
- *                                  emulated via list+CAS at adapter level
- *            seen / signatures  ↔  in-process LRU shadow (AgentCore has
- *                                  no built-in dedup primitive)
- *            feedback           ↔  in-process accumulator (AgentCore
- *                                  doesn't expose a feedback metric API)
- *            search             ↔  NOT exposed in v2.3 — AgentCore's
- *                                  retrieve API is opaque (server-side
- *                                  retrieval pipeline). Will land as
- *                                  `agentcoreRetrieve()` in a later release.
+ * Pattern: Adapter (GoF) — maps the `MemoryStore` interface onto AgentCore Memory's
+ *          data-plane **event** model (`CreateEvent` / `GetEvent` / `ListEvents` /
+ *          `DeleteEvent`, `@aws-sdk/client-bedrock-agentcore`):
+ *            MemoryIdentity.{tenant,principal}  ↔  AgentCore `actorId`
+ *            MemoryIdentity.conversationId      ↔  AgentCore `sessionId`
+ *            MemoryEntry                        ↔  one event whose `payload` is a single
+ *                                                  `blob` document holding the entry
+ *
+ * **AgentCore Memory is an append-only event log, not a key-value store.** The server
+ * assigns each event's `eventId` on `CreateEvent` (you cannot choose it), and there is no
+ * "delete the whole session" call. This shapes the adapter:
  *
- * Role:    Outer ring. Lazy-requires the AWS SDK; no runtime cost when
- *          another adapter is in use.
- * Emits:   N/A (storage adapters don't emit; recorders observe the
- *          memory pipeline that calls them).
+ *   • `put`  → `CreateEvent` (append; `actorId` + `eventTimestamp` are required).  O(1)
+ *   • `list` → `ListEvents` (paginated, `includePayloads`).  ← window / episodic memory.  O(page)
+ *   • `get(id)` / `delete(id)` → list-then-find by the entry id stored in the blob, since
+ *     AgentCore's ids are server-assigned.  **O(events in session)** — fine for typical
+ *     window sizes; if you need O(1) keyed access at scale, use RedisStore.
+ *   • `forget` → `ListEvents` + `DeleteEvent` per event (no `DeleteSession` on AgentCore).
+ *   • `search` → still unwired (AgentCore's `RetrieveMemoryRecords` lands as a later helper).
+ *   • `putIfVersion` / `seen` / `feedback` → in-process emulation (AgentCore has no native
+ *     CAS / dedup / feedback primitive; these don't survive process restart).
  *
- * **Caveats** — call out before adopting:
- *   1. AgentCore is session/event-based with built-in summarization.
- *      Mixing `defineMemory({ strategy: SUMMARIZE })` on top will
- *      double-compress. Pick one summarizer.
- *   2. Optimistic-concurrency `putIfVersion` is emulated; under high
- *      concurrent write rates the CAS window is wider than RedisStore.
- *      Single-writer scenarios (one server process per session) are
- *      fine.
- *   3. seen/feedback are in-process — they don't survive process restart.
- *      For durable recognition, implement at a higher layer or use Redis.
- *   4. AWS rate limits apply. Production deployments should wrap with
- *      `withRetry` and budget calls per session.
+ * Role:    Outer ring. Lazy-requires the AWS SDK; zero runtime cost when another adapter is
+ *          in use.  Emits: N/A (storage adapters don't emit).
  */
 import type { ListOptions, ListResult, MemoryStore, PutIfVersionResult } from '../../memory/store/types.js';
 import type { MemoryEntry } from '../../memory/entry/index.js';
 import type { MemoryIdentity } from '../../memory/identity/index.js';
+/** One event as the adapter cares about it: AgentCore's id + the decoded entry. */
+export interface AgentCoreEvent {
+    /** AgentCore server-assigned event id (needed to delete it). */
+    readonly eventId: string;
+    /** The MemoryEntry decoded from the event's blob payload (null if unparseable). */
+    readonly entry: MemoryEntry | null;
+}
 /**
- * Minimal surface over `@aws-sdk/client-bedrock-agent-runtime` that
- * AgentCoreStore touches. Defined locally so we don't take a hard
- * import on the AWS SDK and tests can inject a mock via `_client`.
+ * Minimal, entry-semantic surface the store uses. The real implementation
+ * (`createAgentCoreClient`) maps these onto `CreateEvent` / `ListEvents` /
+ * `DeleteEvent`; tests inject a mock via `_client`.
  */
 export interface AgentCoreLikeClient {
-    putEvent(input: {
-        memoryId: string;
-        sessionId: string;
-        eventId: string;
-        payload: string;
-    }): Promise<unknown>;
-    getEvent(input: {
+    /** Append one entry as an event (server assigns the eventId). */
+    createEvent(input: {
         memoryId: string;
+        actorId: string;
         sessionId: string;
-        eventId: string;
-    }): Promise<{
-        payload?: string;
-    } | null>;
+        entry: MemoryEntry;
+    }): Promise<void>;
+    /** One page of the session's events (newest-first is AgentCore's default). */
     listEvents(input: {
         memoryId: string;
+        actorId: string;
         sessionId: string;
-        nextToken?: string;
         maxResults?: number;
+        nextToken?: string;
     }): Promise<{
-        events: ReadonlyArray<{
-            eventId: string;
-            payload: string;
-        }>;
+        events: readonly AgentCoreEvent[];
         nextToken?: string;
     }>;
+    /** Delete one event by its AgentCore eventId. */
     deleteEvent(input: {
         memoryId: string;
+        actorId: string;
         sessionId: string;
         eventId: string;
-    }): Promise<unknown>;
-    deleteSession(input: {
-        memoryId: string;
-        sessionId: string;
-    }): Promise<unknown>;
+    }): Promise<void>;
 }
 export interface AgentCoreStoreOptions {
     /** AgentCore Memory ARN or id. Required. */
     readonly memoryId: string;
     /** AWS region. Required when constructing the SDK client internally. */
     readonly region?: string;
-    /**
-     * Pre-built AgentCore client. Use this to share a single SDK
-     * configuration (credentials, retry policy) across the host app.
-     * Adapter does NOT call any close lifecycle on a borrowed client.
-     */
+    /** Pre-built AgentCore client (shares one SDK config across the host app). */
     readonly client?: AgentCoreLikeClient;
-    /** Page size for `listEvents` calls. Default 50. */
+    /** Page size for `listEvents`. Default 100. */
     readonly pageSize?: number;
-    /**
-     * @internal Test injection point. Skips SDK require entirely.
-     */
+    /** @internal Test injection — skips the SDK require entirely. */
     readonly _client?: AgentCoreLikeClient;
+    /** @internal Test injection — the AWS SDK module (to exercise the real shim with a mock SDK). */
+    readonly _sdk?: BedrockAgentCoreSdkModule;
 }
 /**
- * AgentCore Memory-backed `MemoryStore`. Implements every method
- * except `search()`. Vector retrieval via AgentCore's native API
- * lands as a separate read-side helper in a later release.
+ * AgentCore Memory-backed `MemoryStore`. Implements every method except `search()`.
  *
- * @throws when `@aws-sdk/client-bedrock-agent-runtime` is not
- *         installed and no `_client` is supplied.
+ * @throws when `@aws-sdk/client-bedrock-agentcore` is not installed and no `_client`/`_sdk`
+ *         is supplied.
  */
 export declare class AgentCoreStore implements MemoryStore {
     private readonly client;
@@ -125,17 +104,19 @@ export declare class AgentCoreStore implements MemoryStore {
     private readonly signatures;
     private readonly feedbackBag;
     constructor(options: AgentCoreStoreOptions);
+    private actorId;
     private sessionId;
+    private scope;
     private shadowKey;
     private feedbackKey;
+    /** Walk every event in the session (paginated). */
+    private eachEvent;
     get<T = unknown>(identity: MemoryIdentity, id: string): Promise<MemoryEntry<T> | null>;
     put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>): Promise<void>;
     putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[]): Promise<void>;
     /**
-     * Emulated optimistic concurrency. AgentCore's PutEvent overwrites
-     * unconditionally. We read-then-write inside a JS critical section
-     * — adequate for single-writer-per-session deployments. For multi-
-     * writer correctness on AgentCore, layer your own coordination.
+     * Emulated optimistic concurrency. AgentCore appends unconditionally; we read-then-write
+     * inside a JS critical section — adequate for single-writer-per-session deployments.
      */
     putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number): Promise<PutIfVersionResult>;
     list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
@@ -147,13 +128,20 @@ export declare class AgentCoreStore implements MemoryStore {
         average: number;
         count: number;
     } | null>;
+    /** GDPR "everything for this identity, gone." No DeleteSession on AgentCore → delete every event. */
     forget(identity: MemoryIdentity): Promise<void>;
-    /**
-     * Mark the store closed. Subsequent calls throw cleanly. Idempotent.
-     * AgentCore is stateless from the client perspective so there's no
-     * connection to tear down — the close gate is purely defensive.
-     */
     close(): Promise<void>;
     private ensureOpen;
 }
+/** The slice of `@aws-sdk/client-bedrock-agentcore` the shim touches. */
+export interface BedrockAgentCoreSdkModule {
+    readonly BedrockAgentCoreClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly CreateEventCommand?: new (input: unknown) => unknown;
+    readonly ListEventsCommand?: new (input: unknown) => unknown;
+    readonly DeleteEventCommand?: new (input: unknown) => unknown;
+}
 //# sourceMappingURL=agentcore.d.ts.map

package/dist/types/adapters/memory/agentcore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/agentcore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/agentcore.ts"],"names":[],"mappings":"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"}

package/dist/types/core/agent/buildAgentChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAc,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AASrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;;;8DAG0D;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,OAAO,yCAAyC,EAAE,WAAW,CAAC;IAEpG;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C;;yDAEqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAMrC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEzD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAG3C;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAwV/D"}
+{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAc,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAUrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;;;8DAG0D;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,OAAO,yCAAyC,EAAE,WAAW,CAAC;IAEpG;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C;;yDAEqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAMrC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEzD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAG3C;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAoW/D"}

package/dist/types/core/agent/buildDynamicAgentChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildDynamicAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildDynamicAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAczD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAgD3D;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CA6VtE"}
+{"version":3,"file":"buildDynamicAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildDynamicAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAezD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAgD3D;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAwWtE"}

package/dist/types/core/agent/memoryRecallInjections.d.ts

@@ -0,0 +1,9 @@
+import type { ActiveInjection } from '../../lib/injection-engine/types.js';
+/** Build `'memory'`-flavored ActiveInjections from the per-id recall keys in `parent`. */
+export declare function memoryRecallInjections(parent: Record<string, unknown>, memoryIds: readonly string[]): ActiveInjection[];
+/**
+ * Append memory recalls to the active-injection set a slot-fork inputMapper hands to
+ * the system / messages slot subflows. No-op when the agent has no memories.
+ */
+export declare function withMemoryRecall(activeInjections: readonly ActiveInjection[] | undefined, parent: Record<string, unknown>, memoryIds: readonly string[]): readonly ActiveInjection[];
+//# sourceMappingURL=memoryRecallInjections.d.ts.map

package/dist/types/core/agent/memoryRecallInjections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryRecallInjections.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/memoryRecallInjections.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAO3E,0FAA0F;AAC1F,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,eAAe,EAAE,CAyBnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,EACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,SAAS,eAAe,EAAE,CAK5B"}

package/dist/types/observability/contextError/finders/compareFinders.d.ts

@@ -0,0 +1,20 @@
+/**
+ * compareFinders — run several finders on the same case and collect their answers
+ * side by side (a leaderboard row per finder). PARAMETRIC: you pass the finders to
+ * compare, so nothing is auto-discovered or retained — unused finders stay
+ * tree-shakeable.
+ */
+import type { Finder, FindInput, FindResult } from './types.js';
+/** One finder's result in a comparison (or the error it threw). */
+export interface CompareRow {
+    readonly finder: string;
+    readonly result: FindResult | null;
+    readonly error?: string;
+}
+/**
+ * Run each finder on `input`; a finder that throws (e.g. missing a dep it needs)
+ * becomes a row with `result: null` and `error` set, so one finder cannot abort
+ * the comparison.
+ */
+export declare function compareFinders(finders: readonly Finder[], input: FindInput): Promise<CompareRow[]>;
+//# sourceMappingURL=compareFinders.d.ts.map

package/dist/types/observability/contextError/finders/compareFinders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareFinders.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/compareFinders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,UAAU,EAAE,CAAC,CAcvB"}

package/dist/types/observability/contextError/finders/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * observability / contextError / finders — pluggable context-bug localization.
+ *
+ * "Which piece of context made the agent's answer wrong?" Pick a finder and call
+ * `find(input)`. Each finder is a thin, self-explaining adapter over the engines in
+ * `src/lib/context-bisect` + `src/lib/influence-core`; the academic method + citation
+ * live in `meta`, never in the import name.
+ *
+ *   import { rankSuspects } from 'agentfootprint/observability/contextError/finders';
+ *   const r = await rankSuspects.find(input);   // r.lead, r.evidence ('guessed'|'proven')
+ *
+ * Tree-shakeable: one finder = one file = one named export. Importing one finder does
+ * not pull the others (or the heavy ablation path behind removeAndRetry). This barrel
+ * is re-export-only — no runtime code, no registry.
+ */
+export type { ContextPiece, Evidence, Finder, FinderMeta, FindInput, FindResult, Granularity, ScoredSuspect, StepInput, } from './types.js';
+export { rankSuspects } from './rankSuspects.js';
+export { removeAndRetry } from './removeAndRetry.js';
+export { traceSteps } from './traceSteps.js';
+export { testManyCombos } from './testManyCombos.js';
+export { shrinkToCause } from './shrinkToCause.js';
+export { compareFinders, type CompareRow } from './compareFinders.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/observability/contextError/finders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,MAAM,EACN,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,aAAa,EACb,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types/observability/contextError/finders/rankSuspects.d.ts

@@ -0,0 +1,3 @@
+import type { Finder } from './types.js';
+export declare const rankSuspects: Finder;
+//# sourceMappingURL=rankSuspects.d.ts.map

package/dist/types/observability/contextError/finders/rankSuspects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rankSuspects.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/rankSuspects.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,YAAY,CAAC;AAEhE,eAAO,MAAM,YAAY,EAAE,MAsC1B,CAAC"}

package/dist/types/observability/contextError/finders/removeAndRetry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * removeAndRetry — the thorough finder. Removes each context piece, re-runs the
+ * agent, and a piece is the cause iff its removal flips the outcome back. No
+ * embedder, no heuristic: pure counterfactual. Exact, but pays one re-run per
+ * piece (`checks`), and on multi-loop runs it can over-attribute (several pieces
+ * each flip) — narrow with a slice first when that happens.
+ *
+ * Method: leave-one-out ablation (counterfactual necessity).
+ */
+import type { Finder } from './types.js';
+export declare const removeAndRetry: Finder;
+//# sourceMappingURL=removeAndRetry.d.ts.map

package/dist/types/observability/contextError/finders/removeAndRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeAndRetry.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/removeAndRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,YAAY,CAAC;AAEhE,eAAO,MAAM,cAAc,EAAE,MAwC5B,CAAC"}

package/dist/types/observability/contextError/finders/shrinkToCause.d.ts

@@ -0,0 +1,12 @@
+/**
+ * shrinkToCause — keeps cutting the suspect set down until the smallest subset whose
+ * removal still fixes the answer. For a single dominant cause it converges in fewer
+ * re-runs than leave-one-out (delta-debugging minimization); for co-necessary causes it
+ * still returns the minimal recovering set, but may cost more probes than leave-one-out.
+ * The returned set is verified to recover by construction.
+ *
+ * Method: delta-debugging minimization (ddmin) over the removal set that recovers.
+ */
+import type { Finder } from './types.js';
+export declare const shrinkToCause: Finder;
+//# sourceMappingURL=shrinkToCause.d.ts.map

package/dist/types/observability/contextError/finders/shrinkToCause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shrinkToCause.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/shrinkToCause.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,YAAY,CAAC;AAEhE,eAAO,MAAM,aAAa,EAAE,MAwF3B,CAAC"}

package/dist/types/observability/contextError/finders/testManyCombos.d.ts

@@ -0,0 +1,12 @@
+/**
+ * testManyCombos — turns context pieces on and off in many combinations, re-runs each,
+ * and learns which pieces drive the wrong answer (a linear-surrogate attribution), then
+ * confirms the top candidate with one clean ablation. The sampling one: it estimates an
+ * influence weight per piece from counterfactual data rather than ranking by similarity.
+ *
+ * Method: random-subset ablation + linear-surrogate attribution. Deterministic
+ * pseudo-random masking (a reproducible reimplementation of ContextCite's random subsets).
+ */
+import type { Finder } from './types.js';
+export declare const testManyCombos: Finder;
+//# sourceMappingURL=testManyCombos.d.ts.map

package/dist/types/observability/contextError/finders/testManyCombos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testManyCombos.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/testManyCombos.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,YAAY,CAAC;AAWhE,eAAO,MAAM,cAAc,EAAE,MAkF5B,CAAC"}

package/dist/types/observability/contextError/finders/traceSteps.d.ts

@@ -0,0 +1,3 @@
+import type { Finder } from './types.js';
+export declare const traceSteps: Finder;
+//# sourceMappingURL=traceSteps.d.ts.map

package/dist/types/observability/contextError/finders/traceSteps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceSteps.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/traceSteps.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAyB,MAAM,YAAY,CAAC;AAEhE,eAAO,MAAM,UAAU,EAAE,MAkDxB,CAAC"}

package/dist/types/observability/contextError/finders/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Context-error finders — the plain, pluggable public surface for context-bug
+ * localization. A `Finder` answers one question: "which piece of context made the
+ * agent's answer wrong?" Each finder is a thin, named adapter over the engines in
+ * `src/lib/context-bisect` + `src/lib/influence-core`; the academic method + citation
+ * live in `meta`, never in the import name.
+ *
+ * Taxonomy (area / category / thing): observability / contextError / finders.
+ * Tree-shakeable: one finder = one file = one named export; import only what you use.
+ */
+import type { Embedder } from '../../../lib/influence-core/index.js';
+/** How sure the finder is. `guessed` = ranked by a similarity proxy only;
+ *  `proven` = a removal/re-run actually flipped the outcome (counterfactual). */
+export type Evidence = 'guessed' | 'proven';
+/** What the finder points at. `piece` = a context element; `step` = an agent step. */
+export type Granularity = 'piece' | 'step';
+/** A removable piece of context the finder can suspect. */
+export interface ContextPiece {
+    readonly id: string;
+    readonly text: string;
+}
+/** One agent step (a tool-call), for finders that work at step granularity. */
+export interface StepInput {
+    readonly id: string;
+    /** Human-readable label, e.g. `get_promo@L1`. */
+    readonly label: string;
+    readonly text: string;
+}
+/** Everything a finder may need. Light finders use `embedder`; counterfactual
+ *  finders use `rerun`; step finders use `steps`. A finder throws if a field it
+ *  needs is missing. */
+export interface FindInput {
+    /** The removable context pieces to consider. */
+    readonly suspects: readonly ContextPiece[];
+    /** The wrong answer to explain. */
+    readonly wrongOutput: string;
+    /** Embedder for similarity-ranking finders. */
+    readonly embedder?: Embedder;
+    /** Re-run with the given pieces removed; `recovered` = the outcome flipped back. */
+    readonly rerun?: (removedIds: readonly string[]) => Promise<{
+        recovered: boolean;
+        outcome?: string;
+    }>;
+    /** The agent's steps, for step-granularity finders. */
+    readonly steps?: readonly StepInput[];
+    /** For testManyCombos: how many on/off combinations to sample (default ~4×#suspects). */
+    readonly samples?: number;
+}
+/** One suspect in the finder's ranked output. */
+export interface ScoredSuspect {
+    readonly id: string;
+    /** Higher = more suspicious. Absent for finders that don't score. */
+    readonly score?: number;
+}
+/** What a finder returns. Plain fields, namespace-independent. */
+export interface FindResult {
+    /** Which finder produced this. */
+    readonly finder: string;
+    /** Suspects, most-to-least suspicious. */
+    readonly suspects: readonly ScoredSuspect[];
+    /** The single top suspect, if any. */
+    readonly lead?: string;
+    /** The small set worth confirming when there is no clear single winner. */
+    readonly shortlist: readonly string[];
+    /** `guessed` (proxy) vs `proven` (counterfactual). */
+    readonly evidence: Evidence;
+    /** `piece` vs `step`. */
+    readonly granularity: Granularity;
+    /** How many times the finder re-ran the agent (the honest cost). 0 = free. */
+    readonly checks: number;
+    /** A self-explaining narrative of how the finder reached its answer. */
+    readonly explanation: string;
+}
+/** Attribution — kept off the import name, surfaced in docs / leaderboards. */
+export interface FinderMeta {
+    /** Plain one-liner for a leaderboard row. */
+    readonly label: string;
+    /** The precise technique, for experts. */
+    readonly method: string;
+    /** Citation, if the finder reimplements a published method. */
+    readonly paper?: string;
+}
+/** A pluggable context-error finder. */
+export interface Finder {
+    readonly name: string;
+    readonly meta: FinderMeta;
+    find(input: FindInput): Promise<FindResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/observability/contextError/finders/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAErE;iFACiF;AACjF,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5C,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;wBAEwB;AACxB,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,CACf,UAAU,EAAE,SAAS,MAAM,EAAE,KAC1B,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wCAAwC;AACxC,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7C"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentfootprint",
-  "version": "6.40.0",
-  "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
+  "version": "6.42.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",
   "author": "Sanjay Krishna Anbalagan",
   "repository": {
@@ -122,6 +122,11 @@
       "import": "./dist/esm/observe.js",
       "require": "./dist/observe.js"
     },
+    "./observability/contextError/finders": {
+      "types": "./dist/types/observability/contextError/finders/index.d.ts",
+      "import": "./dist/esm/observability/contextError/finders/index.js",
+      "require": "./dist/observability/contextError/finders/index.js"
+    },
     "./resilience": {
       "types": "./dist/types/resilience/index.d.ts",
       "import": "./dist/esm/resilience/index.js",
@@ -180,6 +185,7 @@
   ],
   "peerDependencies": {
     "@anthropic-ai/sdk": "*",
+    "@aws-sdk/client-bedrock-agentcore": "*",
     "@aws-sdk/client-bedrock-agent-runtime": "*",
     "@aws-sdk/client-bedrock-runtime": "*",
     "@aws-sdk/client-cloudwatch-logs": "*",
@@ -201,6 +207,9 @@
     "@aws-sdk/client-bedrock-runtime": {
       "optional": true
     },
+    "@aws-sdk/client-bedrock-agentcore": {
+      "optional": true
+    },
     "@aws-sdk/client-bedrock-agent-runtime": {
       "optional": true
     },