agentfootprint 7.14.0 → 7.15.0

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

@@ -0,0 +1,199 @@
+/**
+ * adapters/hosting/agentcore — AWS Bedrock **AgentCore Runtime** adapters for
+ * the two hosting ports.
+ *
+ *   import { agentCoreRuntimeHost, agentCoreSessions } from 'agentfootprint/hosting-providers';
+ *   import { standingAgent } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *
+ * ── What this file actually is ───────────────────────────────────────────────
+ * Vendor paths, a header name, and two JSON body shapes. That is the whole
+ * adapter, and it is the claim the hosting ports were designed to make: a
+ * container runtime's contract is a CONFIGURATION of HTTP work that already
+ * exists, not a second implementation of it. Nothing here reaches into the
+ * ports, and nothing here needed the ports to change.
+ *
+ * AgentCore Runtime is a **container contract**: an ARM64 image serving HTTP on
+ * `0.0.0.0:8080` —
+ *
+ *   POST /invocations   JSON `{ "prompt": "..." }` → JSON `{ "response", "status" }`
+ *   GET  /ping          → `{ "status": "Healthy", "time_of_last_update": <unix seconds> }`
+ *
+ * and the caller's conversation arrives in the
+ * `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header rather than in the body,
+ * which is the one thing paths-and-bodies configuration alone could not
+ * express before this release.
+ *
+ * ── Verification status, stated plainly ──────────────────────────────────────
+ * `agentCoreRuntimeHost` is **plain HTTP and is really verified**: it runs the
+ * same host conformance suite as `nodeHost`, over a real socket, in
+ * `test/hosting/host-contract.test.ts`. There is no AWS SDK on its path.
+ *
+ * `agentCoreSessions({ store: 'memory' })` is **contract-mapped and
+ * injection-tested**: its AgentCore Memory calls are exercised through the
+ * `_client` seam, never against AWS. Confirm the command and field names
+ * against your installed `@aws-sdk/client-bedrock-agentcore` before you rely
+ * on it; real-cloud verification lands with a field deployment.
+ *
+ * Pattern: Adapter (GoF). Role: outer ring. The file-backed session store uses
+ * `node:fs` and nothing else; the event-backed one lazy-loads the AWS SDK, so
+ * importing this module costs zero peer-dep load.
+ */
+import type { HttpHost, HttpWire } from '../../hosting/httpHost.js';
+import type { CheckpointEnvelope, SessionLifecycle } from '../../hosting/types.js';
+/** Options for {@link agentCoreRuntimeHost}. */
+export interface AgentCoreRuntimeHostOptions {
+    /**
+     * Port to bind. Default `8080` — the port the container contract specifies.
+     * Pass `0` in tests to take an ephemeral one.
+     */
+    readonly port?: number;
+    /**
+     * Interface to bind. Default `'0.0.0.0'`, which the contract requires: bind
+     * to loopback inside the container and the runtime's health probe cannot
+     * reach you.
+     */
+    readonly hostname?: string;
+    /**
+     * Report `'HealthyBusy'` instead of `'Healthy'` on the health path.
+     *
+     * A function, not a flag, because busy is a live fact about the process, not
+     * a setting: the runtime reads it on every probe to decide whether to send
+     * you more work. Omit it and the host reports `'Healthy'`, which is the
+     * honest answer for an agent that answers synchronously.
+     */
+    readonly busy?: () => boolean;
+}
+/**
+ * The AgentCore Runtime contract as an {@link HttpWire}.
+ *
+ * Exported so the body shapes are inspectable and testable without binding a
+ * socket, and so a deployment that must serve the same bodies from somewhere
+ * else can reuse them by name.
+ */
+export declare function agentCoreRuntimeWire(busy?: () => boolean): HttpWire;
+/**
+ * An `AgentHost` that speaks AgentCore Runtime's container contract.
+ *
+ * Passes the same conformance suite as `nodeHost` — it is the same HTTP host
+ * with this runtime's two paths, its header, and its two body shapes.
+ *
+ * @example  The container's entry point
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+export declare function agentCoreRuntimeHost(options?: AgentCoreRuntimeHostOptions): HttpHost;
+/**
+ * Where {@link agentCoreSessions} keeps a conversation between requests.
+ *
+ *  - `'session-storage'` — a JSON file under the container's own storage. The
+ *    runtime keeps that storage for the life of a session, INCLUDING across a
+ *    stop/resume of the container, so a conversation survives the thing most
+ *    likely to interrupt it. It does not survive the session ending.
+ *  - `'memory'` — one AgentCore Memory event per persist. Outlives the session,
+ *    the container and the deployment; costs an API call per turn and the
+ *    `@aws-sdk/client-bedrock-agentcore` peer dependency.
+ *
+ * Chosen at construction, never per call: a store that silently changed where
+ * it wrote would be a store you cannot reason about after an incident.
+ */
+export type AgentCoreSessionStore = 'session-storage' | 'memory';
+/** The default file the `'session-storage'` mode writes to. */
+export declare const DEFAULT_SESSION_STORAGE_PATH = "/tmp/agentcore-session";
+/** Options for the file-backed mode. */
+export interface AgentCoreFileSessionsOptions {
+    readonly store: 'session-storage';
+    /**
+     * Where to write. Default {@link DEFAULT_SESSION_STORAGE_PATH}. One file
+     * holds every session this container has seen, keyed by session id — the
+     * runtime already gives each session its own storage, so the keying is
+     * belt-and-braces for the case where it does not.
+     */
+    readonly path?: string;
+}
+/** One AgentCore Memory event, as this adapter cares about it. */
+export interface AgentCoreSessionEvent {
+    /** Server-assigned event id. */
+    readonly eventId: string;
+    /** The envelope decoded from the event's blob payload, or `null` when unreadable. */
+    readonly envelope: unknown;
+}
+/**
+ * The minimal AgentCore Memory surface the session store calls. The real SDK is
+ * adapted to this shape in one function below; tests inject a fake via
+ * `_client` and never touch AWS.
+ */
+export interface AgentCoreSessionClientLike {
+    /** Append one envelope as an event (the server assigns the event id). */
+    createEvent(input: {
+        memoryId: string;
+        actorId: string;
+        sessionId: string;
+        envelope: CheckpointEnvelope;
+    }): Promise<void>;
+    /** The session's events, newest first — the adapter reads only the newest. */
+    listEvents(input: {
+        memoryId: string;
+        actorId: string;
+        sessionId: string;
+        maxResults?: number;
+    }): Promise<{
+        events: readonly AgentCoreSessionEvent[];
+    }>;
+}
+/** Options for the event-backed mode. */
+export interface AgentCoreMemorySessionsOptions {
+    readonly store: 'memory';
+    /** AgentCore Memory ARN or id. Required. */
+    readonly memoryId: string;
+    /** AWS region, when the adapter constructs the SDK client itself. */
+    readonly region?: string;
+    /**
+     * The AgentCore `actorId` these conversations belong to. Default
+     * `'afp-standing-agent'`. One actor per deployed agent is the usual shape.
+     */
+    readonly actorId?: string;
+    /** Pre-built client, to share one SDK config across the host app. */
+    readonly client?: AgentCoreSessionClientLike;
+    /** @internal Test injection — skips the SDK require entirely. */
+    readonly _client?: AgentCoreSessionClientLike;
+    /** @internal Test injection — the AWS SDK module, to exercise the real shim with a fake SDK. */
+    readonly _sdk?: BedrockAgentCoreSessionSdkModule;
+}
+/** Options for {@link agentCoreSessions}. */
+export type AgentCoreSessionsOptions = AgentCoreFileSessionsOptions | AgentCoreMemorySessionsOptions;
+/**
+ * A `SessionLifecycle` backed by AgentCore, with the checkpoint's home chosen
+ * at construction.
+ *
+ * Both modes store the SAME `CheckpointEnvelope` the port defines, and both
+ * refuse an unknown `format` by name through the shared `readEnvelope` — a
+ * conversation written by a newer runtime is refused, never half-restored.
+ * That law is inherited, not re-implemented.
+ *
+ * @example  Survive a stop/resume, no AWS SDK required
+ *   agentCoreSessions({ store: 'session-storage' });
+ *
+ * @example  Outlive the session entirely
+ *   agentCoreSessions({ store: 'memory', memoryId: process.env.MEMORY_ID!, region: 'us-west-2' });
+ */
+export declare function agentCoreSessions(options: AgentCoreSessionsOptions): SessionLifecycle;
+/** The slice of `@aws-sdk/client-bedrock-agentcore` this shim touches. */
+export interface BedrockAgentCoreSessionSdkModule {
+    readonly BedrockAgentCoreClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly CreateEventCommand?: new (input: unknown) => unknown;
+    readonly ListEventsCommand?: new (input: unknown) => unknown;
+}

package/dist/esm/adapters/hosting/agentcore.js

@@ -0,0 +1,321 @@
+/**
+ * adapters/hosting/agentcore — AWS Bedrock **AgentCore Runtime** adapters for
+ * the two hosting ports.
+ *
+ *   import { agentCoreRuntimeHost, agentCoreSessions } from 'agentfootprint/hosting-providers';
+ *   import { standingAgent } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *
+ * ── What this file actually is ───────────────────────────────────────────────
+ * Vendor paths, a header name, and two JSON body shapes. That is the whole
+ * adapter, and it is the claim the hosting ports were designed to make: a
+ * container runtime's contract is a CONFIGURATION of HTTP work that already
+ * exists, not a second implementation of it. Nothing here reaches into the
+ * ports, and nothing here needed the ports to change.
+ *
+ * AgentCore Runtime is a **container contract**: an ARM64 image serving HTTP on
+ * `0.0.0.0:8080` —
+ *
+ *   POST /invocations   JSON `{ "prompt": "..." }` → JSON `{ "response", "status" }`
+ *   GET  /ping          → `{ "status": "Healthy", "time_of_last_update": <unix seconds> }`
+ *
+ * and the caller's conversation arrives in the
+ * `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header rather than in the body,
+ * which is the one thing paths-and-bodies configuration alone could not
+ * express before this release.
+ *
+ * ── Verification status, stated plainly ──────────────────────────────────────
+ * `agentCoreRuntimeHost` is **plain HTTP and is really verified**: it runs the
+ * same host conformance suite as `nodeHost`, over a real socket, in
+ * `test/hosting/host-contract.test.ts`. There is no AWS SDK on its path.
+ *
+ * `agentCoreSessions({ store: 'memory' })` is **contract-mapped and
+ * injection-tested**: its AgentCore Memory calls are exercised through the
+ * `_client` seam, never against AWS. Confirm the command and field names
+ * against your installed `@aws-sdk/client-bedrock-agentcore` before you rely
+ * on it; real-cloud verification lands with a field deployment.
+ *
+ * Pattern: Adapter (GoF). Role: outer ring. The file-backed session store uses
+ * `node:fs` and nothing else; the event-backed one lazy-loads the AWS SDK, so
+ * importing this module costs zero peer-dep load.
+ */
+import { readEnvelope } from '../../hosting/envelope.js';
+import { headerValue, httpHost } from '../../hosting/httpHost.js';
+import { lazyRequire } from '../../lib/lazyRequire.js';
+// ─── The runtime host ────────────────────────────────────────────────
+const HOST_NAME = 'agentCoreRuntimeHost';
+/** The runtime's container contract, as constants rather than as scattered literals. */
+const INVOKE_PATH = '/invocations';
+const HEALTH_PATH = '/ping';
+const RUNTIME_PORT = 8080;
+/**
+ * The header the runtime puts the caller's conversation in. Matched
+ * case-insensitively — HTTP header names are case-insensitive and a proxy in
+ * front of the container is free to re-case them.
+ */
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+/**
+ * The AgentCore Runtime contract as an {@link HttpWire}.
+ *
+ * Exported so the body shapes are inspectable and testable without binding a
+ * socket, and so a deployment that must serve the same bodies from somewhere
+ * else can reuse them by name.
+ */
+export function agentCoreRuntimeWire(busy) {
+    return {
+        readRequest(facts) {
+            // `prompt` is the field the runtime's own quickstart and this repo's
+            // deploy template use. `input` is accepted too because the runtime passes
+            // the payload through verbatim — it is the CALLER who picks the field —
+            // and refusing a caller who used the port's own word would be a rule this
+            // adapter invented rather than one the contract imposes.
+            const prompt = facts.body.prompt ?? facts.body.input;
+            const input = typeof prompt === 'string' ? prompt : '';
+            // The conversation id arrives in a header, never in the body. It is
+            // caller-adjacent data, not identity — the port says so and it is just as
+            // true here.
+            const sessionId = headerValue(facts, SESSION_HEADER);
+            return sessionId !== undefined ? { input, sessionId } : { input };
+        },
+        // The runtime polls this to decide whether the container is ready and
+        // whether to send it more work. `time_of_last_update` is unix SECONDS.
+        health: () => ({
+            status: busy?.() === true ? 'HealthyBusy' : 'Healthy',
+            time_of_last_update: Math.floor(Date.now() / 1000),
+        }),
+        output: (response) => ({ response, status: 'success' }),
+        // The message only — never a stack. The runtime surfaces the status code;
+        // the body is read by whoever called the agent.
+        failure: (error, code) => ({ error, status: 'error', ...(code !== undefined && { code }) }),
+        // A distinct field from `response` on purpose: a caller concatenating
+        // stream frames must not be able to double-count the final answer by
+        // reading the same key twice.
+        chunk: (chunk) => ({ chunk }),
+    };
+}
+/**
+ * An `AgentHost` that speaks AgentCore Runtime's container contract.
+ *
+ * Passes the same conformance suite as `nodeHost` — it is the same HTTP host
+ * with this runtime's two paths, its header, and its two body shapes.
+ *
+ * @example  The container's entry point
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+export function agentCoreRuntimeHost(options = {}) {
+    return httpHost({
+        name: HOST_NAME,
+        wire: agentCoreRuntimeWire(options.busy),
+        invokePath: INVOKE_PATH,
+        healthPath: HEALTH_PATH,
+        port: options.port ?? RUNTIME_PORT,
+        hostname: options.hostname ?? '0.0.0.0',
+    });
+}
+/** The default file the `'session-storage'` mode writes to. */
+export const DEFAULT_SESSION_STORAGE_PATH = '/tmp/agentcore-session';
+/**
+ * A `SessionLifecycle` backed by AgentCore, with the checkpoint's home chosen
+ * at construction.
+ *
+ * Both modes store the SAME `CheckpointEnvelope` the port defines, and both
+ * refuse an unknown `format` by name through the shared `readEnvelope` — a
+ * conversation written by a newer runtime is refused, never half-restored.
+ * That law is inherited, not re-implemented.
+ *
+ * @example  Survive a stop/resume, no AWS SDK required
+ *   agentCoreSessions({ store: 'session-storage' });
+ *
+ * @example  Outlive the session entirely
+ *   agentCoreSessions({ store: 'memory', memoryId: process.env.MEMORY_ID!, region: 'us-west-2' });
+ */
+export function agentCoreSessions(options) {
+    return options.store === 'memory' ? memoryEventSessions(options) : fileSessions(options);
+}
+function fileSessions(options) {
+    const path = options.path ?? DEFAULT_SESSION_STORAGE_PATH;
+    async function readFile() {
+        const { readFile: read } = await import('node:fs/promises');
+        let raw;
+        try {
+            raw = await read(path, 'utf8');
+        }
+        catch {
+            // No file yet is the ordinary first-request state, not an error.
+            return { version: 1, sessions: {} };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new TypeError(`[hosting] the session file at '${path}' is not JSON (${err.message}). ` +
+                `Refusing rather than starting every conversation over silently — delete the file ` +
+                `to start fresh, or point 'path' somewhere else.`);
+        }
+        const sessions = parsed?.sessions;
+        return sessions && typeof sessions === 'object'
+            ? { version: 1, sessions: sessions }
+            : { version: 1, sessions: {} };
+    }
+    return {
+        async hydrate(sessionId) {
+            const file = await readFile();
+            const stored = file.sessions[sessionId];
+            if (stored === undefined)
+                return undefined;
+            // Validate HERE as well as in the composer, so a refusal points at the
+            // store that produced the bytes rather than at whoever read them next.
+            readEnvelope(stored);
+            return stored;
+        },
+        async persist(sessionId, envelope) {
+            const { writeFile, rename, mkdir } = await import('node:fs/promises');
+            const { dirname } = await import('node:path');
+            const file = await readFile();
+            const next = {
+                version: 1,
+                sessions: { ...file.sessions, [sessionId]: envelope },
+            };
+            await mkdir(dirname(path), { recursive: true }).catch(() => undefined);
+            // Write-then-rename: a container killed mid-write leaves the previous
+            // conversation intact rather than a truncated file that refuses to parse.
+            const temporary = `${path}.${process.pid}.tmp`;
+            await writeFile(temporary, JSON.stringify(next), 'utf8');
+            await rename(temporary, path);
+        },
+    };
+}
+// ─── 'memory': one AgentCore Memory event per persist ────────────────
+const DEFAULT_ACTOR_ID = 'afp-standing-agent';
+function memoryEventSessions(options) {
+    if (!options.memoryId) {
+        throw new Error(`agentCoreSessions({ store: 'memory' }) requires 'memoryId'.`);
+    }
+    const memoryId = options.memoryId;
+    const actorId = options.actorId ?? DEFAULT_ACTOR_ID;
+    const client = options._client ?? options.client ?? createSessionClient(options.region, options._sdk);
+    return {
+        async hydrate(sessionId) {
+            // AgentCore Memory is an append-only log and lists newest-first, so the
+            // newest readable event IS the conversation. Older ones are the earlier
+            // turns and deliberately left where they are — they are the audit trail.
+            const page = await client.listEvents({
+                memoryId,
+                actorId,
+                sessionId: safeSessionId(sessionId),
+                maxResults: 1,
+            });
+            const newest = page.events[0];
+            if (!newest || newest.envelope === null || newest.envelope === undefined)
+                return undefined;
+            readEnvelope(newest.envelope);
+            return newest.envelope;
+        },
+        async persist(sessionId, envelope) {
+            await client.createEvent({
+                memoryId,
+                actorId,
+                sessionId: safeSessionId(sessionId),
+                envelope,
+            });
+        },
+    };
+}
+const SESSION_ID_MAX = 99;
+/** AgentCore ids accept `[A-Za-z0-9_-]`; a session id is caller data and need not. */
+function safeSessionId(raw) {
+    const slug = raw.replace(/[^A-Za-z0-9_-]/g, '-');
+    if (slug.length <= SESSION_ID_MAX)
+        return slug;
+    // Keep a readable head plus a stable tail so two long ids stay distinct.
+    return `${slug.slice(0, SESSION_ID_MAX - 9)}-${fnv1a(raw)}`;
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+/** Pull the envelope out of an event's `payload` (a single `blob` document). */
+function envelopeFromPayload(payload) {
+    if (!Array.isArray(payload))
+        return null;
+    for (const part of payload) {
+        const blob = part?.blob;
+        if (blob && typeof blob === 'object')
+            return blob;
+    }
+    return null;
+}
+/**
+ * Map {@link AgentCoreSessionClientLike} onto the real SDK commands. If AWS
+ * renames a command, only this function changes — which is also why every test
+ * injects past it.
+ */
+function createSessionClient(region, injected) {
+    let mod;
+    if (injected) {
+        mod = injected;
+    }
+    else {
+        try {
+            mod = lazyRequire('@aws-sdk/client-bedrock-agentcore');
+        }
+        catch {
+            throw new Error(`agentCoreSessions({ store: 'memory' }) requires the ` +
+                '`@aws-sdk/client-bedrock-agentcore` peer dependency.\n' +
+                '  Install:  npm install @aws-sdk/client-bedrock-agentcore\n' +
+                "  Or use { store: 'session-storage' }, which needs no SDK at all.");
+        }
+    }
+    if (!mod.BedrockAgentCoreClient) {
+        throw new Error('agentCoreSessions: `@aws-sdk/client-bedrock-agentcore` is installed but ' +
+            '`BedrockAgentCoreClient` was not found. Update the SDK.');
+    }
+    const sdk = new mod.BedrockAgentCoreClient({ ...(region && { region }) });
+    const send = async (Ctor, name, input) => {
+        if (!Ctor) {
+            throw new Error(`agentCoreSessions: \`@aws-sdk/client-bedrock-agentcore\` is missing ${name}. Upgrade the SDK.`);
+        }
+        return sdk.send(new Ctor(input));
+    };
+    return {
+        async createEvent({ memoryId, actorId, sessionId, envelope }) {
+            await send(mod.CreateEventCommand, 'CreateEventCommand', {
+                memoryId,
+                actorId,
+                sessionId,
+                eventTimestamp: new Date(),
+                payload: [{ blob: envelope }],
+            });
+        },
+        async listEvents({ memoryId, actorId, sessionId, maxResults }) {
+            const result = (await send(mod.ListEventsCommand, 'ListEventsCommand', {
+                memoryId,
+                actorId,
+                sessionId,
+                includePayloads: true,
+                ...(maxResults !== undefined && { maxResults }),
+            }));
+            const events = (result?.events ?? []).map((event) => ({
+                eventId: event.eventId ?? '',
+                envelope: envelopeFromPayload(event.payload),
+            }));
+            return { events };
+        },
+    };
+}
+//# sourceMappingURL=agentcore.js.map

package/dist/esm/adapters/hosting/agentcore.js.map

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

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

@@ -27,14 +27,20 @@
  *     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).
+ *   • `search` → `RetrieveMemoryRecords`, **text-in**. AgentCore embeds and ranks on its
+ *     own side, so it takes a natural-language query; the port's `search()` takes a
+ *     vector. Pass `options.text` and this store serves the query; omit it and it refuses
+ *     by name rather than ranking an empty set. See `search()` below for the whole story.
  *   • `putIfVersion` / `seen` / `feedback` → in-process emulation (AgentCore has no native
  *     CAS / dedup / feedback primitive; these don't survive process restart).
+ *   • no `stream()` — AgentCore Memory has no streaming data-plane operation, and the
+ *     `MemoryStore` port has no streaming method to implement. Inventing one for a single
+ *     backend is how a port stops being a port.
  *
  * 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 { ListOptions, ListResult, MemoryStore, PutIfVersionResult, ScoredEntry, SearchOptions } 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. */
@@ -75,6 +81,35 @@ export interface AgentCoreLikeClient {
         sessionId: string;
         eventId: string;
     }): Promise<void>;
+    /**
+     * Server-side semantic retrieval (`RetrieveMemoryRecords`). Optional: a client
+     * built before this existed still satisfies the interface, and `search()`
+     * feature-detects it rather than assuming.
+     */
+    retrieveRecords?(input: {
+        memoryId: string;
+        namespace: string;
+        searchQuery: string;
+        maxResults?: number;
+        memoryStrategyId?: string;
+    }): Promise<{
+        records: readonly AgentCoreMemoryRecord[];
+    }>;
+}
+/** One record as `RetrieveMemoryRecords` returns it. */
+export interface AgentCoreMemoryRecord {
+    /** AgentCore's own record id. */
+    readonly memoryRecordId: string;
+    /** The record's text content. */
+    readonly content: string;
+    /** Relevance as AgentCore scored it, when it reports one. */
+    readonly score?: number;
+    /** Which strategy produced the record (semantic, summary, user-preference, …). */
+    readonly memoryStrategyId?: string;
+    /** The namespace it was found in. */
+    readonly namespace?: string;
+    /** When AgentCore created it (unix ms), when reported. */
+    readonly createdAt?: number;
 }
 export interface AgentCoreStoreOptions {
     /** AgentCore Memory ARN or id. Required. */
@@ -85,6 +120,27 @@ export interface AgentCoreStoreOptions {
     readonly client?: AgentCoreLikeClient;
     /** Page size for `listEvents`. Default 100. */
     readonly pageSize?: number;
+    /**
+     * Where `search()` looks. AgentCore organises extracted memory records into
+     * namespaces configured on the Memory resource's strategies (commonly
+     * something like `/strategies/{strategyId}/actors/{actorId}`).
+     *
+     * A function, because the namespace usually contains the actor: it is handed
+     * the resolved AgentCore ids for the identity being searched. Default:
+     * `/actors/{actorId}/sessions/{sessionId}` — the session's own records.
+     */
+    readonly searchNamespace?: (scope: {
+        readonly actorId: string;
+        readonly sessionId: string;
+    }) => string;
+    /**
+     * Restrict `search()` to one extraction strategy (semantic, summary,
+     * user-preference…). Omit to search across all of them.
+     *
+     * This is the metadata filter that reaches AgentCore's own side; `tiers` /
+     * `minScore` / `k` from {@link SearchOptions} are applied to what comes back.
+     */
+    readonly searchStrategyId?: string;
     /** @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). */
@@ -100,6 +156,8 @@ export declare class AgentCoreStore implements MemoryStore {
     private readonly client;
     private readonly memoryId;
     private readonly pageSize;
+    private readonly searchNamespace;
+    private readonly searchStrategyId;
     private closed;
     private readonly signatures;
     private readonly feedbackBag;
@@ -130,6 +188,33 @@ export declare class AgentCoreStore implements MemoryStore {
     } | null>;
     /** GDPR "everything for this identity, gone." No DeleteSession on AgentCore → delete every event. */
     forget(identity: MemoryIdentity): Promise<void>;
+    /**
+     * Server-side semantic retrieval over AgentCore's extracted memory records
+     * (`RetrieveMemoryRecords`).
+     *
+     * ── Read this before you call it ─────────────────────────────────────────
+     * **It takes TEXT, not the vector.** AgentCore embeds and ranks on its own
+     * side, so `query` — the port's vector — is unusable here, and the query it
+     * actually needs travels in `options.text`. Omit that and this method throws
+     * a corrective error naming what is missing, because the alternative is
+     * ranking nothing and handing back `[]`, which reads as "no matches" when it
+     * really means "wrong query form". Pass both and every store can serve you:
+     * local-ranking backends use the vector and ignore the text.
+     *
+     * **It searches a DIFFERENT population than `list()`.** `list` returns the
+     * events this store wrote. This returns the records AgentCore's extraction
+     * strategies derived FROM those events — summaries, semantic facts, user
+     * preferences. The ids therefore belong to AgentCore, not to entries you
+     * `put()`, and `store.get(entry.id)` will not find them. They arrive as
+     * entries so ranking code needs no special case, with `metadata.source`
+     * saying plainly where they came from.
+     *
+     * Filters: `searchStrategyId` and the namespace reach AgentCore's own side;
+     * `k`, `minScore` and `tiers` are applied to what comes back.
+     *
+     * @throws when `options.text` is absent, or when the client cannot retrieve.
+     */
+    search<T = unknown>(identity: MemoryIdentity, query: readonly number[], options?: SearchOptions): Promise<readonly ScoredEntry<T>[]>;
     close(): Promise<void>;
     private ensureOpen;
 }
@@ -143,4 +228,5 @@ export interface BedrockAgentCoreSdkModule {
     readonly CreateEventCommand?: new (input: unknown) => unknown;
     readonly ListEventsCommand?: new (input: unknown) => unknown;
     readonly DeleteEventCommand?: new (input: unknown) => unknown;
+    readonly RetrieveMemoryRecordsCommand?: new (input: unknown) => unknown;
 }