agentfootprint 9.70.0 → 9.71.0

package/dist/esm/lib/mcp/mockMcpClient.d.ts

@@ -40,6 +40,32 @@ export interface MockMcpTool {
      * registry verbatim — same as a real MCP server's `listTools()`.
      */
     readonly inputSchema: Readonly<Record<string, unknown>>;
+    /**
+     * MCP's extensibility bag, exactly as a real server would send it (9.71.0).
+     *
+     * agentfootprint's tool DECLARATIONS — `argumentsFrom`, `resultKind`,
+     * `owner`, `resultClass`, `resultCeiling` — ride under the `agentfootprint`
+     * key here, and this mock reads them through the SAME defensive reader
+     * `mcpClient` uses. So a rail armed by a remotely-declared tool can be
+     * developed and tested before the real server exists, and so can the
+     * unhappy path: put a malformed declaration in and watch the field get
+     * dropped, the warning name the rule, and the tool register anyway.
+     *
+     * ```ts
+     * mockMcpClient({
+     *   name: 'fleet-mcp',
+     *   tools: [{
+     *     name: 'backup_status',
+     *     inputSchema: { type: 'object', properties: { machine: { type: 'string' } } },
+     *     _meta: { agentfootprint: { argumentsFrom: ['fleet_report'] } },
+     *   }],
+     * });
+     * ```
+     *
+     * Omitted → the registered `Tool` carries no declarations, exactly as
+     * before this existed.
+     */
+    readonly _meta?: Readonly<Record<string, unknown>>;
     /**
      * Async handler that runs when the agent calls this tool. Receives
      * the args the LLM produced; returns the string result the agent

package/dist/esm/lib/mcp/mockMcpClient.js

@@ -28,6 +28,7 @@
  * — stable, documented, and the right level of abstraction for
  * mock-first development.
  */
+import { readToolExtras } from './toolExtras.js';
 /**
  * Build an in-memory `McpClient`. Useful when you want to develop
  * against MCP semantics without spawning subprocesses, hitting the
@@ -77,6 +78,10 @@ function wrapMockTool(serverName, toolMap, mcp) {
         // governs by server name has to be testable against the mock, or the swap
         // from mock to real server changes what the policy sees.
         source: serverName,
+        // …and the same declarations, through the same reader (9.71.0). A rail
+        // that arms on a remotely-declared `argumentsFrom` must arm here too, or
+        // the mock proves nothing about the server it stands in for.
+        ...readToolExtras(mcp._meta, { server: serverName, tool: mcp.name }),
         execute: async (args) => {
             const argsObj = args !== null && typeof args === 'object' && !Array.isArray(args)
                 ? args

package/dist/esm/lib/mcp/mockMcpClient.js.map

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

package/dist/esm/lib/mcp/toolExtras.d.ts

@@ -0,0 +1,129 @@
+/**
+ * toolExtras — agentfootprint's own tool DECLARATIONS, carried over MCP.
+ *
+ * A `Tool` is two different things at once. Half of it is EXECUTION — the
+ * handler, the credential it needs, the human it wants to check in with. The
+ * other half is DECLARATION — flat, inert facts about the tool that no code
+ * runs and every consumer-side rail READS: where its arguments come from, what
+ * kind of artifact its result is, who owns it, what class of answer it gives,
+ * how big a result is too big.
+ *
+ * Over MCP only the execution half used to cross. A tool served by `mcpServe`
+ * arrived at a client as a name, a description and an input schema, so every
+ * rail that reads a declaration went quiet for it: the dangling-reference and
+ * unsupported-argument checks never armed, placement minted
+ * `tool-result/<name>` that no `wants` could spend, and the identity joins had
+ * no subject. An MCP server could be somebody's whole tool catalogue and still
+ * be a second-class citizen of every check this library ships.
+ *
+ * ── The carrier ─────────────────────────────────────────────────────────
+ * MCP's own extensibility bag: `Tool._meta`, under ONE namespaced key
+ * ({@link MCP_TOOL_EXTRAS_KEY}). `_meta` is declared on the spec's `Tool`
+ * object (`@modelcontextprotocol/sdk` types it as
+ * `z.record(z.string(), z.unknown()).optional()` on `ToolSchema`), so it
+ * survives the SDK's own `tools/list` validation in both directions and needs
+ * no new protocol, no side channel and no version negotiation. A server that
+ * has never heard of agentfootprint sends no bag; a client that has never
+ * heard of it ignores the key.
+ *
+ * ── What may travel, and the bar ────────────────────────────────────────
+ * **A declaration a consumer-side check or rail reads; nothing that governs
+ * execution.** The five fields below pass it. `needs` (credentials), `checkIn`
+ * (human consent) and the session hooks do NOT and never will: they govern how
+ * a tool RUNS, and the tool runs on the server. Sending them would tell a
+ * client to hold a gate that the only executor of the tool has already held,
+ * or — worse — that nobody is holding at all. `mcpServe` already refuses to
+ * serve a `checkIn` tool for exactly that reason; this list is the same law,
+ * stated on the way out.
+ *
+ * ── The asymmetry that matters ──────────────────────────────────────────
+ * SERVING validates nothing new: the tool was built by `defineTool`, which
+ * already refused every malformed declaration at definition time.
+ *
+ * INGEST validates everything and THROWS NOTHING. A bag comes from a server
+ * this process does not control, and one server's typo must not take down a
+ * bulk register of forty tools. So each field is judged by the SAME rule
+ * `defineTool` enforces (literally the same exported assert), and a field that
+ * fails is warned about once — naming the server, the tool, the field and the
+ * rule — and DROPPED. The tool still registers, without that one declaration.
+ * That is the honest outcome: the rail it would have armed stays unarmed, and
+ * the developer is told which rail and why.
+ */
+import { type Tool, type ToolOwner, type ToolResultCeiling } from '../../core/tools.js';
+import type { ToolResultClass } from '../semantics/types.js';
+/**
+ * The single `_meta` key every agentfootprint declaration travels under.
+ *
+ * Namespaced so it can never collide with another vendor's `_meta` entry, and
+ * a CONSTANT so there is exactly one spelling in the codebase — the
+ * `branchSegment.ts` precedent upstream: one owner of the grammar, and nobody
+ * else may write the string.
+ */
+export declare const MCP_TOOL_EXTRAS_KEY = "agentfootprint";
+/**
+ * The declarations that cross an MCP boundary — the plain-data half of a
+ * `Tool`, in the shape the receiving side puts straight back onto a `Tool`.
+ *
+ * Every field is optional and ABSENT MEANS ABSENT: a tool that declares
+ * nothing sends no bag at all, and a tool that declares two sends two keys,
+ * never five with three empty placeholders. "Said nothing" and "said empty"
+ * are different statements everywhere else in this library, and they are
+ * different here.
+ *
+ * @see MCP_TOOL_EXTRAS_KEY for the `_meta` key it rides under.
+ */
+export interface McpToolExtras {
+    /** Where this tool's arguments come from — see {@link Tool.argumentsFrom}.
+     *  Arms the dangling-reference and unsupported-argument checks. */
+    readonly argumentsFrom?: readonly string[];
+    /** The artifact kind a PLACED result is minted under — see
+     *  {@link Tool.resultKind}. What makes a placed result spendable by `wants`. */
+    readonly resultKind?: string;
+    /** The identity edge integrity checks join on — see {@link Tool.owner}. */
+    readonly owner?: ToolOwner;
+    /** The declared class of this tool's results — see {@link Tool.resultClass}. */
+    readonly resultClass?: ToolResultClass;
+    /** The author's refusing ceiling on this tool's result — see
+     *  {@link Tool.resultCeiling}. */
+    readonly resultCeiling?: ToolResultCeiling;
+}
+/**
+ * The declarations on `tool`, ready to be written into an MCP `_meta` bag —
+ * or `undefined` when the tool declares none, so `mcpServe` can leave `_meta`
+ * off the listing entirely rather than sending an empty object.
+ *
+ * Copied verbatim, never inferred or defaulted. This is the SERVE side, and
+ * the values were already vetted by `defineTool`.
+ */
+export declare function toolExtrasOf(tool: Tool): McpToolExtras | undefined;
+/** Where a rejected declaration came from, for the warning that names it. */
+export interface McpToolExtrasOrigin {
+    /** The client's logical name — `mcpClient({ name })`. */
+    readonly server: string;
+    /** The tool the bag was attached to. */
+    readonly tool: string;
+}
+/**
+ * Read an MCP `Tool._meta` bag into declarations a `Tool` can carry.
+ *
+ * **Never throws.** Everything here is somebody else's data:
+ *
+ *   - no `_meta`, no `agentfootprint` key, or a non-object under it → `{}`,
+ *     and the ingest is byte-identical to every release before this existed;
+ *   - a field the receiving side does not know → ignored in silence (a NEWER
+ *     server talking to an OLDER client is not an error, and warning about it
+ *     would make every upgrade noisy at the wrong end);
+ *   - a field this library DOES know but cannot honour → warned once and
+ *     dropped, and the rest of the bag still lands.
+ *
+ * The rule each field is judged by is the exported assert `defineTool` itself
+ * calls, so a declaration that would have been refused at definition time is
+ * refused here too, with the same sentence.
+ */
+export declare function readToolExtras(meta: unknown, origin: McpToolExtrasOrigin): McpToolExtras;
+/**
+ * Forget every warning issued so far.
+ * @internal test seam — the ledger is process-wide and warn-ONCE, so a test
+ *   proving the warning fires must be able to start from silence.
+ */
+export declare function _resetToolExtrasWarnings(): void;

package/dist/esm/lib/mcp/toolExtras.js

@@ -0,0 +1,198 @@
+/**
+ * toolExtras — agentfootprint's own tool DECLARATIONS, carried over MCP.
+ *
+ * A `Tool` is two different things at once. Half of it is EXECUTION — the
+ * handler, the credential it needs, the human it wants to check in with. The
+ * other half is DECLARATION — flat, inert facts about the tool that no code
+ * runs and every consumer-side rail READS: where its arguments come from, what
+ * kind of artifact its result is, who owns it, what class of answer it gives,
+ * how big a result is too big.
+ *
+ * Over MCP only the execution half used to cross. A tool served by `mcpServe`
+ * arrived at a client as a name, a description and an input schema, so every
+ * rail that reads a declaration went quiet for it: the dangling-reference and
+ * unsupported-argument checks never armed, placement minted
+ * `tool-result/<name>` that no `wants` could spend, and the identity joins had
+ * no subject. An MCP server could be somebody's whole tool catalogue and still
+ * be a second-class citizen of every check this library ships.
+ *
+ * ── The carrier ─────────────────────────────────────────────────────────
+ * MCP's own extensibility bag: `Tool._meta`, under ONE namespaced key
+ * ({@link MCP_TOOL_EXTRAS_KEY}). `_meta` is declared on the spec's `Tool`
+ * object (`@modelcontextprotocol/sdk` types it as
+ * `z.record(z.string(), z.unknown()).optional()` on `ToolSchema`), so it
+ * survives the SDK's own `tools/list` validation in both directions and needs
+ * no new protocol, no side channel and no version negotiation. A server that
+ * has never heard of agentfootprint sends no bag; a client that has never
+ * heard of it ignores the key.
+ *
+ * ── What may travel, and the bar ────────────────────────────────────────
+ * **A declaration a consumer-side check or rail reads; nothing that governs
+ * execution.** The five fields below pass it. `needs` (credentials), `checkIn`
+ * (human consent) and the session hooks do NOT and never will: they govern how
+ * a tool RUNS, and the tool runs on the server. Sending them would tell a
+ * client to hold a gate that the only executor of the tool has already held,
+ * or — worse — that nobody is holding at all. `mcpServe` already refuses to
+ * serve a `checkIn` tool for exactly that reason; this list is the same law,
+ * stated on the way out.
+ *
+ * ── The asymmetry that matters ──────────────────────────────────────────
+ * SERVING validates nothing new: the tool was built by `defineTool`, which
+ * already refused every malformed declaration at definition time.
+ *
+ * INGEST validates everything and THROWS NOTHING. A bag comes from a server
+ * this process does not control, and one server's typo must not take down a
+ * bulk register of forty tools. So each field is judged by the SAME rule
+ * `defineTool` enforces (literally the same exported assert), and a field that
+ * fails is warned about once — naming the server, the tool, the field and the
+ * rule — and DROPPED. The tool still registers, without that one declaration.
+ * That is the honest outcome: the rail it would have armed stays unarmed, and
+ * the developer is told which rail and why.
+ */
+import { assertArgumentsFrom, assertResultCeiling, assertResultClass, assertResultKind, assertToolOwner, } from '../../core/tools.js';
+/**
+ * The single `_meta` key every agentfootprint declaration travels under.
+ *
+ * Namespaced so it can never collide with another vendor's `_meta` entry, and
+ * a CONSTANT so there is exactly one spelling in the codebase — the
+ * `branchSegment.ts` precedent upstream: one owner of the grammar, and nobody
+ * else may write the string.
+ */
+export const MCP_TOOL_EXTRAS_KEY = 'agentfootprint';
+/**
+ * The declarations on `tool`, ready to be written into an MCP `_meta` bag —
+ * or `undefined` when the tool declares none, so `mcpServe` can leave `_meta`
+ * off the listing entirely rather than sending an empty object.
+ *
+ * Copied verbatim, never inferred or defaulted. This is the SERVE side, and
+ * the values were already vetted by `defineTool`.
+ */
+export function toolExtrasOf(tool) {
+    const extras = {
+        ...(tool.argumentsFrom !== undefined && { argumentsFrom: tool.argumentsFrom }),
+        ...(tool.resultKind !== undefined && { resultKind: tool.resultKind }),
+        ...(tool.owner !== undefined && { owner: tool.owner }),
+        ...(tool.resultClass !== undefined && { resultClass: tool.resultClass }),
+        ...(tool.resultCeiling !== undefined && { resultCeiling: tool.resultCeiling }),
+    };
+    return Object.keys(extras).length > 0 ? extras : undefined;
+}
+/**
+ * Read an MCP `Tool._meta` bag into declarations a `Tool` can carry.
+ *
+ * **Never throws.** Everything here is somebody else's data:
+ *
+ *   - no `_meta`, no `agentfootprint` key, or a non-object under it → `{}`,
+ *     and the ingest is byte-identical to every release before this existed;
+ *   - a field the receiving side does not know → ignored in silence (a NEWER
+ *     server talking to an OLDER client is not an error, and warning about it
+ *     would make every upgrade noisy at the wrong end);
+ *   - a field this library DOES know but cannot honour → warned once and
+ *     dropped, and the rest of the bag still lands.
+ *
+ * The rule each field is judged by is the exported assert `defineTool` itself
+ * calls, so a declaration that would have been refused at definition time is
+ * refused here too, with the same sentence.
+ */
+export function readToolExtras(meta, origin) {
+    const bag = bagOf(meta);
+    if (bag === undefined)
+        return {};
+    const kept = (field, assert) => keepField(bag, field, origin, assert);
+    // One line per field, in the declaration order of `McpToolExtras` — a reader
+    // comparing the two lists should not have to sort. The casts inside each
+    // rule are the point of the exercise: the value is untyped until its own
+    // rule has agreed it is the shape the field claims.
+    const argumentsFrom = kept('argumentsFrom', (v) => assertArgumentsFrom(origin.tool, v));
+    const resultKind = kept('resultKind', (v) => assertResultKind(origin.tool, v));
+    const owner = kept('owner', (v) => assertToolOwner(origin.tool, v));
+    const resultClass = kept('resultClass', (v) => assertResultClass(origin.tool, v));
+    const resultCeiling = kept('resultCeiling', (v) => assertResultCeiling(origin.tool, v));
+    return {
+        ...(argumentsFrom !== undefined && { argumentsFrom }),
+        ...(resultKind !== undefined && { resultKind }),
+        ...(owner !== undefined && { owner }),
+        ...(resultClass !== undefined && { resultClass }),
+        ...(resultCeiling !== undefined && { resultCeiling }),
+    };
+}
+// ─── The reading, field by field ───────────────────────────────────
+/** The bag under our key, or `undefined` when there is nothing to read. */
+function bagOf(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return undefined;
+    const bag = meta[MCP_TOOL_EXTRAS_KEY];
+    if (typeof bag !== 'object' || bag === null || Array.isArray(bag))
+        return undefined;
+    return bag;
+}
+/**
+ * Judge ONE field and answer with the value to keep, or `undefined` to drop.
+ *
+ * The rule is passed IN rather than looked up here, so this function owns the
+ * never-throw discipline and nothing else: every rule lives in `core/tools.ts`
+ * where `defineTool` reads it, and there is no second copy of any of them in
+ * this file.
+ */
+function keepField(bag, field, origin, assert) {
+    // `in` rather than a truthiness test: a server that sent the key holding a
+    // `null` said something wrong and should hear about it, while a server that
+    // never sent the key said nothing and should not.
+    if (!(field in bag))
+        return undefined;
+    const value = bag[field];
+    if (value === undefined)
+        return undefined;
+    try {
+        assert(value);
+    }
+    catch (error) {
+        warnOnce(origin, field, error instanceof Error ? error.message : String(error));
+        return undefined;
+    }
+    return value;
+}
+// ─── The warning ───────────────────────────────────────────────────
+/**
+ * Warn-once ledger, keyed by server + tool + field.
+ *
+ * ONCE because `.refresh()` re-lists the whole catalogue and an agent that
+ * refreshes every minute would otherwise print the same complaint every
+ * minute. Bounded because the key contains a remote server's tool names, and
+ * an unbounded Set fed by a remote party is a memory leak with a hostname
+ * attached — past the cap the warning simply repeats, which is the harmless
+ * failure mode.
+ */
+const warned = new Set();
+const MAX_WARNED = 500;
+/**
+ * NOT gated on `isDevMode()`, unlike the tool-NAME warning next door.
+ *
+ * A dropped declaration is not a style note: it is a check that will not arm,
+ * a placed result that will not be spendable, an identity join with no
+ * subject — and the symptom is silence, which looks exactly like a rail that
+ * ran and agreed. The precedent is `toolArgsValidation`'s uncompilable
+ * `pattern`: an ingested declaration this library cannot honour is reported
+ * unconditionally, once, and then ignored.
+ */
+function warnOnce(origin, field, rule) {
+    const key = `${origin.server}${origin.tool}${field}`;
+    if (warned.has(key))
+        return;
+    if (warned.size < MAX_WARNED)
+        warned.add(key);
+    // eslint-disable-next-line no-console
+    console.warn(`[agentfootprint] MCP server '${origin.server}' declared \`${field}\` on tool ` +
+        `'${origin.tool}' in its _meta.${MCP_TOOL_EXTRAS_KEY} bag, and this library cannot ` +
+        `honour it — the field was DROPPED and the tool registered without it, so whatever ` +
+        `that declaration would have armed stays unarmed. The rule it broke: ${rule}`);
+}
+/**
+ * Forget every warning issued so far.
+ * @internal test seam — the ledger is process-wide and warn-ONCE, so a test
+ *   proving the warning fires must be able to start from silence.
+ */
+export function _resetToolExtrasWarnings() {
+    warned.clear();
+}
+//# sourceMappingURL=toolExtras.js.map

package/dist/esm/lib/mcp/toolExtras.js.map

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

package/dist/esm/lib/mcp/types.d.ts

@@ -253,11 +253,7 @@ export interface McpClient {
 export interface McpSdkClient {
     connect(transport: unknown, options?: McpRequestOptions): Promise<void>;
     listTools(params?: undefined, options?: McpRequestOptions): Promise<{
-        readonly tools: ReadonlyArray<{
-            readonly name: string;
-            readonly description?: string;
-            readonly inputSchema: Readonly<Record<string, unknown>>;
-        }>;
+        readonly tools: ReadonlyArray<McpListedTool>;
     }>;
     callTool(params: {
         readonly name: string;
@@ -267,6 +263,23 @@ export interface McpSdkClient {
     resultSchema?: undefined, options?: McpRequestOptions): Promise<McpCallToolResult>;
     close(): Promise<void>;
 }
+/**
+ * One entry of a `tools/list` answer, narrowed to what this client reads.
+ *
+ * `_meta` is the spec's own extensibility bag on a `Tool` object, and it is in
+ * this shim because agentfootprint's tool DECLARATIONS ride in it under one
+ * namespaced key (see `toolExtras.ts`). It is typed as a loose record on
+ * purpose: everything in it is written by a server this process does not
+ * control, so the shim promises only that it is an object, and
+ * `readToolExtras` does the judging.
+ */
+export interface McpListedTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /** MCP's extensibility bag. Absent from most servers' tools. */
+    readonly _meta?: Readonly<Record<string, unknown>>;
+}
 /**
  * What `tools/call` can answer with — **a union, because the protocol is one.**
  *

package/dist/esm/tool-providers/index.d.ts

@@ -51,7 +51,7 @@ export { staticTools } from './staticTools.js';
 export { gatedTools } from './gatedTools.js';
 export { skillScopedTools, skillScopedToolsTarget, SKILL_SCOPED_TOOLS_ID_PREFIX, } from './skillScopedTools.js';
 export type { ToolProvider, ToolDispatchContext, ToolGatePredicate } from './types.js';
-export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, } from '../lib/mcp/index.js';
+export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, MCP_TOOL_EXTRAS_KEY, } from '../lib/mcp/index.js';
 export { agentCoreGatewayTransport, agentCoreGatewayUrl, gatewaySearchTool, hasGatewaySearch, AGENTCORE_GATEWAY_SEARCH_TOOL, AGENTCORE_POLICY_SESSION_HEADER, AGENTCORE_SIGV4_SERVICE, } from '../adapters/mcp/agentcore.js';
 export type { AgentCoreGatewayTransportOptions, AgentCoreGatewayUrlOptions, } from '../adapters/mcp/agentcore.js';
-export type { GatewayTransportOptions, McpCallToolResult, McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, McpGatewayTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, } from '../lib/mcp/index.js';
+export type { GatewayTransportOptions, McpCallToolResult, McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, McpGatewayTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, McpToolExtras, } from '../lib/mcp/index.js';

package/dist/esm/tool-providers/index.js

@@ -56,7 +56,11 @@ skillScopedToolsTarget, SKILL_SCOPED_TOOLS_ID_PREFIX, } from './skillScopedTools
 // Re-export tool sources from the MCP module so consumers find them in
 // one place. This subpath is the ONLY place `mcpClient` is public — the
 // top-level barrel does not re-export it.
-export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, } from '../lib/mcp/index.js';
+export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, 
+// The `_meta` key agentfootprint's tool declarations travel under, in both
+// directions (9.71.0). Public so a server this library did not write can
+// speak it, and so a client can read a bag it received.
+MCP_TOOL_EXTRAS_KEY, } from '../lib/mcp/index.js';
 // Reaching an AWS Bedrock AgentCore Gateway (9.66.0). A configuration of
 // `gatewayTransport` plus the four facts that are AgentCore's alone — kept in
 // the vendor's own file so the transport above stays able to say, truthfully,

package/dist/esm/tool-providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,gBAAgB;AAChB,kFAAkF;AAClF,kFAAkF;AAClF,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC;AAC7B,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,yCAAyC;AACzC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,6BAA6B,EAC7B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,gBAAgB;AAChB,kFAAkF;AAClF,kFAAkF;AAClF,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC;AACjC,2EAA2E;AAC3E,yEAAyE;AACzE,wDAAwD;AACxD,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,yCAAyC;AACzC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,6BAA6B,EAC7B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,8BAA8B,CAAC"}

package/dist/lib/mcp/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayAuthorizationRequiredError = exports.gatewayTransport = exports.mockMcpClient = exports.mcpServe = exports.mcpClient = void 0;
+exports.GatewayAuthorizationRequiredError = exports.gatewayTransport = exports.mockMcpClient = exports.MCP_TOOL_EXTRAS_KEY = exports.mcpServe = exports.mcpClient = void 0;
 /**
  * MCP — Model Context Protocol, both directions. `mcpClient` connects to
  * someone else's MCP server and registers its tools on your Agent;
@@ -11,6 +11,10 @@ var mcpClient_js_1 = require("./mcpClient.js");
 Object.defineProperty(exports, "mcpClient", { enumerable: true, get: function () { return mcpClient_js_1.mcpClient; } });
 var mcpServe_js_1 = require("./mcpServe.js");
 Object.defineProperty(exports, "mcpServe", { enumerable: true, get: function () { return mcpServe_js_1.mcpServe; } });
+// The declaration bag both directions speak (9.71.0) — one namespaced `_meta`
+// key, and the shape a non-agentfootprint server writes to be understood.
+var toolExtras_js_1 = require("./toolExtras.js");
+Object.defineProperty(exports, "MCP_TOOL_EXTRAS_KEY", { enumerable: true, get: function () { return toolExtras_js_1.MCP_TOOL_EXTRAS_KEY; } });
 var mockMcpClient_js_1 = require("./mockMcpClient.js");
 Object.defineProperty(exports, "mockMcpClient", { enumerable: true, get: function () { return mockMcpClient_js_1.mockMcpClient; } });
 var gatewayTransport_js_1 = require("./gatewayTransport.js");

package/dist/lib/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/mcp/index.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAClB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,uDAAgG;AAAvF,iHAAA,aAAa,OAAA;AACtB,6DAI+B;AAH7B,uHAAA,gBAAgB,OAAA;AAChB,wIAAA,iCAAiC,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/mcp/index.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAClB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,8EAA8E;AAC9E,0EAA0E;AAC1E,iDAA0E;AAAjE,oHAAA,mBAAmB,OAAA;AAC5B,uDAAgG;AAAvF,iHAAA,aAAa,OAAA;AACtB,6DAI+B;AAH7B,uHAAA,gBAAgB,OAAA;AAChB,wIAAA,iCAAiC,OAAA"}

package/dist/lib/mcp/mcpClient.js

@@ -23,6 +23,12 @@
  * Role:    Layer-3 integration. Sits next to `defineTool` — same
  *          shape, different source. Once tools land on the agent,
  *          the rest of the library doesn't know they came from MCP.
+ *          Since 9.71.0 that is true of DECLARATIONS too: a server's
+ *          `_meta` bag becomes `argumentsFrom` / `resultKind` / `owner`
+ *          / `resultClass` / `resultCeiling` on the registered `Tool`,
+ *          so the integrity checks, the placement mint and the identity
+ *          joins arm for a remote tool exactly as for a local one. The
+ *          reading NEVER throws — see `toolExtras.ts`.
  *
  * Emits:   N/A — wrapped tools emit the standard
  *          `agentfootprint.stream.tool_start` / `tool_end` events
@@ -36,6 +42,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mcpClient = void 0;
+const toolExtras_js_1 = require("./toolExtras.js");
 const gatewayTransport_js_1 = require("./gatewayTransport.js");
 const throttleRetry_js_1 = require("./throttleRetry.js");
 const lazyRequire_js_1 = require("../lazyRequire.js");
@@ -189,6 +196,13 @@ function wrapMcpTool(serverName, sdk, mcp, signal) {
         // bare tool name cannot tell two servers' identically-named tools apart;
         // this is the fact that lets it. See `Tool.source`.
         source: serverName,
+        // The DECLARATIONS the server sent in MCP's `_meta` bag (9.71.0) — read
+        // defensively, per field, by the same rules `defineTool` enforces, and
+        // NEVER throwing: a malformed field is warned about once and dropped, and
+        // this tool still registers. That is what keeps one bad tool from killing
+        // a forty-tool bulk register. A server that sent no bag adds no keys here,
+        // so the Tool is byte-identical to one built before this existed.
+        ...(0, toolExtras_js_1.readToolExtras)(mcp._meta, { server: serverName, tool: mcp.name }),
         execute: async (args) => {
             // The agent passes args as `unknown` per Tool contract. MCP
             // expects a JSON object — non-object inputs become `{}` rather

package/dist/lib/mcp/mcpClient.js.map

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

package/dist/lib/mcp/mcpServe.js

@@ -44,6 +44,14 @@
  *   - `needs` (declare-and-push credentials) needs a provider; without
  *     one the tool would run with `ctx.credential` undefined.
  *
+ * ── Declarations travel; execution does not (9.71.0) ─────────────────
+ * A served tool's DECLARATIONS — `argumentsFrom`, `resultKind`, `owner`,
+ * `resultClass`, `resultCeiling` — are written into MCP's own `_meta` bag
+ * under one namespaced key, so an agentfootprint client arms the checks and
+ * rails that read them exactly as it would for a local `defineTool`. The
+ * execution-side fields never go: see `toolExtras.ts` for the bar and the
+ * reasoning. A tool declaring none of the five lists exactly as before.
+ *
  * ── Schemas ──────────────────────────────────────────────────────────
  * Tools already carry JSON Schema in `schema.inputSchema`, and MCP's
  * `tools/list` wants JSON Schema, so the mapping is the identity
@@ -82,6 +90,7 @@ const types_js_1 = require("../../identity/types.js");
 const capability_js_1 = require("../../artifacts/capability.js");
 const wants_js_1 = require("../../artifacts/wants.js");
 const lazyRequire_js_1 = require("../lazyRequire.js");
+const toolExtras_js_1 = require("./toolExtras.js");
 const runChain_js_1 = require("../../core/agent/middleware/runChain.js");
 const DEFAULT_SERVER_NAME = 'agentfootprint';
 const DEFAULT_SERVER_VERSION = '0.0.0';
@@ -101,11 +110,20 @@ async function mcpServe(tools, opts = {}) {
     const version = opts.version ?? DEFAULT_SERVER_VERSION;
     const byName = validateServableTools(tools, name, opts.credentials);
     const credentials = opts.credentials ?? (0, types_js_1.unconfiguredCredentialProvider)();
-    const listing = tools.map((t) => ({
-        name: t.schema.name,
-        ...(t.schema.description !== undefined && { description: t.schema.description }),
-        inputSchema: t.schema.inputSchema ?? { type: 'object', properties: {} },
-    }));
+    const listing = tools.map((t) => {
+        // The declaration half of the tool, in MCP's own extensibility bag
+        // (9.71.0). Absent fields stay absent and a tool that declares NOTHING
+        // gets no `_meta` key at all, so a server whose tools carry no
+        // declarations lists exactly the bytes it always did. See toolExtras.ts
+        // for the inclusion bar and for why `needs` / `checkIn` never travel.
+        const extras = (0, toolExtras_js_1.toolExtrasOf)(t);
+        return {
+            name: t.schema.name,
+            ...(t.schema.description !== undefined && { description: t.schema.description }),
+            inputSchema: t.schema.inputSchema ?? { type: 'object', properties: {} },
+            ...(extras !== undefined && { _meta: { [toolExtras_js_1.MCP_TOOL_EXTRAS_KEY]: extras } }),
+        };
+    });
     // Order matters: the server is resolved FIRST so that a missing SDK is
     // reported by the message that tells you how to install it, rather than
     // by the narrower one about a single submodule.