toolnexus 0.26.0 → 0.27.0

package/dist/acp.d.ts

@@ -48,15 +48,23 @@ export interface ACPOptions {
 /** One warm ACP connection: one child process, one session, alive across many
  *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
  *  wants, so it plugs straight into {@link createInProcessClient}. */
+/** Per-call options for {@link ACPClient.generate} / {@link ACPClient.generateStream}. */
+export interface ACPGenerateOptions {
+    /** Cancels the turn: when it aborts mid-turn the `session/cancel` notification is sent,
+     *  the turn's reply is awaited (bounded by `requestTimeoutMs`, default 30s) so the next
+     *  turn never lands on a busy session, and the call rejects with an `AbortError`. The
+     *  process and session stay warm. */
+    signal?: AbortSignal;
+}
 export interface ACPClient {
-    generate: (request: InProcessRequest) => Promise<InProcessResponse>;
+    generate: (request: InProcessRequest, opts?: ACPGenerateOptions) => Promise<InProcessResponse>;
     /** {@link generate}, streaming: `emit` fires as each `session/update` arrives —
      *  agent_message_chunk → `text`, agent_thought_chunk → `thought` (via "acp"),
      *  tool_call → `tool_call` and a completed/failed tool_call_update → `tool_result`
      *  (both via "acp": the agent's own tools, reported, never executed by the loop).
      *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
      *  message text only. */
-    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void) => Promise<InProcessResponse>;
+    generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void, opts?: ACPGenerateOptions) => Promise<InProcessResponse>;
     /** Terminates the agent's process group. Idempotent — a second call is a no-op. */
     close: () => Promise<void>;
     /** The agent's raw `initialize` result. */

package/dist/acp.js

@@ -298,7 +298,9 @@ export async function loadACP(opts) {
     // each generate() call attaches after whatever is already queued, and the
     // queue itself never rejects (a failed turn does not poison later ones).
     let turnQueue = Promise.resolve();
-    async function promptOnce(request, emit) {
+    async function promptOnce(request, emit, signal) {
+        if (signal?.aborted)
+            throw acpAbortError();
         const text = renderPrompt(request);
         const id = `c-${++nextId}`;
         let content = "";
@@ -361,8 +363,30 @@ export async function loadACP(opts) {
         const timeout = new Promise((_, reject) => {
             timer = setTimeout(() => reject(new Error(`toolnexus: ACP turn timed out after ${permissionTimeoutMs}ms`)), permissionTimeoutMs);
         });
+        let onAbort;
+        const cancelled = new Promise((resolve) => {
+            if (!signal)
+                return;
+            onAbort = () => resolve("cancelled");
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
         try {
-            const msg = await Promise.race([replyPromise, timeout]);
+            const msg = await Promise.race([replyPromise, timeout, cancelled]);
+            if (msg === "cancelled") {
+                // ACP: session/cancel is a notification (no id); the agent then ends the turn with
+                // stopReason "cancelled". Wait (bounded) for that reply so the session is idle again.
+                write({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+                const waitMs = opts.requestTimeoutMs && opts.requestTimeoutMs > 0 ? opts.requestTimeoutMs : 30000;
+                let wait;
+                await Promise.race([
+                    replyPromise,
+                    new Promise((r) => {
+                        wait = setTimeout(r, waitMs);
+                    }),
+                ]);
+                clearTimeout(wait);
+                throw acpAbortError();
+            }
             if (msg.error && msg.error.code === 0)
                 throw new Error(msg.error.message);
             if (msg.error)
@@ -371,14 +395,16 @@ export async function loadACP(opts) {
         }
         finally {
             clearTimeout(timer);
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
             pending.delete(id);
             updateSink = null;
         }
     }
-    const generateStream = (request, emit) => {
+    const generateStream = (request, emit, callOpts) => {
         if (closed)
             return Promise.reject(new Error("toolnexus: ACP client is closed"));
-        const turn = turnQueue.then(() => promptOnce(request, emit));
+        const turn = turnQueue.then(() => promptOnce(request, emit, callOpts?.signal));
         turnQueue = turn.then(() => undefined, () => undefined);
         return turn;
     };
@@ -400,13 +426,18 @@ export async function loadACP(opts) {
         if (t === "late")
             await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())]);
     }
-    const generate = (request) => generateStream(request);
+    const generate = (request, callOpts) => generateStream(request, undefined, callOpts);
     const client = { generate, generateStream, close, initializeResult };
     // Non-enumerable, undocumented — internal test hook only, so the public
     // ACPClient surface stays exactly {generate, generateStream, close}.
     Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false });
     return client;
 }
+function acpAbortError() {
+    const e = new Error("toolnexus: ACP turn cancelled");
+    e.name = "AbortError";
+    return e;
+}
 /** Signals the child's whole process group (POSIX), else the child itself. Never throws. */
 function killGroup(pid, signal) {
     if (process.platform !== "win32") {

package/dist/classifier.d.ts

@@ -47,6 +47,13 @@ export declare const CLASSIFIER_REQUEST_IMAGE_BYTES: number;
  * Cloudflare-Jev images stay false until a live probe proves them.
  */
 export declare const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, Readonly<ClassifierBackendPreset>>>;
+/**
+ * The env var whose key may be sent to `baseUrl` (already `${NAME}`-expanded): the backend's own
+ * variable, and only when `baseUrl` is that backend's own host over https (OpenRouter also its
+ * subdomains). `""` when none may — `custom` has no preset key at all. A key is never sent to a
+ * host the caller did not name (#155, SPEC §8B).
+ */
+export declare function classifierKeyEnv(backend: ClassifierBackend, baseUrl: string): string;
 /**
  * Raised BEFORE any network call when the backend table says the backend cannot take what the
  * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
@@ -377,6 +384,9 @@ export declare class Classifier {
     private readonly baseUrl;
     private readonly model;
     private readonly apiKeyEnv;
+    /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+     * and only to its own host (classifierKeyEnv, #155). */
+    private readonly explicitKeyEnv;
     private readonly timeoutMs;
     private readonly backend;
     private readonly preset;

package/dist/classifier.js

@@ -71,11 +71,36 @@ export const CLASSIFIER_BACKENDS = Object.freeze({
     custom: {
         baseUrl: "",
         model: DEFAULT_CLASSIFIER_MODEL,
-        apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV,
+        apiKeyEnv: "",
         wire: "systemone",
         imagesHeader: true,
     },
 });
+/**
+ * The env var whose key may be sent to `baseUrl` (already `${NAME}`-expanded): the backend's own
+ * variable, and only when `baseUrl` is that backend's own host over https (OpenRouter also its
+ * subdomains). `""` when none may — `custom` has no preset key at all. A key is never sent to a
+ * host the caller did not name (#155, SPEC §8B).
+ */
+export function classifierKeyEnv(backend, baseUrl) {
+    const p = Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, backend) ? CLASSIFIER_BACKENDS[backend] : undefined;
+    if (!p || !p.apiKeyEnv || !p.baseUrl)
+        return "";
+    const hostOf = (u) => {
+        try {
+            const url = new URL(u);
+            return url.protocol === "https:" ? url.hostname.toLowerCase() : "";
+        }
+        catch {
+            return "";
+        }
+    };
+    const h = hostOf(baseUrl);
+    const own = hostOf(p.baseUrl);
+    if (!h || !own)
+        return "";
+    return h === own || (backend === "openrouter" && h.endsWith(".openrouter.ai")) ? p.apiKeyEnv : "";
+}
 /**
  * Raised BEFORE any network call when the backend table says the backend cannot take what the
  * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
@@ -380,6 +405,9 @@ export class Classifier {
     baseUrl;
     model;
     apiKeyEnv;
+    /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+     * and only to its own host (classifierKeyEnv, #155). */
+    explicitKeyEnv;
     timeoutMs;
     backend;
     preset;
@@ -403,6 +431,7 @@ export class Classifier {
         this.baseUrl = opts.baseUrl || preset.baseUrl;
         this.model = opts.model ?? preset.model;
         this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv;
+        this.explicitKeyEnv = opts.apiKeyEnv !== undefined;
         const mismatch = backendMismatch(this.baseUrl, this.model);
         if (mismatch)
             throw new Error(mismatch);
@@ -745,7 +774,7 @@ export class Classifier {
             try {
                 res = await doFetch(url, {
                     method: "POST",
-                    headers: this.requestHeaders(extraHeaders),
+                    headers: this.requestHeaders(extraHeaders, url),
                     body: payload,
                     signal: timer.signal,
                 });
@@ -781,9 +810,10 @@ export class Classifier {
         }
     }
     /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
-    requestHeaders(extra = {}) {
+    requestHeaders(extra, url) {
         const headers = { "Content-Type": "application/json" };
-        const key = process.env[this.apiKeyEnv];
+        const keyEnv = this.explicitKeyEnv ? this.apiKeyEnv : classifierKeyEnv(this.backend, url);
+        const key = keyEnv ? process.env[keyEnv] : undefined;
         if (key)
             headers["Authorization"] = `Bearer ${key}`;
         // The image opt-in header goes BEFORE host headers, which win.
@@ -1057,10 +1087,29 @@ function imageSize(format, b) {
     }
     return undefined;
 }
-/** The System One reply inside a Cloudflare `/ai/run` envelope. Its error list is never echoed. */
+/**
+ * `: <code> <message>` from errors[0] of a failed envelope (SPEC §8B), through the same redaction
+ * and cap as cause(). Cloudflare reports a missing balance, a bad model id and a malformed
+ * request alike as HTTP 200 + success:false, so this is the only thing that tells them apart.
+ * `""` when there is nothing to show.
+ */
+function cloudflareCause(env) {
+    const errs = env !== null && typeof env === "object" ? env.errors : undefined;
+    const e0 = Array.isArray(errs) ? errs[0] : undefined;
+    if (e0 === null || typeof e0 !== "object")
+        return "";
+    const parts = [];
+    if ((typeof e0.code === "number" || typeof e0.code === "string") && String(e0.code) !== "")
+        parts.push(String(e0.code));
+    if (typeof e0.message === "string" && e0.message !== "")
+        parts.push(e0.message);
+    const s = capErrorBody(redactErrorBody(parts.join(" ")));
+    return s ? ": " + s : "";
+}
+/** The System One reply inside a Cloudflare `/ai/run` envelope. Only errors[0] is ever echoed. */
 function unwrapCloudflare(env) {
     if (env === null || typeof env !== "object" || Array.isArray(env) || env.success !== true) {
-        throw new Error("classifier: cloudflare: envelope not successful");
+        throw new Error("classifier: cloudflare: envelope not successful" + cloudflareCause(env));
     }
     let result = env.result;
     if (result !== null && typeof result === "object" && !Array.isArray(result) && typeof result.state === "string") {

package/dist/mcp.js

@@ -6,14 +6,16 @@
 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 { 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",
@@ -410,6 +412,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 +475,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 +492,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 +509,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 +600,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) => {