agentfootprint 10.2.0 → 10.3.1

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

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

package/dist/esm/mcp/sdkLoadFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdkLoadFailure.js","sourceRoot":"","sources":["../../../src/mcp/sdkLoadFailure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA0BH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,KAA0B;IACrE,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,gBAAgB,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC,YAAY,CAAC;IACxD,OAAO,CACL,GAAG,KAAK,CAAC,MAAM,mBAAmB,KAAK,CAAC,SAAS,6BAA6B;QAC9E,yBAAyB,MAAM,IAAI;QACnC,iFAAiF;QACjF,yDAAyD;QACzD,KAAK,KAAK,CAAC,OAAO,EAAE,CACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,MAAc;IACtC,OAAO,gGAAgG,CAAC,IAAI,CAC1G,MAAM,CACP,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,QAAQ,CAAC,GAAY;IAC5B,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,wCAAwC,CAAC;IAClD,CAAC;AACH,CAAC"}

package/dist/esm/mcp/throttleRetry.js

@@ -0,0 +1,189 @@
+/**
+ * throttleRetry — when an MCP server says "too many requests", wait and ask again.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ * Managed MCP gateways enforce per-principal rate limits. A throttled
+ * `tools/call` is not a fault, it is the endpoint working as designed — and
+ * before 8.11.0 it arrived at the model as a thrown tool error, which the model
+ * reads as **"this tool is broken"**. It then apologises, picks a different
+ * tool, or invents an answer. A designed, transient, self-clearing condition
+ * was being turned into a wrong answer.
+ *
+ * ── Why retrying a 429 is safe, and why the policy is 429-ONLY ───────────────
+ * **A 429 is a pre-execution rejection.** The rate limiter refused the request
+ * at the edge; the server never ran the tool. Retrying therefore cannot
+ * double-execute anything — which is exactly what is NOT true of a 500 or a
+ * timeout, where the call may have half-run and a retry could charge a card
+ * twice.
+ *
+ * That asymmetry is the whole license for this module, so the policy must never
+ * widen. Only HTTP 429 retries here. Not 5xx, not network errors, not timeouts
+ * — those belong to a caller who knows whether the specific tool is idempotent,
+ * and this seam does not. A property test pins the boundary.
+ *
+ * ── Why it lives at the fetch seam and not around `Tool.execute` ─────────────
+ * Because `Retry-After` is only reachable here. The MCP SDK reads the response,
+ * throws `StreamableHTTPError(status, text)` and drops the `Response` — so by
+ * the time a throttle reaches `Tool.execute` the header is gone and the status
+ * survives only as `err.code`. A retry wrapper around the tool could guess a
+ * backoff; only a wrapper around `fetch` can honour the number the server
+ * actually asked for. Honouring it is also what keeps a fleet of agents from
+ * synchronising into a thundering herd.
+ *
+ * ── Ordering: retry OUTSIDE, signing and vending INSIDE ──────────────────────
+ * The wrapper composes over the caller's `fetch` (a SigV4/DPoP signer) or over
+ * `createVendingFetch` (a per-request credential). Sitting outside means every
+ * attempt is signed afresh and vended afresh — signatures expire, and a token
+ * that would have died during the wait is simply never the one reused. The
+ * gateway secrecy invariant is untouched: each attempt vends, applies, drops.
+ *
+ * Pattern: Decorator over `fetch`. Role: Layer-3 tool transport.
+ */
+import { sleep } from '../lib/sleep.js';
+// ─── Defaults ────────────────────────────────────────────────────────
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_MAX_WAIT_MS = 10_000;
+/** First backoff when the server sent no `Retry-After`. */
+const BASE_BACKOFF_MS = 200;
+/** `undefined` means "do not retry" — the caller then leaves `fetch` alone. */
+function resolveConfig(config) {
+    if (config === false)
+        return undefined;
+    const opts = config === true || config === undefined ? {} : config;
+    return {
+        maxAttempts: Math.max(1, opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS),
+        maxWaitMs: Math.max(0, opts.maxWaitMs ?? DEFAULT_MAX_WAIT_MS),
+        ...(opts.onRetry && { onRetry: opts.onRetry }),
+    };
+}
+// ─── The decorator ───────────────────────────────────────────────────
+/**
+ * Wrap a `fetch` so HTTP 429 responses are retried, honouring `Retry-After`.
+ *
+ * Returns `inner` untouched when retry is disabled — including `undefined`,
+ * so a transport that passed no custom fetch keeps passing none and its
+ * behaviour is byte-identical to before this existed.
+ *
+ * ── Why this is public ───────────────────────────────────────────────────────
+ * `mcpClient({ transport })` applies it for you, ON by default. `mcpClient({
+ * connection })` cannot: the library builds no transport on that arm, so there
+ * is no `fetch` of its own to wrap — and a browser consumer, who is the main
+ * reason that arm exists, would silently lose the 429 handling Node gets for
+ * free. That asymmetry is invisible from the outside, which is why the answer
+ * is to hand over the same implementation rather than to document the gap:
+ *
+ * ```ts
+ * import { retryingFetch } from 'agentfootprint/providers';
+ * import { StreamableHTTPClientTransport }
+ *   from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+ *
+ * const transport = new StreamableHTTPClientTransport(new URL('/mcp', location.href), {
+ *   fetch: retryingFetch(undefined, { maxAttempts: 5 }),
+ * });
+ * ```
+ *
+ * @param inner the fetch to wrap. `undefined` means the global `fetch`,
+ *   resolved at CALL time so a later polyfill still wins.
+ * @param config `true` / `undefined` for the defaults, `false` to get `inner`
+ *   back unchanged, or an object to tune the ceilings.
+ */
+export function retryingFetch(inner, config) {
+    const resolved = resolveConfig(config);
+    if (!resolved)
+        return inner;
+    const base = inner ?? ((input, init) => globalThis.fetch(input, init));
+    return async (input, init) => {
+        let totalWaited = 0;
+        for (let attempt = 1;; attempt++) {
+            const response = await base(input, init);
+            if (response.status !== 429)
+                return response;
+            if (attempt >= resolved.maxAttempts)
+                return response;
+            // A body we cannot send twice makes a retry a different request. Rare
+            // for MCP (JSON strings), but silently replaying half a stream would be
+            // worse than surfacing the throttle.
+            if (!isReplayable(input, init))
+                return response;
+            if (init?.signal?.aborted)
+                return response;
+            const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
+            const waitMs = retryAfterMs ?? backoffMs(attempt);
+            // The rail on Retry-After: never let a server talk us into a wait that
+            // breaks the caller's budget.
+            if (totalWaited + waitMs > resolved.maxWaitMs)
+                return response;
+            // Release the throttle response's body before asking again, so a
+            // keep-alive connection is not pinned by an unread stream.
+            discardBody(response);
+            resolved.onRetry?.({
+                attempt: attempt + 1,
+                maxAttempts: resolved.maxAttempts,
+                waitMs,
+                ...(retryAfterMs !== undefined && { retryAfterMs }),
+                url: describeUrl(input),
+            });
+            await sleep(waitMs, init?.signal);
+            totalWaited += waitMs;
+        }
+    };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────
+/**
+ * `Retry-After` in either legal form: delta-seconds (`"2"`) or an HTTP-date
+ * (`"Wed, 21 Oct 2026 07:28:00 GMT"`). Anything else is treated as absent so a
+ * malformed header degrades to our own backoff rather than to a wrong wait.
+ */
+export function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    const when = Date.parse(trimmed);
+    if (Number.isNaN(when))
+        return undefined;
+    return Math.max(0, when - Date.now());
+}
+/**
+ * Exponential backoff with equal jitter — half fixed, half random. The fixed
+ * half keeps the wait meaningful; the random half stops a fleet of agents that
+ * were all throttled at the same instant from retrying at the same instant.
+ */
+function backoffMs(attempt) {
+    const ceiling = BASE_BACKOFF_MS * Math.pow(2, attempt - 1);
+    return Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+}
+/** Can this exact request be sent again? A stream body cannot be rewound. */
+function isReplayable(input, init) {
+    // Defensive: the declared type says otherwise, but a `Request` carries its
+    // own (possibly already-consumed) body and must never be replayed.
+    if (typeof Request !== 'undefined' && input instanceof Request)
+        return false;
+    const body = init?.body;
+    if (body === undefined || body === null)
+        return true;
+    if (typeof body === 'string')
+        return true;
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams)
+        return true;
+    if (typeof Blob !== 'undefined' && body instanceof Blob)
+        return true;
+    if (body instanceof ArrayBuffer || ArrayBuffer.isView(body))
+        return true;
+    return false;
+}
+/** Best-effort release of an unread response body. Never throws. */
+function discardBody(response) {
+    try {
+        void response.body?.cancel?.();
+    }
+    catch {
+        // A body that refuses to cancel is not worth failing a retry over.
+    }
+}
+/** The endpoint, for the `onRetry` report. Never a credential. */
+function describeUrl(input) {
+    return typeof input === 'string' ? input : input.toString();
+}
+//# sourceMappingURL=throttleRetry.js.map

package/dist/esm/mcp/throttleRetry.js.map

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

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

@@ -0,0 +1,194 @@
+/**
+ * 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.** Every field below passes 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, type ToolResultColumns } from '../tools/tools.js';
+import type { ToolResultClass } from '../semantics/types.js';
+import { type AskOrAssume, type ToolPeriod } from '../tools/declare.js';
+import { type TimeContext } from '../time/wire.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;
+    /**
+     * What this tool's ROWS contain (9.78.0) — see {@link Tool.resultColumns}.
+     * Arms the write seam's `column-type-mismatch` and `missing-column` checks.
+     *
+     * It clears the bar this file states, and by the widest margin of the eight.
+     * It is a flat, inert fact about the RESULT that a consumer-side check
+     * reads; it governs nothing about how the tool runs, and the tool runs on
+     * the server. It is also the field case for carrying declarations at all: a
+     * remote catalogue of rowset tools is exactly where a numeric column
+     * arriving as text goes unnoticed, because the consumer holding the chart
+     * has no way to know what the producer meant. Leaving it behind would arm
+     * the check for local tools and leave every MCP tool a second-class citizen
+     * of it — the whole defect `toolExtras` was built to end.
+     */
+    readonly resultColumns?: ToolResultColumns;
+    /** 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 named ingredient tools this tool is composed of (9.76.0) — see
+     *  {@link Tool.composedOf}. Feeds the receiving agent's build-time drift
+     *  gate. */
+    readonly composedOf?: readonly string[];
+    /** Whether this tool's procedure can raise an approval gate (9.76.0) — see
+     *  {@link Tool.gates}. Read by composition-time checks that must keep a
+     *  gating tool out of a fan-out branch. */
+    readonly gates?: boolean;
+    /**
+     * The per-argument rules (the inputs layer, honesty layer 2) — see
+     * {@link Tool.askOrAssume}. It passes this file's bar: the fill and the
+     * batch ask happen in the CLIENT's own loop before the call
+     * is sent — exactly as the client applies a served `resultCeiling` — and
+     * nothing about how the server runs the tool changes. The FIRST extra
+     * judged against the tool's schema, which is why the origin carries the
+     * listed tool's `inputSchema`. A client that ignores `_meta` sees the
+     * author's `required` and sends the value, or the server applies its own
+     * default.
+     */
+    readonly askOrAssume?: AskOrAssume;
+    /** Which arguments set the period the answer covers, the forms they take
+     *  and the facts about the source — see {@link Tool.period}. Judged
+     *  against the listed tool's own `inputSchema` and the KEPT `askOrAssume`
+     *  (every argument a form names must carry a kept rule). A host tool
+     *  written in another language declares the same object, field for field. */
+    readonly period?: ToolPeriod;
+}
+/**
+ * The `_meta` bag a `tools/call` request carries for a call handed
+ * `ctx.time` (the time layer, `time/wire.ts` · `TimeContext`): the
+ * same object, under the one namespaced key — so a host tool in another
+ * process can declare the `period.queried` its read covered without parsing
+ * its own argument.
+ */
+export declare function callMetaOf(time: TimeContext): Readonly<Record<string, unknown>>;
+/**
+ * The call's time a `tools/call` request carried in its `_meta` bag, read —
+ * or `undefined` when it carried none, or one this runtime cannot read (a
+ * different version, a malformed field): never repaired, never guessed. What
+ * `mcpServe` hands a served tool as `ctx.time`.
+ */
+export declare function callTimeOf(meta: unknown): TimeContext | undefined;
+/**
+ * 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;
+    /**
+     * The listed tool's own `inputSchema` — what `askOrAssume` and `period` are
+     * judged against (each ruled property by its OWN schema). Absent → those
+     * two fields are judged against an empty schema, so every rule is dropped
+     * with a warning rather than trusted unjudged.
+     */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 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/mcp/toolExtras.js

@@ -0,0 +1,241 @@
+/**
+ * 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.** Every field below passes 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, assertComposedOf, assertGates, assertResultCeiling, assertResultClass, assertResultColumns, assertResultKind, assertToolOwner, } from '../tools/tools.js';
+import { assertAskOrAssume } from '../tools/declare.js';
+import { readTimeContext, TIME_CONTEXT_META_KEY } from '../time/wire.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';
+// ─── A call's own metadata: the time layer's `ctx.time` ──────────────
+/**
+ * The `_meta` bag a `tools/call` request carries for a call handed
+ * `ctx.time` (the time layer, `time/wire.ts` · `TimeContext`): the
+ * same object, under the one namespaced key — so a host tool in another
+ * process can declare the `period.queried` its read covered without parsing
+ * its own argument.
+ */
+export function callMetaOf(time) {
+    return { [MCP_TOOL_EXTRAS_KEY]: { [TIME_CONTEXT_META_KEY]: time } };
+}
+/**
+ * The call's time a `tools/call` request carried in its `_meta` bag, read —
+ * or `undefined` when it carried none, or one this runtime cannot read (a
+ * different version, a malformed field): never repaired, never guessed. What
+ * `mcpServe` hands a served tool as `ctx.time`.
+ */
+export function callTimeOf(meta) {
+    const bag = bagOf(meta);
+    return bag === undefined ? undefined : readTimeContext(bag[TIME_CONTEXT_META_KEY]);
+}
+/**
+ * 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.resultColumns !== undefined && { resultColumns: tool.resultColumns }),
+        ...(tool.owner !== undefined && { owner: tool.owner }),
+        ...(tool.resultClass !== undefined && { resultClass: tool.resultClass }),
+        ...(tool.resultCeiling !== undefined && { resultCeiling: tool.resultCeiling }),
+        ...(tool.composedOf !== undefined && { composedOf: tool.composedOf }),
+        ...(tool.gates !== undefined && { gates: tool.gates }),
+        ...(tool.askOrAssume !== undefined && { askOrAssume: tool.askOrAssume }),
+        ...(tool.period !== undefined && { period: tool.period }),
+    };
+    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 resultColumns = kept('resultColumns', (v) => assertResultColumns(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));
+    const composedOf = kept('composedOf', (v) => assertComposedOf(origin.tool, v));
+    const gates = kept('gates', (v) => assertGates(origin.tool, v));
+    // The inputs layer's two, judged TOGETHER in order: the rules against the
+    // listed schema, then the period against the rules that were KEPT — a period
+    // naming an argument whose rule was dropped is dropped too (a period never
+    // arms anything alone).
+    const schema = origin.inputSchema ?? { type: 'object', properties: {} };
+    const askOrAssume = kept('askOrAssume', (v) => assertAskOrAssume(origin.tool, v, undefined, schema));
+    const period = kept('period', (v) => assertAskOrAssume(origin.tool, askOrAssume, v, schema));
+    return {
+        ...(argumentsFrom !== undefined && { argumentsFrom }),
+        ...(resultKind !== undefined && { resultKind }),
+        ...(resultColumns !== undefined && { resultColumns }),
+        ...(owner !== undefined && { owner }),
+        ...(resultClass !== undefined && { resultClass }),
+        ...(resultCeiling !== undefined && { resultCeiling }),
+        ...(composedOf !== undefined && { composedOf }),
+        ...(gates !== undefined && { gates }),
+        ...(askOrAssume !== undefined && { askOrAssume }),
+        ...(period !== undefined && { period }),
+    };
+}
+// ─── 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 `tools/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