kritya 0.8.15-beta → 0.8.17-beta

package/dist/mcp/client.js

@@ -10,7 +10,8 @@ import { isPrivateOrLoopbackHost } from "../net/urlSafety.js";
 import { checkToolsShape, serverFingerprint } from "../trust/mcpTrust.js";
 import { probeStdioEra, probeHttpEra } from "./eraDetect.js";
 import { ModernMcpConnection } from "./clientModern.js";
-import { ModernHttpTransport, ReusedProcessTransport } from "./transportModern.js";
+import { ModernHttpTransport, ReusedProcessTransport, validateToolHeaders, } from "./transportModern.js";
+import { checkSchemaSafety } from "./schemaSafety.js";
 /**
  * Thrown when a server's live tool shape no longer matches what was recorded
  * the first time its config was trusted — see checkToolsShape.
@@ -659,6 +660,53 @@ function exposedToolName(server, toolName) {
     const suffix = `_${shortHash(identity)}`;
     return base.slice(0, MAX_TOOL_NAME_LEN - suffix.length) + suffix;
 }
+/**
+ * Sub-project 3 (`x-mcp-header` parameter mirroring, HTTP only): validate
+ * every modern tool's `inputSchema` for `x-mcp-header` annotations and drop
+ * any tool with an invalid one, per spec ("clients MUST exclude the invalid
+ * tool from the result of tools/list"). A valid tool's resolved header map
+ * is registered on the transport so `tools/call` can mirror argument values
+ * into `Mcp-Param-{Name}` headers later — see `ModernHttpTransport.
+ * setToolHeaderMap`/`send`. Logged the same way other "skip with a warning"
+ * MCP failures are (`process.stderr.write("kritya: ...")`).
+ */
+function filterHeaderAnnotatedTools(server, specs, transport) {
+    const kept = [];
+    for (const spec of specs) {
+        const result = validateToolHeaders(spec.inputSchema);
+        if (!result.ok) {
+            process.stderr.write(`kritya: MCP server "${server}" tool "${spec.name}" excluded — invalid x-mcp-header ` +
+                `annotation: ${result.reason}\n`);
+            continue;
+        }
+        transport.setToolHeaderMap(spec.name, result.entries);
+        kept.push(spec);
+    }
+    return kept;
+}
+/**
+ * JSON-Schema safety hardening: exclude any tool whose declared `inputSchema`
+ * fails `checkSchemaSafety` (an unsupported dialect, a `$ref` that would
+ * require a network fetch, or a schema that busts the depth/node-count
+ * bounds) before it's ever exposed to the model or the user. Applies to
+ * every MCP tool from every server — legacy and modern, stdio and HTTP —
+ * unlike `filterHeaderAnnotatedTools`, which is HTTP-only and checks a
+ * narrower, unrelated thing. Logged the same way other "skip with a
+ * warning" MCP failures are.
+ */
+function filterSchemaSafeTools(server, specs) {
+    const kept = [];
+    for (const spec of specs) {
+        const result = checkSchemaSafety(spec.inputSchema);
+        if (!result.ok) {
+            process.stderr.write(`kritya: MCP server "${server}" tool "${spec.name}" excluded — unsafe inputSchema: ` +
+                `${result.reason}\n`);
+            continue;
+        }
+        kept.push(spec);
+    }
+    return kept;
+}
 /**
  * Connect to all configured MCP servers and return their tools as ToolDefs.
  * Resilient: a server that fails to start is skipped with a warning (and shows
@@ -728,12 +776,20 @@ export async function connectServer(name, cfg, trace) {
             throw new Error(`server "${name}" sets both "command" and "url"; pick one`);
         }
         let modernConn;
+        // Set only for the modern+HTTP case — the one combination x-mcp-header
+        // mirroring applies to (stdio MAY ignore it per spec, and legacy HTTP
+        // never speaks the modern per-request wire format at all).
+        let modernHttpTransport;
         if (cfg.url) {
             assertSafeUrl(name, cfg.url);
             const probe = await probeHttpEra(cfg.url, cfg.headers ?? {});
             if (probe.era === "modern") {
                 if (probe.discover) {
-                    modernConn = new ModernMcpConnection(name, new ModernHttpTransport(cfg.url, cfg.headers ?? {}));
+                    modernHttpTransport = new ModernHttpTransport(cfg.url, cfg.headers ?? {});
+                    modernConn = new ModernMcpConnection(name, modernHttpTransport, workspace, {
+                        onSampling: trace?.onSampling,
+                        onElicitation: trace?.onElicitation,
+                    });
                 }
                 else {
                     throw new Error(`server "${name}" speaks the modern MCP protocol but rejected protocol version ` +
@@ -752,7 +808,7 @@ export async function connectServer(name, cfg, trace) {
                 // speak our version, producing a misleading "method not found"-style
                 // error instead of naming the real problem.
                 if (probe.process) {
-                    modernConn = new ModernMcpConnection(name, new ReusedProcessTransport(probe.process));
+                    modernConn = new ModernMcpConnection(name, new ReusedProcessTransport(probe.process), workspace, { onSampling: trace?.onSampling, onElicitation: trace?.onElicitation });
                 }
                 else {
                     throw new Error(`server "${name}" speaks the modern MCP protocol but rejected protocol version ` +
@@ -767,7 +823,10 @@ export async function connectServer(name, cfg, trace) {
                     onElicitation: trace?.onElicitation,
                 });
         const listed = await conn.initialize();
-        const specs = listed.tools;
+        const headerFiltered = modernHttpTransport
+            ? filterHeaderAnnotatedTools(name, listed.tools, modernHttpTransport)
+            : listed.tools;
+        const specs = filterSchemaSafeTools(name, headerFiltered);
         const shape = checkToolsShape(serverFingerprint(cfg), specs, trace?.mcpTrustFile);
         if (!shape.ok)
             throw new McpShapeChangedError(name);
@@ -925,7 +984,7 @@ export function replaceStatus(status) {
  * ElicitationFields the UI can render. Anything with nesting or an
  * unrecognized type is rejected outright, rather than guessed at.
  */
-function toElicitationFields(schema) {
+export function toElicitationFields(schema) {
     const props = schema.properties ?? {};
     return Object.entries(props).map(([name, prop]) => {
         const label = prop.title ?? name;

package/dist/mcp/clientModern.js

@@ -1,4 +1,7 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { modernMeta } from "./eraDetect.js";
+import { toElicitationFields } from "./client.js";
 /**
  * Split the same way legacy McpConnection splits its timeouts: connect-time
  * calls (the three list calls during initialize()) get a short ceiling since
@@ -7,23 +10,38 @@ import { modernMeta } from "./eraDetect.js";
  */
 const CONNECT_TIMEOUT_MS = 15_000;
 const CALL_TIMEOUT_MS = 120_000;
+/** MRTR round-trip ceiling — a misbehaving server can't loop us forever. */
+const MAX_MRTR_ROUNDS = 10;
 /**
  * Modern (2026-07-28+) MCP client: no `initialize`, every request carries
  * its own `_meta`. Implements the same minimal surface as the legacy
  * `McpConnection` (see docs/superpowers/specs/2026-08-30-mcp-modern-protocol-design.md)
- * so `connectServer()` can use either interchangeably. `resultType:
- * "input_required"` (MRTR — sampling/elicitation/roots) is rejected with a
- * clear error here; Sub-project 2 replaces this with the real retry loop.
+ * so `connectServer()` can use either interchangeably.
+ *
+ * MRTR (sampling/elicitation/roots): a modern server never sends its own
+ * JSON-RPC request for these — instead a response comes back with
+ * `resultType: "input_required"` and an `inputRequests` map. `requestWithMRTR`
+ * answers each entry (via `answerInputRequired`, modeled on legacy's
+ * `onServerRequest`/`McpConnection.answerInputRequired`) and resends the
+ * original request with `inputResponses` attached, repeating until the
+ * server returns `resultType: "complete"` (or errors) — bounded by
+ * `MAX_MRTR_ROUNDS` so a misbehaving server can't loop forever.
  */
 export class ModernMcpConnection {
     name;
     transport;
+    workspace;
+    options;
     nextId = 1;
     pending = new Map();
     closed = false;
-    constructor(name, transport) {
+    constructor(name, transport, 
+    /** The workspace this session is working on — what `roots/list` reports. */
+    workspace = process.cwd(), options = {}) {
         this.name = name;
         this.transport = transport;
+        this.workspace = workspace;
+        this.options = options;
         transport.onMessage = (msg) => this.onMessage(msg);
         transport.onError = (err) => this.fail(new Error(`MCP server "${name}": ${err.message}`));
     }
@@ -50,6 +68,16 @@ export class ModernMcpConnection {
         else
             p.resolve(msg.result);
     }
+    /** The capabilities this connection can actually back, for `_meta.clientCapabilities` —
+     *  only claim what a callback is actually configured to answer, plus roots (always local). */
+    clientCapabilities() {
+        const caps = { roots: {} };
+        if (this.options.onSampling)
+            caps.sampling = {};
+        if (this.options.onElicitation)
+            caps.elicitation = {};
+        return caps;
+    }
     request(method, params, timeoutMs, signal) {
         if (this.closed)
             return Promise.reject(new Error(`MCP server "${this.name}" is not running`));
@@ -61,7 +89,12 @@ export class ModernMcpConnection {
             }, timeoutMs);
             this.pending.set(id, { resolve, reject, timer });
             this.transport
-                .send({ jsonrpc: "2.0", id, method, params: { ...params, _meta: modernMeta() } }, timeoutMs, signal)
+                .send({
+                jsonrpc: "2.0",
+                id,
+                method,
+                params: { ...params, _meta: modernMeta(this.clientCapabilities()) },
+            }, timeoutMs, signal)
                 .catch((err) => {
                 const p = this.pending.get(id);
                 if (!p)
@@ -72,31 +105,105 @@ export class ModernMcpConnection {
             });
         });
     }
-    /** Unwrap a modern result's resultType, throwing for input_required (MRTR — Sub-project 2). */
-    unwrap(result) {
-        const r = result;
-        if (r.resultType === "input_required") {
-            throw new Error(`MCP server "${this.name}" requires an interactive capability (sampling, elicitation, ` +
-                `or roots) that modern-mode kritya does not yet support`);
-        }
-        if (r.resultType !== undefined && r.resultType !== "complete") {
+    /**
+     * Send `method`/`params`, answering any `input_required` rounds (MRTR) and
+     * resending with `inputResponses` until the server completes or errors.
+     */
+    async requestWithMRTR(method, params, timeoutMs, signal) {
+        let currentParams = params;
+        for (let round = 0; round < MAX_MRTR_ROUNDS; round++) {
+            const result = await this.request(method, currentParams, timeoutMs, signal);
+            const r = result;
+            if (r.resultType === undefined || r.resultType === "complete") {
+                return result;
+            }
+            if (r.resultType === "input_required") {
+                const inputRequired = result;
+                const inputResponses = await this.answerInputRequired(inputRequired.inputRequests ?? {});
+                currentParams = { ...params, inputResponses };
+                continue;
+            }
             throw new Error(`MCP server "${this.name}" returned an unrecognized resultType "${r.resultType}"`);
         }
-        return result;
+        throw new Error(`MCP server "${this.name}" requested input more than ${MAX_MRTR_ROUNDS} times in a row for ` +
+            `"${method}" — giving up`);
+    }
+    /**
+     * Answer every `inputRequests` entry (sampling/elicitation/roots), same
+     * capability dispatch and field/result shapes as legacy's
+     * `McpConnection.onServerRequest` — but building an `inputResponses` map
+     * to send back in the retry rather than replying to a server-sent request.
+     */
+    async answerInputRequired(inputRequests) {
+        const inputResponses = {};
+        for (const [key, req] of Object.entries(inputRequests)) {
+            if (req.method === "roots/list") {
+                inputResponses[key] = {
+                    roots: [{ uri: pathToFileURL(this.workspace).href, name: path.basename(this.workspace) }],
+                };
+                continue;
+            }
+            if (req.method === "sampling/createMessage") {
+                if (!this.options.onSampling) {
+                    throw new Error(`MCP server "${this.name}" requires sampling, but sampling is not supported here`);
+                }
+                const p = req.params;
+                const samplingReq = {
+                    server: this.name,
+                    messages: (p?.messages ?? []).map((m) => ({
+                        role: m.role === "assistant" ? "assistant" : "user",
+                        content: m.content?.text ?? "",
+                    })),
+                    systemPrompt: p?.systemPrompt,
+                    maxTokens: p?.maxTokens,
+                };
+                const result = await this.options.onSampling(this.name, samplingReq);
+                if (!result.ok) {
+                    inputResponses[key] = { error: { code: -32603, message: result.reason } };
+                    continue;
+                }
+                inputResponses[key] = {
+                    role: "assistant",
+                    content: { type: "text", text: result.content },
+                    model: result.model,
+                    stopReason: result.stopReason,
+                };
+                continue;
+            }
+            if (req.method === "elicitation/create") {
+                if (!this.options.onElicitation) {
+                    throw new Error(`MCP server "${this.name}" requires elicitation, but elicitation is not supported here`);
+                }
+                const p = req.params;
+                let fields;
+                try {
+                    fields = toElicitationFields(p?.requestedSchema ?? {});
+                }
+                catch (err) {
+                    throw new Error(`MCP server "${this.name}" sent an unsupported elicitation schema: ` +
+                        (err instanceof Error ? err.message : String(err)), { cause: err });
+                }
+                const result = await this.options.onElicitation(this.name, p?.message ?? "", fields);
+                inputResponses[key] = result;
+                continue;
+            }
+            throw new Error(`MCP server "${this.name}" requires unsupported input method "${req.method}"`);
+        }
+        return inputResponses;
     }
     async initialize() {
-        const listed = this.unwrap(await this.request("tools/list", {}, CONNECT_TIMEOUT_MS));
+        const listed = await this.requestWithMRTR("tools/list", {}, CONNECT_TIMEOUT_MS);
         let prompts = [];
         let resources = [];
         try {
-            const p = this.unwrap(await this.request("prompts/list", {}, CONNECT_TIMEOUT_MS));
+            const p = await this.requestWithMRTR("prompts/list", {}, CONNECT_TIMEOUT_MS);
             prompts = p.prompts ?? [];
         }
         catch {
             // prompts unsupported by this server — non-fatal, same as legacy behavior
         }
         try {
-            const r = this.unwrap(await this.request("resources/list", {}, CONNECT_TIMEOUT_MS));
+            const r = await this.requestWithMRTR("resources/list", {}, CONNECT_TIMEOUT_MS);
             resources = r.resources ?? [];
         }
         catch {
@@ -105,7 +212,7 @@ export class ModernMcpConnection {
         return { tools: listed.tools ?? [], prompts, resources };
     }
     async getPrompt(name, args) {
-        const result = this.unwrap(await this.request("prompts/get", { name, arguments: args }, CALL_TIMEOUT_MS));
+        const result = await this.requestWithMRTR("prompts/get", { name, arguments: args }, CALL_TIMEOUT_MS);
         const messages = result.messages ?? [];
         const multiRole = new Set(messages.map((m) => m.role ?? "user")).size > 1;
         return messages
@@ -117,7 +224,7 @@ export class ModernMcpConnection {
             .join("\n\n");
     }
     async readResource(uri) {
-        const result = this.unwrap(await this.request("resources/read", { uri }, CALL_TIMEOUT_MS));
+        const result = await this.requestWithMRTR("resources/read", { uri }, CALL_TIMEOUT_MS);
         return (result.contents ?? []).map((c) => c.text ?? "").join("\n");
     }
     async callTool(toolName, args, signal, _tasksEnabled, _onProgress) {
@@ -125,7 +232,7 @@ export class ModernMcpConnection {
         // scope"); the params exist only so this signature matches
         // McpConnection.callTool's, which callers invoke uniformly through the
         // McpConnection | ModernMcpConnection union built in Task 6.
-        const result = this.unwrap(await this.request("tools/call", { name: toolName, arguments: args }, CALL_TIMEOUT_MS, signal));
+        const result = await this.requestWithMRTR("tools/call", { name: toolName, arguments: args }, CALL_TIMEOUT_MS, signal);
         const text = (result.content ?? [])
             .filter((b) => b.type === "text")
             .map((b) => b.text ?? "")

package/dist/mcp/schemaSafety.js

@@ -0,0 +1,178 @@
+/**
+ * JSON-Schema dialect / `$ref` / composition-keyword safety hardening for
+ * MCP-declared tool `inputSchema`s.
+ *
+ * kritya never runs a JSON Schema *validator* against tool-call arguments —
+ * the model fills tool arguments and kritya forwards `inputSchema` to the
+ * provider's function-calling API as opaque JSON. What kritya does expose,
+ * unfiltered, is every MCP-declared tool's `inputSchema` to the agent and to
+ * the user. This module is the registration-time gate that keeps an unsafe
+ * schema from ever reaching either: see the spec's "JSON Schema Usage"
+ * section (2026-07-28/basic) for the three requirements this implements.
+ *
+ * This is a separate, general-purpose check from `validateToolHeaders` in
+ * transportModern.ts, which walks a schema for a narrow, HTTP-only purpose
+ * (finding/validating `x-mcp-header` annotations) and only runs for
+ * modern+HTTP servers. This module applies to every tool from every server,
+ * legacy or modern, stdio or HTTP.
+ */
+/**
+ * Dialect strings accepted as "JSON Schema 2020-12", the spec's default and
+ * required dialect. The canonical URI is
+ * "https://json-schema.org/draft/2020-12/schema"; real-world schemas vary in
+ * small, harmless ways (a trailing slash, a trailing `#` fragment, or the
+ * legacy `http://` scheme some tooling still emits for a `https://`-canonical
+ * URI), so this list is deliberately a little lenient about exact string
+ * matching without accepting anything that names a genuinely different
+ * dialect (draft-07, draft-04, an unrecognized string, etc.).
+ */
+const ACCEPTED_2020_12_DIALECTS = new Set([
+    "https://json-schema.org/draft/2020-12/schema",
+    "https://json-schema.org/draft/2020-12/schema#",
+    "https://json-schema.org/draft/2020-12/schema/",
+    "http://json-schema.org/draft/2020-12/schema",
+    "http://json-schema.org/draft/2020-12/schema#",
+    "http://json-schema.org/draft/2020-12/schema/",
+]);
+/**
+ * Bounds on the untrusted-schema walk below, in the same spirit as (and with
+ * the same values as) validateToolHeaders's walk in transportModern.ts. A
+ * malicious or buggy server's inputSchema must not be able to hang or crash
+ * kritya, or run a validator out of memory, while it's inspected.
+ */
+const MAX_SCHEMA_DEPTH = 50;
+const MAX_SCHEMA_NODES = 5000;
+const COMPOSITION_KEYWORDS = ["oneOf", "anyOf", "allOf"];
+const CONDITIONAL_KEYWORDS = ["if", "then", "else"];
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** True when a `$ref` value would require a network fetch to resolve. */
+function isNetworkRef(ref) {
+    try {
+        const url = new URL(ref);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        // Not an absolute URI at all (e.g. "#/$defs/foo", a relative path) — no
+        // network fetch is implied.
+        return false;
+    }
+}
+/**
+ * Check one MCP tool's declared `inputSchema` (or `outputSchema`, or any
+ * other JSON-Schema-shaped value) for the three safety requirements the MCP
+ * spec calls out under "JSON Schema Usage":
+ *
+ * 1. Dialect: an absent `$schema` defaults to 2020-12 (fine); a `$schema`
+ *    naming anything other than 2020-12 is rejected, since kritya only
+ *    supports the required dialect today.
+ * 2. `$ref` resolution: kritya never dereferences a remote `$ref` (there is
+ *    no such code anywhere in this codebase, and this check doesn't add
+ *    any) — so a `$ref` that names an http(s) URI is rejected outright
+ *    rather than silently treated as permissive. A local pointer (`#...`)
+ *    is normal same-document JSON Schema and is left alone.
+ * 3. Bounds: the walk into `properties`, `items`/`prefixItems`,
+ *    `oneOf`/`anyOf`/`allOf`, `not`, `if`/`then`/`else`, and
+ *    `$defs`/`definitions` is capped on depth and total node count, so a
+ *    pathological schema can't act as a DoS vector.
+ */
+export function checkSchemaSafety(schema) {
+    if (!isPlainObject(schema))
+        return { ok: true };
+    const dialect = schema["$schema"];
+    if (dialect !== undefined) {
+        if (typeof dialect !== "string") {
+            return { ok: false, reason: `"$schema" must be a string, got ${typeof dialect}` };
+        }
+        if (!ACCEPTED_2020_12_DIALECTS.has(dialect)) {
+            return {
+                ok: false,
+                reason: `unsupported JSON Schema dialect "${dialect}" — kritya only supports 2020-12`,
+            };
+        }
+    }
+    let nodeCount = 0;
+    function visit(node, depth) {
+        if (!isPlainObject(node))
+            return undefined;
+        nodeCount++;
+        if (nodeCount > MAX_SCHEMA_NODES) {
+            return `inputSchema exceeds the maximum node count (${MAX_SCHEMA_NODES})`;
+        }
+        if (depth > MAX_SCHEMA_DEPTH) {
+            return `inputSchema exceeds the maximum nesting depth (${MAX_SCHEMA_DEPTH})`;
+        }
+        if (Object.prototype.hasOwnProperty.call(node, "$ref")) {
+            const ref = node["$ref"];
+            if (typeof ref === "string" && isNetworkRef(ref)) {
+                return (`"$ref" resolves to a network URI ("${ref}") — kritya never dereferences a remote ` +
+                    `$ref, so this schema can't be validated`);
+            }
+        }
+        if (isPlainObject(node.properties)) {
+            for (const val of Object.values(node.properties)) {
+                const err = visit(val, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        if ("items" in node) {
+            const items = node.items;
+            if (Array.isArray(items)) {
+                for (const it of items) {
+                    const err = visit(it, depth + 1);
+                    if (err)
+                        return err;
+                }
+            }
+            else {
+                const err = visit(items, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        if (Array.isArray(node.prefixItems)) {
+            for (const it of node.prefixItems) {
+                const err = visit(it, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        for (const kw of COMPOSITION_KEYWORDS) {
+            if (Array.isArray(node[kw])) {
+                for (const sub of node[kw]) {
+                    const err = visit(sub, depth + 1);
+                    if (err)
+                        return err;
+                }
+            }
+        }
+        if ("not" in node) {
+            const err = visit(node.not, depth + 1);
+            if (err)
+                return err;
+        }
+        for (const kw of CONDITIONAL_KEYWORDS) {
+            if (kw in node) {
+                const err = visit(node[kw], depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        for (const defsKey of ["$defs", "definitions"]) {
+            if (isPlainObject(node[defsKey])) {
+                for (const val of Object.values(node[defsKey])) {
+                    const err = visit(val, depth + 1);
+                    if (err)
+                        return err;
+                }
+            }
+        }
+        return undefined;
+    }
+    const err = visit(schema, 0);
+    if (err)
+        return { ok: false, reason: err };
+    return { ok: true };
+}

package/dist/mcp/transportModern.js

@@ -31,6 +31,192 @@ export function encodeHeaderValue(value) {
         return value;
     return `=?base64?${Buffer.from(value, "utf8").toString("base64")}?=`;
 }
+// ---------------------------------------------------------------------------
+// x-mcp-header parameter mirroring (Sub-project 3, HTTP only)
+//
+// See /specification/2026-07-28/basic/transports/streamable-http, "Custom
+// Headers from Tool Parameters". A server MAY annotate a primitive tool
+// parameter with `x-mcp-header: "Name"` inside `inputSchema`; a conforming
+// client mirrors that argument's value into an `Mcp-Param-{Name}` header on
+// `tools/call`. This is entirely a client-side, HTTP-transport-only concern
+// (stdio MAY ignore it) — none of it touches `ModernMcpConnection`'s
+// request/MRTR internals.
+// ---------------------------------------------------------------------------
+/** `1*tchar` per RFC 9110 §5.1 — the token syntax HTTP field names must satisfy. */
+const TCHAR_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * Bounds on the untrusted-schema walk below: a malicious or buggy server's
+ * `inputSchema` must not be able to hang or crash the client while we scan
+ * it for `x-mcp-header` annotations. Either bound being exceeded rejects the
+ * schema (same as an invalid annotation — the whole tool is excluded).
+ */
+const MAX_SCHEMA_DEPTH = 50;
+const MAX_SCHEMA_NODES = 5000;
+/** Validate one `x-mcp-header` value against every constraint the spec lists. */
+function checkHeaderName(name) {
+    if (name.length === 0)
+        return `x-mcp-header value must not be empty`;
+    for (let i = 0; i < name.length; i++) {
+        const code = name.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f) {
+            return `x-mcp-header value "${name}" contains a control character`;
+        }
+    }
+    if (!TCHAR_RE.test(name)) {
+        return `x-mcp-header value "${name}" is not a valid HTTP field-name token (RFC 9110 §5.1)`;
+    }
+    return undefined;
+}
+const COMPOSITION_KEYWORDS = ["oneOf", "anyOf", "allOf"];
+const CONDITIONAL_KEYWORDS = ["if", "then", "else"];
+/**
+ * Walk a tool's `inputSchema` looking for `x-mcp-header` annotations,
+ * validating every constraint from the spec's Schema Extension section:
+ * non-empty, HTTP token syntax, no control chars, case-insensitively unique,
+ * primitive type only, and statically reachable from the root via a chain of
+ * only `properties` keys (no `items`, composition/conditional keywords, or
+ * `$ref` anywhere in the path). Bounded recursion/node-count guards against
+ * a pathological schema from an untrusted server.
+ *
+ * Returns every valid annotation found, or the first reason the whole tool
+ * must be rejected (per spec: one invalid annotation invalidates the tool).
+ */
+export function validateToolHeaders(inputSchema) {
+    const entries = [];
+    let nodeCount = 0;
+    function visit(node, path, reachable, depth) {
+        if (node === null || typeof node !== "object" || Array.isArray(node))
+            return undefined;
+        nodeCount++;
+        if (nodeCount > MAX_SCHEMA_NODES)
+            return `inputSchema exceeds the maximum node count (${MAX_SCHEMA_NODES})`;
+        if (depth > MAX_SCHEMA_DEPTH)
+            return `inputSchema exceeds the maximum nesting depth (${MAX_SCHEMA_DEPTH})`;
+        const obj = node;
+        if (Object.prototype.hasOwnProperty.call(obj, "x-mcp-header")) {
+            const raw = obj["x-mcp-header"];
+            if (typeof raw !== "string")
+                return `x-mcp-header must be a string`;
+            if (!reachable) {
+                return (`x-mcp-header "${raw}" is not statically reachable from the schema root via a ` +
+                    `chain of only "properties" keys`);
+            }
+            if (Object.prototype.hasOwnProperty.call(obj, "$ref")) {
+                return (`x-mcp-header "${raw}" is co-located with "$ref" on the same schema node; the ` +
+                    `resolved shape comes from the ref target, so this annotation is not statically ` +
+                    `reachable`);
+            }
+            const nameErr = checkHeaderName(raw);
+            if (nameErr)
+                return nameErr;
+            const type = obj["type"];
+            if (type !== "string" && type !== "integer" && type !== "boolean") {
+                return (`x-mcp-header "${raw}" is applied to a property of type ` +
+                    `${typeof type === "string" ? `"${type}"` : "unknown"}, but only string/integer/boolean are permitted`);
+            }
+            entries.push({ path, header: raw });
+        }
+        if (obj.properties && typeof obj.properties === "object" && !Array.isArray(obj.properties)) {
+            for (const [key, val] of Object.entries(obj.properties)) {
+                const err = visit(val, [...path, key], reachable, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        if ("items" in obj) {
+            const items = obj.items;
+            if (Array.isArray(items)) {
+                for (const it of items) {
+                    const err = visit(it, path, false, depth + 1);
+                    if (err)
+                        return err;
+                }
+            }
+            else {
+                const err = visit(items, path, false, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        if (Array.isArray(obj.prefixItems)) {
+            for (const it of obj.prefixItems) {
+                const err = visit(it, path, false, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        for (const kw of COMPOSITION_KEYWORDS) {
+            if (Array.isArray(obj[kw])) {
+                for (const sub of obj[kw]) {
+                    const err = visit(sub, path, false, depth + 1);
+                    if (err)
+                        return err;
+                }
+            }
+        }
+        if ("not" in obj) {
+            const err = visit(obj.not, path, false, depth + 1);
+            if (err)
+                return err;
+        }
+        for (const kw of CONDITIONAL_KEYWORDS) {
+            if (kw in obj) {
+                const err = visit(obj[kw], path, false, depth + 1);
+                if (err)
+                    return err;
+            }
+        }
+        return undefined;
+    }
+    const err = visit(inputSchema, [], true, 0);
+    if (err)
+        return { ok: false, reason: err };
+    const seenLower = new Set();
+    for (const e of entries) {
+        const lower = e.header.toLowerCase();
+        if (seenLower.has(lower)) {
+            return {
+                ok: false,
+                reason: `x-mcp-header value "${e.header}" collides case-insensitively with another property in the same inputSchema`,
+            };
+        }
+        seenLower.add(lower);
+    }
+    return { ok: true, entries };
+}
+/**
+ * Read the value at each annotated property's exact path in a `tools/call`
+ * request's arguments, convert it per the spec's Value Encoding type-
+ * conversion rules, and encode it via `encodeHeaderValue`. A `null` value or
+ * an absent property is omitted entirely (not sent as an empty header), per
+ * the "Server Behavior for Custom Headers" table.
+ */
+export function buildParamHeaders(entries, args) {
+    const headers = {};
+    for (const { path, header } of entries) {
+        let cur = args;
+        for (const key of path) {
+            if (cur === null || typeof cur !== "object" || Array.isArray(cur)) {
+                cur = undefined;
+                break;
+            }
+            cur = cur[key];
+        }
+        if (cur === undefined || cur === null)
+            continue;
+        let str;
+        if (typeof cur === "string")
+            str = cur;
+        else if (typeof cur === "boolean")
+            str = cur ? "true" : "false";
+        else if (typeof cur === "number" && Number.isInteger(cur))
+            str = String(cur);
+        else
+            continue; // schema promised a primitive; a non-conforming value is skipped, not sent malformed
+        headers[`mcp-param-${header.toLowerCase()}`] = encodeHeaderValue(str);
+    }
+    return headers;
+}
 /** Pull the `Mcp-Name` source value (params.name or params.uri) for a request, if any. */
 function mcpNameFor(msg) {
     const params = msg.params;
@@ -53,11 +239,27 @@ export class ModernHttpTransport {
     onMessage = () => { };
     onError = () => { };
     oauth;
+    /** Per-tool `x-mcp-header` maps, set at tool-registration time (see client.ts). */
+    toolHeaderMaps = new Map();
     constructor(url, headers) {
         this.url = url;
         this.headers = headers;
         this.oauth = new OAuthSession(url);
     }
+    /**
+     * Record a tool's valid `x-mcp-header` annotations (schema-path → header
+     * name), computed once at `tools/list` time by `validateToolHeaders`.
+     * `send()` consults this map on every `tools/call` for that tool name to
+     * mirror argument values into `Mcp-Param-{Name}` headers, without
+     * `ModernMcpConnection`'s request/MRTR internals needing to know about
+     * `x-mcp-header` at all.
+     */
+    setToolHeaderMap(toolName, entries) {
+        if (entries.length === 0)
+            this.toolHeaderMaps.delete(toolName);
+        else
+            this.toolHeaderMaps.set(toolName, entries);
+    }
     async buildHeaders(msg) {
         const headers = {
             ...this.headers,
@@ -69,6 +271,13 @@ export class ModernHttpTransport {
         const name = mcpNameFor(msg);
         if (name !== undefined)
             headers["mcp-name"] = encodeHeaderValue(name);
+        if (msg.method === "tools/call") {
+            const params = msg.params;
+            const toolName = typeof params?.name === "string" ? params.name : undefined;
+            const entries = toolName !== undefined ? this.toolHeaderMaps.get(toolName) : undefined;
+            if (entries)
+                Object.assign(headers, buildParamHeaders(entries, params?.arguments));
+        }
         const hasExplicitAuth = Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
         if (!hasExplicitAuth) {
             const token = await this.oauth.accessToken();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritya",
-  "version": "0.8.15-beta",
+  "version": "0.8.17-beta",
   "description": "Kritya — a lean, provider-agnostic terminal coding agent (NVIDIA, OpenAI, OpenRouter, Groq, Ollama, and more)",
   "type": "module",
   "publishConfig": {
@@ -74,7 +74,7 @@
     "@types/node": "^26.4.0",
     "@types/react": "^19.2.18",
     "c8": "^12.0.0",
-    "electron": "^43.4.1",
+    "electron": "^44.0.0",
     "electron-builder": "^26.15.3",
     "eslint": "^10.9.1",
     "globals": "^17.11.0",