@namzu/sdk 40.0.0 → 41.0.0

package/dist/connector/mcp/client.js

@@ -3,10 +3,14 @@ import { generateMCPClientId } from '../../utils/id.js';
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js';
 import { resolveLogger } from '../../utils/logger.js';
 import { validateConnectorTimeoutMs } from '../http-operation.js';
+import { buildEnvelope, decodeResult } from './envelope.js';
+import { classifyModernHttpFailure, defaultMcpEraCache, mcpEraCacheKey, resolveMcpEra, serverInfoFromDiscover, } from './era.js';
+import { MCPHttpStatusError, MCPInputRequiredError, isHeaderMismatchError, protocolErrorFromReply, } from './errors.js';
 import { HttpSseTransport } from './http-sse.js';
 import { StdioTransport } from './stdio.js';
 import { StreamableHttpTransport } from './streamable-http.js';
-import { DEFAULT_MCP_REQUEST_TIMEOUT_MS, JSON_RPC_METHOD_NOT_FOUND, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, } from '../../constants/mcp/index.js';
+import { validateMcpHeaderAnnotations } from './x-mcp-header.js';
+import { DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS, DEFAULT_MCP_REQUEST_TIMEOUT_MS, JSON_RPC_METHOD_NOT_FOUND, MCP_DISCOVER_METHOD, MCP_LEGACY_VERSIONS, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SUPPORTED_PROTOCOL_VERSIONS, } from '../../constants/mcp/index.js';
 import { NAMZU } from '../../constants/telemetry/index.js';
 import { VERSION } from '../../version.js';
 /** Runaway guard for a server whose cursor never ends. */
@@ -14,12 +18,49 @@ const MAX_LIST_PAGES = 100;
 /** A cancellation notification must never become the next unbounded wait. */
 const CANCEL_NOTIFICATION_TIMEOUT_MS = 1_000;
 const NAMZU_CLIENT_INFO = { name: 'namzu-sdk', version: VERSION };
+/**
+ * The three header names the protocol owns, lower-cased for matching.
+ *
+ * Protected regardless of what era the connection resolved to, and
+ * regardless of whether {@link buildEnvelope} put any headers of its own on
+ * THIS request. A legacy era older than `2025-06-18` sends none of its
+ * own — `buildEnvelope` returns `{ headers: {} }` for it, same as an
+ * unresolved era — so deriving the protected set from the era's own header
+ * keys (as this used to) protected nothing there: a caller could set
+ * `Mcp-Method` on a 2024-11-05 or 2025-03-26 session and it reached the
+ * wire unchanged. `Mcp-Method` and `Mcp-Name` are modern-only headers
+ * {@link buildEnvelope} never writes on ANY legacy connection, so that gap
+ * existed on every legacy era, not only the two oldest ones. The set below
+ * is fixed and total precisely so "does this era currently emit the
+ * header" never again decides whether a caller can forge it.
+ */
+const CANONICAL_MCP_REQUEST_HEADERS = new Set([MCP_PROTOCOL_VERSION_HEADER, MCP_METHOD_HEADER, MCP_NAME_HEADER].map((name) => name.toLowerCase()));
+/**
+ * Did the peer answer `-32020` (`HeaderMismatch`)?
+ *
+ * Two shapes, because a conforming server sends this one BOTH ways. The spec
+ * has it arrive as `400 Bad Request` carrying the JSON-RPC error in the
+ * response body, which this transport surfaces as an `MCPHttpStatusError`
+ * and never as a reply; a server that answers `200` with a JSON-RPC error
+ * frame produces the ordinary `MCPProtocolError` instead. Recognising only
+ * the second would leave the recovery dead on exactly the path the spec
+ * describes.
+ */
+function isHeaderMismatch(error) {
+    if (isHeaderMismatchError(error))
+        return true;
+    if (!(error instanceof MCPHttpStatusError))
+        return false;
+    const verdict = classifyModernHttpFailure(error.status, error.bodyText);
+    return verdict.kind === 'modern' && isHeaderMismatchError(verdict.error);
+}
 export class MCPClient {
     id;
     transport;
     status = 'disconnected';
     serverInfo;
     serverCapabilities;
+    era;
     connectedAt;
     error;
     pendingRequests = new Map();
@@ -31,9 +72,28 @@ export class MCPClient {
     log;
     config;
     requestTimeoutMs;
+    eraCache;
+    eraCacheKey;
+    eraProbeTimeoutMs;
+    /**
+     * What each listed tool asked to mirror into `Mcp-Param-*` headers,
+     * by tool name.
+     *
+     * Rebuilt by every `listTools()` and empty until the first one: a header
+     * is only ever written from a schema this client has seen the server
+     * publish, so a stale binding cannot outlive the listing that produced
+     * it.
+     */
+    toolParamHeaders = new Map();
     constructor(config) {
         this.config = config;
         this.requestTimeoutMs = validateConnectorTimeoutMs(config.requestTimeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS, 'MCPClient requestTimeoutMs');
+        // Never longer than one round trip's deadline: a probe IS a request,
+        // and one that outlived the bound every other request is held to
+        // would be a connect that hangs past its own timeout.
+        this.eraProbeTimeoutMs = Math.min(validateConnectorTimeoutMs(config.eraProbeTimeoutMs ?? DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS, 'MCPClient eraProbeTimeoutMs'), this.requestTimeoutMs);
+        this.eraCache = config.eraCache ?? defaultMcpEraCache;
+        this.eraCacheKey = mcpEraCacheKey(config.transport);
         this.id = config.id ?? generateMCPClientId();
         // Built BEFORE the transport, not after: `createTransport` threads
         // `this.log` into whichever transport it constructs (LOG-10), so the
@@ -49,6 +109,16 @@ export class MCPClient {
             throw new Error(`MCPClient already connected to "${this.config.serverName}"`);
         }
         this.status = 'connecting';
+        // Tool schemas belong to a listing, and a listing belongs to a
+        // connection. Carrying bindings across a reconnect would mirror the
+        // previous server's schema onto the new one's calls.
+        this.toolParamHeaders = new Map();
+        // A reconnect must renegotiate from scratch: the era does not belong
+        // to this new handshake until this new handshake has happened. The
+        // era CACHE survives — it is a memory of the peer, not of this
+        // connection — so a reconnect to a known-legacy origin skips the
+        // probe while still running a fresh `initialize`.
+        this.era = undefined;
         try {
             this.transport.onMessage((msg) => this.handleMessage(msg));
             this.transport.onClose(() => {
@@ -67,29 +137,11 @@ export class MCPClient {
                 this.rejectAllPending(`MCP transport to "${this.config.serverName}" failed: ${err.message}`);
             });
             await this.transport.connect();
-            const result = (await this.request('initialize', {
-                protocolVersion: MCP_PROTOCOL_VERSION,
-                capabilities: this.config.capabilities ?? {},
-                clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
-            }));
-            // The server answers with the version IT will speak, which need
-            // not be the one we asked for. Ignoring that answer — as this did
-            // — makes an unspeakable version look like a healthy connection
-            // until something downstream breaks in a confusing way.
-            const negotiated = result.protocolVersion;
-            if (negotiated && !MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(negotiated)) {
-                throw new Error(`MCP server "${this.config.serverName}" negotiated protocol version "${negotiated}", ` +
-                    `which this client cannot speak (supported: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(', ')}).`);
-            }
-            if (negotiated && negotiated !== MCP_PROTOCOL_VERSION) {
-                this.log.info('MCP server negotiated a different protocol version', {
-                    'namzu.connector.requested': MCP_PROTOCOL_VERSION,
-                    'namzu.connector.negotiated': negotiated,
-                });
+            const resolution = await this.resolveEra();
+            if (resolution.era.kind === 'modern') {
+                return this.completeModernConnection(resolution);
             }
-            this.serverInfo = result.serverInfo;
-            this.serverCapabilities = result.capabilities;
-            await this.notify('notifications/initialized', {});
+            const result = await this.performLegacyInitializeHandshake();
             this.status = 'connected';
             this.connectedAt = Date.now();
             this.emitLifecycle({
@@ -104,6 +156,10 @@ export class MCPClient {
             return result;
         }
         catch (err) {
+            // A remembered era that cannot complete a handshake is a memory
+            // worth forgetting: the next connect re-probes from scratch rather
+            // than inheriting the assumption that just failed.
+            this.eraCache.delete(this.eraCacheKey);
             this.status = 'error';
             this.error = toErrorMessage(err);
             this.log.error('MCP connection failed', { 'exception.message': this.error });
@@ -111,6 +167,248 @@ export class MCPClient {
             throw err;
         }
     }
+    /**
+     * One `initialize` round trip, offering the newest legacy version this
+     * client speaks — never a per-version waterfall. The spec's own
+     * backward-compatibility algorithm offers one version and honors
+     * whatever the server answers with; a three-step retry loop would be
+     * three times the latency for a path no server expects.
+     * `protocol-negotiation.test.ts` counts `initialize` frames so this
+     * stays true.
+     *
+     * Shared by `connect()`'s first handshake and by
+     * {@link reinitializeLegacySession}'s recovery from a `404`d session —
+     * the second call is not a special case, it is this same function run
+     * again on a connection that already exists.
+     */
+    async performLegacyInitializeHandshake() {
+        const offered = MCP_LEGACY_VERSIONS[0];
+        const result = (await this.request('initialize', {
+            protocolVersion: offered,
+            capabilities: this.config.capabilities ?? {},
+            clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+        }));
+        // The server answers with the version IT will speak, which need
+        // not be the one we asked for. Ignoring that answer — as this once
+        // did — makes an unspeakable version look like a healthy
+        // connection until something downstream breaks in a confusing
+        // way. A server that omits the field entirely is tolerated and
+        // treated as having accepted the offer, exactly as before this
+        // broadened the set.
+        const negotiated = result.protocolVersion ?? offered;
+        if (!MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(negotiated)) {
+            throw new Error(`MCP server "${this.config.serverName}" negotiated protocol version "${negotiated}", ` +
+                `which this client cannot speak (offered "${offered}"; supported: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(', ')}).`);
+        }
+        if (negotiated !== offered) {
+            this.log.info('MCP server negotiated a different protocol version', {
+                'namzu.connector.requested': offered,
+                'namzu.connector.negotiated': negotiated,
+            });
+        }
+        // A real modern server does not implement `initialize` at all, so a
+        // success shape here naming a modern revision is a server
+        // contradicting itself. Refusing is the only honest answer: the
+        // alternative is recording a `legacy` era at a version that is not
+        // a legacy one, which would then write a modern version number
+        // onto requests carrying none of what that version requires.
+        if (!MCP_LEGACY_VERSIONS.includes(negotiated)) {
+            throw new Error(`MCP server "${this.config.serverName}" answered the legacy initialize handshake with "${negotiated}", ` +
+                `which is not a legacy revision (offered "${offered}"; legacy revisions: ${MCP_LEGACY_VERSIONS.join(', ')}). ` +
+                'A server that speaks that revision does not implement initialize at all.');
+        }
+        this.era = { kind: 'legacy', version: negotiated };
+        this.serverInfo = result.serverInfo;
+        this.serverCapabilities = result.capabilities;
+        await this.notify('notifications/initialized', {});
+        return result;
+    }
+    /**
+     * A request answered `404` on a session-bearing legacy connection: the
+     * legacy Streamable HTTP transports specify that a terminated session
+     * answers this way, and the client's remedy is to drop it and run the
+     * handshake again, exactly once, before giving up.
+     *
+     * Gated to legacy by construction, not by a flag: `hasSession()` is only
+     * ever true on a connection that completed the legacy `initialize`
+     * handshake in the first place — a modern connection never calls it (see
+     * `probeDiscover`), so `resetSession`/`hasSession` have nothing to report
+     * there.
+     */
+    isLegacySessionLostError(err) {
+        return (this.era?.kind === 'legacy' &&
+            this.transport instanceof StreamableHttpTransport &&
+            this.transport.hasSession() &&
+            err instanceof MCPHttpStatusError &&
+            err.status === 404);
+    }
+    /** Drop the stale session and run the legacy handshake again, from scratch. */
+    async reinitializeLegacySession() {
+        if (this.transport instanceof StreamableHttpTransport) {
+            this.transport.resetSession();
+        }
+        await this.performLegacyInitializeHandshake();
+    }
+    /**
+     * `request()`, with the legacy session recovery a live connection needs
+     * that the initial handshake does not: `connect()`'s own `initialize`
+     * call has no session yet to lose, so it goes through `request()`
+     * directly and never through here.
+     *
+     * At most one recovery attempt. A retry that fails the same way is not
+     * retried again — surfacing it is more honest than masking a second
+     * genuine failure as a transient one.
+     */
+    async requestWithSessionRecovery(method, params, options) {
+        try {
+            return await this.request(method, params, options);
+        }
+        catch (err) {
+            if (!this.isLegacySessionLostError(err))
+                throw err;
+            this.log.warn('MCP legacy session lost; re-initializing once before retrying', {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.connector.method': method,
+            });
+            await this.reinitializeLegacySession();
+            return await this.request(method, params, options);
+        }
+    }
+    /**
+     * Which era this peer speaks, probed once and remembered per origin (or
+     * per stdio command).
+     *
+     * Modern first. The wasted round trip against a legacy server is real
+     * and is the reason the cache exists; the alternative is worse than
+     * wasted latency, because a legacy server handed an era-ambiguous method
+     * processes it under legacy semantics and fails confusingly, where a
+     * probe fails cleanly and recovers.
+     */
+    async resolveEra() {
+        const resolution = await resolveMcpEra({
+            cache: this.eraCache,
+            key: this.eraCacheKey,
+            serverName: this.config.serverName,
+            // HTTP+SSE is the 2024-11-05 transport. An origin reached through
+            // it is legacy by the operator's own choice of transport, so the
+            // probe would spend a round trip learning what the config said.
+            probeSupported: this.config.transport.type !== 'http-sse',
+            probe: (version) => this.probeDiscover(version),
+        });
+        this.log.debug('MCP era resolved', {
+            'namzu.connector.server': this.config.serverName,
+            'namzu.connector.era': resolution.era.kind,
+            'namzu.connector.negotiated': resolution.era.version,
+            'namzu.connector.probes': resolution.probes,
+            'namzu.connector.cached': resolution.fromCache,
+        });
+        return resolution;
+    }
+    /**
+     * Ask the peer to describe itself, and report silence as an answer.
+     *
+     * Deliberately NOT `request()`. A probe differs from a request in the
+     * two ways that matter: a timeout is a legitimate outcome rather than a
+     * failure — the stdio spec says in so many words that a legacy server
+     * may not respond at all — and a probe that gives up must not send
+     * `notifications/cancelled`, because the peer it would be sent to is, by
+     * hypothesis, one that did not understand the request in the first
+     * place. Everything `request()` owns about cancellation ordering is left
+     * exactly as it is rather than taught a second mode.
+     */
+    probeDiscover(version) {
+        const id = this.nextRequestId++;
+        const envelope = buildEnvelope({
+            era: { kind: 'modern', version },
+            method: MCP_DISCOVER_METHOD,
+            params: {},
+            clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+            capabilities: this.config.capabilities ?? {},
+        });
+        const controller = new AbortController();
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (answer) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (this.pendingRequests.get(id) === entry)
+                    this.pendingRequests.delete(id);
+                resolve(answer);
+            };
+            const entry = {
+                resolve: (value) => finish({ kind: 'result', result: value }),
+                reject: (reason) => finish({ kind: 'error', error: reason }),
+                abort: (reason) => finish({ kind: 'error', error: reason }),
+            };
+            const timer = setTimeout(() => {
+                controller.abort(new Error('MCP era probe timed out'));
+                finish({ kind: 'timeout' });
+            }, this.eraProbeTimeoutMs);
+            timer.unref?.();
+            this.pendingRequests.set(id, entry);
+            try {
+                void this.transport
+                    .send({ jsonrpc: '2.0', id, method: MCP_DISCOVER_METHOD, params: envelope.params }, { signal: controller.signal, ...this.eraHeaderOptions(envelope.headers) })
+                    .catch((err) => finish({ kind: 'error', error: err }));
+            }
+            catch (err) {
+                finish({ kind: 'error', error: err });
+            }
+        });
+    }
+    /**
+     * Finish a connection that resolved modern, with no handshake at all.
+     *
+     * The modern era has no `initialize` and no `notifications/initialized`,
+     * so there is nothing here to await: the probe already carried the only
+     * round trip a modern connection needs. `MCPInitializeResult` is
+     * synthesised from the `DiscoverResult` so a host sees the same return
+     * shape whichever era resolved — the era is this client's business, not
+     * something every caller has to branch on.
+     */
+    completeModernConnection(resolution) {
+        const era = resolution.era;
+        if (era.kind !== 'modern') {
+            // Unreachable: only `connect()` calls this, and only on the modern
+            // arm. Narrowing rather than casting keeps that true by
+            // construction if a second call site is ever added.
+            throw new Error('completeModernConnection requires a modern era');
+        }
+        this.era = era;
+        const result = this.modernInitializeResult(era.version, resolution.discover);
+        this.serverInfo = result.serverInfo;
+        this.serverCapabilities = result.capabilities;
+        this.status = 'connected';
+        this.connectedAt = Date.now();
+        this.emitLifecycle({
+            type: 'mcp_client_connected',
+            clientId: this.id,
+            serverName: this.config.serverName,
+        });
+        const connectedAttributes = {
+            [NAMZU.SERVER_NAME]: result.serverInfo.name,
+        };
+        this.log.info('Connected to MCP server', connectedAttributes);
+        return result;
+    }
+    /**
+     * A `DiscoverResult` read as the `MCPInitializeResult` a host expects.
+     *
+     * `serverInfo` is a SHOULD on a discover result, not a MUST, and
+     * `MCPInitializeResult.serverInfo` is required — so a server that does
+     * not name itself is reported under the name the operator gave it.
+     * Inventing a placeholder like "unknown" would put a word in the
+     * server's mouth in the one field a person reads to identify it.
+     */
+    modernInitializeResult(version, discover) {
+        return {
+            protocolVersion: version,
+            capabilities: discover?.capabilities ?? {},
+            serverInfo: serverInfoFromDiscover(discover) ?? { name: this.config.serverName },
+        };
+    }
     async disconnect() {
         const reason = new Error('MCPClient disconnecting');
         this.abortCancellations(reason);
@@ -127,6 +425,16 @@ export class MCPClient {
     isConnected() {
         return this.status === 'connected';
     }
+    /**
+     * Which era and exact revision the last `connect()` negotiated.
+     *
+     * `undefined` before a connection has been negotiated. Which arm it
+     * lands on is the peer's answer, not a configuration: `connect()` probes
+     * for a modern server and falls back to the legacy handshake.
+     */
+    getEra() {
+        return this.era;
+    }
     getState() {
         return {
             id: this.id,
@@ -138,17 +446,150 @@ export class MCPClient {
             error: this.error,
         };
     }
+    /**
+     * Every tool this server publishes that this client is willing to expose.
+     *
+     * The second clause is new and it is the first place namzu refuses
+     * something a server offered. A tool whose `inputSchema` carries an
+     * invalid `x-mcp-header` annotation is excluded from the result, with the
+     * tool name and the reason logged — the spec's requirement, and the
+     * reason it is a requirement is that the annotation names a header this
+     * client would otherwise write from a value it cannot vouch for.
+     *
+     * It lives HERE rather than in `MCPToolDiscovery` or the tool adapter
+     * because the shipping CLI calls `listTools()` directly and never
+     * touches discovery: validating one layer up would exempt the one caller
+     * that matters most.
+     */
     async listTools(options) {
         this.requireConnected();
-        return await this.listAllPages('tools/list', 'tools', options);
+        const listed = await this.listAllPages('tools/list', 'tools', options);
+        return this.admitToolHeaderAnnotations(listed);
     }
+    /**
+     * Call one tool, and recover once from a server that says our mirrored
+     * headers disagree with its current schema.
+     *
+     * `-32020` (`HeaderMismatch`) means the `Mcp-Param-*` headers this client
+     * wrote are missing or wrong for the schema the server holds NOW — which
+     * a server can legitimately cause by changing a tool between the listing
+     * and the call. The spec's recovery is to re-read `tools/list` and retry
+     * the request once. Exactly once: the retry goes through `request()`
+     * rather than back through this method, so a second `-32020` surfaces to
+     * the caller instead of starting a third round trip.
+     */
     async callTool(name, args, options) {
         this.requireConnected();
-        const result = (await this.request('tools/call', {
-            name,
-            arguments: args ?? {},
-        }, options));
-        return result;
+        try {
+            return (await this.callToolDecoded(name, args ?? {}, options));
+        }
+        catch (err) {
+            if (!this.mirrorsParamHeaders() || !isHeaderMismatch(err))
+                throw err;
+            this.log.warn("MCP server rejected a call's mirrored headers; re-listing tools once", {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.mcp.tool': name,
+            });
+            await this.listTools(options);
+            return (await this.callToolDecoded(name, args ?? {}, options));
+        }
+    }
+    /**
+     * Does this connection mirror tool parameters into `Mcp-Param-*` headers?
+     *
+     * Conditioned on the TRANSPORT, not on the era, because that is how the
+     * spec conditions it: the feature belongs to Streamable HTTP, and a
+     * client on another transport may ignore `x-mcp-header` entirely. stdio
+     * has no headers to mirror into, and `http-sse` is the 2024-11-05
+     * transport, which predates the annotation by two years.
+     *
+     * The headers themselves are written only on a modern request — that is
+     * `buildEnvelope`'s doing, not this predicate's — but the VALIDATION runs
+     * in both eras on this transport, so a tool's admission does not silently
+     * change shape the day the server behind it stops answering `initialize`.
+     */
+    mirrorsParamHeaders() {
+        const type = this.config.transport.type;
+        return type === 'streamable_http' || type === 'streamable-http';
+    }
+    /**
+     * Drop the tools whose header annotations this client will not honour,
+     * and remember what the rest asked to mirror.
+     *
+     * One malformed definition must not deny the others, which is why this
+     * filters rather than throws: a server with fifty tools and one bad
+     * annotation stays a server with forty-nine usable tools.
+     */
+    admitToolHeaderAnnotations(tools) {
+        if (!this.mirrorsParamHeaders())
+            return tools;
+        const bindings = new Map();
+        const admitted = [];
+        for (const tool of tools) {
+            const verdict = validateMcpHeaderAnnotations(tool?.inputSchema);
+            const name = typeof tool?.name === 'string' ? tool.name : '(unnamed)';
+            if (!verdict.ok) {
+                this.log.warn('Excluded an MCP tool with an invalid x-mcp-header annotation', {
+                    'namzu.connector.server': this.config.serverName,
+                    'namzu.mcp.tool': name,
+                    'namzu.mcp.reason': verdict.reason,
+                });
+                continue;
+            }
+            if (verdict.bindings.length > 0)
+                bindings.set(name, verdict.bindings);
+            admitted.push(tool);
+        }
+        this.toolParamHeaders = bindings;
+        return admitted;
+    }
+    /**
+     * `tools/call`, resolved past the MRTR `resultType` envelope.
+     *
+     * Absent or `"complete"` is the ordinary path — unchanged from before
+     * this existed. `"input_required"` with nothing but a `requestState` is
+     * retried exactly once, echoing that state byte-for-byte under a NEW
+     * JSON-RPC id (a fresh `request()` call, which allocates one): the
+     * spec's own words are that the client MAY retry immediately when there
+     * is nothing for it to gather. Any other shape — `inputRequests` this
+     * client cannot satisfy, or a second `input_required` after the one
+     * retry — throws `MCPInputRequiredError` rather than looping or
+     * returning something that looks like success; `mcpToolToToolDefinition`
+     * catches it and turns it into a named, catchable `ToolResult` instead
+     * of letting it reach a caller as an unexplained rejection.
+     *
+     * `requestState` travels back as a top-level `requestState` param,
+     * alongside `name`/`arguments`, the same way `listAllPages` threads a
+     * `cursor` — the one continuation-style field this codebase already has
+     * a convention for.
+     */
+    async callToolDecoded(name, args, options) {
+        const raw = await this.requestWithSessionRecovery('tools/call', { name, arguments: args }, options);
+        const decoded = decodeResult(raw);
+        if (decoded.kind === 'complete')
+            return decoded.result;
+        const unsatisfiable = decoded.inputRequests !== undefined && decoded.inputRequests.length > 0;
+        if (!unsatisfiable && decoded.requestState !== undefined) {
+            this.log.info('MCP tool call asked for no new input; retrying once with echoed state', {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.connector.tool': name,
+            });
+            const retryRaw = await this.requestWithSessionRecovery('tools/call', { name, arguments: args, requestState: decoded.requestState }, options);
+            const retried = decodeResult(retryRaw);
+            if (retried.kind === 'complete')
+                return retried.result;
+            this.log.warn('MCP tool call required input again after the one automatic retry', {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.connector.tool': name,
+            });
+            throw new MCPInputRequiredError(retried.inputRequests ?? []);
+        }
+        this.log.warn('MCP tool call requires input this client cannot supply', {
+            'namzu.connector.server': this.config.serverName,
+            'namzu.connector.tool': name,
+            'namzu.connector.requested': (decoded.inputRequests ?? []).map((r) => r.method).join(', '),
+        });
+        throw new MCPInputRequiredError(decoded.inputRequests ?? []);
     }
     async listResources(options) {
         this.requireConnected();
@@ -156,7 +597,7 @@ export class MCPClient {
     }
     async readResource(uri, options) {
         this.requireConnected();
-        const result = (await this.request('resources/read', { uri }, options));
+        const result = (await this.requestWithSessionRecovery('resources/read', { uri }, options));
         return result.contents;
     }
     /**
@@ -187,7 +628,7 @@ export class MCPClient {
      */
     async getPrompt(name, args, options) {
         this.requireConnected();
-        const result = (await this.request('prompts/get', {
+        const result = (await this.requestWithSessionRecovery('prompts/get', {
             name,
             arguments: args ?? {},
         }, options));
@@ -221,7 +662,7 @@ export class MCPClient {
         const items = [];
         let cursor;
         for (let page = 1;; page++) {
-            const result = (await this.request(method, cursor === undefined ? {} : { cursor }, options));
+            const result = (await this.requestWithSessionRecovery(method, cursor === undefined ? {} : { cursor }, options));
             const batch = result[field];
             if (Array.isArray(batch))
                 items.push(...batch);
@@ -305,11 +746,19 @@ export class MCPClient {
         // Refuse before allocating an id or asking the transport to do work.
         options?.signal?.throwIfAborted();
         const id = this.nextRequestId++;
+        const envelope = buildEnvelope({
+            era: this.era,
+            method,
+            params,
+            clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+            capabilities: this.config.capabilities ?? {},
+            ...this.paramHeaderBindings(method, params),
+        });
         const message = {
             jsonrpc: '2.0',
             id,
             method,
-            params,
+            params: envelope.params,
         };
         const transportController = new AbortController();
         let issued = false;
@@ -353,7 +802,10 @@ export class MCPClient {
                 // longer owns this request and cannot replace the first cause.
                 transportController.abort(value);
             }
-            if (issued && method !== 'initialize' && (terminal === 'caller' || terminal === 'timeout')) {
+            if (issued &&
+                method !== 'initialize' &&
+                (terminal === 'caller' || terminal === 'timeout') &&
+                this.sendsCancellationNotification()) {
                 this.sendCancellation(id, terminal === 'caller' ? 'Caller cancelled request' : 'Request deadline expired');
             }
             return true;
@@ -391,6 +843,7 @@ export class MCPClient {
             issued = true;
             const sending = this.transport.send(message, {
                 signal: transportController.signal,
+                ...this.requestAuthorityHeaders(envelope.headers, options),
             });
             void sending.catch((err) => {
                 settleSendFailure(err);
@@ -401,8 +854,120 @@ export class MCPClient {
         }
         return result;
     }
+    /**
+     * `{ headers: {...} }` when the era produced any, `{}` otherwise —
+     * spread into a `send()` options object so a send with no era headers
+     * (a legacy era before 2025-06-18, and everything sent before an era is
+     * resolved) gets no `headers` key at all rather than one holding an
+     * empty object.
+     */
+    eraHeaderOptions(headers) {
+        return Object.keys(headers).length > 0 ? { headers } : {};
+    }
+    /**
+     * `{ paramHeaders }` for a `tools/call` whose tool asked for mirrored
+     * headers, `{}` for everything else — spread into the envelope input so
+     * every other request is built from exactly the object it was built from
+     * before this existed.
+     *
+     * Read from the last listing rather than passed down from `callTool`, so
+     * the bindings are the ones that came with the schema the caller was
+     * shown, whichever call site reached `request()`.
+     */
+    paramHeaderBindings(method, params) {
+        if (method !== 'tools/call' || typeof params.name !== 'string')
+            return {};
+        const bindings = this.toolParamHeaders.get(params.name);
+        return bindings === undefined ? {} : { paramHeaders: bindings };
+    }
+    /**
+     * `request()`'s full per-send header authority: the era's own headers
+     * from `buildEnvelope`, this call's `MCPRequestOptions.headers` merged
+     * over them — a collision resolves to the caller's value, except on the
+     * headers the protocol itself owns — and this call's `bearerToken`, if
+     * given, applied last as `Authorization` so it overrides a same-named
+     * header from either of the other two sources.
+     *
+     * **The exception.** `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name`
+     * are not decoration: each mirrors a value the same request carries in
+     * its body — the negotiated version in
+     * `_meta['io.modelcontextprotocol/protocolVersion']`, the method, the
+     * target's name — and a conforming modern server rejects a header that
+     * disagrees with what it mirrors (`-32020`, HeaderMismatch). Letting a
+     * caller's value win there would make the mismatched pair
+     * {@link buildEnvelope} exists to render unconstructible constructible
+     * again one layer up, and the failure would reach the host as an opaque
+     * 400 with nothing pointing at the header that caused it. So a caller
+     * header colliding with one of {@link CANONICAL_MCP_REQUEST_HEADERS} is
+     * refused and warn-logged, naming it — in EVERY era, including a legacy
+     * one old enough that {@link buildEnvelope} puts no headers of its own
+     * on this request. Matching ignores case, because HTTP field names are
+     * case-insensitive and `{ 'mcp-protocol-version': … }` alongside the
+     * era's `MCP-Protocol-Version` would otherwise reach the wire as one
+     * field holding both values, comma-joined.
+     *
+     * Every other header a caller sends is untouched, in both eras.
+     *
+     * `notify()` and `sendCancellation()` are internal, not caller-facing,
+     * so they carry era headers alone — only a public request the caller
+     * shaped can carry a per-call header or token.
+     *
+     * Returns `{}`, never `{ headers: undefined }`, when nothing applies, so
+     * the zero-option path stays the exact object shape `request()` sent
+     * before any of this existed.
+     */
+    requestAuthorityHeaders(eraHeaders, options) {
+        const hasEraHeaders = Object.keys(eraHeaders).length > 0;
+        if (!hasEraHeaders && !options?.headers && !options?.bearerToken)
+            return {};
+        const headers = { ...eraHeaders };
+        const protocolOwned = new Set([
+            ...CANONICAL_MCP_REQUEST_HEADERS,
+            ...Object.keys(eraHeaders).map((name) => name.toLowerCase()),
+        ]);
+        for (const [name, value] of Object.entries(options?.headers ?? {})) {
+            if (protocolOwned.has(name.toLowerCase())) {
+                this.log.warn('Refused a per-request MCP header the protocol owns', {
+                    'namzu.connector.server': this.config.serverName,
+                    'namzu.mcp.header': name,
+                    'namzu.mcp.era': this.era?.kind ?? 'unresolved',
+                });
+                continue;
+            }
+            headers[name] = value;
+        }
+        if (options?.bearerToken)
+            headers.Authorization = `Bearer ${options.bearerToken}`;
+        return { headers };
+    }
+    /**
+     * Does a cancelled request on THIS connection owe the peer a
+     * `notifications/cancelled`?
+     *
+     * Everywhere except modern Streamable HTTP, yes. There, no: closing the
+     * SSE response stream IS the cancellation signal, so the notification is
+     * a second, redundant POST — and one the spec does not ask for. stdio
+     * has no stream to close, so it still sends it, in every era.
+     *
+     * This predicate is the ONLY thing the modern era changes about
+     * cancellation. The ordering guarantees in `request()` — who owns
+     * cleanup, which cause wins, when the transport is aborted — are
+     * untouched.
+     */
+    sendsCancellationNotification() {
+        if (this.era?.kind !== 'modern')
+            return true;
+        return this.config.transport.type === 'stdio';
+    }
     /** Ask the peer to stop without letting cleanup become another hanging request. */
     sendCancellation(id, reason) {
+        const envelope = buildEnvelope({
+            era: this.era,
+            method: 'notifications/cancelled',
+            params: { requestId: id, reason },
+            clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+            capabilities: this.config.capabilities ?? {},
+        });
         const controller = new AbortController();
         this.cancellationControllers.add(controller);
         const timer = setTimeout(() => {
@@ -417,8 +982,8 @@ export class MCPClient {
             sending = this.transport.send({
                 jsonrpc: '2.0',
                 method: 'notifications/cancelled',
-                params: { requestId: id, reason },
-            }, { signal: controller.signal });
+                params: envelope.params,
+            }, { signal: controller.signal, ...this.eraHeaderOptions(envelope.headers) });
         }
         catch (err) {
             clearTimeout(timer);
@@ -464,19 +1029,26 @@ export class MCPClient {
         }
     }
     async notify(method, params) {
+        const envelope = buildEnvelope({
+            era: this.era,
+            method,
+            params,
+            clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+            capabilities: this.config.capabilities ?? {},
+        });
         const message = {
             jsonrpc: '2.0',
             method,
-            params,
+            params: envelope.params,
         };
-        await this.transport.send(message);
+        await this.transport.send(message, this.eraHeaderOptions(envelope.headers));
     }
     handleMessage(message) {
         if (message.id !== undefined) {
             const pending = this.pendingRequests.get(message.id);
             if (pending) {
                 if (message.error) {
-                    pending.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`));
+                    pending.reject(protocolErrorFromReply(message.error));
                 }
                 else {
                     pending.resolve(message.result);