agentfootprint 6.44.0 → 6.45.0

package/dist/esm/adapters/llm/MockProvider.d.ts

@@ -0,0 +1,153 @@
+/**
+ * MockProvider — deterministic LLMProvider for tests + examples.
+ *
+ * Pattern: Adapter (GoF, Design Patterns ch. 4).
+ * Role:    Ports-and-Adapters outer ring (Cockburn, 2005) — implements the
+ *          LLMProvider port without calling out to a real LLM service.
+ * Emits:   N/A (adapters don't emit; recorders observe them).
+ *
+ * Two modes, same provider:
+ *   • DEFAULT (no latency options)  — instant `complete()`, no streaming.
+ *     Use in unit tests; behavior unchanged from earlier revisions.
+ *   • REALISTIC (`thinkingMs` set)  — randomised "thinking" latency before
+ *     the response, plus a `stream()` implementation that emits the
+ *     content word-by-word with `chunkDelayMs` between chunks. Lets
+ *     consumers SEE the run unfold (pauses, streaming tokens, tool
+ *     dispatch) instead of having every step finish in microseconds.
+ *
+ * Realistic mode is the right default for the playground / Lens demos:
+ * a real OpenAI / Anthropic call takes 3–8 s, so the UX you build for
+ * that timing is what matters. Use `MockProvider.realistic()` for the
+ * common 3–8 s thinking + 30–80 ms per word streaming preset.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+/** Either a fixed value (in ms) or a random `[min, max]` range (inclusive). */
+export type LatencyMs = number | readonly [number, number];
+/**
+ * One scripted reply consumed in order from `MockProviderOptions.replies`.
+ * String → plain text content; Partial<LLMResponse> → can include
+ * `toolCalls`, `usage`, `stopReason` for tool-using ReAct loops.
+ */
+export type MockReply = string | Partial<LLMResponse>;
+export interface MockProviderOptions {
+    readonly name?: string;
+    /** Fixed response content. Overrides `respond` when set. */
+    readonly reply?: string;
+    /**
+     * Scripted replies for multi-turn / tool-using agents. Each entry
+     * is consumed in order — iteration 1 reads `replies[0]`, iteration
+     * 2 reads `replies[1]`, and so on. Use Partial<LLMResponse> to
+     * inject `toolCalls`:
+     *
+     * ```ts
+     * mock({
+     *   replies: [
+     *     { toolCalls: [{ id: '1', name: 'lookup', args: { id: 42 } }] },
+     *     { content: 'Found it: refunds take 3 business days.' },
+     *   ],
+     * });
+     * ```
+     *
+     * **Exhaustion semantics:** if the agent calls the LLM more times
+     * than there are replies, `complete()` / `stream()` throw a clear
+     * error. This makes mock-script bugs loud, not silent. Tune the
+     * agent's `maxIterations` to bound the call count.
+     *
+     * Takes precedence over `reply` and `respond` when set.
+     */
+    readonly replies?: readonly MockReply[];
+    /**
+     * Build the response from the request. Returns either a plain
+     * string (renders as content with no tool calls) or a partial
+     * `LLMResponse` so consumers can simulate tool calls + multi-turn
+     * loops without needing a separate `scripted()` helper.
+     *
+     * Default: echoes the last user message.
+     */
+    readonly respond?: (req: LLMRequest) => string | Partial<LLMResponse>;
+    /**
+     * Simulated wall-clock delay per request (ms).
+     * Pass a single number for a fixed delay or a `[min, max]` tuple for
+     * a uniformly random delay (e.g. `[3000, 8000]` for "real LLM"
+     * thinking time). Default 0 (instant).
+     *
+     * Aliased via `delayMs` for backward compatibility.
+     */
+    readonly thinkingMs?: LatencyMs;
+    /** Alias for `thinkingMs`. Kept for back-compat with prior revisions. */
+    readonly delayMs?: LatencyMs;
+    /**
+     * For `stream()`: delay between successive chunks (ms). Pass a
+     * single number for a fixed delay or a `[min, max]` tuple for a
+     * uniformly random delay per chunk (e.g. `[30, 80]` for typing-like
+     * cadence). Default 30ms.
+     *
+     * Has no effect on `complete()`.
+     */
+    readonly chunkDelayMs?: LatencyMs;
+    /** Fixed stop reason to return. Default 'stop'. */
+    readonly stopReason?: string;
+    /** Override usage counts returned. Default: chars/4 heuristic. */
+    readonly usage?: Readonly<{
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    }>;
+}
+export declare class MockProvider implements LLMProvider {
+    readonly name: string;
+    private readonly reply?;
+    private readonly replies?;
+    private repliesCursor;
+    private readonly respond;
+    private readonly thinkingMs;
+    private readonly chunkDelayMs;
+    private readonly stopReason;
+    private readonly usageOverride;
+    constructor(options?: MockProviderOptions);
+    /**
+     * Reset the scripted-replies cursor. Useful when reusing one
+     * `MockProvider` instance across multiple test scenarios — each
+     * scenario can `provider.resetReplies()` to start from `replies[0]`
+     * again. No-op when `replies` was not supplied.
+     */
+    resetReplies(): void;
+    /**
+     * Convenience factory for the playground / Lens demo defaults: a
+     * real-feel mock with 3–8 s of "thinking" before the response and
+     * 30–80 ms per streamed word. Lets users observe pause/resume,
+     * streaming, and tool dispatch happening live without hitting a
+     * paid API.
+     */
+    static realistic(options?: MockProviderOptions): MockProvider;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Streaming mode — emits the response content word-by-word so
+     * consumers (Lens commentary, chat UIs) can render tokens as they
+     * arrive. Tool calls land all at once on the final chunk because
+     * that is how real providers (OpenAI, Anthropic) deliver them too.
+     */
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+    private buildResponse;
+    /**
+     * Resolve the next reply source for one `complete()` / `stream()` call.
+     * Priority: `replies` (scripted, throws on exhaustion) → `reply` (single
+     * fixed string) → `respond` (callback default). Replies are consumed
+     * in order; the cursor is per-instance, not per-request.
+     */
+    private consumeNextReply;
+}
+/**
+ * Lowercase factory for `MockProvider` — matches the v1 `mock()` import
+ * shape so docs and quick-starts stay copy-pasteable. Equivalent to
+ * `new MockProvider(options)`.
+ *
+ * @example
+ *   import { Agent, mock, defineTool } from 'agentfootprint';
+ *
+ *   const agent = Agent.create({ provider: mock({ reply: 'hello' }) })
+ *     .tool(defineTool({ name: 'echo', ... }))
+ *     .build();
+ */
+export declare function mock(options?: MockProviderOptions): MockProvider;

package/dist/esm/adapters/llm/OpenAIProvider.d.ts

@@ -0,0 +1,220 @@
+/**
+ * OpenAIProvider — wraps the `openai` SDK as an `LLMProvider`.
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from
+ *          OpenAI's Chat Completions API. Knows nothing about agents,
+ *          recorders, or compositions.
+ * Emits:   N/A.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT supported  (`LLMMessage.content` is
+ *   `string`). May extend in a future release.
+ * • `responseFormat` (JSON-mode) NOT exposed  — pass schema
+ *   instructions via `systemPrompt` for now.
+ *
+ * The `baseURL` option enables OpenAI-compatible APIs (Ollama, Together,
+ * Groq, vLLM, LM Studio) without a separate adapter — see the `ollama()`
+ * convenience factory below.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+interface OpenAIClient {
+    chat: {
+        completions: {
+            create(params: OpenAICreateParams): Promise<OpenAIChatCompletion> | AsyncIterable<OpenAIStreamChunk>;
+        };
+    };
+}
+interface OpenAICreateParams {
+    model: string;
+    messages: OpenAIMessage[];
+    tools?: OpenAITool[];
+    /** Legacy token cap — DEPRECATED by OpenAI and REJECTED by o-series reasoning
+     *  models. Kept only for custom OpenAI-compatible endpoints (Ollama/vLLM/…). */
+    max_tokens?: number;
+    /** Current token cap — accepted by all OpenAI/Azure chat models incl. o-series. */
+    max_completion_tokens?: number;
+    temperature?: number;
+    stop?: string[];
+    stream?: boolean;
+    /** Ask OpenAI/Azure to emit a final usage chunk while streaming. */
+    stream_options?: {
+        include_usage: boolean;
+    };
+}
+interface OpenAIMessage {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+}
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface OpenAIChatCompletion {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: 'assistant';
+            content: string | null;
+            tool_calls?: OpenAIToolCall[];
+        };
+        finish_reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | string;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+interface OpenAIStreamChunk {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                type?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+export interface OpenAIProviderOptions {
+    /** API key. Defaults to `OPENAI_API_KEY` env var. */
+    readonly apiKey?: string;
+    /** Base URL — set for OpenAI-compatible APIs (Ollama, Together, vLLM). */
+    readonly baseURL?: string;
+    /**
+     * Default model used when `LLMRequest.model` is `'openai'` (the
+     * shorthand). Full model ids pass through unchanged.
+     */
+    readonly defaultModel?: string;
+    /** Default max tokens when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /**
+     * Treat the target as a **reasoning model** (o-series: o1 / o3 / o4-mini, or an
+     * Azure reasoning deployment). Reasoning models reject `max_tokens` and an explicit
+     * `temperature`, and use the `developer` role in place of `system`. Standard o-series
+     * model ids are auto-detected; set this explicitly for Azure deployments whose name
+     * does not reveal the underlying model.
+     */
+    readonly reasoning?: boolean;
+    /** @internal Pre-built client for testing. Skips SDK import. */
+    readonly _client?: OpenAIClient;
+}
+/**
+ * Build an `LLMProvider` backed by OpenAI's Chat Completions API.
+ *
+ * @example
+ *   import { Agent } from 'agentfootprint';
+ *   import { openai } from 'agentfootprint/llm-providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: openai({ defaultModel: 'gpt-4o' }),
+ *     model: 'openai',
+ *   })
+ *     .tool(searchTool)
+ *     .build();
+ */
+export declare function openai(options?: OpenAIProviderOptions): LLMProvider;
+/**
+ * Class form for consumers who prefer `new OpenAIProvider(...)`.
+ */
+export declare class OpenAIProvider implements LLMProvider {
+    readonly name = "openai";
+    private readonly inner;
+    constructor(options?: OpenAIProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export interface AzureOpenAIProviderOptions {
+    /** Resource endpoint, e.g. `https://my-co.openai.azure.com`. Env fallbacks:
+     *  `AZURE_OPENAI_ENDPOINT`, then `OPENAI_BASE_URL`. */
+    readonly endpoint?: string;
+    /** API key. Env fallbacks: `AZURE_OPENAI_API_KEY`, then `OPENAI_API_KEY`. */
+    readonly apiKey?: string;
+    /** Azure API version, e.g. `2024-12-01-preview`. Env fallback:
+     *  `AZURE_OPENAI_API_VERSION`. Required. */
+    readonly apiVersion?: string;
+    /** The DEPLOYMENT name (Azure's "model"), e.g. `gpt-4o-128k`. Env fallbacks:
+     *  `AZURE_OPENAI_DEPLOYMENT`, then `MODEL_NAME`. Required. */
+    readonly deployment?: string;
+    /** Default max tokens when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /**
+     * Set when the Azure DEPLOYMENT is a **reasoning model** (o1/o3/o4-mini). Azure
+     * deployment names are arbitrary, so this cannot be auto-detected — declare it to
+     * omit `temperature` and send the `developer` role. (`max_completion_tokens` is used
+     * for all Azure deployments regardless.)
+     */
+    readonly reasoning?: boolean;
+    /** @internal Pre-built client for testing. Skips SDK import. */
+    readonly _client?: OpenAIClient;
+}
+/**
+ * Build an `LLMProvider` for **Azure OpenAI**.
+ *
+ * Azure is NOT a drop-in OpenAI-compatible URL — it uses a deployment-scoped
+ * path, `api-key` header auth, and an `api-version` query param. This wraps the
+ * `openai` SDK's `AzureOpenAI` client (which handles all that) and reuses the
+ * exact same completion/streaming/tool-call logic as `openai()`.
+ *
+ * The request's `model` is the Azure **deployment** name. Pass a deployment id
+ * to target it; the shorthands `'azure'` / `'azure-openai'` resolve to the
+ * configured default `deployment`.
+ *
+ * @example
+ *   import { azureOpenai } from 'agentfootprint/llm-providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: azureOpenai({
+ *       endpoint: process.env.OPENAI_BASE_URL,            // *.openai.azure.com
+ *       apiKey: process.env.AZURE_OPENAI_API_KEY,
+ *       apiVersion: process.env.AZURE_OPENAI_API_VERSION, // 2024-12-01-preview
+ *       deployment: process.env.MODEL_NAME,               // gpt-4o-128k
+ *     }),
+ *     model: 'azure',
+ *   }).build();
+ */
+export declare function azureOpenai(options?: AzureOpenAIProviderOptions): LLMProvider;
+/**
+ * Convenience factory for Ollama (OpenAI-compatible endpoint).
+ *
+ * @example
+ *   import { ollama } from 'agentfootprint/llm-providers';
+ *
+ *   const provider = ollama({ defaultModel: 'llama3.2' });
+ *   // Talks to http://localhost:11434/v1 by default.
+ */
+export declare function ollama(options?: OpenAIProviderOptions & {
+    readonly host?: string;
+}): LLMProvider;
+export {};

package/dist/esm/adapters/llm/createProvider.d.ts

@@ -0,0 +1,85 @@
+/**
+ * createProvider — by-name factory for any built-in LLMProvider.
+ *
+ * Pattern: Abstract Factory (GoF) over the concrete provider factories.
+ * Role:    Convenience entry point. Useful for config-driven setups
+ *          where the provider is chosen at runtime (env var, feature
+ *          flag, tenant preference).
+ * Emits:   N/A.
+ *
+ * @example
+ *   const kind = (process.env.LLM_PROVIDER ?? 'anthropic') as ProviderKind;
+ *   const provider = createProvider({
+ *     kind,
+ *     apiKey: process.env.LLM_API_KEY,
+ *     defaultModel: process.env.LLM_MODEL,
+ *   } as CreateProviderOptions);
+ *
+ * For provider-specific options (Bedrock region, Ollama host, Browser
+ * apiUrl, etc.) construct the underlying factory directly — this
+ * helper deliberately exposes only the common subset.
+ */
+import type { LLMProvider } from '../types.js';
+import { type MockProviderOptions } from './MockProvider.js';
+import { type AnthropicProviderOptions } from './AnthropicProvider.js';
+import { type OpenAIProviderOptions } from './OpenAIProvider.js';
+import { type BedrockProviderOptions } from './BedrockProvider.js';
+import { type BrowserAnthropicProviderOptions } from './BrowserAnthropicProvider.js';
+import { type BrowserOpenAIProviderOptions } from './BrowserOpenAIProvider.js';
+/** Built-in provider kinds. Custom providers don't go through this factory. */
+export type ProviderKind = 'mock' | 'anthropic' | 'openai' | 'ollama' | 'bedrock' | 'browser-anthropic' | 'browser-openai';
+/**
+ * Common subset of options accepted across all built-in providers.
+ * Provider-specific keys (region for Bedrock, host for Ollama,
+ * organization for OpenAI, apiUrl for browser) are passed through
+ * verbatim — TypeScript narrows by `kind`.
+ */
+export type CreateProviderOptions = ({
+    readonly kind: 'mock';
+} & MockProviderOptions) | ({
+    readonly kind: 'anthropic';
+} & AnthropicProviderOptions) | ({
+    readonly kind: 'openai';
+} & OpenAIProviderOptions) | ({
+    readonly kind: 'ollama';
+} & OpenAIProviderOptions & {
+    readonly host?: string;
+}) | ({
+    readonly kind: 'bedrock';
+} & BedrockProviderOptions) | ({
+    readonly kind: 'browser-anthropic';
+} & BrowserAnthropicProviderOptions) | ({
+    readonly kind: 'browser-openai';
+} & BrowserOpenAIProviderOptions);
+/**
+ * Build any built-in LLMProvider from a tagged options object.
+ */
+export declare function createProvider(options: CreateProviderOptions): LLMProvider;
+/** What `providerFromEnv()` resolved: the provider + the `model` to pass to
+ *  `Agent.create({ provider, model })`, and which `kind` was detected. */
+export interface ProviderFromEnv {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly kind: 'azure-openai' | 'anthropic' | 'openai' | 'mock';
+}
+/**
+ * Resolve an `LLMProvider` from environment variables — drop your company's
+ * values in `.env` and the right provider is configured automatically, with no
+ * code branching. (Node only — reads `process.env`; the vendor SDK is lazy-loaded
+ * only for the detected provider.)
+ *
+ * Detection order (first match wins):
+ *   1. **Azure OpenAI** — `AZURE_OPENAI_API_KEY` + (`AZURE_OPENAI_ENDPOINT` |
+ *      `OPENAI_BASE_URL`) [+ `AZURE_OPENAI_API_VERSION`, `AZURE_OPENAI_DEPLOYMENT`|`MODEL_NAME`]
+ *   2. **Anthropic** — `ANTHROPIC_API_KEY`
+ *   3. **OpenAI** — `OPENAI_API_KEY`
+ * Otherwise throws (or returns the mock when `{ fallbackToMock: true }`).
+ *
+ * @example
+ *   import { providerFromEnv } from 'agentfootprint';
+ *   const { provider, model, kind } = providerFromEnv({ fallbackToMock: true });
+ *   const agent = Agent.create({ provider, model }).build();
+ */
+export declare function providerFromEnv(opts?: {
+    readonly fallbackToMock?: boolean;
+}): ProviderFromEnv;

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;
+}