agentfootprint 10.3.1 → 10.4.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../../../../src/adapters/mcp/agentcoreRuntime/invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMnE,iFAAiF;AACjF,MAAM,WAAW,yBAAyB;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnF;AAED,8EAA8E;AAC9E,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,KAAK,MAAM,EAAE;QAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,KAAK,yBAAyB,CAAC;IAChC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACtE;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,gCAAgC,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG;IACpD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,QAAQ,CAAC,yBAAyB,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACrE,CAqBA;AAqCD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,yBAAyB,EACjC,yBAAyB,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,GACzD,aAAa,CA+Bf"}

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

@@ -0,0 +1,50 @@
+/**
+ * safeAnswer — what the MCP client may read of an answer: read ONCE, checked,
+ * and handed on as the canonical form of exactly what was checked.
+ *
+ * ── Why an allow-list ────────────────────────────────────────────────────────
+ * Whatever an answer's body says becomes the MCP client's error text, and a
+ * failed tool call hands that text to the model, the run's history and
+ * `tool_end`. Service text can carry anything the request did: AWS answers a
+ * signature mismatch with the whole signed request (the session token among
+ * it), its validation errors quote the value they refused, a proxy may echo a
+ * header. So a failure is RE-WRITTEN from parts that cannot carry a secret:
+ * the status; the AWS error type when it is a plain name; `Retry-After` when
+ * it is seconds or a date; and for a JSON-RPC error its integer `code`, the
+ * client's own `id`, and its `message` ONLY when it is one of the fixed
+ * sentences the MCP SDK and the AgentCore Runtime contract use
+ * ({@link KNOWN_ERROR_MESSAGES}).
+ *
+ * ── Why one reading ──────────────────────────────────────────────────────────
+ * A check that reads a body one way and a client that reads the same bytes
+ * another is a parser differential: a crafted answer passes the check and is
+ * used as something else. So a 2xx answer is never handed on as its raw bytes.
+ * It is classified by ONE rule (its media type, exactly `application/json` or
+ * `text/event-stream`, UTF-8), decoded strictly, parsed once
+ * (`strictJson.ts` — a duplicated key, trailing data or a byte-order mark is
+ * refused), checked, and RE-SERIALIZED: the client reads the value that was
+ * checked, never the bytes it came from. One message per body or event — a
+ * batch is refused. An answer that cannot be read unambiguously is refused by
+ * name, as a 502 whose text is this library's.
+ *
+ * Pattern: pure functions + one TransformStream. Role: outer ring, the
+ * transport's one rule for what the client reads.
+ */
+/**
+ * JSON-RPC error messages a reply may keep word for word — fixed strings that
+ * carry nothing of the request: the JSON-RPC 2.0 standard errors, the MCP
+ * Streamable HTTP session error, and the AgentCore Runtime MCP contract's
+ * mappings of its exceptions.
+ */
+export declare const KNOWN_ERROR_MESSAGES: ReadonlySet<string>;
+/** Is this answer an authentication or authorization failure? */
+export declare function isAuthFailure(status: number, type: string | undefined): boolean;
+/**
+ * The answer the MCP client may read: a failure rewritten from safe parts; a
+ * 2xx read once and re-serialized; an answer that cannot be read
+ * unambiguously refused (502).
+ */
+export declare function safeAnswer(response: Response): Promise<Response>;
+/** The fixed sentence a failure with no JSON-RPC reply is answered with. */
+export declare function failureSentence(status: number, type: string | undefined): string;
+//# sourceMappingURL=safeAnswer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safeAnswer.d.ts","sourceRoot":"","sources":["../../../../../src/adapters/mcp/agentcoreRuntime/safeAnswer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAanD,CAAC;AAqCH,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAG/E;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAQtE;AAoID,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAYhF"}

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"}