toolnexus 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./acp.js";
+export * from "./transcript_search.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./mcphandler.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./acp.js";
+export * from "./transcript_search.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./mcphandler.js";

package/dist/mcp.js

@@ -6,14 +6,17 @@
 import { readFileSync } from "node:fs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+import { AdoptedStdioTransport } from "./mcp2026/stdio.js";
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.js";
 import { summarizePart } from "./content.js";
-import { probe, newOAuth, defaultTokenStore } from "./mcp2026/source.js";
 import { PendingError } from "./mcp2026/auth.js";
 export { Token, MemoryTokenStore } from "./mcp2026/auth.js";
+// Loaded on first use, not at import: the 2026 client is only needed once a config is loaded,
+// and the SDK's remote transports (streamable-HTTP, SSE) only when a remote server falls back.
+let mcp2026;
+const loadMcp2026 = () => (mcp2026 ??= import("./mcp2026/source.js"));
 // ---------------------------------------------------------------------------
 // MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
 // (a reverse-request). We map it onto the one `waitFor`: form mode → kind:"input",
@@ -396,8 +399,19 @@ function resourceTools(servers) {
  *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
  *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
  *  stdio child (no orphaned processes on cancellation). */
+/**
+ * The SDK's default validator, built on first use instead of per Client. Building an Ajv instance
+ * (meta-schemas + formats) costs ~2-3 ms on every connect, yet it is only consulted when a tool
+ * declares an `outputSchema`. Same validator, same results — just not paid for up front.
+ */
+class LazyAjvValidator {
+    inner;
+    getValidator(schema) {
+        return (this.inner ??= new AjvJsonSchemaValidator()).getValidator(schema);
+    }
+}
 function newMcpClient(waitFor) {
-    const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} });
+    const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {}, jsonSchemaValidator: new LazyAjvValidator() });
     if (waitFor) {
         client.setRequestHandler(ElicitRequestSchema, async (request) => answerToElicitResult(await waitFor(elicitationToRequest(request.params))));
     }
@@ -410,6 +424,10 @@ async function connectTransport(client, cfg, auth) {
         const expanded = expandEnvHeaders(cfg.headers);
         const requestInit = expanded ? { headers: expanded } : undefined;
         const fetch = auth ? bearerFetch(cfg.url, auth) : undefined;
+        const [{ StreamableHTTPClientTransport }, { SSEClientTransport }] = await Promise.all([
+            import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+            import("@modelcontextprotocol/sdk/client/sse.js"),
+        ]);
         try {
             await client.connect(new StreamableHTTPClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }));
         }
@@ -469,6 +487,7 @@ function bearerFetch(resource, a) {
  * path, with the OAuth bearer attached for remote servers. Throws ⇒ the server failed.
  */
 async function connectServer(name, cfg, timeout, opts, store, sdkClient, onSdk) {
+    const { newOAuth, probe } = await loadMcp2026();
     const o = { waitFor: opts.waitFor, tokenStore: store, openUrl: opts.openUrl, signal: opts.signal, disableTools: opts.disableTools };
     const remote = isRemote(cfg);
     const oauth = remote ? newOAuth(cfg.auth, o, store) : undefined;
@@ -485,7 +504,10 @@ async function connectServer(name, cfg, timeout, opts, store, sdkClient, onSdk)
         return p;
     const client = sdkClient();
     onSdk(client);
-    await raceTimeout(connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined), timeout, opts.signal);
+    const connecting = p.reuse
+        ? client.connect(new AdoptedStdioTransport(p.reuse.child, p.reuse.leftover)) // §2.2a: same child, no respawn
+        : connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined);
+    await raceTimeout(connecting, timeout, opts.signal);
     const defs = await raceTimeout(paginateTools(client, timeout), timeout, opts.signal);
     return { kind: "sdk", client, defs };
 }
@@ -499,7 +521,7 @@ export async function loadMcp(input, opts) {
     const clients = [];
     const servers = new Map();
     const skills = [];
-    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
+    const store = (await loadMcp2026()).defaultTokenStore({ tokenStore: opts?.tokenStore });
     const waitFor = opts?.waitFor;
     const signal = opts?.signal;
     const onServer = opts?.onServer;
@@ -590,7 +612,7 @@ export async function listMcpTools(input, opts) {
     const toolsByServer = {};
     const status = {};
     const signal = opts?.signal;
-    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
+    const store = (await loadMcp2026()).defaultTokenStore({ tokenStore: opts?.tokenStore });
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";

package/dist/mcp2026/source.d.ts

@@ -1,6 +1,7 @@
 import { Mcp2026Client } from "./client.js";
 import { type Obj } from "./protocol.js";
 import { OAuth, type TokenStore } from "./auth.js";
+import type { ChildProcess } from "node:child_process";
 import type { Answer, Request, Tool, ToolContext, ToolResult } from "../types.js";
 import type { SkillDef } from "../skill.js";
 export type WaitFor = (request: Request) => Promise<Answer>;
@@ -33,6 +34,10 @@ export type Probe = {
     server: ModernServer;
 } | {
     kind: "fallback";
+    reuse?: {
+        child: ChildProcess;
+        leftover: Buffer;
+    };
 };
 export interface ProbeTarget {
     name: string;

package/dist/mcp2026/source.js

@@ -78,12 +78,15 @@ function supports2026(r) {
 /** Discover first (§2.2). Resolves `modern` (tools listed) or `fallback`; throws on a load failure. */
 export async function probe(t, o) {
     let client;
+    let stdio;
     if (t.remote) {
         client = new Mcp2026Client(t.remote.url, { headers: t.remote.headers, auth: t.remote.oauth, timeoutMs: t.timeout });
     }
     else {
-        const tr = await spawnStdio(t.local.argv, t.local.env, t.local.cwd);
-        client = new Mcp2026Client("", { transport: tr, timeoutMs: t.timeout });
+        stdio = await spawnStdio(t.local.argv, t.local.env, t.local.cwd);
+        // Stop parsing right after the discover reply so an old server's child can be handed over.
+        stdio.holdAfterNextResponse();
+        client = new Mcp2026Client("", { transport: stdio, timeoutMs: t.timeout });
     }
     const oauth = t.remote?.oauth;
     let disc;
@@ -94,6 +97,9 @@ export async function probe(t, o) {
     }
     catch (e) {
         const stdioTimeout = !!t.local && e instanceof Error && e.message === "stdio request timed out";
+        // §2.2a: a fast JSON-RPC error over stdio ⇒ the SAME child continues into initialize.
+        if (stdio && e instanceof RpcError && !o.signal?.aborted)
+            return { kind: "fallback", reuse: stdio.detach() };
         await client.close().catch(() => { });
         if (o.signal?.aborted)
             throw e;
@@ -104,9 +110,12 @@ export async function probe(t, o) {
         throw e;
     }
     if (!supports2026(disc)) {
+        if (stdio)
+            return { kind: "fallback", reuse: stdio.detach() };
         await client.close().catch(() => { });
         return { kind: "fallback" };
     }
+    stdio?.release();
     try {
         const server = new ModernServer(t, client, disc, o);
         await server.load();

package/dist/mcp2026/stdio.d.ts

@@ -6,6 +6,8 @@
 import { type ChildProcess } from "node:child_process";
 import type { Transport } from "./client.js";
 import type { Obj } from "./protocol.js";
+import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
 /** The child exited / closed stdout before answering. */
 export declare class StdioClosedError extends Error {
 }
@@ -14,7 +16,28 @@ export declare class StdioTransport implements Transport {
     private err?;
     private done;
     private child;
+    private buf;
+    private onData;
+    private onEnd;
+    private detached;
+    private hold;
+    private held;
     constructor(child: ChildProcess);
+    private drain;
+    /** Probe mode: after the next delivered response, stop parsing (bytes stay buffered for detach). */
+    holdAfterNextResponse(): void;
+    /** Leave probe mode and parse whatever was held. */
+    release(): void;
+    private onLine;
+    /**
+     * §2.2a handoff: stop reading stdout (listeners removed, stream paused — no read left pending)
+     * and give the live child plus any bytes already read past the last delivered line to the
+     * frozen path. The transport is unusable afterwards; the child is NOT killed.
+     */
+    detach(): {
+        child: ChildProcess;
+        leftover: Buffer;
+    };
     /** Writes one line and waits for the response with the same id. Never retried. */
     roundTrip(id: number, body: string, timeoutMs: number, signal?: AbortSignal): Promise<Obj>;
     /** Close stdin, then SIGKILL after 2 s if the child is still alive. */
@@ -22,3 +45,23 @@ export declare class StdioTransport implements Transport {
 }
 /** Spawns argv (no shell) and returns its transport; rejects if the spawn itself fails. */
 export declare function spawnStdio(argv: string[], env: NodeJS.ProcessEnv, cwd?: string): Promise<StdioTransport>;
+/**
+ * §2.2a: the frozen SDK path over a child the probe already started (StdioClientTransport always
+ * spawns). Takes the detached probe's stdin/stdout plus any bytes it had read but not parsed.
+ */
+export declare class AdoptedStdioTransport implements SdkTransport {
+    private child;
+    private leftover;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    private rb;
+    private closed;
+    constructor(child: ChildProcess, leftover: Buffer);
+    start(): Promise<void>;
+    private feed;
+    send(message: JSONRPCMessage): Promise<void>;
+    private finish;
+    /** Close stdin, then SIGKILL after 2 s if the child is still alive. */
+    close(): Promise<void>;
+}

package/dist/mcp2026/stdio.js

@@ -4,7 +4,7 @@
  * pending call instead of hanging. No headers, no auth.
  */
 import { spawn } from "node:child_process";
-import { createInterface } from "node:readline";
+import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
 /** The child exited / closed stdout before answering. */
 export class StdioClosedError extends Error {
 }
@@ -13,33 +13,86 @@ export class StdioTransport {
     err;
     done;
     child;
+    buf = Buffer.alloc(0);
+    onData;
+    onEnd;
+    detached = false;
+    hold = false;
+    held = false;
     constructor(child) {
         this.child = child;
-        const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
-        rl.on("line", (line) => {
-            let m;
-            try {
-                m = JSON.parse(line);
-            }
-            catch {
-                return; // noise
-            }
-            if (!m || typeof m !== "object" || m.method !== undefined || m.id === undefined || m.id === null)
-                return; // not a response
-            const key = JSON.stringify(m.id);
-            const f = this.pending.get(key);
-            this.pending.delete(key);
-            f?.(m);
-        });
-        this.done = new Promise((r) => rl.once("close", () => {
+        // Line-exact own reader (no readline): detach() can stop it and hand over unread bytes.
+        let closed;
+        this.done = new Promise((r) => (closed = r));
+        this.onData = (chunk) => {
+            this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk;
+            this.drain();
+        };
+        this.onEnd = () => {
             this.err ??= new StdioClosedError("stdio server closed its stdout");
             for (const f of this.pending.values())
                 f({ __closed: true });
             this.pending.clear();
-            r();
-        }));
+            closed();
+        };
+        const out = child.stdout;
+        out.on("data", this.onData);
+        out.once("end", this.onEnd);
+        out.once("close", this.onEnd);
         child.stdin?.on("error", () => { }); // EPIPE after the server died surfaces as a closed stdout
     }
+    drain() {
+        let nl;
+        while (!this.detached && !this.held && (nl = this.buf.indexOf(10)) >= 0) {
+            const line = this.buf.subarray(0, nl).toString("utf8").replace(/\r$/, "");
+            this.buf = this.buf.subarray(nl + 1);
+            this.onLine(line);
+        }
+    }
+    /** Probe mode: after the next delivered response, stop parsing (bytes stay buffered for detach). */
+    holdAfterNextResponse() {
+        this.hold = true;
+    }
+    /** Leave probe mode and parse whatever was held. */
+    release() {
+        this.hold = false;
+        this.held = false;
+        this.drain();
+    }
+    onLine(line) {
+        let m;
+        try {
+            m = JSON.parse(line);
+        }
+        catch {
+            return; // noise
+        }
+        if (!m || typeof m !== "object" || m.method !== undefined || m.id === undefined || m.id === null)
+            return; // not a response
+        const key = JSON.stringify(m.id);
+        const f = this.pending.get(key);
+        this.pending.delete(key);
+        if (f && this.hold)
+            this.held = true;
+        f?.(m);
+    }
+    /**
+     * §2.2a handoff: stop reading stdout (listeners removed, stream paused — no read left pending)
+     * and give the live child plus any bytes already read past the last delivered line to the
+     * frozen path. The transport is unusable afterwards; the child is NOT killed.
+     */
+    detach() {
+        this.detached = true;
+        const out = this.child.stdout;
+        out.off("data", this.onData);
+        out.off("end", this.onEnd);
+        out.off("close", this.onEnd);
+        out.pause();
+        this.err ??= new StdioClosedError("stdio transport detached");
+        const leftover = this.buf;
+        this.buf = Buffer.alloc(0);
+        return { child: this.child, leftover };
+    }
     /** Writes one line and waits for the response with the same id. Never retried. */
     roundTrip(id, body, timeoutMs, signal) {
         if (this.err)
@@ -97,3 +150,74 @@ export function spawnStdio(argv, env, cwd) {
         child.once("spawn", () => resolve(new StdioTransport(child)));
     });
 }
+/**
+ * §2.2a: the frozen SDK path over a child the probe already started (StdioClientTransport always
+ * spawns). Takes the detached probe's stdin/stdout plus any bytes it had read but not parsed.
+ */
+export class AdoptedStdioTransport {
+    child;
+    leftover;
+    onclose;
+    onerror;
+    onmessage;
+    rb = new ReadBuffer();
+    closed = false;
+    constructor(child, leftover) {
+        this.child = child;
+        this.leftover = leftover;
+    }
+    async start() {
+        const out = this.child.stdout;
+        out.on("data", (chunk) => this.feed(chunk));
+        out.on("error", (e) => this.onerror?.(e));
+        this.child.stdin?.on("error", (e) => this.onerror?.(e));
+        this.child.once("close", () => this.finish());
+        if (this.leftover.length)
+            this.feed(this.leftover);
+        this.leftover = Buffer.alloc(0);
+        out.resume();
+    }
+    feed(chunk) {
+        this.rb.append(chunk);
+        for (;;) {
+            let m;
+            try {
+                m = this.rb.readMessage();
+            }
+            catch (e) {
+                this.onerror?.(e);
+                continue;
+            }
+            if (m === null)
+                break;
+            this.onmessage?.(m);
+        }
+    }
+    send(message) {
+        return new Promise((resolve) => {
+            if (!this.child.stdin?.write(serializeMessage(message)))
+                this.child.stdin?.once("drain", resolve);
+            else
+                resolve();
+        });
+    }
+    finish() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.rb.clear();
+        this.onclose?.();
+    }
+    /** Close stdin, then SIGKILL after 2 s if the child is still alive. */
+    async close() {
+        if (this.child.exitCode === null && this.child.signalCode === null) {
+            const exited = new Promise((r) => this.child.once("exit", () => r()));
+            this.child.stdin?.end();
+            const t = setTimeout(() => this.child.kill("SIGKILL"), 2000);
+            await exited;
+            clearTimeout(t);
+        }
+        this.child.stdout?.destroy();
+        this.finish();
+    }
+}

package/dist/mcphandler.js

@@ -196,7 +196,7 @@ export function createMcpHandler(toolkitTools, cfg = {}) {
     /** Validates protocol header + session (stateful). Writes the HTTP error itself on failure. */
     async function checkSession(ctx, req, res) {
         const v = header(req, "MCP-Protocol-Version");
-        if (v !== "" && !legacy.includes(v)) {
+        if (v !== "" && !versions.includes(v)) {
             httpError(res, 400, "Bad Request: unsupported MCP-Protocol-Version");
             return false;
         }
@@ -655,9 +655,7 @@ export function createMcpHandler(toolkitTools, cfg = {}) {
         if (method === "initialize")
             return false;
         const hv = header(req, "MCP-Protocol-Version");
-        if (hv === MCP_PROTOCOL_2026)
-            return true;
-        if (hv !== "" && versions.includes(hv))
+        if (hv !== "" && legacy.includes(hv))
             return false;
         return method === "server/discover" || header(req, "Mcp-Method") !== "" || (meta !== undefined && META_VERSION in meta);
     }

package/dist/mcpserve.js

@@ -15,7 +15,6 @@
 import http from "node:http";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
 const DEFAULT_NAME = "toolnexus";
 const DEFAULT_VERSION = "0.1.0";
@@ -133,6 +132,8 @@ function partBlocks(parts) {
  */
 export async function serveLocalMcp(tools, cfg) {
     const exposed = exposedMcpTools(tools, cfg);
+    // Loaded on first serve, not at import: the transport pulls in @hono/node-server.
+    const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
     const token = randomBytes(32).toString("hex");
     const want = Buffer.from("Bearer " + token);
     const server = http.createServer((req, res) => {

package/dist/nodefetch.d.ts

@@ -0,0 +1 @@
+export declare const nodeFetch: typeof fetch;

package/dist/nodefetch.js

@@ -0,0 +1,156 @@
+/**
+ * Default LLM transport: a `fetch`-shaped function over `node:http`/`node:https` with a shared
+ * keep-alive agent.
+ *
+ * Why: Node's built-in `fetch` (undici + web streams) costs ~1.5 ms per local round-trip, against
+ * ~0.3 ms for `node:http` on the same keep-alive socket. With two LLM calls per tool-calling turn
+ * that was most of the client's per-request overhead (benchmarks/run_toolnexus_js.mjs).
+ *
+ * Behavior is kept identical to `fetch` for what the client uses (status, headers incl.
+ * Retry-After, json/text, a streamed `body` for SSE, abort via `signal` rejecting with its reason).
+ * Anything this path does not cover is handed to `globalThis.fetch` unchanged: a proxy env
+ * (`HTTP(S)_PROXY`, `NODE_USE_ENV_PROXY`), a replaced global `fetch`, a non-http(s) URL, a body
+ * that is not a string/bytes, and redirects.
+ */
+import http from "node:http";
+import https from "node:https";
+import { Readable } from "node:stream";
+import zlib from "node:zlib";
+const nativeFetch = globalThis.fetch;
+const httpAgent = new http.Agent({ keepAlive: true });
+const httpsAgent = new https.Agent({ keepAlive: true });
+function proxyEnv() {
+    const e = process.env;
+    return !!(e.HTTP_PROXY || e.HTTPS_PROXY || e.http_proxy || e.https_proxy || e.NODE_USE_ENV_PROXY);
+}
+function toHeaderRecord(h) {
+    const out = {};
+    if (!h)
+        return out;
+    if (h instanceof Headers || Array.isArray(h)) {
+        for (const [k, v] of h)
+            out[k] = v;
+        return out;
+    }
+    return { ...h };
+}
+// undici's global dispatcher slot. Node fills it lazily with a default Agent on the first fetch;
+// anything else there (a ProxyAgent, a mock, a tuned Agent) means the host routed fetch on purpose.
+const DISPATCHER = Symbol.for("undici.globalDispatcher.1");
+let knownDefaultDispatcher;
+function customDispatcher() {
+    const d = globalThis[DISPATCHER];
+    return d !== undefined && d !== knownDefaultDispatcher;
+}
+/** Calls the platform fetch; if that call is what created Node's default dispatcher, remember it
+ * so later calls still take the fast path. */
+function platformFetch(input, init) {
+    const before = globalThis[DISPATCHER];
+    const p = globalThis.fetch(input, init);
+    if (before === undefined) {
+        const after = globalThis[DISPATCHER];
+        if (after !== undefined)
+            knownDefaultDispatcher = after;
+    }
+    return p;
+}
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+export const nodeFetch = (input, init) => {
+    const fallback = () => platformFetch(input, init);
+    if (globalThis.fetch !== nativeFetch || proxyEnv() || customDispatcher())
+        return fallback();
+    if (init?.redirect && init.redirect !== "follow")
+        return fallback();
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : undefined;
+    const body = init?.body;
+    if (url === undefined || (body != null && typeof body !== "string" && !(body instanceof Uint8Array)))
+        return fallback();
+    const isHttps = url.startsWith("https:");
+    if (!isHttps && !url.startsWith("http:"))
+        return fallback();
+    const signal = init?.signal ?? undefined;
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const headers = toHeaderRecord(init?.headers);
+        if (body != null && !Object.keys(headers).some((k) => k.toLowerCase() === "content-length")) {
+            headers["content-length"] = String(typeof body === "string" ? Buffer.byteLength(body) : body.byteLength);
+        }
+        const mod = isHttps ? https : http;
+        let settled = false;
+        const onAbort = () => {
+            req.destroy(signal.reason);
+            if (!settled) {
+                settled = true;
+                reject(signal.reason);
+            }
+        };
+        const req = mod.request(url, { method: init?.method ?? "GET", headers, agent: isHttps ? httpsAgent : httpAgent }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (REDIRECTS.has(status) && res.headers.location) {
+                // Follow it the way fetch does, from the redirect target: re-sending to the original URL
+                // would reach the server twice. 303, and 301/302 after a POST, become a bodiless GET;
+                // 307/308 repeat the method and body. Further hops are fetch's to follow.
+                res.resume();
+                signal?.removeEventListener("abort", onAbort);
+                settled = true;
+                const target = new URL(res.headers.location, url).href;
+                const method = (init?.method ?? "GET").toUpperCase();
+                const toGet = status === 303 ? method !== "HEAD" : (status === 301 || status === 302) && method === "POST";
+                let next = init;
+                if (toGet) {
+                    const h = toHeaderRecord(init?.headers);
+                    for (const k of Object.keys(h)) {
+                        if (/^content-(type|length|encoding|language|location)$/i.test(k))
+                            delete h[k];
+                    }
+                    next = { ...init, method: "GET", body: undefined, headers: h };
+                }
+                platformFetch(target, next).then(resolve, reject);
+                return;
+            }
+            const h = new Headers();
+            for (let i = 0; i < res.rawHeaders.length; i += 2)
+                h.append(res.rawHeaders[i], res.rawHeaders[i + 1]);
+            let stream = res;
+            const enc = (res.headers["content-encoding"] ?? "").toLowerCase();
+            if (enc === "gzip" || enc === "x-gzip" || enc === "deflate")
+                stream = res.pipe(zlib.createUnzip());
+            else if (enc === "br")
+                stream = res.pipe(zlib.createBrotliDecompress());
+            const nullBody = status === 204 || status === 304 || init?.method === "HEAD";
+            const ctype = (res.headers["content-type"] ?? "").toLowerCase();
+            const done = (b) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(new Response(nullBody ? null : b, { status, statusText: res.statusMessage, headers: h }));
+            };
+            if (ctype.includes("text/event-stream")) {
+                // Streamed: the body is consumed incrementally (SSE). Abort still destroys the socket.
+                stream.once("end", () => signal?.removeEventListener("abort", onAbort));
+                done(Readable.toWeb(stream));
+                return;
+            }
+            const chunks = [];
+            stream.on("data", (c) => chunks.push(c));
+            stream.once("error", (e) => { if (!settled) {
+                settled = true;
+                reject(e);
+            } });
+            stream.once("end", () => {
+                signal?.removeEventListener("abort", onAbort);
+                done(Buffer.concat(chunks));
+            });
+        });
+        req.once("error", (e) => {
+            signal?.removeEventListener("abort", onAbort);
+            if (!settled) {
+                settled = true;
+                reject(signal?.aborted ? signal.reason : new TypeError("fetch failed", { cause: e }));
+            }
+        });
+        signal?.addEventListener("abort", onAbort, { once: true });
+        req.end(body ?? undefined);
+    });
+};

package/dist/serve.js

@@ -18,7 +18,8 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+// The SDK server transport (and the @hono/node-server it pulls in) is loaded only when an MCP
+// profile is actually served, so importing toolnexus does not pay for it.
 import { sanitize } from "./types.js";
 import { buildMcpServer, exposedMcpTools } from "./mcpserve.js";
 /** Default in-memory store — Tasks live only for the lifetime of the process. */
@@ -136,6 +137,9 @@ export async function startA2AServer(opts) {
     const [host, portStr] = splitAddr(opts.addr);
     const store = a2a ? resolveStore(a2a.store) : undefined;
     const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : [];
+    const StreamableHTTPServerTransport = mcp
+        ? (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport
+        : undefined;
     const server = http.createServer((req, res) => {
         const rpcRes = (id, payload) => {
             res.writeHead(200, { "content-type": "application/json" });

package/dist/skill.d.ts

@@ -39,10 +39,22 @@ export interface SkillSkip {
      */
     detail?: string;
 }
+/** Why a KEPT skill carries a warning (SPEC.md §3, #84). The skill still loads unchanged. */
+export type SkillWarningReason = "oversized-description";
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export declare const SKILL_DESCRIPTION_MAX_CHARS = 1024;
+export interface SkillWarning {
+    location: string;
+    reason: SkillWarningReason;
+    /** Description length in Unicode CODE POINTS (not bytes, not UTF-16 units). */
+    chars: number;
+}
 /** Result of a list-only validate pass (SPEC.md §3, S3). */
 export interface SkillInventory {
     skills: SkillInfo[];
     skipped: SkillSkip[];
+    /** Kept skills that load but carry a warning (oversized description), in discovery order. */
+    warnings: SkillWarning[];
 }
 /** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
 export interface LoadSkillsOptions {
@@ -65,6 +77,8 @@ export interface SkillSource {
      * that stops being reported is indistinguishable from something that was finished.
      */
     skipped: SkillSkip[];
+    /** Exposed (post-allowlist) skills whose description is oversized; never modified (#84). */
+    warnings: SkillWarning[];
 }
 /**
  * Discover + validate skills from the same sources loadSkills accepts, returning