agentfootprint 10.3.0 → 10.4.0

package/dist/types/adapters/mcp/agentcoreRuntime/session.d.ts

@@ -0,0 +1,81 @@
+/**
+ * session — the session strategies: which AgentCore Runtime session a request
+ * lands in.
+ *
+ * ── The facts they rest on ───────────────────────────────────────────────────
+ * From the AgentCore Runtime MCP protocol contract and the `InvokeAgentRuntime`
+ * API reference:
+ *
+ *   - The runtime routes by `Mcp-Session-Id` and always returns one. A client
+ *     "must capture the Mcp-Session-Id returned in the response and include it
+ *     in all subsequent requests" for microVM affinity; without it "each request
+ *     may be routed to a new microVM".
+ *   - `InvokeAgentRuntime` also carries `runtimeSessionId`
+ *     (`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`, 33–256 characters), and
+ *     the AWS SDK models it as an idempotency token — it fills a FRESH random id
+ *     on every call that leaves it unset.
+ *
+ * ── 'per-call' (the default) ─────────────────────────────────────────────────
+ * Every request in a session of its own: this strategy sends a FRESH runtime
+ * session id with every request and no `Mcp-Session-Id`, and the
+ * `Mcp-Session-Id` a response carries is not handed to the MCP client, so
+ * nothing can carry one call's session into the next. Isolation by
+ * construction: a client shared by every user of a process (tools built once at
+ * startup — the common shape) never puts two users in one microVM. The price is
+ * a cold start per call, and it needs a STATELESS server (`stateless_http=True`,
+ * the runtime's recommended default) — a stateful one sees every request as a
+ * stranger.
+ *
+ * ── 'reuse' ──────────────────────────────────────────────────────────────────
+ * One session per CONNECTION (per `mcpClient` built on the transport), and the
+ * TRANSPORT owns the key. A request with no `Mcp-Session-Id` (a client's
+ * `initialize`) opens a connection with a fresh runtime session id; the
+ * `Mcp-Session-Id` the server returns for it is stored WITH that connection,
+ * and the client is handed an opaque handle of the transport's own in its
+ * place. Every later request carrying the handle is sent in that connection's
+ * runtime session with the server's own id; a handle the transport does not
+ * know is answered 404 "Session not found" here, never sent.
+ *
+ * Why a handle and not the server's id: the server's ids are unique only as far
+ * as the server makes them. One that numbers sessions per process hands every
+ * fresh microVM the same first id, and a map keyed by it would send the second
+ * client into the first one's microVM. A handle is ours, random, and per
+ * connection, so two clients on one transport are two sessions whatever the
+ * server returns — while ONE client is still one session for whoever calls
+ * through it. Build a client per conversation; never share a 'reuse' client
+ * between users.
+ *
+ * At most {@link MAX_CONNECTIONS} connections are remembered, least recently
+ * used forgotten first; a client's `DELETE` (its `close()`) forgets its own.
+ *
+ * Pattern: Strategy. Role: outer ring, vendor fact. Holds no credential.
+ */
+/** The runtime session header, as `InvokeAgentRuntime` binds `runtimeSessionId` to it. */
+export declare const AGENTCORE_RUNTIME_SESSION_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id";
+/** The MCP Streamable HTTP session header. */
+export declare const MCP_SESSION_HEADER = "Mcp-Session-Id";
+/** Which session a request lands in. See the module note for each. */
+export type AgentCoreRuntimeSession = 'reuse' | 'per-call';
+/**
+ * What a strategy does with one request: either answer it here, unsent, or
+ * let it go — with its session headers fixed in place — and say what the MCP
+ * client may see of the response.
+ */
+export type SessionStep = {
+    readonly answer: Response;
+} | {
+    readonly settle: (response: Response) => Response;
+};
+/** One strategy, applied once per request the MCP client makes. */
+export interface SessionStrategy {
+    request(headers: Headers, method: string): SessionStep;
+}
+/** How many connections a 'reuse' transport remembers before it forgets the least recently used. */
+export declare const MAX_CONNECTIONS = 256;
+/**
+ * Build the strategy for one transport.
+ *
+ * @throws when `kind` is not one of the two strategies.
+ */
+export declare function sessionStrategy(kind: AgentCoreRuntimeSession): SessionStrategy;
+//# sourceMappingURL=session.d.ts.map

package/dist/types/adapters/mcp/agentcoreRuntime/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../../src/adapters/mcp/agentcoreRuntime/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,0FAA0F;AAC1F,eAAO,MAAM,gCAAgC,gDAAgD,CAAC;AAE9F,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD,sEAAsE;AACtE,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,QAAQ,CAAA;CAAE,CAAC;AAE1D,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;CACxD;AAED,oGAAoG;AACpG,eAAO,MAAM,eAAe,MAAM,CAAC;AAUnC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,GAAG,eAAe,CAQ9E"}

package/dist/types/adapters/mcp/agentcoreRuntime/sessionBusy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * sessionBusy — the retry strategy: AgentCore Runtime's "session operation in
+ * progress", recognised. One small function, on purpose.
+ *
+ * ── What the service says, in its own words ──────────────────────────────────
+ * The AgentCore Runtime MCP protocol contract maps the runtime's exceptions onto
+ * JSON-RPC errors, and exactly one of them is retryable by design:
+ *
+ *   -32005  RetryableConflictException  HTTP 200  "Session operation in progress, please retry"
+ *
+ * returned "when a second operation targets a session while the service is
+ * provisioning or tearing down that session. Because MCP returns HTTP 200 with
+ * the error in the JSON-RPC body, the caller must inspect the response body and
+ * retry with short exponential backoff — MCP clients do not auto-retry it."
+ *
+ * So no status code says it, and the MCP SDK will not wait for it: left alone,
+ * it reaches the model as a failed tool call, a moment after the session it was
+ * waiting for came up.
+ *
+ * ── Why asking again is safe ─────────────────────────────────────────────────
+ * The refusal is the PLATFORM's, about the session, made before the request
+ * reached the MCP server: nothing ran. That is the license a 429 holds, and the
+ * only one `retryingFetchWhen` accepts (see `mcp/throttleRetry.ts` ·
+ * `RetryDecision`).
+ *
+ * ── What it must NOT match ───────────────────────────────────────────────────
+ * `ConflictException` shares the code -32005 ("Resource conflict - Resource
+ * already exists") and is not retryable; the contract tells the two apart only
+ * by the message, so the message is part of the match. Anything else — another
+ * status, an SSE stream, a batch reply, a body that is not JSON — is delivered
+ * as it is.
+ *
+ * ── The API-layer form ───────────────────────────────────────────────────────
+ * `InvokeAgentRuntime`'s API reference gives the same exception as an HTTP 409,
+ * its type in the `x-amzn-errortype` header (the REST protocol's error-type
+ * header; the SigV4 strategy rebuilds exactly that from the SDK's exception,
+ * because the transport's SDK client has its own retry off). It is the same
+ * refusal, so it is the same decision — matched by the type, never by the 409
+ * alone.
+ *
+ * Pattern: Strategy (a `RetryDecision`). Role: outer ring, vendor fact.
+ */
+import type { RetryVerdict } from '../../../mcp/throttleRetry.js';
+/** The JSON-RPC error code the contract gives `RetryableConflictException`. */
+export declare const SESSION_BUSY_CODE = -32005;
+/**
+ * Is this response AgentCore Runtime's session-busy refusal — in either form:
+ * the MCP contract's HTTP 200 with JSON-RPC -32005, or the API's 409
+ * `RetryableConflictException`?
+ *
+ * Reads a CLONE of the body, so the response is delivered intact either way.
+ * Answers `{}` (wait the loop's own backoff, then send the same request again)
+ * or `undefined` (deliver it).
+ */
+export declare function sessionBusy(response: Response): Promise<RetryVerdict | undefined>;
+/**
+ * The match itself, over a parsed body: ONE JSON-RPC reply whose error carries
+ * the contract's code and message. A batch is never retried whole — some of
+ * its replies may be the record of work that ran.
+ */
+export declare function isSessionBusyReply(body: unknown): boolean;
+//# sourceMappingURL=sessionBusy.d.ts.map

package/dist/types/adapters/mcp/agentcoreRuntime/sessionBusy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionBusy.d.ts","sourceRoot":"","sources":["../../../../../src/adapters/mcp/agentcoreRuntime/sessionBusy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGlE,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAYxC;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAsBvF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAQzD"}

package/dist/types/adapters/mcp/agentcoreRuntime/strictJson.d.ts

@@ -0,0 +1,38 @@
+/**
+ * strictJson — ONE reading of a JSON text, with every ambiguity refused.
+ *
+ * `JSON.parse` resolves ambiguity silently: a duplicated key keeps its LAST
+ * value, while another reader may keep the first. A check that reads a body one
+ * way and a consumer that reads it another is a parser differential — a crafted
+ * answer passes the check and is used as something else. So the transport reads
+ * an answer once, here, refusing what two readers could disagree on, and hands
+ * the client the canonical re-serialization of exactly the value it checked.
+ *
+ * Refused, by name: a duplicated object key, trailing data after the value, a
+ * leading byte-order mark, nesting deeper than {@link MAX_DEPTH}, a number
+ * out of range (its re-serialization would be `null`), and anything that is
+ * not RFC 8259 JSON.
+ *
+ * Objects are built with own properties only (a `__proto__` key is data, never
+ * a prototype).
+ *
+ * Pattern: recursive-descent parser. Role: outer ring, the one reader.
+ */
+/** Why a text was refused. */
+export declare class AmbiguousJsonError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** How deep a value may nest. */
+export declare const MAX_DEPTH = 256;
+/** A JSON value, as read. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * The one value `text` holds.
+ *
+ * @throws AmbiguousJsonError when the text is not exactly one unambiguous value.
+ */
+export declare function parseStrictJson(text: string): JsonValue;
+//# sourceMappingURL=strictJson.d.ts.map

package/dist/types/adapters/mcp/agentcoreRuntime/strictJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strictJson.d.ts","sourceRoot":"","sources":["../../../../../src/adapters/mcp/agentcoreRuntime/strictJson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,8BAA8B;AAC9B,qBAAa,kBAAmB,SAAQ,KAAK;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAED,iCAAiC;AACjC,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B,6BAA6B;AAC7B,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,SAAS,EAAE,GACpB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAQvD"}

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

@@ -0,0 +1,177 @@
+/**
+ * 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;
+//# sourceMappingURL=transport.d.ts.map

package/dist/types/adapters/mcp/agentcoreRuntime/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../../src/adapters/mcp/agentcoreRuntime/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACtC,MAAM,aAAa,CAAC;AAErB,OAAO,EAAmB,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAG7E;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,0BAA0B,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAAC;AAEhE,wDAAwD;AACxD,MAAM,WAAW,mCAAmC;IAClD;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;IACrC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAC3C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAC;IACxD;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,gCAAgC,CAAC;CAClD;AAWD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mCAAmC,GAC3C,gBAAgB,CAqBlB;AAED,kFAAkF;AAClF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,MAAM,CAuB/E"}

package/dist/types/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,5 +461,10 @@ 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;
 }
 //# sourceMappingURL=agentcore.d.ts.map