agentfootprint 9.66.0 → 9.68.0

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

@@ -0,0 +1,166 @@
+/**
+ * adapters/hosting/a2aWire — the A2A protocol, as an `HttpWire`.
+ *
+ * ── What this is ─────────────────────────────────────────────────────────────
+ * **A2A** (agent-to-agent) is an open protocol for one agent calling another:
+ * JSON-RPC 2.0 over HTTP, a `message/send` method carrying text parts, a result
+ * carrying artifacts, and a discovery document — the **agent card** — that says
+ * what the agent is and what it can do. It is nobody's product; several
+ * runtimes speak it, so it lives here on its own and the runtimes that host it
+ * configure this rather than reimplement it.
+ *
+ * ── The subset, stated plainly ───────────────────────────────────────────────
+ * One method: `message/send`, text parts only. Deliberately NOT carried:
+ * `message/stream` and the rest of the task lifecycle (`tasks/get`,
+ * `tasks/cancel`, push notifications), non-text parts, and multi-turn task
+ * state. An agent card built here therefore declares `streaming: false` by
+ * default — advertising a capability this wire cannot honour is how a caller
+ * finds out by hanging.
+ *
+ * ── Why it fits `httpHost` without changing it ───────────────────────────────
+ * JSON-RPC's one hard requirement on a reply is that it ECHOES the request's
+ * `id`. That is possible here only because `HttpWire`'s body methods receive
+ * the request that produced them — a seam added for a different protocol
+ * entirely, and the reason this one needed no new machinery.
+ *
+ * @example  A2A on paths of your own choosing
+ *   httpHost({
+ *     name: 'myA2AHost',
+ *     wire: a2aWire({ card: { name: 'triage', description: '…', version: '1.0.0' } }),
+ *     invokePath: '/',
+ *     healthPath: '/health',
+ *   });
+ */
+import { WireRequestRefusal } from '../../hosting/errors.js';
+/** The A2A protocol revision this wire's documents declare. */
+export const A2A_PROTOCOL_VERSION = '0.3.0';
+/** Where the A2A specification puts an agent's discovery document. */
+export const A2A_AGENT_CARD_PATH = '/.well-known/agent-card.json';
+/** The one method this wire carries. */
+export const A2A_SEND_METHOD = 'message/send';
+/**
+ * JSON-RPC's own reserved codes, the two this wire can raise.
+ *
+ * `-32601` is "method not found" and `-32602` is "invalid params" — both from
+ * the JSON-RPC specification rather than from A2A or any runtime, which is why
+ * they are the only numbers this neutral file knows. A runtime's own error
+ * codes belong to that runtime's adapter.
+ */
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+export const JSONRPC_INVALID_PARAMS = -32602;
+export const JSONRPC_INTERNAL_ERROR = -32603;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The request's JSON-RPC id, echoed onto every reply. `null` is legal and distinct from absent. */
+function requestId(facts) {
+    const id = facts?.body.id;
+    return typeof id === 'string' || typeof id === 'number' ? id : null;
+}
+/**
+ * The text of one A2A message — every part concatenated, refusing what is not text.
+ *
+ * A non-text part is refused rather than skipped for the reason every dialect
+ * in this library refuses rather than skips: an answer produced from the parts
+ * that happened to be understood is a wrong answer delivered confidently.
+ */
+export function readA2AMessageText(message) {
+    if (!isRecord(message)) {
+        throw new WireRequestRefusal('invalid_params', 'params.message must be an object', 400);
+    }
+    const parts = message.parts;
+    if (!Array.isArray(parts) || parts.length === 0) {
+        throw new WireRequestRefusal('invalid_params', 'params.message.parts must be a non-empty array', 400);
+    }
+    const text = [];
+    for (const part of parts) {
+        if (!isRecord(part) || part.kind !== 'text' || typeof part.text !== 'string') {
+            const kind = isRecord(part) && typeof part.kind === 'string' ? part.kind : 'unknown';
+            throw new WireRequestRefusal('unsupported_part', `this agent carries text parts only; '${kind}' parts are not supported`, 400);
+        }
+        text.push(part.text);
+    }
+    return text.join('');
+}
+/**
+ * The agent card document, as the protocol prints it.
+ *
+ * Exported on its own because a deployment often has to serve the card from
+ * somewhere this wire does not own — a CDN, a route in a framework, a runtime's
+ * own discovery API — and the document should be built once, here, rather than
+ * hand-copied into each of those places.
+ */
+export function a2aAgentCardDocument(card) {
+    return {
+        name: card.name,
+        description: card.description,
+        version: card.version,
+        ...(card.url !== undefined && { url: card.url }),
+        protocolVersion: A2A_PROTOCOL_VERSION,
+        preferredTransport: 'JSONRPC',
+        capabilities: { streaming: card.streaming === true },
+        defaultInputModes: card.defaultInputModes ?? ['text'],
+        defaultOutputModes: card.defaultOutputModes ?? ['text'],
+        skills: (card.skills ?? []).map((s) => ({
+            id: s.id,
+            name: s.name,
+            description: s.description,
+            tags: s.tags ?? [],
+        })),
+    };
+}
+/** An `HttpWire` speaking A2A's `message/send`. */
+export function a2aWire(options) {
+    const health = options.health ?? { status: 'ok' };
+    const name = options.name ?? 'a2aWire';
+    const codeFor = options.errorCodeFor ?? (() => JSONRPC_INTERNAL_ERROR);
+    const envelope = (facts, body) => ({
+        jsonrpc: '2.0',
+        id: requestId(facts),
+        ...body,
+    });
+    return {
+        readRequest(facts) {
+            const { body } = facts;
+            if (body.jsonrpc !== '2.0') {
+                throw new WireRequestRefusal('invalid_request', `${name}: every request must carry "jsonrpc": "2.0"`, 400);
+            }
+            if (body.method !== A2A_SEND_METHOD) {
+                // Named rather than ignored: a caller using a method this agent does
+                // not implement learns which one it does, instead of receiving an
+                // empty answer to a question that was never asked.
+                throw new WireRequestRefusal('method_not_found', `${name}: only '${A2A_SEND_METHOD}' is implemented; received '${String(body.method)}'`, 404);
+            }
+            const params = isRecord(body.params) ? body.params : undefined;
+            const input = readA2AMessageText(params?.message);
+            if (input.trim() === '') {
+                throw new WireRequestRefusal('invalid_params', `${name}: message text must not be empty`, 400);
+            }
+            // A2A carries no session of its own — the transport hosting it does, and
+            // the runtime adapter reads it from wherever that transport puts it.
+            return { input };
+        },
+        health: () => health,
+        output: (output, facts) => envelope(facts, {
+            result: {
+                artifacts: [
+                    {
+                        artifactId: String(facts?.body.id ?? 'artifact'),
+                        name: 'agent_response',
+                        parts: [{ kind: 'text', text: output }],
+                    },
+                ],
+            },
+        }),
+        chunk: (text) => ({ kind: 'text', text }),
+        failure: (message, code, facts, origin) => envelope(facts, {
+            error: {
+                code: codeFor(code),
+                // A thrown exception's words are the author's note to their own logs.
+                // A refusal this library authored was written to be read.
+                message: origin === 'threw' ? 'The agent could not complete this request.' : message,
+            },
+        }),
+    };
+}
+//# sourceMappingURL=a2aWire.js.map

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

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

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

@@ -0,0 +1,95 @@
+/**
+ * adapters/hosting/agentCoreA2A — an agentfootprint agent as an AWS Bedrock
+ * **AgentCore A2A** server, callable by other agents.
+ *
+ * ── The split, again ─────────────────────────────────────────────────────────
+ * Two different things are needed, and only one is Amazon's:
+ *
+ *   • The **A2A protocol** — JSON-RPC 2.0, `message/send`, artifacts, the agent
+ *     card. An open protocol several runtimes speak, so it lives in
+ *     `a2aWire.ts` with no vendor in it.
+ *   • The **container contract** — port 9000 (not 8080, and not 8000: each
+ *     protocol gets its own), the agent mounted at `/`, `GET /ping` answering
+ *     `{"status":"Healthy"}`, the session id arriving in
+ *     `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`, and a table of JSON-RPC
+ *     error codes that are this runtime's exceptions rather than A2A's. That
+ *     IS Amazon's, and it is what this file supplies.
+ *
+ * ── One deviation you must know about ────────────────────────────────────────
+ * The A2A specification delivers JSON-RPC errors over HTTP 200. **AgentCore
+ * does not** — it returns the real status code (409, 404, …) with the JSON-RPC
+ * error body. That is a fact about the platform in front of your container, so
+ * a CLIENT must parse the error body even on a non-2xx response; see
+ * `agentCoreA2AErrorCode` for the table this host mirrors on the way out.
+ *
+ * ── What is NOT provided ─────────────────────────────────────────────────────
+ * `message/stream` and the task lifecycle. The agent card this host serves
+ * therefore declares `streaming: false` unless you overrule it, because a card
+ * that advertises streaming to a wire that cannot stream is a caller left
+ * waiting. AWS's own sample card says `true`; ours says what is true of ours.
+ *
+ * @example  An agent other agents can call
+ *   import { agentCoreA2AHost, memorySessions, standingAgent } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     sessions: memorySessions(),
+ *     host: agentCoreA2AHost({
+ *       card: { name: 'triage', description: 'Triages SAN alerts.', version: '1.0.0' },
+ *     }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+/// <reference types="node" />
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { type HttpHost } from '../../hosting/httpHost.js';
+import { type A2AAgentCard } from './a2aWire.js';
+/** The port an AgentCore A2A server is expected on — its own, not HTTP's or MCP's. */
+export declare const DEFAULT_AGENTCORE_A2A_PORT = 9000;
+/** A2A mounts the agent at the root. */
+export declare const AGENTCORE_A2A_INVOKE_PATH = "/";
+/** The runtime's health path for every protocol. */
+export declare const AGENTCORE_PING_PATH = "/ping";
+/** Where the platform puts the caller's session. */
+export declare const AGENTCORE_SESSION_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id";
+/**
+ * AgentCore's own JSON-RPC error codes, mapped from this library's refusal codes.
+ *
+ * These numbers are the RUNTIME's exception table, not A2A's: `-32051`
+ * ResourceNotFound, `-32052` Validation, `-32053` Throttling and
+ * ServiceQuotaExceeded, `-32054` Conflict and RetryableConflict, `-32055`
+ * RuntimeClientError, `-32603` anything else. A client reads them to decide
+ * whether to retry — `-32054` with "Session operation in progress" is the one
+ * that must be retried with backoff, and A2A clients do not do that on their
+ * own.
+ *
+ * Exported so a client built against this host can share one table with it
+ * rather than keep a second copy that drifts.
+ */
+export declare function agentCoreA2AErrorCode(code: string | undefined): number;
+export interface AgentCoreA2AHostOptions {
+    /** The agent card other agents read. Required — discovery is not optional in A2A. */
+    readonly card: A2AAgentCard;
+    /** Port to bind. Default {@link DEFAULT_AGENTCORE_A2A_PORT}. Pass `0` in tests. */
+    readonly port?: number;
+    /** Interface to bind. Default `'0.0.0.0'` — a container's door must be reachable. */
+    readonly hostname?: string;
+    /** Ceiling on a request body. Default one mebibyte. */
+    readonly maxBodyBytes?: number;
+    /** A `node:http` server you own. Refused together with `port`/`hostname`. */
+    readonly server?: Server;
+    /**
+     * Answer a path this host does not own. The agent card is served BEFORE this
+     * runs, and everything else falls through to you unchanged — so supplying one
+     * costs you nothing the card was not already going to take.
+     */
+    readonly onUnhandled?: (req: IncomingMessage, res: ServerResponse) => void;
+}
+/**
+ * An {@link HttpHost} serving AgentCore's A2A container contract.
+ *
+ * `httpHost` keeps its own promises — draining, aborting on disconnect, failing
+ * a handler that throws or answers nothing — and this supplies the protocol,
+ * the paths, the port, the session header and the error table.
+ */
+export declare function agentCoreA2AHost(options: AgentCoreA2AHostOptions): HttpHost;

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

@@ -0,0 +1,168 @@
+/**
+ * adapters/hosting/agentCoreA2A — an agentfootprint agent as an AWS Bedrock
+ * **AgentCore A2A** server, callable by other agents.
+ *
+ * ── The split, again ─────────────────────────────────────────────────────────
+ * Two different things are needed, and only one is Amazon's:
+ *
+ *   • The **A2A protocol** — JSON-RPC 2.0, `message/send`, artifacts, the agent
+ *     card. An open protocol several runtimes speak, so it lives in
+ *     `a2aWire.ts` with no vendor in it.
+ *   • The **container contract** — port 9000 (not 8080, and not 8000: each
+ *     protocol gets its own), the agent mounted at `/`, `GET /ping` answering
+ *     `{"status":"Healthy"}`, the session id arriving in
+ *     `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`, and a table of JSON-RPC
+ *     error codes that are this runtime's exceptions rather than A2A's. That
+ *     IS Amazon's, and it is what this file supplies.
+ *
+ * ── One deviation you must know about ────────────────────────────────────────
+ * The A2A specification delivers JSON-RPC errors over HTTP 200. **AgentCore
+ * does not** — it returns the real status code (409, 404, …) with the JSON-RPC
+ * error body. That is a fact about the platform in front of your container, so
+ * a CLIENT must parse the error body even on a non-2xx response; see
+ * `agentCoreA2AErrorCode` for the table this host mirrors on the way out.
+ *
+ * ── What is NOT provided ─────────────────────────────────────────────────────
+ * `message/stream` and the task lifecycle. The agent card this host serves
+ * therefore declares `streaming: false` unless you overrule it, because a card
+ * that advertises streaming to a wire that cannot stream is a caller left
+ * waiting. AWS's own sample card says `true`; ours says what is true of ours.
+ *
+ * @example  An agent other agents can call
+ *   import { agentCoreA2AHost, memorySessions, standingAgent } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     sessions: memorySessions(),
+ *     host: agentCoreA2AHost({
+ *       card: { name: 'triage', description: 'Triages SAN alerts.', version: '1.0.0' },
+ *     }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+import { headerValue, httpHost } from '../../hosting/httpHost.js';
+import { a2aAgentCardDocument, a2aWire, A2A_AGENT_CARD_PATH, } from './a2aWire.js';
+/** The port an AgentCore A2A server is expected on — its own, not HTTP's or MCP's. */
+export const DEFAULT_AGENTCORE_A2A_PORT = 9000;
+/** A2A mounts the agent at the root. */
+export const AGENTCORE_A2A_INVOKE_PATH = '/';
+/** The runtime's health path for every protocol. */
+export const AGENTCORE_PING_PATH = '/ping';
+/** Where the platform puts the caller's session. */
+export const AGENTCORE_SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+/**
+ * AgentCore's own JSON-RPC error codes, mapped from this library's refusal codes.
+ *
+ * These numbers are the RUNTIME's exception table, not A2A's: `-32051`
+ * ResourceNotFound, `-32052` Validation, `-32053` Throttling and
+ * ServiceQuotaExceeded, `-32054` Conflict and RetryableConflict, `-32055`
+ * RuntimeClientError, `-32603` anything else. A client reads them to decide
+ * whether to retry — `-32054` with "Session operation in progress" is the one
+ * that must be retried with backoff, and A2A clients do not do that on their
+ * own.
+ *
+ * Exported so a client built against this host can share one table with it
+ * rather than keep a second copy that drifts.
+ */
+export function agentCoreA2AErrorCode(code) {
+    switch (code) {
+        case 'ERR_SESSION_NOT_FOUND':
+        case 'ERR_ARTIFACT_NOT_FOUND':
+            return -32051;
+        case 'ERR_INVALID_WIRE_OP':
+        case 'ERR_DECISION_REQUIRED':
+        case 'ERR_ARTIFACT_SESSION_REQUIRED':
+        case 'invalid_request':
+        case 'invalid_params':
+        case 'unsupported_part':
+            return -32052;
+        case 'ERR_ADMISSION_REFUSED':
+        case 'ERR_REQUEST_TOO_LARGE':
+            return -32053;
+        case 'ERR_CONCURRENT_RUN':
+        case 'ERR_HOST_CLOSED':
+        case 'ERR_AWAITING_DECISION':
+        case 'ERR_PAUSE_NOT_CARRIED':
+            return -32054;
+        case 'method_not_found':
+            // JSON-RPC's own "method not found" is -32601, but this runtime reports a
+            // route it cannot resolve as ResourceNotFound. The platform's table wins
+            // inside the platform's container.
+            return -32051;
+        default:
+            return -32603;
+    }
+}
+const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+/**
+ * An {@link HttpHost} serving AgentCore's A2A container contract.
+ *
+ * `httpHost` keeps its own promises — draining, aborting on disconnect, failing
+ * a handler that throws or answers nothing — and this supplies the protocol,
+ * the paths, the port, the session header and the error table.
+ */
+export function agentCoreA2AHost(options) {
+    const { server, onUnhandled, hostname, card } = options;
+    const cardDocument = JSON.stringify(a2aAgentCardDocument(card));
+    /** The discovery document, served before anything falls through to the caller. */
+    const serveCard = (req, res) => {
+        const path = (req.url ?? '').split('?')[0];
+        if (req.method === 'GET' && path === A2A_AGENT_CARD_PATH) {
+            res.writeHead(200, {
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(cardDocument),
+            });
+            res.end(cardDocument);
+            return;
+        }
+        // Not the card: the caller's own routes, if they have any. Chaining rather
+        // than consuming the slot — an adapter that took `onUnhandled` for itself
+        // would silently remove a seam the host documents as the consumer's.
+        if (onUnhandled) {
+            onUnhandled(req, res);
+            return;
+        }
+        res.writeHead(404, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: `no route for ${req.method ?? '?'} ${path}` }));
+    };
+    const socket = server
+        ? { server }
+        : {
+            port: options.port ?? DEFAULT_AGENTCORE_A2A_PORT,
+            ...(hostname === undefined ? {} : { hostname }),
+            onUnhandled: serveCard,
+        };
+    const protocol = a2aWire({
+        card,
+        // The runtime's health contract, not A2A's — A2A has no /ping at all.
+        health: { status: 'Healthy' },
+        errorCodeFor: agentCoreA2AErrorCode,
+        name: 'agentCoreA2AHost',
+    });
+    return httpHost({
+        name: 'agentCoreA2AHost',
+        wire: {
+            ...protocol,
+            // The one thing the protocol does not carry and the platform does: which
+            // conversation this call belongs to, in a header of the runtime's own.
+            readRequest(facts) {
+                const base = protocol.readRequest(facts);
+                const sessionId = headerValue(facts, AGENTCORE_SESSION_HEADER);
+                return { ...base, ...(sessionId !== undefined && { sessionId }) };
+            },
+        },
+        invokePath: AGENTCORE_A2A_INVOKE_PATH,
+        healthPath: AGENTCORE_PING_PATH,
+        // NOT `['streaming']`, which is this file's default. `message/send` has
+        // nowhere to put a chunk: a caller gets one JSON-RPC reply and nothing
+        // before it. Declaring streaming anyway would make `requireCapability`
+        // pass for a host that cannot honour it, and would contradict the agent
+        // card, which says `streaming: false` for the same reason. The host
+        // conformance suite catches exactly this — it asserts chunks IF AND ONLY IF
+        // the capability is declared, and it caught it here.
+        capabilities: [],
+        maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+        ...socket,
+    });
+}
+//# sourceMappingURL=agentCoreA2A.js.map

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

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

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

@@ -0,0 +1,143 @@
+/**
+ * adapters/mcp/agentcore — reaching an AWS Bedrock **AgentCore Gateway**.
+ *
+ * ── What lives here, and why it is one file ──────────────────────────────────
+ * A Gateway is an MCP server, and `mcpClient` + `gatewayTransport` already know
+ * how to talk to one of those. Neither knows — and neither should learn — the
+ * handful of facts that are AgentCore's alone: the hostname its endpoints take,
+ * the name of the tool that searches its catalogue, the header that groups a
+ * caller's requests into one policy session, and the service name a SigV4
+ * signature is computed against. Those four facts are this file, and this file
+ * is the only place in the library that holds them.
+ *
+ * `gatewayTransport` says of itself: *"Nothing here is vendor-specific."* That
+ * stays true precisely because this exists next to it.
+ *
+ * ── What it does NOT do ──────────────────────────────────────────────────────
+ * It does not manage a Gateway. Creating one, adding targets, attaching a
+ * policy engine, enabling semantic search — all control-plane operations on
+ * `bedrock-agentcore-control`, all things an operator does once with the
+ * console, the CLI or their IaC. This is the CLIENT side: an agent using a
+ * gateway somebody already stood up.
+ *
+ * @example  An agent whose tools come from a Gateway
+ *   import { mcpClient } from 'agentfootprint/providers';
+ *   import { agentCoreGatewayTransport } from 'agentfootprint/providers';
+ *   import { agentCoreIdentity } from 'agentfootprint/security';
+ *
+ *   const gateway = await mcpClient({
+ *     name: 'gateway',
+ *     transport: agentCoreGatewayTransport({
+ *       gatewayId: 'my-gateway-a1b2c3d4e5',
+ *       region: 'us-east-1',
+ *       credentials: agentCoreIdentity({ region: 'us-east-1' }),
+ *     }),
+ *   });
+ *   const tools = await gateway.tools();
+ */
+import { type FetchLike } from '../../lib/mcp/gatewayTransport.js';
+import type { McpGatewayTransport } from '../../lib/mcp/types.js';
+import type { CredentialProvider } from '../../identity/types.js';
+import type { Tool } from '../../core/tools.js';
+/**
+ * The Gateway's built-in semantic tool search, by its exact wire name.
+ *
+ * It is an ordinary MCP tool — `tools/call` with `{ query }` — that returns the
+ * catalogue entries closest to a natural-language description. It matters at
+ * the scale where listing every tool into a prompt stops being sensible.
+ *
+ * **It can only be enabled when the Gateway is CREATED**, never afterwards, so
+ * its absence from a catalogue is a fact about that gateway rather than a
+ * transient condition to retry.
+ */
+export declare const AGENTCORE_GATEWAY_SEARCH_TOOL = "x_amz_bedrock_agentcore_search";
+/**
+ * The header that groups a caller's requests into ONE policy session.
+ *
+ * AgentCore's temporal policies decide on SEQUENCES of actions — "not after
+ * three refunds", "only once this was approved" — and a sequence needs a
+ * boundary. This header is that boundary, and without it every request is its
+ * own history of one, which quietly makes every sequence rule unenforceable.
+ */
+export declare const AGENTCORE_POLICY_SESSION_HEADER = "x-amzn-bedrock-agentcore-policy-session-id";
+/** The service name a SigV4 signature for a Gateway is computed against. */
+export declare const AGENTCORE_SIGV4_SERVICE = "bedrock-agentcore";
+export interface AgentCoreGatewayUrlOptions {
+    /** The gateway's id, as the console and `CreateGateway`'s response give it. */
+    readonly gatewayId: string;
+    /** The region it lives in, e.g. `'us-east-1'`. */
+    readonly region: string;
+}
+/**
+ * The MCP endpoint of a Gateway.
+ *
+ * `https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/mcp` —
+ * a shape nobody remembers correctly, which is the entire reason it is a
+ * function and not a line in a README.
+ */
+export declare function agentCoreGatewayUrl(options: AgentCoreGatewayUrlOptions): string;
+export interface AgentCoreGatewayTransportOptions extends AgentCoreGatewayUrlOptions {
+    /** Who vends the token. `agentCoreIdentity()` is the usual answer. */
+    readonly credentials: CredentialProvider;
+    /** The downstream service id your provider keys on. Default `'gateway'`. */
+    readonly service?: string;
+    /** OAuth scopes, when the provider uses them. */
+    readonly scopes?: readonly string[];
+    /** `machine` (default) or `user`, for a gateway that acts on someone's behalf. */
+    readonly mode?: 'machine' | 'user';
+    /**
+     * The policy session this caller's requests belong to — a string, or a
+     * function consulted PER REQUEST.
+     *
+     * **Prefer the function on any transport more than one person shares.** A
+     * fixed string on a shared transport merges every caller's action history
+     * into a single policy session, which is not a small mistake: it makes one
+     * person's earlier actions count against another person's rule. Passing
+     * `() => currentSessionId` keeps the boundary where it belongs, and returning
+     * `undefined` sends no header at all.
+     */
+    readonly policySessionId?: string | (() => string | undefined);
+    /** Extra static headers. **No secrets** — these live as long as the transport. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Your own `fetch`, called underneath the per-request vending. */
+    readonly fetch?: FetchLike;
+}
+/**
+ * An MCP transport pointed at an AgentCore Gateway.
+ *
+ * A configuration of {@link gatewayTransport}: the endpoint built from your
+ * gateway's id and region, and — when you name one — the policy session header
+ * stamped on every request. Token vending, the once-and-dropped secrecy rule
+ * and the rotation behaviour are all the neutral transport's, unchanged.
+ */
+export declare function agentCoreGatewayTransport(options: AgentCoreGatewayTransportOptions): McpGatewayTransport;
+/**
+ * The Gateway's semantic search tool, if this gateway has one.
+ *
+ * Returns `undefined` rather than throwing, because absence is a legitimate and
+ * PERMANENT answer: semantic search is enabled when a Gateway is created and
+ * cannot be turned on afterwards, so there is nothing to retry.
+ *
+ * ── Why this finds the tool instead of calling it ────────────────────────────
+ * The obvious convenience would be `search(gateway, 'refund an order')`, and it
+ * is deliberately not here. Executing a tool needs a `ToolExecutionContext` —
+ * the call id, the iteration, the credential seam, the artifact store — and
+ * that object belongs to the agent loop. A helper would have to invent one,
+ * and a call made on an invented context is a call that appears in no trace:
+ * the model would be handed a shortlist nobody can later explain the origin of,
+ * which is the opposite of what this library is for.
+ *
+ * So the search tool is registered like any other tool, the model calls it when
+ * the catalogue is too large to reason about, and that call is an ordinary
+ * tool call in the trace — visible, attributable, and replayable.
+ *
+ * @example  Give the model the catalogue's own search
+ *   const tools = await gateway.tools();
+ *   const search = gatewaySearchTool(tools);
+ *   Agent.create({ provider, model })
+ *     .tools(search ? [search] : tools)   // search it, or list it
+ *     .build();
+ */
+export declare function gatewaySearchTool(tools: readonly Tool[]): Tool | undefined;
+/** Whether this gateway's catalogue can be searched rather than listed. */
+export declare function hasGatewaySearch(tools: readonly Tool[]): boolean;