agentfootprint 9.66.0 → 9.68.0

package/dist/adapters/hosting/a2aWire.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * 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',
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.a2aWire = exports.a2aAgentCardDocument = exports.readA2AMessageText = exports.JSONRPC_INTERNAL_ERROR = exports.JSONRPC_INVALID_PARAMS = exports.JSONRPC_METHOD_NOT_FOUND = exports.A2A_SEND_METHOD = exports.A2A_AGENT_CARD_PATH = exports.A2A_PROTOCOL_VERSION = void 0;
+const errors_js_1 = require("../../hosting/errors.js");
+/** The A2A protocol revision this wire's documents declare. */
+exports.A2A_PROTOCOL_VERSION = '0.3.0';
+/** Where the A2A specification puts an agent's discovery document. */
+exports.A2A_AGENT_CARD_PATH = '/.well-known/agent-card.json';
+/** The one method this wire carries. */
+exports.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.
+ */
+exports.JSONRPC_METHOD_NOT_FOUND = -32601;
+exports.JSONRPC_INVALID_PARAMS = -32602;
+exports.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.
+ */
+function readA2AMessageText(message) {
+    if (!isRecord(message)) {
+        throw new errors_js_1.WireRequestRefusal('invalid_params', 'params.message must be an object', 400);
+    }
+    const parts = message.parts;
+    if (!Array.isArray(parts) || parts.length === 0) {
+        throw new errors_js_1.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 errors_js_1.WireRequestRefusal('unsupported_part', `this agent carries text parts only; '${kind}' parts are not supported`, 400);
+        }
+        text.push(part.text);
+    }
+    return text.join('');
+}
+exports.readA2AMessageText = readA2AMessageText;
+/**
+ * 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.
+ */
+function a2aAgentCardDocument(card) {
+    return {
+        name: card.name,
+        description: card.description,
+        version: card.version,
+        ...(card.url !== undefined && { url: card.url }),
+        protocolVersion: exports.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 ?? [],
+        })),
+    };
+}
+exports.a2aAgentCardDocument = a2aAgentCardDocument;
+/** An `HttpWire` speaking A2A's `message/send`. */
+function a2aWire(options) {
+    const health = options.health ?? { status: 'ok' };
+    const name = options.name ?? 'a2aWire';
+    const codeFor = options.errorCodeFor ?? (() => exports.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 errors_js_1.WireRequestRefusal('invalid_request', `${name}: every request must carry "jsonrpc": "2.0"`, 400);
+            }
+            if (body.method !== exports.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 errors_js_1.WireRequestRefusal('method_not_found', `${name}: only '${exports.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 errors_js_1.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,
+            },
+        }),
+    };
+}
+exports.a2aWire = a2aWire;
+//# sourceMappingURL=a2aWire.js.map

package/dist/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/adapters/hosting/agentCoreA2A.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * 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());
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentCoreA2AHost = exports.agentCoreA2AErrorCode = exports.AGENTCORE_SESSION_HEADER = exports.AGENTCORE_PING_PATH = exports.AGENTCORE_A2A_INVOKE_PATH = exports.DEFAULT_AGENTCORE_A2A_PORT = void 0;
+const httpHost_js_1 = require("../../hosting/httpHost.js");
+const a2aWire_js_1 = require("./a2aWire.js");
+/** The port an AgentCore A2A server is expected on — its own, not HTTP's or MCP's. */
+exports.DEFAULT_AGENTCORE_A2A_PORT = 9000;
+/** A2A mounts the agent at the root. */
+exports.AGENTCORE_A2A_INVOKE_PATH = '/';
+/** The runtime's health path for every protocol. */
+exports.AGENTCORE_PING_PATH = '/ping';
+/** Where the platform puts the caller's session. */
+exports.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.
+ */
+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;
+    }
+}
+exports.agentCoreA2AErrorCode = agentCoreA2AErrorCode;
+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.
+ */
+function agentCoreA2AHost(options) {
+    const { server, onUnhandled, hostname, card } = options;
+    const cardDocument = JSON.stringify((0, a2aWire_js_1.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 === a2aWire_js_1.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 ?? exports.DEFAULT_AGENTCORE_A2A_PORT,
+            ...(hostname === undefined ? {} : { hostname }),
+            onUnhandled: serveCard,
+        };
+    const protocol = (0, a2aWire_js_1.a2aWire)({
+        card,
+        // The runtime's health contract, not A2A's — A2A has no /ping at all.
+        health: { status: 'Healthy' },
+        errorCodeFor: agentCoreA2AErrorCode,
+        name: 'agentCoreA2AHost',
+    });
+    return (0, httpHost_js_1.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 = (0, httpHost_js_1.headerValue)(facts, exports.AGENTCORE_SESSION_HEADER);
+                return { ...base, ...(sessionId !== undefined && { sessionId }) };
+            },
+        },
+        invokePath: exports.AGENTCORE_A2A_INVOKE_PATH,
+        healthPath: exports.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,
+    });
+}
+exports.agentCoreA2AHost = agentCoreA2AHost;
+//# sourceMappingURL=agentCoreA2A.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agentCoreA2A.js","sourceRoot":"","sources":["../../../src/adapters/hosting/agentCoreA2A.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;;;AAIH,2DAAiF;AACjF,6CAKsB;AAEtB,sFAAsF;AACzE,QAAA,0BAA0B,GAAG,IAAI,CAAC;AAE/C,wCAAwC;AAC3B,QAAA,yBAAyB,GAAG,GAAG,CAAC;AAE7C,oDAAoD;AACvC,QAAA,mBAAmB,GAAG,OAAO,CAAC;AAE3C,oDAAoD;AACvC,QAAA,wBAAwB,GAAG,6CAA6C,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,SAAgB,qBAAqB,CAAC,IAAwB;IAC5D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,uBAAuB,CAAC;QAC7B,KAAK,wBAAwB;YAC3B,OAAO,CAAC,KAAK,CAAC;QAChB,KAAK,qBAAqB,CAAC;QAC3B,KAAK,uBAAuB,CAAC;QAC7B,KAAK,+BAA+B,CAAC;QACrC,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,kBAAkB;YACrB,OAAO,CAAC,KAAK,CAAC;QAChB,KAAK,uBAAuB,CAAC;QAC7B,KAAK,uBAAuB;YAC1B,OAAO,CAAC,KAAK,CAAC;QAChB,KAAK,oBAAoB,CAAC;QAC1B,KAAK,iBAAiB,CAAC;QACvB,KAAK,uBAAuB,CAAC;QAC7B,KAAK,uBAAuB;YAC1B,OAAO,CAAC,KAAK,CAAC;QAChB,KAAK,kBAAkB;YACrB,0EAA0E;YAC1E,yEAAyE;YACzE,mCAAmC;YACnC,OAAO,CAAC,KAAK,CAAC;QAChB;YACE,OAAO,CAAC,KAAK,CAAC;IAClB,CAAC;AACH,CAAC;AA5BD,sDA4BC;AAqBD,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAEzC;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,OAAgC;IAC/D,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAA,iCAAoB,EAAC,IAAI,CAAC,CAAC,CAAC;IAEhE,kFAAkF;IAClF,MAAM,SAAS,GAAG,CAAC,GAAoB,EAAE,GAAmB,EAAQ,EAAE;QACpE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,IAAI,KAAK,gCAAmB,EAAE,CAAC;YACzD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;gBACjB,cAAc,EAAE,kBAAkB;gBAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC;aAClD,CAAC,CAAC;YACH,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,2EAA2E;QAC3E,0EAA0E;QAC1E,qEAAqE;QACrE,IAAI,WAAW,EAAE,CAAC;YAChB,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,gBAAgB,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,MAAM;QACnB,CAAC,CAAC,EAAE,MAAM,EAAE;QACZ,CAAC,CAAC;YACE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,kCAA0B;YAChD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;YAC/C,WAAW,EAAE,SAAS;SACvB,CAAC;IAEN,MAAM,QAAQ,GAAG,IAAA,oBAAO,EAAC;QACvB,IAAI;QACJ,sEAAsE;QACtE,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE;QAC7B,YAAY,EAAE,qBAAqB;QACnC,IAAI,EAAE,kBAAkB;KACzB,CAAC,CAAC;IAEH,OAAO,IAAA,sBAAQ,EAAC;QACd,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE;YACJ,GAAG,QAAQ;YACX,yEAAyE;YACzE,uEAAuE;YACvE,WAAW,CAAC,KAAK;gBACf,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBACzC,MAAM,SAAS,GAAG,IAAA,yBAAW,EAAC,KAAK,EAAE,gCAAwB,CAAC,CAAC;gBAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;YACpE,CAAC;SACF;QACD,UAAU,EAAE,iCAAyB;QACrC,UAAU,EAAE,2BAAmB;QAC/B,wEAAwE;QACxE,uEAAuE;QACvE,uEAAuE;QACvE,wEAAwE;QACxE,oEAAoE;QACpE,4EAA4E;QAC5E,qDAAqD;QACrD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,sBAAsB;QAC5D,GAAG,MAAM;KACV,CAAC,CAAC;AACL,CAAC;AAnED,4CAmEC"}

package/dist/adapters/mcp/agentcore.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * 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();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasGatewaySearch = exports.gatewaySearchTool = exports.agentCoreGatewayTransport = exports.agentCoreGatewayUrl = exports.AGENTCORE_SIGV4_SERVICE = exports.AGENTCORE_POLICY_SESSION_HEADER = exports.AGENTCORE_GATEWAY_SEARCH_TOOL = void 0;
+const gatewayTransport_js_1 = require("../../lib/mcp/gatewayTransport.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.
+ */
+exports.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.
+ */
+exports.AGENTCORE_POLICY_SESSION_HEADER = 'x-amzn-bedrock-agentcore-policy-session-id';
+/** The service name a SigV4 signature for a Gateway is computed against. */
+exports.AGENTCORE_SIGV4_SERVICE = 'bedrock-agentcore';
+/**
+ * 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.
+ */
+function agentCoreGatewayUrl(options) {
+    const { gatewayId, region } = options;
+    if (!gatewayId || !region) {
+        throw new TypeError('agentCoreGatewayUrl: both `gatewayId` and `region` are required — the endpoint hostname ' +
+            'is built from the two.');
+    }
+    return `https://${gatewayId}.gateway.bedrock-agentcore.${region}.amazonaws.com/mcp`;
+}
+exports.agentCoreGatewayUrl = agentCoreGatewayUrl;
+/**
+ * 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.
+ */
+function agentCoreGatewayTransport(options) {
+    const { policySessionId, fetch: innerFetch } = options;
+    // The header is stamped in the `fetch` seam rather than in `headers` because
+    // the seam runs per request. That is what lets the session id come from a
+    // function, which is what keeps two people on one transport in two sessions.
+    const stampPolicySession = policySessionId === undefined
+        ? innerFetch
+        : async (input, init) => {
+            const id = typeof policySessionId === 'function' ? policySessionId() : policySessionId;
+            const next = id === undefined || id === ''
+                ? init
+                : {
+                    ...init,
+                    headers: {
+                        ...init?.headers,
+                        [exports.AGENTCORE_POLICY_SESSION_HEADER]: id,
+                    },
+                };
+            return innerFetch ? innerFetch(input, next) : globalThis.fetch(input, next);
+        };
+    return (0, gatewayTransport_js_1.gatewayTransport)({
+        url: agentCoreGatewayUrl(options),
+        credentials: options.credentials,
+        ...(options.service !== undefined && { service: options.service }),
+        ...(options.scopes !== undefined && { scopes: options.scopes }),
+        ...(options.mode !== undefined && { mode: options.mode }),
+        ...(options.headers !== undefined && { headers: options.headers }),
+        ...(stampPolicySession !== undefined && { fetch: stampPolicySession }),
+    });
+}
+exports.agentCoreGatewayTransport = agentCoreGatewayTransport;
+/**
+ * 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();
+ */
+function gatewaySearchTool(tools) {
+    return tools.find((t) => t.schema.name === exports.AGENTCORE_GATEWAY_SEARCH_TOOL);
+}
+exports.gatewaySearchTool = gatewaySearchTool;
+/** Whether this gateway's catalogue can be searched rather than listed. */
+function hasGatewaySearch(tools) {
+    return gatewaySearchTool(tools) !== undefined;
+}
+exports.hasGatewaySearch = hasGatewaySearch;
+//# sourceMappingURL=agentcore.js.map

package/dist/adapters/mcp/agentcore.js.map

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

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

@@ -0,0 +1,110 @@
+/**
+ * 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 type { HttpWire } from '../../hosting/httpHost.js';
+/** The A2A protocol revision this wire's documents declare. */
+export declare const A2A_PROTOCOL_VERSION = "0.3.0";
+/** Where the A2A specification puts an agent's discovery document. */
+export declare const A2A_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+/** The one method this wire carries. */
+export declare 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 declare const JSONRPC_METHOD_NOT_FOUND = -32601;
+export declare const JSONRPC_INVALID_PARAMS = -32602;
+export declare const JSONRPC_INTERNAL_ERROR = -32603;
+/** One skill an agent card advertises. */
+export interface A2ASkill {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly tags?: readonly string[];
+}
+/** The agent card this wire serves — what another agent reads to decide to call yours. */
+export interface A2AAgentCard {
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    /** Where callers reach this agent. A runtime that mounts the agent behind its
+     *  own URL fills this in; left out, the card simply omits it. */
+    readonly url?: string;
+    /** Default `false` — see the module note on why this wire does not claim it. */
+    readonly streaming?: boolean;
+    readonly defaultInputModes?: readonly string[];
+    readonly defaultOutputModes?: readonly string[];
+    readonly skills?: readonly A2ASkill[];
+}
+export interface A2AWireOptions {
+    /** The agent card. Required: A2A discovery is not optional in the protocol. */
+    readonly card: A2AAgentCard;
+    /** Body for the health probe. Default `{ status: 'ok' }`. */
+    readonly health?: unknown;
+    /**
+     * Map a refusal's stable code onto the numeric JSON-RPC code this deployment
+     * reports. Absent, everything that is not a malformed request is
+     * `-32603` (internal error) — the JSON-RPC catch-all.
+     *
+     * A runtime with its own published code table passes one; that table is the
+     * runtime's, and this file does not carry anybody's.
+     */
+    readonly errorCodeFor?: (code: string | undefined) => number;
+    /** Name used in refusal messages. Default `'a2aWire'`. */
+    readonly name?: string;
+}
+type JsonObject = Readonly<Record<string, unknown>>;
+/**
+ * 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 declare function readA2AMessageText(message: unknown): string;
+/**
+ * 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 declare function a2aAgentCardDocument(card: A2AAgentCard): JsonObject;
+/** An `HttpWire` speaking A2A's `message/send`. */
+export declare function a2aWire(options: A2AWireOptions): HttpWire;
+export {};