toolnexus 0.25.0 → 0.27.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.

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

@@ -6,18 +6,22 @@
 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 type { Tool as McpToolDef, ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js"
 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 { 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"
 
+// 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: Promise<typeof import("./mcp2026/source.js")> | undefined
+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",
@@ -477,6 +481,10 @@ async function connectTransport(client: Client, cfg: ServerConfig, auth?: Fallba
     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 } : {}) }))
     } catch {
@@ -552,6 +560,7 @@ type Connected =
  * 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 { newOAuth, probe } = await loadMcp2026()
   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
@@ -570,7 +579,10 @@ async function connectServer(name: string, cfg: ServerConfig, timeout: number, 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 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 }
 }
@@ -596,7 +608,7 @@ export async function loadMcp(
   const clients: { close(): Promise<void> }[] = []
   const servers = new Map<string, ServerConn>()
   const skills: SkillDef[] = []
-  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
@@ -701,7 +713,7 @@ export async function listMcpTools(input: string | object, opts?: McpLoadOptions
   const toolsByServer: Record<string, ToolInfo[]> = {}
   const status: Record<string, McpStatus> = {}
   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]) => {

package/src/mcp2026/source.ts

@@ -8,7 +8,8 @@ import { randomBytes } from "node:crypto"
 import { Mcp2026Client } from "./client.js"
 import { HttpStatusError, NotJsonRpcError, PROTOCOL_VERSION, RpcError, SKILLS_EXT, type Obj } from "./protocol.js"
 import { LoopbackAuthorizer, MemoryTokenStore, OAuth, PauseAuthorizer, PendingError, type TokenStore } from "./auth.js"
-import { spawnStdio, StdioClosedError } from "./stdio.js"
+import { spawnStdio, StdioClosedError, type StdioTransport } from "./stdio.js"
+import type { ChildProcess } from "node:child_process"
 import { rank } from "./toolsearch.js"
 import type { Answer, JSONSchema, Request, Tool, ToolContext, ToolResult } from "../types.js"
 import { sanitize } from "../types.js"
@@ -88,7 +89,9 @@ async function authed(oauth: OAuth | undefined, waitFor: WaitFor | undefined, f:
 }
 
 /** What the probe decided. `fallback` ⇒ take the frozen SDK path; anything thrown ⇒ status failed. */
-export type Probe = { kind: "modern"; server: ModernServer } | { kind: "fallback" }
+export type Probe =
+  | { kind: "modern"; server: ModernServer }
+  | { kind: "fallback"; reuse?: { child: ChildProcess; leftover: Buffer } }
 
 /** §2.2a: which discover failures mean "old server". */
 function isFallbackError(e: unknown): boolean {
@@ -115,11 +118,14 @@ export interface ProbeTarget {
 /** Discover first (§2.2). Resolves `modern` (tools listed) or `fallback`; throws on a load failure. */
 export async function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe> {
   let client: Mcp2026Client
+  let stdio: StdioTransport | undefined
   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: Obj
@@ -129,6 +135,8 @@ export async function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe>
     disc = await authed(oauth, o.waitFor, () => client.call("server/discover", {}, { timeoutMs, signal: o.signal }))
   } 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
     if (e instanceof StdioClosedError) throw e
@@ -136,9 +144,11 @@ export async function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe>
     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/src/mcp2026/stdio.ts

@@ -4,10 +4,12 @@
  * pending call instead of hanging. No headers, no auth.
  */
 import { spawn, type ChildProcess } from "node:child_process"
-import { createInterface } from "node:readline"
 import type { Readable } from "node:stream"
 import type { Transport } from "./client.js"
 import type { Obj } from "./protocol.js"
+import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js"
+import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js"
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js"
 
 /** The child exited / closed stdout before answering. */
 export class StdioClosedError extends Error {}
@@ -18,33 +20,89 @@ export class StdioTransport implements Transport {
   private done: Promise<void>
   private child: ChildProcess
 
+  private buf: Buffer = Buffer.alloc(0)
+  private onData: (chunk: Buffer) => void
+  private onEnd: () => void
+  private detached = false
+  private hold = false
+  private held = false
+
   constructor(child: ChildProcess) {
     this.child = child
-    const rl = createInterface({ input: child.stdout as Readable, crlfDelay: Infinity })
-    rl.on("line", (line) => {
-      let m: any
-      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", () => {
-        this.err ??= new StdioClosedError("stdio server closed its stdout")
-        for (const f of this.pending.values()) f({ __closed: true })
-        this.pending.clear()
-        r()
-      }),
-    )
+    // Line-exact own reader (no readline): detach() can stop it and hand over unread bytes.
+    let closed!: () => void
+    this.done = new Promise<void>((r) => (closed = r))
+    this.onData = (chunk: Buffer) => {
+      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()
+      closed()
+    }
+    const out = child.stdout as Readable
+    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
   }
 
+  private drain(): void {
+    let nl: number
+    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(): void {
+    this.hold = true
+  }
+
+  /** Leave probe mode and parse whatever was held. */
+  release(): void {
+    this.hold = false
+    this.held = false
+    this.drain()
+  }
+
+  private onLine(line: string): void {
+    let m: any
+    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(): { child: ChildProcess; leftover: Buffer } {
+    this.detached = true
+    const out = this.child.stdout as Readable
+    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: number, body: string, timeoutMs: number, signal?: AbortSignal): Promise<Obj> {
     if (this.err) return Promise.reject(this.err)
@@ -100,3 +158,70 @@ export function spawnStdio(argv: string[], env: NodeJS.ProcessEnv, cwd?: string)
     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 implements SdkTransport {
+  onclose?: () => void
+  onerror?: (error: Error) => void
+  onmessage?: (message: JSONRPCMessage) => void
+  private rb = new ReadBuffer()
+  private closed = false
+
+  constructor(private child: ChildProcess, private leftover: Buffer) {}
+
+  async start(): Promise<void> {
+    const out = this.child.stdout as Readable
+    out.on("data", (chunk: Buffer) => 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()
+  }
+
+  private feed(chunk: Buffer): void {
+    this.rb.append(chunk)
+    for (;;) {
+      let m: JSONRPCMessage | null
+      try {
+        m = this.rb.readMessage()
+      } catch (e) {
+        this.onerror?.(e as Error)
+        continue
+      }
+      if (m === null) break
+      this.onmessage?.(m)
+    }
+  }
+
+  send(message: JSONRPCMessage): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.child.stdin?.write(serializeMessage(message))) this.child.stdin?.once("drain", resolve)
+      else resolve()
+    })
+  }
+
+  private finish(): void {
+    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(): Promise<void> {
+    if (this.child.exitCode === null && this.child.signalCode === null) {
+      const exited = new Promise<void>((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/src/mcphandler.ts

@@ -348,7 +348,7 @@ export function createMcpHandler(toolkitTools: () => Tool[], cfg: McpHandlerConf
   /** Validates protocol header + session (stateful). Writes the HTTP error itself on failure. */
   async function checkSession(ctx: McpContext, req: IncomingMessage, res: ServerResponse): Promise<boolean> {
     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
     }
@@ -775,8 +775,7 @@ export function createMcpHandler(toolkitTools: () => Tool[], cfg: McpHandlerConf
     if (only2026) return true
     if (method === "initialize") return false
     const hv = header(req, "MCP-Protocol-Version")
-    if (hv === MCP_PROTOCOL_2026) return true
-    if (hv !== "" && versions.includes(hv)) return false
+    if (hv !== "" && legacy.includes(hv)) return false
     return method === "server/discover" || header(req, "Mcp-Method") !== "" || (meta !== undefined && META_VERSION in meta)
   }
 

package/src/mcpserve.ts

@@ -16,7 +16,6 @@ import http from "node:http"
 import type { AddressInfo } from "node:net"
 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"
 import type { Tool, ToolSource, ToolResult } from "./types.js"
 import type { ContentPart } from "./content.js"
@@ -166,6 +165,8 @@ export interface LocalMcpServer {
  */
 export async function serveLocalMcp(tools: Tool[], cfg?: MCPServeConfig): Promise<LocalMcpServer> {
   const exposed = exposedMcpTools(tools, cfg)
+  // Loaded on first serve, not at import: the transport pulls in @hono/node-server.
+  const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js")
   const token = randomBytes(32).toString("hex")
   const want = Buffer.from("Bearer " + token)
   const server = http.createServer((req, res) => {

package/src/serve.ts

@@ -18,7 +18,8 @@ import http from "node:http"
 import fs from "node:fs"
 import path from "node:path"
 import { randomUUID } from "node:crypto"
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+// The SDK server transport (and the @hono/node-server it pulls in) is loaded only when an MCP
+// profile is actually served, so importing toolnexus does not pay for it.
 import { sanitize, type Tool } from "./types.js"
 import type { SkillInfo } from "./skill.js"
 import type { RunResult } from "./client.js"
@@ -213,6 +214,9 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
   const [host, portStr] = splitAddr(opts.addr)
   const store = a2a ? resolveStore(a2a.store) : undefined
   const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : []
+  const StreamableHTTPServerTransport = mcp
+    ? (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport
+    : undefined
 
   const server = http.createServer((req, res) => {
     const rpcRes = (id: unknown, payload: object) => {
@@ -233,11 +237,18 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
     // per request (stateless — sessionIdGenerator undefined). Checked first so
     // `/mcp` is never shadowed by the A2A POST handler.
     if (mcp && req.url && (req.url === "/mcp" || req.url.startsWith("/mcp?"))) {
+      // Stateless profile: no server-initiated SSE stream exists, so only POST is
+      // served. Refuse anything else at once (§7C) instead of holding a GET open.
+      if (req.method !== "POST") {
+        res.writeHead(405, { Allow: "POST" })
+        res.end()
+        return
+      }
       void (async () => {
         const body = req.method === "POST" ? await readBody(req) : ""
         const parsed = body ? safeJson(body) : undefined
         const mcpServer = buildMcpServer(exposedTools, mcp, onCall)
-        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
+        const transport = new StreamableHTTPServerTransport!({ sessionIdGenerator: undefined })
         res.on("close", () => {
           void transport.close()
           void mcpServer.close()

package/src/skill.ts

@@ -12,10 +12,19 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs"
 import path from "node:path"
 import { pathToFileURL } from "node:url"
-import { parse as parseYaml } from "yaml"
+import { createRequire } from "node:module"
 import { compareCodePoints, compareDiscovery, sortEntriesByName } from "./order.js"
 import type { Tool, ToolResult } from "./types.js"
 
+// yaml is required on the first frontmatter parse, not at import, so a host with no skills never
+// loads it. `require` keeps the parse synchronous (listSkills/loadSkills are sync); yaml's Node
+// entry is CommonJS, so this is the same module instance an `import` would get.
+let yamlParse: ((src: string) => unknown) | undefined
+function parseYaml(src: string): unknown {
+  yamlParse ??= (createRequire(import.meta.url)("yaml") as typeof import("yaml")).parse
+  return yamlParse(src)
+}
+
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
@@ -68,10 +77,25 @@ export interface SkillSkip {
   detail?: string
 }
 
+/** Why a KEPT skill carries a warning (SPEC.md §3, #84). The skill still loads unchanged. */
+export type SkillWarningReason = "oversized-description"
+
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export const SKILL_DESCRIPTION_MAX_CHARS = 1024
+
+export interface SkillWarning {
+  location: string
+  reason: SkillWarningReason
+  /** Description length in Unicode CODE POINTS (not bytes, not UTF-16 units). */
+  chars: number
+}
+
 /** Result of a list-only validate pass (SPEC.md §3, S3). */
 export interface SkillInventory {
   skills: SkillInfo[]
   skipped: SkillSkip[]
+  /** Kept skills that load but carry a warning (oversized description), in discovery order. */
+  warnings: SkillWarning[]
 }
 
 /** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
@@ -353,6 +377,26 @@ function collectCandidates(opts: LoadSkillsOptions): RawCandidate[] {
   return cands
 }
 
+/**
+ * Warn — never modify — skills whose description exceeds SKILL_DESCRIPTION_MAX_CHARS code
+ * points (SPEC.md §3, #84). Each warning is also sent to the same channel as the
+ * duplicate-name warning. Order follows the given skills (discovery order).
+ */
+function describeWarnings(skills: SkillInfo[]): SkillWarning[] {
+  const out: SkillWarning[] = []
+  for (const s of skills) {
+    if (s.description === undefined) continue
+    const chars = [...s.description].length
+    if (chars > SKILL_DESCRIPTION_MAX_CHARS) {
+      console.warn(
+        `[toolnexus] skill "${s.name}" (${s.location}) description is ${chars} chars, over ${SKILL_DESCRIPTION_MAX_CHARS} — kept unmodified`,
+      )
+      out.push({ location: s.location, reason: "oversized-description", chars })
+    }
+  }
+  return out
+}
+
 /** Dedupe candidates by name (first-wins); later duplicates become skips. */
 function mergeCandidates(cands: RawCandidate[]): { skills: Record<string, SkillInfo>; skipped: SkillSkip[] } {
   const skills: Record<string, SkillInfo> = {}
@@ -409,6 +453,8 @@ export interface SkillSource {
    * that stops being reported is indistinguishable from something that was finished.
    */
   skipped: SkillSkip[]
+  /** Exposed (post-allowlist) skills whose description is oversized; never modified (#84). */
+  warnings: SkillWarning[]
 }
 
 /**
@@ -420,7 +466,8 @@ export function listSkills(input: string | string[] | LoadSkillsOptions): SkillI
   const opts: LoadSkillsOptions =
     typeof input === "string" || Array.isArray(input) ? { dirs: input } : input
   const merged = mergeCandidates(collectCandidates(opts))
-  return { skills: Object.values(merged.skills), skipped: merged.skipped }
+  const list = Object.values(merged.skills)
+  return { skills: list, skipped: merged.skipped, warnings: describeWarnings(list) }
 }
 
 /** Discover skills (dirs and/or data) and build the `skill` loader tool. */
@@ -432,6 +479,7 @@ export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillS
   const skills = applySkillsFilter(merged.skills, opts.filter)
 
   const skipped = merged.skipped
+  const warnings = describeWarnings(Object.values(skills))
   const tool: Tool = {
     name: "skill",
     description: SKILL_TOOL_DESCRIPTION,
@@ -499,6 +547,7 @@ export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillS
     skills,
     tool,
     skipped,
+    warnings,
     prompt() {
       const described = Object.values(skills)
         .filter((s) => s.description !== undefined)