toolnexus 0.24.0 → 0.25.0

package/dist/client.d.ts

@@ -358,12 +358,21 @@ export interface RunResult {
 export type StreamEvent = {
     type: "text";
     delta: string;
-} | {
+}
+/** Model reasoning narration (e.g. an ACP agent's `agent_thought_chunk`). Never part of
+ *  the answer text or the RunResult. */
+ | {
+    type: "thought";
+    delta: string;
+    via?: "acp";
+}
+/** `via: "acp"` marks a tool the ACP agent ran itself: reported, never executed by the loop. */
+ | {
     type: "tool_call";
     id: string;
     name: string;
     args: Record<string, unknown>;
-    via?: "call_tool";
+    via?: "call_tool" | "acp";
 } | {
     type: "tool_result";
     id: string;
@@ -371,7 +380,7 @@ export type StreamEvent = {
     output: string;
     isError: boolean;
     metadata?: Record<string, unknown>;
-    via?: "call_tool";
+    via?: "call_tool" | "acp";
 } | {
     type: "usage";
     usage: Usage;
@@ -582,11 +591,22 @@ export interface InProcessResponse {
         totalTokens?: number;
     };
 }
+/** A streaming in-process model: `emit` each event as it happens — `text` deltas become
+ *  the streamed answer as they arrive; any other event (thought, an agent's own tool_call /
+ *  tool_result) goes straight to the stream consumer and is never executed by the loop.
+ *  Return the whole message when done (its `toolCalls`, if any, are what the loop runs). */
+export type InProcessGenerateStream = (request: InProcessRequest, emit: (event: StreamEvent) => void) => InProcessResponse | Promise<InProcessResponse>;
+type InProcessGenerate = (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
 /** Options for {@link createInProcessClient}: every client option EXCEPT the three
- *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate`. */
+ *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate` and/or
+ *  `generateStream` (at least one). */
 export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style" | "fetch"> & {
     /** Your model. Receives the assembled request, returns one assistant message. */
-    generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
+    generate?: InProcessGenerate;
+    /** Your model, streaming for real. With it, `stream()` is incremental; without it a
+     *  `stream()` on a plain `generate` is refused. When both are set, `generate` serves
+     *  non-streaming calls; alone, it serves them too (with a no-op `emit`). */
+    generateStream?: InProcessGenerateStream;
 };
 /**
  * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
@@ -596,9 +616,11 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
  * or the agent runtime's `inProcess` option) goes through this ONE function, so there
  * is no second copy of the request/response assembly to drift.
  *
- * Streaming is refused rather than faked — see the thrown error.
+ * Streaming with only a plain `generate` is refused rather than faked — see the thrown
+ * error. With `generateStream` it streams for real: each text event is written to the
+ * SSE body the moment it is emitted.
  */
-export declare function createInProcessFetch(generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>): typeof fetch;
+export declare function createInProcessFetch(generate?: InProcessGenerate, generateStream?: InProcessGenerateStream): typeof fetch;
 /**
  * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
  * HTTP types to construct.
@@ -609,7 +631,8 @@ export declare function createInProcessFetch(generate: (request: InProcessReques
  * The `fetch`-shaped adapter itself is {@link createInProcessFetch} — this function
  * is just that adapter wired into a `Client`.
  *
- * Streaming is refused rather than faked — see {@link createInProcessFetch}.
+ * Streaming is refused rather than faked for a plain `generate`; with `generateStream`
+ * it streams for real — see {@link createInProcessFetch}.
  */
 export declare function createInProcessClient(opts: InProcessOptions): Client;
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
@@ -625,3 +648,4 @@ export declare class Conversation {
     /** Reset the conversation memory. */
     reset(): void;
 }
+export {};

package/dist/client.js

@@ -1132,6 +1132,13 @@ export class Client {
                         if (payload === "[DONE]")
                             break;
                         const j = safeParse(payload);
+                        // A non-text event from an in-process streaming generate rides in-band so it keeps
+                        // its order and arrives as it happens; it goes straight to the consumer and is never
+                        // executed. Honoured only on the in-process sentinel URL, never from a real server.
+                        if (j && j[IN_PROCESS_SIDE_KEY] && this.opts.baseUrl === IN_PROCESS_BASE_URL) {
+                            yield j[IN_PROCESS_SIDE_KEY];
+                            continue;
+                        }
                         if (j?.usage)
                             addUsage(usage, j.usage, "openai");
                         const choice = j?.choices?.[0];
@@ -1336,6 +1343,9 @@ export function createClient(opts) {
  *  it must be syntactically valid. `.invalid` is reserved by RFC 2606 precisely so a
  *  name can never resolve. */
 const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
+/** The in-band SSE key that carries a non-text stream event from an in-process
+ *  streaming generate to the consumer (honoured only on {@link IN_PROCESS_BASE_URL}). */
+const IN_PROCESS_SIDE_KEY = "toolnexus_event";
 /**
  * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
  * the reusable piece of {@link createInProcessClient} — assembles the wire request,
@@ -1344,14 +1354,19 @@ const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
  * or the agent runtime's `inProcess` option) goes through this ONE function, so there
  * is no second copy of the request/response assembly to drift.
  *
- * Streaming is refused rather than faked — see the thrown error.
+ * Streaming with only a plain `generate` is refused rather than faked — see the thrown
+ * error. With `generateStream` it streams for real: each text event is written to the
+ * SSE body the moment it is emitted.
  */
-export function createInProcessFetch(generate) {
-    if (typeof generate !== "function") {
-        throw new Error("toolnexus: createInProcessFetch requires a `generate` function");
+export function createInProcessFetch(generate, generateStream) {
+    if (typeof generate !== "function" && typeof generateStream !== "function") {
+        throw new Error("toolnexus: createInProcessFetch requires a `generate` (or `generateStream`) function");
     }
     const inProcessFetch = async (_url, init) => {
         const body = JSON.parse(String(init?.body ?? "{}"));
+        const request = { messages: body.messages ?? [], tools: body.tools, model: body.model, body };
+        if (body.stream && generateStream)
+            return inProcessStream(generateStream, request);
         // A generate() returns a whole answer, so a stream would be one chunk pretending
         // to be many. Content and delta-count assertions cannot tell that from a real
         // stream, so refuse instead of degrading silently.
@@ -1359,24 +1374,10 @@ export function createInProcessFetch(generate) {
             throw new Error("toolnexus: createInProcessClient does not support streaming — `generate` returns a " +
                 "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.");
         }
-        const answer = await generate({
-            messages: body.messages ?? [],
-            tools: body.tools,
-            model: body.model,
-            body,
-        });
+        const answer = generate ? await generate(request) : await generateStream(request, () => { });
         const message = { role: "assistant" };
         if (answer.toolCalls && answer.toolCalls.length > 0) {
-            message.tool_calls = answer.toolCalls.map((c, i) => ({
-                id: c.id ?? `call_${i}`,
-                type: "function",
-                function: {
-                    name: c.name,
-                    // A string is already encoded; anything else is encoded here so a model
-                    // author never has to think about the wire.
-                    arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
-                },
-            }));
+            message.tool_calls = wireToolCalls(answer.toolCalls, false);
         }
         else {
             message.content = answer.content ?? "";
@@ -1395,6 +1396,80 @@ export function createInProcessFetch(generate) {
     };
     return inProcessFetch;
 }
+function wireToolCalls(calls, indexed) {
+    return calls.map((c, i) => ({
+        ...(indexed ? { index: i } : {}),
+        id: c.id ?? `call_${i}`,
+        type: "function",
+        function: {
+            name: c.name,
+            // A string is already encoded; anything else is encoded here so a model
+            // author never has to think about the wire.
+            arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
+        },
+    }));
+}
+/** Runs a streaming generate and answers with an OpenAI SSE body written AS EVENTS ARRIVE:
+ *  text → a content delta; any other event → an in-band side chunk for the consumer; then
+ *  (tool calls as one delta | the content as one delta when no text was emitted), the
+ *  finish_reason chunk, usage, and [DONE]. */
+function inProcessStream(generateStream, request) {
+    const enc = new TextEncoder();
+    let open = true;
+    const sse = new ReadableStream({
+        start(controller) {
+            const chunk = (v) => {
+                if (open)
+                    controller.enqueue(enc.encode(`data: ${JSON.stringify(v)}\n\n`));
+            };
+            let sawText = false;
+            void (async () => {
+                try {
+                    const answer = await generateStream(request, (ev) => {
+                        if (!ev || typeof ev !== "object")
+                            return;
+                        if (ev.type === "text") {
+                            if (ev.delta) {
+                                sawText = true;
+                                chunk({ choices: [{ index: 0, delta: { content: ev.delta } }] });
+                            }
+                            return;
+                        }
+                        chunk({ [IN_PROCESS_SIDE_KEY]: ev });
+                    });
+                    let finish = "stop";
+                    if (answer.toolCalls && answer.toolCalls.length > 0) {
+                        chunk({ choices: [{ index: 0, delta: { tool_calls: wireToolCalls(answer.toolCalls, true) } }] });
+                        finish = "tool_calls";
+                    }
+                    else if (!sawText && answer.content) {
+                        chunk({ choices: [{ index: 0, delta: { content: answer.content } }] });
+                    }
+                    chunk({ choices: [{ index: 0, delta: {}, finish_reason: finish }] });
+                    const u = answer.usage;
+                    if (u) {
+                        const p = u.promptTokens ?? 0, c = u.completionTokens ?? 0;
+                        chunk({ choices: [], usage: { prompt_tokens: p, completion_tokens: c, total_tokens: u.totalTokens || p + c } });
+                    }
+                    if (open)
+                        controller.enqueue(enc.encode("data: [DONE]\n\n"));
+                    open = false;
+                    controller.close();
+                }
+                catch (e) {
+                    if (open) {
+                        open = false;
+                        controller.error(e);
+                    }
+                }
+            })();
+        },
+        cancel() {
+            open = false;
+        },
+    });
+    return new Response(sse, { status: 200, headers: { "content-type": "text/event-stream" } });
+}
 /**
  * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
  * HTTP types to construct.
@@ -1405,11 +1480,15 @@ export function createInProcessFetch(generate) {
  * The `fetch`-shaped adapter itself is {@link createInProcessFetch} — this function
  * is just that adapter wired into a `Client`.
  *
- * Streaming is refused rather than faked — see {@link createInProcessFetch}.
+ * Streaming is refused rather than faked for a plain `generate`; with `generateStream`
+ * it streams for real — see {@link createInProcessFetch}.
  */
 export function createInProcessClient(opts) {
-    const { generate, ...rest } = opts;
-    const inProcessFetch = createInProcessFetch(generate);
+    const { generate, generateStream, ...rest } = opts;
+    if (typeof generate !== "function" && typeof generateStream !== "function") {
+        throw new Error("toolnexus: createInProcessClient requires a `generate` (or `generateStream`) function");
+    }
+    const inProcessFetch = createInProcessFetch(generate, generateStream);
     return new Client({
         // Retries default to ZERO here, unlike a network client. There is no wire, so
         // there is no transient failure to ride out: whatever `generate` throws will

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export * from "./a2a.js";
 export * from "./acp.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
+export * from "./mcphandler.js";
+export * from "./mcpserverauth.js";
 export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";

package/dist/index.js

@@ -10,6 +10,8 @@ export * from "./a2a.js";
 export * from "./acp.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
+export * from "./mcphandler.js";
+export * from "./mcpserverauth.js";
 export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";

package/dist/mcp.d.ts

@@ -1,6 +1,11 @@
 import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
-import { type JSONSchema, type Tool, type ToolHints, type McpStatus, type Request, type Answer } from "./types.js";
+import { type JSONSchema, type Tool, type ToolHints, type ToolResult, type McpStatus, type Request, type Answer } from "./types.js";
 import { type ContentPart } from "./content.js";
+import type { SkillDef } from "./skill.js";
+import { type AuthConfig } from "./mcp2026/source.js";
+import { type TokenStore } from "./mcp2026/auth.js";
+export { Token, MemoryTokenStore, type TokenStore } from "./mcp2026/auth.js";
+export type { AuthConfig } from "./mcp2026/source.js";
 /** Map an MCP `elicitation/create` request onto a §10 `Request`. */
 export declare function elicitationToRequest(params: ElicitRequest["params"]): Request;
 /** Map a resolved §10 `Answer` back onto an MCP `ElicitResult`. ok→accept; declined→decline; else→cancel. */
@@ -18,6 +23,10 @@ export interface LocalServer {
      * builtins/skills filter (nil/empty ⇒ all; ≥1 true ⇒ allowlist; only-false ⇒ drop-list; unknown
      * ⇒ ignore+warn). Applied to the listed defs before sanitize/prefix. */
     tools?: Record<string, boolean>;
+    /** §2.8 lazy tool search: expose `<server>_search_tools` + `<server>_call_tool` instead of every tool. */
+    toolSearch?: boolean;
+    /** §2.8 what this server is for (shown by search_tools). */
+    description?: string;
 }
 export interface RemoteServer {
     type?: "remote";
@@ -28,6 +37,11 @@ export interface RemoteServer {
     timeout?: number;
     /** §2 Gap 7. Per-server tool allowlist (see LocalServer.tools). */
     tools?: Record<string, boolean>;
+    /** §2.8 lazy tool search (see LocalServer.toolSearch). */
+    toolSearch?: boolean;
+    description?: string;
+    /** §2A OAuth 2.1 client settings. Absent ⇒ a 401 still triggers the flow (CIMD if the AS supports it). */
+    auth?: AuthConfig;
 }
 export type ServerConfig = LocalServer | RemoteServer;
 export type McpConfig = Record<string, ServerConfig>;
@@ -46,6 +60,8 @@ export declare function expandEnvHeaders(headers?: Record<string, string>): Reco
  * takes it there.
  */
 export declare function mcpContentToParts(content: unknown): ContentPart[] | undefined;
+/** §2 `tools/call` result → ToolResult (shared by the 2026 path and the frozen fallback). */
+export declare function mapCallToolResult(result: any, server: string): ToolResult;
 export interface McpSource {
     tools: Tool[];
     status: Record<string, McpStatus>;
@@ -56,6 +72,8 @@ export interface McpSource {
      * source is closed.
      */
     resourceTools(): Tool[];
+    /** §2.7 skills served by 2026 servers (skills extension); the toolkit adds them to the `skill` tool. */
+    skills: SkillDef[];
 }
 /** One server's outcome, reported by `loadMcp`'s `onServer` the moment that server finishes. */
 export interface McpServerResult {
@@ -75,12 +93,21 @@ export declare function mcpHints(a: {
     destructiveHint?: boolean;
     openWorldHint?: boolean;
 } | undefined): ToolHints | undefined;
+/** Options shared by loadMcp / listMcpTools for the 2026 path and OAuth (§2A.1a). */
+export interface McpLoadOptions {
+    waitFor?: (request: Request) => Promise<Answer>;
+    signal?: AbortSignal;
+    /** Where OAuth tokens live (default: in memory, per load). */
+    tokenStore?: TokenStore;
+    /** How `auto` OAuth mode opens the authorization URL (default: the OS opener). */
+    openUrl?: (url: string) => unknown | Promise<unknown>;
+    /** Final exposed names to drop; on a tool-search server they are also hidden from search/call. */
+    disableTools?: string[];
+}
 /** Connect to every enabled server, list + convert tools. Failures are isolated.
  *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
  *  whole load promptly on parent cancellation. */
-export declare function loadMcp(input: string | object, opts?: {
-    waitFor?: (request: Request) => Promise<Answer>;
-    signal?: AbortSignal;
+export declare function loadMcp(input: string | object, opts?: McpLoadOptions & {
     /**
      * Called once per server the moment it is connected, failed or found disabled (SPEC §4C),
      * so a host can register a fast server's tools while a slow one is still connecting.
@@ -105,6 +132,4 @@ export interface McpInventory {
  * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
  * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
  */
-export declare function listMcpTools(input: string | object, opts?: {
-    signal?: AbortSignal;
-}): Promise<McpInventory>;
+export declare function listMcpTools(input: string | object, opts?: McpLoadOptions): Promise<McpInventory>;

package/dist/mcp.js

@@ -11,6 +11,9 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.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";
 // ---------------------------------------------------------------------------
 // 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",
@@ -224,6 +227,22 @@ async function paginateTools(client, timeout) {
     }
     throw new Error(`MCP list exceeded ${MAX_LIST_PAGES} pages`);
 }
+/** §2 `tools/call` result → ToolResult (shared by the 2026 path and the frozen fallback). */
+export function mapCallToolResult(result, server) {
+    // Parts are collected BEFORE any branch returns: the isError and structuredContent
+    // short-circuits both read `content[]` on the way past, so neither reintroduces the
+    // silent drop this mapping exists to remove (§2).
+    const parts = mcpContentToParts(result.content);
+    const withParts = (r) => (parts ? { ...r, parts } : r);
+    if (result.isError) {
+        return withParts({ output: formatToolErrorContent(result.content), isError: true, metadata: { server } });
+    }
+    if (result.structuredContent !== undefined && result.structuredContent !== null) {
+        return withParts({ output: JSON.stringify(result.structuredContent), isError: false, metadata: { server } });
+    }
+    const text = joinTextContent(result.content);
+    return withParts({ output: text || describeMcpParts(parts), isError: false, metadata: { server } });
+}
 function convertTool(server, def, client, timeout) {
     const inputSchema = {
         ...def.inputSchema,
@@ -244,19 +263,7 @@ function convertTool(server, def, client, timeout) {
                 // `resetTimeoutOnProgress` never fires (add-mcp-progress-timeout). Notifications for a
                 // token that matches no in-flight request are dropped by the SDK, so they never reset.
                 { onprogress: () => { }, resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout });
-                // Parts are collected BEFORE any branch returns: the isError and structuredContent
-                // short-circuits both read `content[]` on the way past, so neither reintroduces the
-                // silent drop this mapping exists to remove (§2).
-                const parts = mcpContentToParts(result.content);
-                const withParts = (r) => (parts ? { ...r, parts } : r);
-                if (result.isError) {
-                    return withParts({ output: formatToolErrorContent(result.content), isError: true, metadata: { server } });
-                }
-                if (result.structuredContent !== undefined && result.structuredContent !== null) {
-                    return withParts({ output: JSON.stringify(result.structuredContent), isError: false, metadata: { server } });
-                }
-                const text = joinTextContent(result.content);
-                return withParts({ output: text || describeMcpParts(parts), isError: false, metadata: { server } });
+                return mapCallToolResult(result, server);
             }
             catch (e) {
                 return { output: e instanceof Error ? e.message : String(e), isError: true, metadata: { server } };
@@ -276,6 +283,15 @@ export function mcpHints(a) {
         h.destructive = false;
     return h;
 }
+function sdkConn(client, timeout) {
+    return {
+        listResources: async (signal) => (await client.listResources({}, { timeout, signal })).resources ?? [],
+        readResource: async (uri, signal) => (await client.readResource({ uri }, { timeout, signal })).contents ?? [],
+    };
+}
+function modernConn(s) {
+    return { listResources: (signal) => s.listResources(signal), readResource: (uri, signal) => s.readResource(uri, signal) };
+}
 function resourceTools(servers) {
     const ro = { readOnly: true, destructive: false, openWorld: false };
     const names = () => [...servers.keys()].sort();
@@ -312,8 +328,7 @@ function resourceTools(servers) {
             for (const name of targets) {
                 const c = conn(name);
                 try {
-                    const res = await c.client.listResources({}, { timeout: c.timeout, signal: ctx?.signal });
-                    for (const r of res.resources ?? []) {
+                    for (const r of await c.listResources(ctx?.signal)) {
                         let line = `${name} ${r.uri}`;
                         if (r.name)
                             line += ` — ${r.name}`;
@@ -361,9 +376,8 @@ function resourceTools(servers) {
             if (!uri)
                 return { output: "read_mcp_resource: uri is required", isError: true };
             try {
-                const res = await c.client.readResource({ uri }, { timeout: c.timeout, signal: ctx?.signal });
                 const parts = [];
-                for (const rc of res.contents ?? []) {
+                for (const rc of await c.readResource(uri, ctx?.signal)) {
                     if (typeof rc.text === "string")
                         parts.push(rc.text);
                     else if (typeof rc.blob === "string")
@@ -390,16 +404,17 @@ function newMcpClient(waitFor) {
     return client;
 }
 /** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
-async function connectTransport(client, cfg) {
+async function connectTransport(client, cfg, auth) {
     if (isRemote(cfg)) {
         const url = new URL(cfg.url);
         const expanded = expandEnvHeaders(cfg.headers);
         const requestInit = expanded ? { headers: expanded } : undefined;
+        const fetch = auth ? bearerFetch(cfg.url, auth) : undefined;
         try {
-            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
+            await client.connect(new StreamableHTTPClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }));
         }
         catch {
-            await client.connect(new SSEClientTransport(url, { requestInit }));
+            await client.connect(new SSEClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }));
         }
     }
     else {
@@ -414,6 +429,66 @@ async function connectTransport(client, cfg) {
         }));
     }
 }
+/**
+ * §2A.1a frozen fallback + OAuth: the SDK transport's fetch attaches the current bearer token
+ * (refreshing as needed); a 401/403 challenge runs the same OAuth flow once, then the request is
+ * re-sent. A pause is answered through waitFor, else the request fails ("authorization pending").
+ */
+function bearerFetch(resource, a) {
+    return async (input, init) => {
+        for (let attempt = 0;; attempt++) {
+            const headers = new Headers(init?.headers);
+            const tok = await a.oauth.bearer(resource);
+            if (tok)
+                headers.set("Authorization", "Bearer " + tok);
+            const res = await globalThis.fetch(input, { ...init, headers });
+            const www = res.headers.get("www-authenticate") ?? "";
+            if (attempt > 0 || (res.status !== 401 && res.status !== 403) || !www)
+                return res;
+            try {
+                await a.oauth.challenge(resource, res.status, www, tok, async () => ({}));
+            }
+            catch (e) {
+                if (!(e instanceof PendingError))
+                    throw e;
+                if (!a.waitFor)
+                    throw new Error("authorization pending");
+                const ans = await a.waitFor({ ...e.pending });
+                if (!ans?.ok)
+                    throw new Error(`authorization denied: ${ans?.reason ?? "cancelled"}`);
+                const cb = ans.data?.callbackUrl;
+                if (typeof cb !== "string")
+                    throw new Error("authorization answer carries no data.callbackUrl");
+                await a.oauth.resume(e.pending.id, cb);
+            }
+        }
+    };
+}
+/**
+ * Discover first (§2.2): a 2026 server is used directly; an old one (§2.2a) gets the frozen SDK
+ * path, with the OAuth bearer attached for remote servers. Throws ⇒ the server failed.
+ */
+async function connectServer(name, cfg, timeout, opts, store, sdkClient, onSdk) {
+    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;
+    const p = await probe({
+        name, timeout, tools: cfg.tools, toolSearch: cfg.toolSearch === true, description: cfg.description,
+        remote: remote ? { url: cfg.url, headers: expandEnvHeaders(cfg.headers), oauth: oauth } : undefined,
+        local: remote ? undefined : {
+            argv: cfg.command,
+            env: { ...process.env, ...(cfg.environment ?? cfg.env ?? {}) },
+            cwd: cfg.cwd,
+        },
+    }, o);
+    if (p.kind === "modern")
+        return p;
+    const client = sdkClient();
+    onSdk(client);
+    await raceTimeout(connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined), timeout, opts.signal);
+    const defs = await raceTimeout(paginateTools(client, timeout), timeout, opts.signal);
+    return { kind: "sdk", client, defs };
+}
 /** Connect to every enabled server, list + convert tools. Failures are isolated.
  *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
  *  whole load promptly on parent cancellation. */
@@ -423,6 +498,8 @@ export async function loadMcp(input, opts) {
     const status = {};
     const clients = [];
     const servers = new Map();
+    const skills = [];
+    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
     const waitFor = opts?.waitFor;
     const signal = opts?.signal;
     const onServer = opts?.onServer;
@@ -447,23 +524,31 @@ export async function loadMcp(input, opts) {
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        // Create the client up front so a timed-out/aborted connect still has a closeable handle
-        // (its stdio child is killed by close() — never orphaned).
-        const client = newMcpClient(waitFor);
+        // The fallback SDK client is created before its connect so a timed-out/aborted connect
+        // still has a closeable handle (its stdio child is killed by close() — never orphaned).
+        let client;
         try {
-            await raceTimeout(connectTransport(client, cfg), timeout, signal);
-            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
-            const kept = applyToolsFilter(name, defs, cfg.tools);
-            const converted = kept.map((def) => convertTool(name, def, client, timeout));
+            const c = await connectServer(name, cfg, timeout, opts ?? {}, store, () => newMcpClient(waitFor), (cl) => (client = cl));
+            let converted;
+            if (c.kind === "modern") {
+                converted = c.server.tools();
+                skills.push(...c.server.skills);
+                clients.push(c.server);
+                servers.set(name, modernConn(c.server));
+            }
+            else {
+                const kept = applyToolsFilter(name, c.defs, cfg.tools);
+                converted = kept.map((def) => convertTool(name, def, c.client, timeout));
+                clients.push(c.client);
+                servers.set(name, sdkConn(c.client, timeout));
+            }
             tools.push(...converted);
-            clients.push(client);
-            servers.set(name, { client, timeout });
             status[name] = "connected";
             report({ name, status: "connected", tools: converted });
         }
         catch (e) {
             status[name] = "failed";
-            await client.close().catch(() => { });
+            await client?.close().catch(() => { });
             // Parent cancellation/deadline aborts the whole load (§2 Gap 3, A1); a per-server timeout
             // within budget isolates just this server.
             if (signal?.aborted)
@@ -493,6 +578,7 @@ export async function loadMcp(input, opts) {
             await Promise.all(clients.map((c) => c.close().catch(() => { })));
         },
         resourceTools: () => resourceTools(servers),
+        skills,
     };
 }
 /**
@@ -504,17 +590,20 @@ export async function listMcpTools(input, opts) {
     const toolsByServer = {};
     const status = {};
     const signal = opts?.signal;
+    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        // Client created up front so an aborted/timed-out connect is still closed (no orphaned child).
-        const client = newMcpClient();
+        // The fallback client is created before its connect so an aborted/timed-out connect is still closed.
+        let client;
         try {
-            await raceTimeout(connectTransport(client, cfg), timeout, signal);
-            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
+            const c = await connectServer(name, cfg, timeout, { ...opts, waitFor: opts?.waitFor }, store, () => newMcpClient(), (cl) => (client = cl));
+            const defs = c.kind === "modern" ? c.server.rawDefs() : c.defs;
+            if (c.kind === "modern")
+                await c.server.close().catch(() => { });
             toolsByServer[name] = defs.map((d) => ({
                 name: d.name,
                 description: d.description ?? "",
@@ -529,13 +618,13 @@ export async function listMcpTools(input, opts) {
         catch (e) {
             status[name] = "failed";
             if (signal?.aborted) {
-                await client.close().catch(() => { });
+                await client?.close().catch(() => { });
                 throw e;
             }
             console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
         }
         finally {
-            await client.close().catch(() => { });
+            await client?.close().catch(() => { });
         }
     }));
     return { tools: toolsByServer, status };