toolnexus 0.24.0 → 0.26.0

package/src/client.ts

@@ -227,6 +227,12 @@ export type MetricEvent =
       promptTokens: number
       completionTokens: number
       error?: string
+      /** L1: how many questions were asked. */
+      questions: number
+      /** L1: sha256 hex of `canonicalRequest(model, questions)` ("" when unencodable). */
+      questionsHash: string
+      /** True when the decision came from the classifier cache and no request was sent. */
+      cached: boolean
     }
   // `warning`, never `error`: a degenerate-criteria report is advisory, and a consumer that
   // counts "has an error" as a failure must not count this.
@@ -388,8 +394,12 @@ export interface RunResult {
 /** Events yielded by client.stream(). */
 export type StreamEvent =
   | { type: "text"; delta: string }
-  | { type: "tool_call"; id: string; name: string; args: Record<string, unknown>; via?: "call_tool" }
-  | { type: "tool_result"; id: string; name: string; output: string; isError: boolean; metadata?: Record<string, unknown>; via?: "call_tool" }
+  /** 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" | "acp" }
+  | { type: "tool_result"; id: string; name: string; output: string; isError: boolean; metadata?: Record<string, unknown>; via?: "call_tool" | "acp" }
   | { type: "usage"; usage: Usage }
   | { type: "pending"; request: Request }
   | { type: "done"; result: RunResult }
@@ -1407,6 +1417,13 @@ export class Client {
             const payload = line.slice(5).trim()
             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] as StreamEvent
+              continue
+            }
             if (j?.usage) addUsage(usage, j.usage, "openai")
             const choice = j?.choices?.[0]
             const d = choice?.delta
@@ -1611,11 +1628,27 @@ export interface InProcessResponse {
   usage?: { promptTokens?: number; completionTokens?: number; 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
 }
 
 /** The sentinel base URL. Never dialled — the transport below answers every request
@@ -1624,6 +1657,10 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
  *  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,
@@ -1632,15 +1669,20 @@ 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: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>): typeof fetch {
-  if (typeof generate !== "function") {
-    throw new Error("toolnexus: createInProcessFetch requires a `generate` function")
+export function createInProcessFetch(generate?: InProcessGenerate, generateStream?: InProcessGenerateStream): typeof fetch {
+  if (typeof generate !== "function" && typeof generateStream !== "function") {
+    throw new Error("toolnexus: createInProcessFetch requires a `generate` (or `generateStream`) function")
   }
 
   const inProcessFetch: typeof fetch = async (_url, init) => {
     const body = JSON.parse(String((init as any)?.body ?? "{}"))
+    const request: InProcessRequest = { 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
@@ -1652,25 +1694,11 @@ export function createInProcessFetch(generate: (request: InProcessRequest) => In
       )
     }
 
-    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: Record<string, any> = { 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 ?? ""
     }
@@ -1694,6 +1722,77 @@ export function createInProcessFetch(generate: (request: InProcessRequest) => In
   return inProcessFetch
 }
 
+function wireToolCalls(calls: InProcessToolCall[], indexed: boolean): any[] {
+  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: InProcessGenerateStream, request: InProcessRequest): Response {
+  const enc = new TextEncoder()
+  let open = true
+  const sse = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const chunk = (v: unknown) => {
+        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.
@@ -1704,11 +1803,15 @@ export function createInProcessFetch(generate: (request: InProcessRequest) => In
  * 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: InProcessOptions): Client {
-  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

package/src/index.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/src/judge.ts

@@ -12,8 +12,10 @@ import {
   Decision,
   type DecisionAnswer,
   type NoulCriteria,
-  type Question,
+  type AnyQuestion,
   type RecordedDecision,
+  isRawAnswer,
+  raw as rawQ,
   noul as noulQ,
   choice as choiceQ,
   score as scoreQ,
@@ -25,7 +27,7 @@ import type { Request } from "./types.js"
 /** One named question of an ordered question list. */
 export interface NamedQuestion {
   name: string
-  question: Question
+  question: AnyQuestion
 }
 
 /** `noul` question with a name. Name the state field it judges in `instructions`. */
@@ -41,9 +43,15 @@ export function score(name: string, instructions: string, levels: string[]): Nam
   return { name, question: scoreQ(instructions, levels) }
 }
 
+/** A raw question with a name: a System One type the library does not model (e.g. `box`), sent
+ * as written. Its answer decodes to a raw answer `{type, value}`. */
+export function raw(name: string, type: string, instructions: string, criteria?: unknown): NamedQuestion {
+  return { name, question: rawQ(type, instructions, criteria) }
+}
+
 /** Ordered list -> the §8B questions map. A duplicate name is an error naming it. */
-export function questionMap(questions: readonly NamedQuestion[]): Record<string, Question> {
-  const out: Record<string, Question> = {}
+export function questionMap(questions: readonly NamedQuestion[]): Record<string, AnyQuestion> {
+  const out: Record<string, AnyQuestion> = {}
   for (const { name, question } of questions) {
     if (Object.prototype.hasOwnProperty.call(out, name)) throw new Error(`duplicate question name ${JSON.stringify(name)}`)
     out[name] = question
@@ -93,6 +101,13 @@ function noulBand(p: number, b: Bands): Band {
 }
 
 function wrap(a: DecisionAnswer, b: Bands): Answer {
+  if (isRawAnswer(a)) {
+    // An unmodelled answer type is never sure: there is no number to band.
+    const out = { ...(a as object), sure: false } as Answer
+    Object.defineProperty(out, "value", { value: () => 0, enumerable: false })
+    Object.defineProperty(out, "pick", { value: () => "", enumerable: false })
+    return out
+  }
   const extra =
     a.type === "noul"
       ? { band: noulBand(a.noul, b) }

package/src/mcp.ts

@@ -12,6 +12,11 @@ import type { Tool as McpToolDef, ElicitRequest, ElicitResult } from "@modelcont
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js"
 import { type JSONSchema, type Tool, type ToolContext, type ToolHints, type ToolResult, type McpStatus, type Request, type Answer, sanitize } from "./types.js"
 import { type ContentPart, summarizePart } from "./content.js"
+import type { SkillDef } from "./skill.js"
+import { probe, newOAuth, defaultTokenStore, type AuthConfig, type ModernServer, type Load2026Options } from "./mcp2026/source.js"
+import { PendingError, type OAuth, type TokenStore } from "./mcp2026/auth.js"
+export { Token, MemoryTokenStore, type TokenStore } from "./mcp2026/auth.js"
+export type { AuthConfig } from "./mcp2026/source.js"
 
 // ---------------------------------------------------------------------------
 // MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
@@ -56,6 +61,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 {
@@ -67,6 +76,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
@@ -254,6 +268,23 @@ async function paginateTools(client: Client, timeout: number): Promise<McpToolDe
   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: any, server: string): ToolResult {
+  // 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: ToolResult): ToolResult => (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: string, def: McpToolDef, client: Client, timeout: number): Tool {
   const inputSchema: JSONSchema = {
     ...(def.inputSchema as object),
@@ -277,19 +308,7 @@ function convertTool(server: string, def: McpToolDef, client: Client, timeout: n
           // 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: ToolResult): ToolResult => (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 } }
       }
@@ -307,6 +326,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. */
@@ -331,8 +352,19 @@ export function mcpHints(a: { readOnlyHint?: boolean; destructiveHint?: boolean;
 }
 
 interface ServerConn {
-  client: Client
-  timeout: number
+  listResources(signal?: AbortSignal): Promise<any[]>
+  readResource(uri: string, signal?: AbortSignal): Promise<any[]>
+}
+
+function sdkConn(client: Client, timeout: number): ServerConn {
+  return {
+    listResources: async (signal) => ((await client.listResources({}, { timeout, signal })) as any).resources ?? [],
+    readResource: async (uri, signal) => ((await client.readResource({ uri }, { timeout, signal })) as any).contents ?? [],
+  }
+}
+
+function modernConn(s: ModernServer): ServerConn {
+  return { listResources: (signal) => s.listResources(signal), readResource: (uri, signal) => s.readResource(uri, signal) }
 }
 
 function resourceTools(servers: Map<string, ServerConn>): Tool[] {
@@ -369,8 +401,7 @@ function resourceTools(servers: Map<string, ServerConn>): Tool[] {
       for (const name of targets) {
         const c = conn(name)
         try {
-          const res: any = 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}`
             if (r.mimeType) line += ` (${r.mimeType})`
@@ -411,9 +442,8 @@ function resourceTools(servers: Map<string, ServerConn>): Tool[] {
       }
       if (!uri) return { output: "read_mcp_resource: uri is required", isError: true }
       try {
-        const res: any = await c.client.readResource({ uri }, { timeout: c.timeout, signal: ctx?.signal })
         const parts: string[] = []
-        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") parts.push(`[binary ${rc.mimeType ?? ""}, ${rc.blob.length} base64 chars]`)
         }
@@ -441,15 +471,16 @@ function newMcpClient(waitFor?: (request: Request) => Promise<Answer>): Client {
 }
 
 /** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
-async function connectTransport(client: Client, cfg: ServerConfig): Promise<void> {
+async function connectTransport(client: Client, cfg: ServerConfig, auth?: FallbackAuth): Promise<void> {
   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 {
     const local = cfg as LocalServer
@@ -466,14 +497,90 @@ async function connectTransport(client: Client, cfg: ServerConfig): Promise<void
   }
 }
 
+interface FallbackAuth {
+  oauth: OAuth
+  waitFor?: (request: Request) => Promise<Answer>
+}
+
+/**
+ * §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: string, a: FallbackAuth): typeof globalThis.fetch {
+  return async (input: any, init?: any) => {
+    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)
+      }
+    }
+  }
+}
+
+/** 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[]
+}
+
+type Connected =
+  | { kind: "modern"; server: ModernServer }
+  | { kind: "sdk"; client: Client; defs: McpToolDef[] }
+
+/**
+ * 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: string, cfg: ServerConfig, timeout: number, opts: McpLoadOptions, store: TokenStore, sdkClient: () => Client, onSdk: (c: Client) => void): Promise<Connected> {
+  const o: Load2026Options = { 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 as LocalServer).command,
+        env: { ...process.env, ...((cfg as LocalServer).environment ?? (cfg as LocalServer).env ?? {}) },
+        cwd: (cfg as LocalServer).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. */
 export async function loadMcp(
   input: string | object,
-  opts?: {
-    waitFor?: (request: Request) => Promise<Answer>
-    signal?: AbortSignal
+  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.
@@ -486,8 +593,10 @@ export async function loadMcp(
   const config = parseMcpConfig(input)
   const tools: Tool[] = []
   const status: Record<string, McpStatus> = {}
-  const clients: Client[] = []
+  const clients: { close(): Promise<void> }[] = []
   const servers = new Map<string, ServerConn>()
+  const skills: SkillDef[] = []
+  const store = defaultTokenStore({ tokenStore: opts?.tokenStore })
   const waitFor = opts?.waitFor
   const signal = opts?.signal
   const onServer = opts?.onServer
@@ -512,22 +621,29 @@ export async function loadMcp(
         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: Client | undefined
       try {
-        await raceTimeout(connectTransport(client, cfg), timeout, signal)
-        const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal)
-        const kept = applyToolsFilter(name, defs, (cfg as { tools?: Record<string, boolean> }).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: Tool[]
+        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 as { tools?: Record<string, boolean> }).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 as Client | undefined)?.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) throw e
@@ -558,6 +674,7 @@ export async function loadMcp(
       await Promise.all(clients.map((c) => c.close().catch(() => {})))
     },
     resourceTools: () => resourceTools(servers),
+    skills,
   }
 }
 
@@ -579,11 +696,12 @@ 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 async function listMcpTools(input: string | object, opts?: { signal?: AbortSignal }): Promise<McpInventory> {
+export async function listMcpTools(input: string | object, opts?: McpLoadOptions): Promise<McpInventory> {
   const config = parseMcpConfig(input)
   const toolsByServer: Record<string, ToolInfo[]> = {}
   const status: Record<string, McpStatus> = {}
   const signal = opts?.signal
+  const store = defaultTokenStore({ tokenStore: opts?.tokenStore })
 
   await Promise.all(
     Object.entries(config).map(async ([name, cfg]) => {
@@ -592,11 +710,12 @@ export async function listMcpTools(input: string | object, opts?: { signal?: Abo
         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: Client | undefined
       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: any[] = 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 ?? "",
@@ -609,10 +728,10 @@ export async function listMcpTools(input: string | object, opts?: { signal?: Abo
         status[name] = "connected"
       } catch (e) {
         status[name] = "failed"
-        if (signal?.aborted) { await client.close().catch(() => {}); throw e }
+        if (signal?.aborted) { await (client as Client | undefined)?.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 as Client | undefined)?.close().catch(() => {})
       }
     }),
   )