agentfootprint 6.43.0 → 6.45.0

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

@@ -0,0 +1,146 @@
+/**
+ * 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-agentcore:us-west-2:...:memory/my-mem',
+ *     region: 'us-west-2',
+ *   });
+ *
+ * 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:
+ *
+ *   • `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).
+ *
+ * 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, 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 {
+    /** Append one entry as an event (server assigns the eventId). */
+    createEvent(input: {
+        memoryId: string;
+        actorId: string;
+        sessionId: string;
+        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;
+        maxResults?: number;
+        nextToken?: string;
+    }): Promise<{
+        events: readonly AgentCoreEvent[];
+        nextToken?: string;
+    }>;
+    /** Delete one event by its AgentCore eventId. */
+    deleteEvent(input: {
+        memoryId: string;
+        actorId: string;
+        sessionId: string;
+        eventId: string;
+    }): 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 (shares one SDK config across the host app). */
+    readonly client?: AgentCoreLikeClient;
+    /** Page size for `listEvents`. Default 100. */
+    readonly pageSize?: number;
+    /** @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()`.
+ *
+ * @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;
+    private readonly memoryId;
+    private readonly pageSize;
+    private closed;
+    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 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>>;
+    delete(identity: MemoryIdentity, id: string): Promise<void>;
+    seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
+    recordSignature(identity: MemoryIdentity, signature: string): Promise<void>;
+    feedback(identity: MemoryIdentity, id: string, usefulness: number): Promise<void>;
+    getFeedback(identity: MemoryIdentity, id: string): Promise<{
+        average: number;
+        count: number;
+    } | null>;
+    /** GDPR "everything for this identity, gone." No DeleteSession on AgentCore → delete every event. */
+    forget(identity: MemoryIdentity): Promise<void>;
+    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;
+}

package/dist/esm/adapters/memory/bedrockAgentMemory.d.ts

@@ -0,0 +1,95 @@
+/**
+ * BedrockAgentMemory — read the **auto-generated session-summary memory** of a
+ * (legacy) Amazon **Bedrock Agents** agent (peer-dep `@aws-sdk/client-bedrock-agent-runtime`).
+ *
+ *   import { BedrockAgentMemory } from 'agentfootprint/memory-providers';
+ *
+ *   const mem = new BedrockAgentMemory({ agentId, agentAliasId, region: 'us-west-2' });
+ *   const summaries = await mem.readSummaries(userMemoryId);   // string summaries Bedrock wrote
+ *
+ * **This is NOT a `MemoryStore`** — and intentionally so. Bedrock Agents *owns the writes*:
+ * the agent generates `SESSION_SUMMARY` records itself (`GetAgentMemory` reads them,
+ * `DeleteAgentMemory` clears them). There is no "put an arbitrary entry" operation, so wrapping
+ * it as a `defineMemory({ store })` would be a "store that can't store." Instead it's a small
+ * **reader** you use to *surface* Bedrock's built-in memory — e.g. inject the summaries as a
+ * Fact/context block into an agentfootprint agent.
+ *
+ * For a real read/write agent memory store on AWS, use `AgentCoreStore` (the newer
+ * Bedrock **AgentCore** platform) — that's the go-forward path; this targets the prior-gen
+ * Bedrock Agents product and exists for teams migrating off it.
+ *
+ * Role:   Outer ring. Lazy-requires the AWS SDK; zero cost when unused.
+ */
+/** One auto-generated session summary from Bedrock Agents memory. */
+export interface BedrockAgentSummary {
+    readonly sessionId: string;
+    readonly summaryText: string;
+    /** ISO timestamps (the SDK returns Date; serialized here for portability). */
+    readonly sessionStartTime?: string;
+    readonly sessionExpiryTime?: string;
+}
+/** Minimal surface the reader uses; tests inject a mock via `_client`. */
+export interface BedrockAgentMemoryLikeClient {
+    getSessionSummaries(input: {
+        agentId: string;
+        agentAliasId: string;
+        memoryId: string;
+        maxItems?: number;
+        nextToken?: string;
+    }): Promise<{
+        summaries: readonly BedrockAgentSummary[];
+        nextToken?: string;
+    }>;
+    deleteMemory(input: {
+        agentId: string;
+        agentAliasId: string;
+        memoryId: string;
+        sessionId?: string;
+    }): Promise<void>;
+}
+export interface BedrockAgentMemoryOptions {
+    /** The Bedrock Agent id whose memory to read. Required. */
+    readonly agentId: string;
+    /** The Bedrock Agent alias id. Required. */
+    readonly agentAliasId: string;
+    /** AWS region (when constructing the SDK client internally). */
+    readonly region?: string;
+    /** Pre-built client (shares one SDK config across the host app). */
+    readonly client?: BedrockAgentMemoryLikeClient;
+    /** Default page size for `readSummaries`. Default 20. */
+    readonly maxItems?: number;
+    /** @internal Test injection — skips the SDK require. */
+    readonly _client?: BedrockAgentMemoryLikeClient;
+    /** @internal Test injection — the AWS SDK module. */
+    readonly _sdk?: BedrockAgentRuntimeSdkModule;
+}
+/**
+ * Read-only reader for Bedrock Agents' auto session-summary memory.
+ *
+ * @throws when `@aws-sdk/client-bedrock-agent-runtime` is not installed and no
+ *         `_client`/`_sdk` is supplied.
+ */
+export declare class BedrockAgentMemory {
+    private readonly client;
+    private readonly agentId;
+    private readonly agentAliasId;
+    private readonly maxItems;
+    constructor(options: BedrockAgentMemoryOptions);
+    /** All session summaries Bedrock generated for `memoryId` (paginated). */
+    readSummaries(memoryId: string, opts?: {
+        maxItems?: number;
+    }): Promise<BedrockAgentSummary[]>;
+    /** The concatenated summary text — handy to inject as a single context/Fact block. */
+    readText(memoryId: string): Promise<string>;
+    /** Clear Bedrock's memory for `memoryId` (optionally a single `sessionId`). */
+    forget(memoryId: string, sessionId?: string): Promise<void>;
+}
+export interface BedrockAgentRuntimeSdkModule {
+    readonly BedrockAgentRuntimeClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly GetAgentMemoryCommand?: new (input: unknown) => unknown;
+    readonly DeleteAgentMemoryCommand?: new (input: unknown) => unknown;
+}

package/dist/esm/adapters/memory/redis.d.ts

@@ -0,0 +1,127 @@
+/**
+ * RedisStore — Redis-backed `MemoryStore` adapter (peer-dep `ioredis`).
+ *
+ * Import from the canonical subpath (the `agentfootprint/memory-redis` alias
+ * was removed in 4.0.0):
+ *
+ *   import { RedisStore } from 'agentfootprint/memory-providers';
+ *
+ *   const store = new RedisStore({ url: 'redis://localhost:6379' });
+ *
+ * Pattern: Adapter (GoF) — translates the `MemoryStore` interface onto
+ *          Redis primitives (key/value for entries, set for signatures,
+ *          hash for feedback aggregates).
+ * Role:    Outer ring. Lazy-requires `ioredis`; 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).
+ *
+ * Vector search (`search()`) is NOT implemented in this adapter — RedisSearch
+ * is a separate Redis module with its own API surface. A `RedisSearchStore`
+ * may ship in a future release. RAG users with v2.3 should use
+ * `InMemoryStore` until the search-capable adapter lands.
+ *
+ * Concurrency model:
+ *   - `put` / `putMany` use simple SET / pipelined SET (last-write-wins).
+ *   - `putIfVersion` uses a small Lua script for atomic version compare-and-swap.
+ *   - Multi-writer correctness ⇒ prefer `putIfVersion` in stage code.
+ */
+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';
+/**
+ * Minimal `ioredis` client surface this adapter needs. Defined locally so
+ * we don't take a hard import on `ioredis` (lazy peer-dep) and tests can
+ * inject a mock implementation via `_client`.
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: ReadonlyArray<string | number>): Promise<unknown>;
+    del(...keys: ReadonlyArray<string>): Promise<number>;
+    sadd(key: string, ...members: ReadonlyArray<string>): Promise<number>;
+    srem(key: string, ...members: ReadonlyArray<string>): Promise<number>;
+    sismember(key: string, member: string): Promise<number>;
+    smembers(key: string): Promise<readonly string[]>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hset(key: string, ...args: ReadonlyArray<string | number>): Promise<number>;
+    scan(cursor: string, match: 'MATCH', pattern: string, count: 'COUNT', n: number): Promise<readonly [string, readonly string[]]>;
+    eval(script: string, numKeys: number, ...args: ReadonlyArray<string | number>): Promise<unknown>;
+    pipeline(): RedisLikePipeline;
+    quit(): Promise<unknown>;
+}
+export interface RedisLikePipeline {
+    set(key: string, value: string, ...args: ReadonlyArray<string | number>): RedisLikePipeline;
+    sadd(key: string, ...members: ReadonlyArray<string>): RedisLikePipeline;
+    exec(): Promise<unknown>;
+}
+export interface RedisStoreOptions {
+    /**
+     * Connection URL (e.g. `redis://default:password@host:6379/0`). Required
+     * unless `_client` is supplied.
+     */
+    readonly url?: string;
+    /**
+     * Pre-built `ioredis` client. Use this when the host app already manages
+     * a Redis connection pool. Adapter does NOT call `quit()` on a borrowed
+     * client — caller owns the lifecycle.
+     */
+    readonly client?: RedisLikeClient;
+    /** Key prefix for namespace isolation across apps sharing one Redis. Default `'agentfootprint'`. */
+    readonly prefix?: string;
+    /**
+     * SCAN page size when iterating keys. Default 100. Larger = fewer
+     * round-trips but more memory per response. Adapter never uses `KEYS *`
+     * (which blocks Redis).
+     */
+    readonly scanCount?: number;
+    /**
+     * @internal Test injection point. When provided, skips the SDK require.
+     */
+    readonly _client?: RedisLikeClient;
+}
+/**
+ * Redis-backed `MemoryStore`. Implements every method except `search()`.
+ *
+ * @throws when `ioredis` is not installed and no `_client` is supplied.
+ */
+export declare class RedisStore implements MemoryStore {
+    private readonly client;
+    private readonly prefix;
+    private readonly scanCount;
+    private readonly ownsClient;
+    private closed;
+    constructor(options?: RedisStoreOptions);
+    private nsKey;
+    private entryKey;
+    private indexKey;
+    private sigKey;
+    private feedbackKey;
+    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>;
+    /**
+     * Optimistic concurrency via a small Lua script — atomic
+     * compare-and-swap on the JSON-encoded `version` field.
+     */
+    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number): Promise<PutIfVersionResult>;
+    list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
+    delete(identity: MemoryIdentity, id: string): Promise<void>;
+    seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
+    recordSignature(identity: MemoryIdentity, signature: string): Promise<void>;
+    feedback(identity: MemoryIdentity, id: string, usefulness: number): Promise<void>;
+    getFeedback(identity: MemoryIdentity, id: string): Promise<{
+        average: number;
+        count: number;
+    } | null>;
+    /**
+     * GDPR — drop every key under this identity's namespace.
+     */
+    forget(identity: MemoryIdentity): Promise<void>;
+    /**
+     * Close the underlying Redis connection — only when this adapter
+     * owns it. Borrowed clients (passed via `client` option) are left to
+     * the caller. Idempotent.
+     */
+    close(): Promise<void>;
+    private ensureOpen;
+}

package/dist/esm/adapters/observability/agentcore.d.ts

@@ -0,0 +1,67 @@
+/**
+ * agentcoreObservability — AWS Bedrock AgentCore observability adapter.
+ *
+ * Ships every `AgentfootprintEvent` to **CloudWatch Logs** in a
+ * structured-JSON shape AgentCore's hosted-agent telemetry layer
+ * understands. Use when:
+ *
+ *   1. Your agent runs INSIDE AgentCore — events show up alongside
+ *      AgentCore's own runtime telemetry in the same log group.
+ *   2. Your agent runs OUTSIDE AgentCore but you want to query agent
+ *      behavior in CloudWatch Insights / X-Ray traces using the same
+ *      schema AgentCore uses internally.
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
+ *           only when this adapter is used; declared via
+ *           `peerDependenciesMeta.{name}.optional = true`).
+ *
+ * **Implementation:** thin wrapper over `cloudwatchObservability`'s
+ * shared base. The only difference is the strategy `name` (used for
+ * registry lookup + diagnostics). All batching, flush, error-routing,
+ * and SDK-loading behavior is identical. As we evolve the CloudWatch
+ * shipping path (retry, sequence tokens, metrics emission), every
+ * CloudWatch-shaped adapter inherits the improvement.
+ *
+ * @example Basic
+ * ```ts
+ * import { agentcoreObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: agentcoreObservability({
+ *     region: 'us-east-1',
+ *     logGroupName: '/agentfootprint/my-agent',
+ *     logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * @example Test injection (skip SDK require entirely)
+ * ```ts
+ * agentcoreObservability({
+ *   logGroupName: '/agentfootprint/test',
+ *   _client: {
+ *     putLogEvents: async (input) => { capturedBatches.push(input); },
+ *   },
+ * });
+ * ```
+ */
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+import { type CloudwatchObservabilityOptions } from './cloudwatch.js';
+/**
+ * AgentCore-specific options. Currently identical to the generic
+ * `CloudwatchObservabilityOptions` — kept as a separate type for
+ * future-proofing (AgentCore-specific knobs like
+ * `agentcoreSessionId` propagation could land here without a
+ * breaking change).
+ */
+export type AgentcoreObservabilityOptions = CloudwatchObservabilityOptions;
+/**
+ * Build an AgentCore-flavored CloudWatch Logs observability strategy.
+ * Functionally identical to `cloudwatchObservability` except for the
+ * strategy `name`, which lets registry-lookup + diagnostics
+ * distinguish AgentCore-targeted shipping from generic CloudWatch.
+ */
+export declare function agentcoreObservability(opts: AgentcoreObservabilityOptions): ObservabilityStrategy;