agentfootprint 10.3.1 → 10.4.0

package/dist/esm/adapters/mcp/agentcoreRuntime/transport.d.ts

@@ -0,0 +1,176 @@
+/**
+ * agentCoreRuntimeMcpTransport — an MCP server hosted on AWS Bedrock
+ * **AgentCore Runtime**, reached as an ordinary MCP transport.
+ *
+ *   const orders = await mcpClient({
+ *     name: 'orders',
+ *     transport: agentCoreRuntimeMcpTransport({
+ *       agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/orders_mcp-a1b2c3',
+ *       region: 'us-west-2',
+ *     }),
+ *   });
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ * `agentCoreGatewayTransport` reaches a Gateway; `agentCoreRuntimeHost` hosts
+ * OUR agent on Runtime. Neither calls an MCP server somebody deployed TO
+ * Runtime, and that server is not reachable as a plain URL: every request goes
+ * through `InvokeAgentRuntime`, it lands in a runtime SESSION that has to be
+ * carried from call to call, and the platform answers a request that arrives
+ * while that session is still coming up with an HTTP 200 whose body says
+ * "Session operation in progress, please retry" — which no MCP client retries.
+ *
+ * ── What it is: one port, three strategies ───────────────────────────────────
+ * The port is the existing one: this returns an `http` member of
+ * `McpTransport`, so `mcpClient` builds it like any other Streamable HTTP
+ * server and knows nothing about AgentCore. Everything AgentCore-specific sits
+ * in the `fetch` it carries, composed from three choices, one file each:
+ *
+ *   session (`session.ts`)      'per-call' (the default: a session per request),
+ *                               or 'reuse' (one session per MCP client, keyed by
+ *                               a handle the transport issues)
+ *   retry   (`sessionBusy.ts`)  the session-busy refusal, retried with bounded
+ *                               backoff by the SAME loop `mcpClient` uses for a
+ *                               429 (`mcp/throttleRetry.ts` · `retryingFetchWhen`)
+ *   auth    (`invoke.ts`)       'sigv4' through the AWS SDK's InvokeAgentRuntime,
+ *                               or a bearer token over the documented HTTPS
+ *                               endpoint — the SDK has no bearer scheme, and the
+ *                               API reference says an OAuth caller must use HTTPS
+ *
+ * in that order, outermost first: the session is applied once per request, so
+ * every attempt of it lands in the same runtime session, and every attempt is
+ * signed (or vended) afresh, the ordering `mcp/throttleRetry.ts` requires.
+ * What the MCP client reads of a failure is rewritten from the library's own
+ * fixed sentences and safe ids (`safeAnswer.ts`), never the service's text.
+ * `mcpClient`'s own 429 retry still wraps the whole thing.
+ *
+ * ── What it does NOT do ──────────────────────────────────────────────────────
+ * Deploy or manage a runtime (a control-plane job), or host one (that is
+ * `agentCoreRuntimeHost`). This is the CLIENT side of a server somebody already
+ * deployed with `--protocol MCP`.
+ *
+ * Pattern: Facade over three Strategies. Role: outer ring, vendor adapter.
+ */
+import { type FetchLike } from '../../../mcp/gatewayTransport.js';
+import { type ThrottleRetryOptions } from '../../../mcp/throttleRetry.js';
+import type { McpHttpTransport } from '../../../mcp/types.js';
+import type { CredentialProvider } from '../../../identity/types.js';
+import { type AgentCoreRuntimeSdkClient, type BedrockAgentCoreRuntimeSdkModule } from './invoke.js';
+import { type AgentCoreRuntimeSession } from './session.js';
+/**
+ * A bearer token, for a runtime whose inbound auth is OAuth (a JWT authorizer).
+ *
+ * Vended PER REQUEST by the provider — the same once-and-dropped rule as
+ * `gatewayTransport`, through the same code.
+ */
+export interface AgentCoreRuntimeBearerAuth {
+    /** Who vends the token. `agentCoreIdentity()` or any `CredentialProvider`. */
+    readonly bearer: CredentialProvider;
+    /** The downstream service id your provider keys on. Default `'runtime'`. */
+    readonly service?: string;
+    /** OAuth scopes, when the provider uses them. */
+    readonly scopes?: readonly string[];
+    /**
+     * `'machine'` (2-legged), the only mode. `'user'` is refused: the transport
+     * asks for its token without naming any user, so a user-delegated token
+     * would be sent for whoever calls through the client. For a token per user,
+     * build a transport per user whose provider vends that user's token.
+     */
+    readonly mode?: 'machine';
+    /**
+     * Your own `fetch`, called UNDERNEATH the per-request vending — an HTTP
+     * agent, a proxy. It sees the final headers, the vended one included.
+     */
+    readonly fetch?: FetchLike;
+}
+/**
+ * How requests are authenticated — the runtime's inbound auth decides which.
+ *
+ *   - `'sigv4'` — IAM. The AWS SDK signs `InvokeAgentRuntime` with your AWS
+ *     credentials (the default chain, or the `client` you pass).
+ *   - `{ bearer }` — OAuth. A plain HTTPS request with `Authorization: Bearer`,
+ *     because the SDK cannot send a bearer token.
+ */
+export type AgentCoreRuntimeAuth = 'sigv4' | AgentCoreRuntimeBearerAuth;
+/**
+ * The session-busy retry: the same ceilings and the same `onRetry` report as
+ * `mcpClient`'s `retryOnThrottle`, applied to AgentCore's own refusal.
+ */
+export type AgentCoreRuntimeRetryOptions = ThrottleRetryOptions;
+/** Options for {@link agentCoreRuntimeMcpTransport}. */
+export interface AgentCoreRuntimeMcpTransportOptions {
+    /**
+     * The runtime hosting the MCP server — its ARN, as `agentcore deploy` prints
+     * it, or its id together with {@link accountId}.
+     */
+    readonly agentRuntimeArn: string;
+    /** The region it runs in, e.g. `'us-west-2'`. */
+    readonly region: string;
+    /** The endpoint (version) to invoke. The runtime's default endpoint when omitted. */
+    readonly qualifier?: string;
+    /** The owning account — required by AgentCore when `agentRuntimeArn` is an id, not an ARN. */
+    readonly accountId?: string;
+    /** How requests are authenticated. Default `'sigv4'`. */
+    readonly auth?: AgentCoreRuntimeAuth;
+    /**
+     * Which runtime session each request lands in. Default `'per-call'`.
+     *
+     *   - `'per-call'` — every request in a session of its own; nothing carries
+     *     over, so one client can serve every user of a process. Needs a
+     *     stateless server (the runtime's recommended default).
+     *   - `'reuse'` — one session per CLIENT: each `mcpClient` built on this
+     *     transport keeps its own runtime session for its life. **Build one
+     *     client per conversation**: a client shared by two users is one
+     *     session — one microVM, one server state — for both.
+     */
+    readonly session?: AgentCoreRuntimeSession;
+    /**
+     * Retry AgentCore's "session operation in progress" refusal — the MCP
+     * contract's HTTP 200 with JSON-RPC -32005, or the API's 409
+     * `RetryableConflictException`. On by default: up to 5 attempts, never more
+     * than 10 s of waiting in total, jittered exponential backoff. `false` lets
+     * the refusal through on the first attempt.
+     *
+     * Nothing else is retried here: a 429 goes to `mcpClient`'s own throttle
+     * retry, and a 5xx, a dropped connection or any other JSON-RPC error
+     * (throttling's -32003 included) is delivered as it is — it may be the
+     * record of work that ran.
+     */
+    readonly retry?: boolean | AgentCoreRuntimeRetryOptions;
+    /**
+     * SigV4 only: a `BedrockAgentCoreClient` you built, so its credentials,
+     * region and retry settings are the ones used. Refused with `{ bearer }`.
+     *
+     * **Build it with `maxAttempts: 1`.** The client this transport builds has
+     * the SDK's own retry off, because the SDK's standard policy re-sends a call
+     * after a 5xx or a dropped connection — work that may already have run. Your
+     * client keeps whatever policy you gave it.
+     */
+    readonly client?: AgentCoreRuntimeSdkClient;
+    /** @internal Test injection — the AWS SDK module. */
+    readonly _sdk?: BedrockAgentCoreRuntimeSdkModule;
+}
+/**
+ * An MCP transport for a server hosted on AgentCore Runtime.
+ *
+ * @throws when the runtime or region is missing, when a strategy is unknown,
+ *   when `client` is given beside `{ bearer }`, or — for `'sigv4'` — when the
+ *   AWS SDK peer dependency cannot be loaded.
+ */
+export declare function agentCoreRuntimeMcpTransport(options: AgentCoreRuntimeMcpTransportOptions): McpHttpTransport;
+/** Where a runtime's MCP endpoint is, as {@link agentCoreRuntimeUrl} needs it. */
+export interface AgentCoreRuntimeUrlOptions {
+    readonly agentRuntimeArn: string;
+    readonly region: string;
+    readonly qualifier?: string;
+    readonly accountId?: string;
+}
+/**
+ * The HTTPS endpoint of a runtime's MCP server:
+ * `https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{url-encoded ARN}/invocations`,
+ * with `qualifier` / `accountId` as query parameters when given — the request
+ * line of `InvokeAgentRuntime`, and the URL AgentCore's own MCP examples dial.
+ *
+ * @throws when `agentRuntimeArn` or `region` is missing, or the region is not
+ *   shaped like one (it becomes part of a hostname).
+ */
+export declare function agentCoreRuntimeUrl(options: AgentCoreRuntimeUrlOptions): string;

package/dist/esm/adapters/mcp/agentcoreRuntime/transport.js

@@ -0,0 +1,199 @@
+/**
+ * agentCoreRuntimeMcpTransport — an MCP server hosted on AWS Bedrock
+ * **AgentCore Runtime**, reached as an ordinary MCP transport.
+ *
+ *   const orders = await mcpClient({
+ *     name: 'orders',
+ *     transport: agentCoreRuntimeMcpTransport({
+ *       agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/orders_mcp-a1b2c3',
+ *       region: 'us-west-2',
+ *     }),
+ *   });
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ * `agentCoreGatewayTransport` reaches a Gateway; `agentCoreRuntimeHost` hosts
+ * OUR agent on Runtime. Neither calls an MCP server somebody deployed TO
+ * Runtime, and that server is not reachable as a plain URL: every request goes
+ * through `InvokeAgentRuntime`, it lands in a runtime SESSION that has to be
+ * carried from call to call, and the platform answers a request that arrives
+ * while that session is still coming up with an HTTP 200 whose body says
+ * "Session operation in progress, please retry" — which no MCP client retries.
+ *
+ * ── What it is: one port, three strategies ───────────────────────────────────
+ * The port is the existing one: this returns an `http` member of
+ * `McpTransport`, so `mcpClient` builds it like any other Streamable HTTP
+ * server and knows nothing about AgentCore. Everything AgentCore-specific sits
+ * in the `fetch` it carries, composed from three choices, one file each:
+ *
+ *   session (`session.ts`)      'per-call' (the default: a session per request),
+ *                               or 'reuse' (one session per MCP client, keyed by
+ *                               a handle the transport issues)
+ *   retry   (`sessionBusy.ts`)  the session-busy refusal, retried with bounded
+ *                               backoff by the SAME loop `mcpClient` uses for a
+ *                               429 (`mcp/throttleRetry.ts` · `retryingFetchWhen`)
+ *   auth    (`invoke.ts`)       'sigv4' through the AWS SDK's InvokeAgentRuntime,
+ *                               or a bearer token over the documented HTTPS
+ *                               endpoint — the SDK has no bearer scheme, and the
+ *                               API reference says an OAuth caller must use HTTPS
+ *
+ * in that order, outermost first: the session is applied once per request, so
+ * every attempt of it lands in the same runtime session, and every attempt is
+ * signed (or vended) afresh, the ordering `mcp/throttleRetry.ts` requires.
+ * What the MCP client reads of a failure is rewritten from the library's own
+ * fixed sentences and safe ids (`safeAnswer.ts`), never the service's text.
+ * `mcpClient`'s own 429 retry still wraps the whole thing.
+ *
+ * ── What it does NOT do ──────────────────────────────────────────────────────
+ * Deploy or manage a runtime (a control-plane job), or host one (that is
+ * `agentCoreRuntimeHost`). This is the CLIENT side of a server somebody already
+ * deployed with `--protocol MCP`.
+ *
+ * Pattern: Facade over three Strategies. Role: outer ring, vendor adapter.
+ */
+import { createVendingFetch, gatewayTransport, } from '../../../mcp/gatewayTransport.js';
+import { retryingFetchWhen, } from '../../../mcp/throttleRetry.js';
+import { invokeFetch, invokeSdk, } from './invoke.js';
+import { safeAnswer } from './safeAnswer.js';
+import { sessionStrategy } from './session.js';
+import { sessionBusy } from './sessionBusy.js';
+/** The session-busy retry's own ceilings, when the caller set none. */
+const DEFAULT_RETRY = { maxAttempts: 5, maxWaitMs: 10_000 };
+/** What a bearer token is vended for, unless the caller names another service. */
+const DEFAULT_BEARER_SERVICE = 'runtime';
+/** A region is a DNS label run, nothing more — it is spliced into a hostname. */
+const REGION_SHAPE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * An MCP transport for a server hosted on AgentCore Runtime.
+ *
+ * @throws when the runtime or region is missing, when a strategy is unknown,
+ *   when `client` is given beside `{ bearer }`, or — for `'sigv4'` — when the
+ *   AWS SDK peer dependency cannot be loaded.
+ */
+export function agentCoreRuntimeMcpTransport(options) {
+    const url = agentCoreRuntimeUrl(options);
+    const send = authStrategy(options, url);
+    const retried = retryingFetchWhen(send, retryConfig(options.retry), sessionBusy) ?? send;
+    const session = sessionStrategy(options.session ?? 'per-call');
+    // The session is applied ONCE per request the MCP client makes, outside the
+    // retry: every attempt of one request goes to the same runtime session (a
+    // busy refusal is about THAT session coming up), and only the final answer
+    // binds anything.
+    const sessioned = async (input, init) => {
+        const headers = new Headers(init?.headers);
+        const step = session.request(headers, (init?.method ?? 'GET').toUpperCase());
+        if ('answer' in step)
+            return step.answer;
+        const response = await retried(input, { ...init, headers });
+        // What the MCP client may read of a failure is rewritten from safe parts —
+        // ONE rule for both auth paths, after the retry has read the original.
+        return step.settle(await safeAnswer(response));
+    };
+    return { transport: 'http', url, fetch: sessioned };
+}
+/**
+ * The HTTPS endpoint of a runtime's MCP server:
+ * `https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{url-encoded ARN}/invocations`,
+ * with `qualifier` / `accountId` as query parameters when given — the request
+ * line of `InvokeAgentRuntime`, and the URL AgentCore's own MCP examples dial.
+ *
+ * @throws when `agentRuntimeArn` or `region` is missing, or the region is not
+ *   shaped like one (it becomes part of a hostname).
+ */
+export function agentCoreRuntimeUrl(options) {
+    const { agentRuntimeArn, region, qualifier, accountId } = options;
+    if (!agentRuntimeArn || !region) {
+        throw new TypeError('agentCoreRuntimeUrl: both `agentRuntimeArn` and `region` are required — the runtime ' +
+            'is named by the first and reached through the second.');
+    }
+    if (!REGION_SHAPE.test(region)) {
+        throw new TypeError(`agentCoreRuntimeUrl: \`region\` ${JSON.stringify(region)} is not a region name ` +
+            "(lowercase letters, digits and '-', e.g. 'us-west-2'). It becomes part of the " +
+            'hostname, so it is refused rather than spliced in.');
+    }
+    const query = new URLSearchParams();
+    if (qualifier)
+        query.set('qualifier', qualifier);
+    if (accountId)
+        query.set('accountId', accountId);
+    const base = `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/` +
+        `${encodeURIComponent(agentRuntimeArn)}/invocations`;
+    const search = query.toString();
+    return search === '' ? base : `${base}?${search}`;
+}
+// ── The auth strategy ─────────────────────────────────────────────────
+/** The innermost `fetch`: the one that authenticates and sends. */
+function authStrategy(options, url) {
+    const auth = options.auth ?? 'sigv4';
+    if (auth === 'sigv4') {
+        const { client, InvokeAgentRuntimeCommand } = invokeSdk({
+            region: options.region,
+            ...(options.client !== undefined && { client: options.client }),
+            ...(options._sdk !== undefined && { sdk: options._sdk }),
+        });
+        return invokeFetch({
+            agentRuntimeArn: options.agentRuntimeArn,
+            ...(options.qualifier !== undefined && { qualifier: options.qualifier }),
+            ...(options.accountId !== undefined && { accountId: options.accountId }),
+        }, client, InvokeAgentRuntimeCommand);
+    }
+    if (auth !== null && typeof auth === 'object' && auth.bearer !== undefined) {
+        if (typeof auth.bearer.getCredential !== 'function') {
+            throw new TypeError('agentCoreRuntimeMcpTransport: `auth.bearer` must be a CredentialProvider (an object ' +
+                'with getCredential — agentCoreIdentity(), staticTokens(), your own), not the token ' +
+                'itself: a token is vended per request so it can rotate, and is never held here.');
+        }
+        if (options.client !== undefined) {
+            throw new TypeError('agentCoreRuntimeMcpTransport: `client` is the SigV4 strategy’s AWS SDK client, and ' +
+                '`auth: { bearer }` sends no AWS SDK request — the SDK cannot carry a bearer token, ' +
+                'so this path is plain HTTPS. Remove `client`, or use `auth: "sigv4"`.');
+        }
+        if (auth.mode !== undefined && auth.mode !== 'machine') {
+            // The vending request names no user: it carries `service`, `scopes` and
+            // `mode`, never an identity or the user's own token. A user-delegated
+            // token asked for that way belongs to nobody in particular — and would be
+            // sent for whoever calls through the client.
+            throw new TypeError(`agentCoreRuntimeMcpTransport: \`auth.mode\` must be 'machine' — got ${describe(auth.mode)}. ` +
+                'This transport asks its provider for a token without naming any user, so a ' +
+                'user-delegated token would be sent for whoever calls through the client. Leave ' +
+                '`mode` unset for the client credential; for a token per user, build a transport per ' +
+                'user whose `bearer` provider vends that user’s token.');
+        }
+        // The Gateway's vending fetch, reused as is: the token is vended per
+        // request, applied to that one request, and dropped.
+        return createVendingFetch(gatewayTransport({
+            url,
+            credentials: auth.bearer,
+            service: auth.service ?? DEFAULT_BEARER_SERVICE,
+            ...(auth.scopes !== undefined && { scopes: auth.scopes }),
+            ...(auth.mode !== undefined && { mode: auth.mode }),
+        }), auth.fetch);
+    }
+    throw new TypeError(`agentCoreRuntimeMcpTransport: \`auth\` must be 'sigv4' or { bearer: <CredentialProvider> } ` +
+        `— got ${describe(auth)}. Which one is decided by the runtime's inbound auth: IAM is ` +
+        "'sigv4', an OAuth (JWT) authorizer is a bearer token.");
+}
+// ── The retry strategy's configuration ────────────────────────────────
+function retryConfig(retry) {
+    if (retry === false)
+        return false;
+    const given = typeof retry === 'object' && retry !== null ? retry : {};
+    // An explicitly `undefined` field means "not set" — it must fall back to this
+    // transport's default, not erase it (and land on the loop's own default).
+    const set = Object.fromEntries(Object.entries(given).filter(([, v]) => v !== undefined));
+    return { ...DEFAULT_RETRY, ...set };
+}
+/**
+ * A refused value, described by SHAPE — never echoed. A mistyped `auth` can be
+ * the token itself (`auth: process.env.RUNTIME_TOKEN`), and an error message is
+ * the last place it should land.
+ */
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `a string of ${value.length} characters`;
+    if (typeof value === 'object')
+        return `an object with keys [${Object.keys(value).join(', ')}]`;
+    return typeof value;
+}
+//# sourceMappingURL=transport.js.map

package/dist/esm/adapters/mcp/agentcoreRuntime/transport.js.map

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

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

@@ -22,6 +22,8 @@
  * "delete the whole session" call. This shapes the adapter:
  *
  *   • `put`  → `CreateEvent` (append; `actorId` + `eventTimestamp` are required).  O(1)
+ *     Its write options become CreateEvent's own fields: `extraction: 'skip'` →
+ *     `extractionMode: 'SKIP'`, `namespaceScope` → `extractionConfig.namespaceVariables`.
  *   • `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
@@ -43,6 +45,35 @@
 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';
+import { type MemoryWriteOptionName, type MemoryWriteOptions } from '../../memory/store/writeOptions.js';
+/**
+ * A caller's value — a tenant id — in the alphabet AgentCore admits for a
+ * namespace variable, ONE-TO-ONE.
+ *
+ * The alphabet is narrow (`[a-z0-9][a-z0-9-_]*`, at most 64 characters), so the
+ * easy mappings fold: lowercasing merges `Acme` with `acme`, stripping merges
+ * `a.b` with `ab`, truncating merges any two long ids that share a prefix — and
+ * a fold here files two tenants' derived records under one namespace. This is
+ * the same law as the actor and session ids above, in this alphabet:
+ *
+ *   - `[a-z0-9-]` passes through; every other UTF-16 code unit becomes `_`
+ *     plus its four lowercase hex digits (fixed width, so it decodes);
+ *   - every value starts with `v`, so one whose first character had to be
+ *     escaped still starts with a letter — and no two inputs share an output;
+ *   - every value ENDS with `_z`, which cannot occur inside an encoding (an
+ *     `_` there is always followed by four hex digits) — so no tenant's value
+ *     is the beginning of another's (`1` and `12` would otherwise be `v1` and
+ *     `v12`), and a prefix match over namespaces cannot reach a neighbour;
+ *   - too long is REFUSED, never truncated.
+ *
+ * `agentCoreNamespaceValue('acme')` is `'vacme_z'`; `'Acme'` is `'v_0041cme_z'`.
+ * Use the same mapping wherever the namespace is read back (`searchNamespace`).
+ *
+ * @throws {TypeError} for an empty value — an absent tenant is not a tenant
+ * @throws {RangeError} when the encoding exceeds 64 characters (the value is
+ *   not quoted: it names a tenant)
+ */
+export declare function agentCoreNamespaceValue(raw: string): string;
 /** 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). */
@@ -114,12 +145,35 @@ export declare class UnreadableMemoryEntryError extends TypeError {
  * `DeleteEvent`; tests inject a mock via `_client`.
  */
 export interface AgentCoreLikeClient {
+    /**
+     * `true` when {@link createEvent} forwards `extractionMode` and
+     * `extractionConfig` to `CreateEvent` unchanged. The built-in client does.
+     *
+     * Declared, not assumed: a client written before these fields existed
+     * compiles against the wider input and drops them, and a dropped
+     * `extractionMode: 'SKIP'` sends a turn the caller kept out of long-term
+     * memory INTO extraction. Without this, `AgentCoreStore` honours no write
+     * options and refuses them by name.
+     */
+    readonly forwardsWriteOptions?: true;
     /** Append one entry as an event (server assigns the eventId). */
     createEvent(input: {
         memoryId: string;
         actorId: string;
         sessionId: string;
         entry: MemoryEntry;
+        /**
+         * `CreateEvent`'s own field (`ExtractionMode.SKIP`): store the event in
+         * short-term memory, exclude it from long-term extraction.
+         */
+        extractionMode?: 'SKIP';
+        /**
+         * `CreateEvent`'s own field: `namespaceVariables` are substituted into the
+         * memory's `namespaceTemplates` during long-term extraction.
+         */
+        extractionConfig?: {
+            readonly namespaceVariables: Readonly<Record<string, string>>;
+        };
     }): Promise<void>;
     /** One page of the session's events (newest-first is AgentCore's default). */
     listEvents(input: {
@@ -164,8 +218,14 @@ export interface AgentCoreMemoryRecord {
     readonly score?: number;
     /** Which strategy produced the record (semantic, summary, user-preference, …). */
     readonly memoryStrategyId?: string;
-    /** The namespace it was found in. */
+    /** The namespace it was found in — the first of {@link namespaces}. */
     readonly namespace?: string;
+    /**
+     * Every namespace the record is filed under, as `RetrieveMemoryRecords`
+     * reports them (`MemoryRecordSummary.namespaces`). `search()` keeps a record
+     * only when one of these is the namespace it asked for, or lies under it.
+     */
+    readonly namespaces?: readonly string[];
     /** When AgentCore created it (unix ms), when reported. */
     readonly createdAt?: number;
 }
@@ -184,12 +244,21 @@ export interface AgentCoreStoreOptions {
      * 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.
+     * the resolved AgentCore ids for the identity being searched, the identity
+     * itself, and — when the memory binds one (`writeOptions.namespaceScope`) —
+     * the SAME namespace scope its writes are filed under, resolved for this
+     * identity. Build the namespace from that scope
+     * (`({ namespaceScope }) => '/tenants/' + namespaceScope?.tenantid + '/facts'`):
+     * a search given a scope is refused unless every one of its values is a
+     * path segment of the namespace, so a read cannot leave the tenant its
+     * writes were filed under. Default: `/actors/{actorId}/sessions/{sessionId}`
+     * — the session's own records.
      */
     readonly searchNamespace?: (scope: {
         readonly actorId: string;
         readonly sessionId: string;
+        readonly identity: MemoryIdentity;
+        readonly namespaceScope?: Readonly<Record<string, string>>;
     }) => string;
     /**
      * Restrict `search()` to one extraction strategy (semantic, summary,
@@ -199,6 +268,27 @@ export interface AgentCoreStoreOptions {
      * `minScore` / `k` from {@link SearchOptions} are applied to what comes back.
      */
     readonly searchStrategyId?: string;
+    /**
+     * Refuse, by name, every write and search that carries no `namespaceScope`.
+     *
+     * Set it on a store whose every memory is scoped — a multi-tenant
+     * deployment. A memory, a `defineRAG` or a direct call that forgot its scope
+     * is then refused, instead of filing or reading under a namespace no tenant
+     * owns (a template with an empty variable). Default `false`.
+     */
+    readonly requireNamespaceScope?: boolean;
+    /**
+     * Let a search read the records derived from EVERY principal of a tenant.
+     *
+     * Off by default: a search for an identity that names a principal is refused
+     * unless its namespace holds that identity's `actorId` as path segments —
+     * a namespace that stops at the tenant serves one person's extracted facts,
+     * preferences and summaries to another. Set it only when the memory's
+     * strategies file per tenant ON PURPOSE (knowledge the whole tenant shares).
+     * It applies to SCOPED searches only: a search with no scope has no tenant to
+     * stay inside, so it must always hold the actor.
+     */
+    readonly searchAcrossPrincipals?: boolean;
     /** @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). */
@@ -245,11 +335,45 @@ export declare class AgentCoreStore implements MemoryStore {
      * anything.
      */
     readonly ranksBy: "server-text";
+    /**
+     * **Both write options, translated to `CreateEvent`'s own fields:**
+     *
+     *   `extraction: 'skip'`   → `extractionMode: 'SKIP'` — the event stays in
+     *                            short-term memory and is excluded from
+     *                            long-term extraction.
+     *   `namespaceScope`       → `extractionConfig: { namespaceVariables }` —
+     *                            substituted into the memory's
+     *                            `namespaceTemplates` during extraction, which
+     *                            is how one tenant's derived records stay in
+     *                            that tenant's namespace.
+     *
+     * Absent — and both refused by name — when they could not reach AgentCore:
+     * an injected client that does not declare `forwardsWriteOptions`, or an
+     * installed SDK too old to MODEL the two fields (its serializer would drop
+     * them without a word). The variables are checked here against AgentCore's
+     * documented domain before anything is sent (see `checkNamespaceVariables`).
+     *
+     * A getter, not a field: a wrapper built by spreading this store
+     * (`{ ...store, put }`) does not copy it — and a wrapper that does not carry
+     * the third argument must not carry the declaration either.
+     */
+    get writeOptions(): readonly MemoryWriteOptionName[] | undefined;
     private readonly client;
     private readonly memoryId;
     private readonly pageSize;
     private readonly searchNamespace;
     private readonly searchStrategyId;
+    private readonly requireNamespaceScope;
+    /**
+     * Set by the first write or search that carries a scope: from then on this
+     * store is a SCOPED store, and a call without one is refused — a second
+     * memory, a `defineRAG` or a direct call that forgot its scope never reads
+     * or files across the tenants the first one kept apart.
+     */
+    private servedScoped;
+    private readonly searchAcrossPrincipals;
+    /** Why the write options cannot be honoured — `undefined` when they can. */
+    private readonly writeOptionsRefusal;
     private closed;
     private readonly signatures;
     private readonly feedbackBag;
@@ -262,13 +386,28 @@ export declare class AgentCoreStore implements MemoryStore {
     /** 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>;
+    put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, options?: MemoryWriteOptions): Promise<void>;
+    /** One event, with the write options already turned into fields (and checked) once. */
+    private createEvent;
+    putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[], options?: MemoryWriteOptions): 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>;
+    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number, options?: MemoryWriteOptions): Promise<PutIfVersionResult>;
+    /**
+     * The namespace one search reads — rendered by `searchNamespace` and refused
+     * by name when it could read beyond this identity: a wildcard, a namespace
+     * that does not hold the scope segment for segment, or one that stops above
+     * this identity's actor while the identity names a principal.
+     */
+    private namespaceFor;
+    /**
+     * The write options as `CreateEvent`'s own fields — or a refusal by name for
+     * any this store's client cannot carry. The ONE place the vendor-neutral
+     * names become AWS's.
+     */
+    private extractionFields;
     list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
     delete(identity: MemoryIdentity, id: string): Promise<void>;
     seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
@@ -299,7 +438,8 @@ export declare class AgentCoreStore implements MemoryStore {
      * 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.
+     * saying plainly where they came from, and each value is `{ content }` —
+     * the record's text where every memory formatter reads it.
      *
      * Filters: `searchStrategyId` and the namespace reach AgentCore's own side;
      * `k`, `minScore` and `tiers` are applied to what comes back.
@@ -321,4 +461,9 @@ export interface BedrockAgentCoreSdkModule {
     readonly ListEventsCommand?: new (input: unknown) => unknown;
     readonly DeleteEventCommand?: new (input: unknown) => unknown;
     readonly RetrieveMemoryRecordsCommand?: new (input: unknown) => unknown;
+    /**
+     * The SDK's own schema of `CreateEventInput` — read only to learn whether this
+     * SDK MODELS the extraction fields (see `sdkModelsExtraction`).
+     */
+    readonly CreateEventInput$?: unknown;
 }