toolnexus 0.25.0 → 0.27.0

package/dist/client.d.ts

@@ -208,6 +208,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;
 } | {
     event: "classifier.warning";
     question: string;

package/dist/judge.d.ts

@@ -7,12 +7,12 @@
  *
  * A gate never authorises; it only declines to decide.
  */
-import { Classifier, Decision, type DecisionAnswer, type NoulCriteria, type Question, type RecordedDecision } from "./classifier.js";
+import { Classifier, Decision, type DecisionAnswer, type NoulCriteria, type AnyQuestion, type RecordedDecision } from "./classifier.js";
 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`. */
 export declare function noul(name: string, instructions: string, criteria?: NoulCriteria): NamedQuestion;
@@ -20,8 +20,11 @@ export declare function noul(name: string, instructions: string, criteria?: Noul
 export declare function choice(name: string, instructions: string, options: Record<string, string>): NamedQuestion;
 /** `score` question with a name; `levels` is the ordered rubric. */
 export declare function score(name: string, instructions: string, levels: string[]): NamedQuestion;
+/** 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 declare function raw(name: string, type: string, instructions: string, criteria?: unknown): NamedQuestion;
 /** Ordered list -> the §8B questions map. A duplicate name is an error naming it. */
-export declare function questionMap(questions: readonly NamedQuestion[]): Record<string, Question>;
+export declare function questionMap(questions: readonly NamedQuestion[]): Record<string, AnyQuestion>;
 /** `role` next to the data's fields; a non-object value goes under `data`. */
 export declare function State(role: string, data: unknown): Record<string, unknown>;
 /** Sugar: `{context, message, ...extra}`. */

package/dist/judge.js

@@ -7,7 +7,7 @@
  *
  * A gate never authorises; it only declines to decide.
  */
-import { Classifier, noul as noulQ, choice as choiceQ, score as scoreQ, } from "./classifier.js";
+import { Classifier, isRawAnswer, raw as rawQ, noul as noulQ, choice as choiceQ, score as scoreQ, } from "./classifier.js";
 /** `noul` question with a name. Name the state field it judges in `instructions`. */
 export function noul(name, instructions, criteria) {
     return { name, question: noulQ(instructions, criteria) };
@@ -20,6 +20,11 @@ export function choice(name, instructions, options) {
 export function score(name, instructions, levels) {
     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, type, instructions, criteria) {
+    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) {
     const out = {};
@@ -47,6 +52,13 @@ function noulBand(p, b) {
     return p < b.low ? "no" : p > b.high ? "yes" : "uncertain";
 }
 function wrap(a, b) {
+    if (isRawAnswer(a)) {
+        // An unmodelled answer type is never sure: there is no number to band.
+        const out = { ...a, sure: false };
+        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) }
         : { sure: a.confidence > b.high && !(a.type === "choice" && a.nearUniform) };

package/dist/mcp.js

@@ -6,14 +6,16 @@
 import { readFileSync } from "node:fs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { AdoptedStdioTransport } from "./mcp2026/stdio.js";
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.js";
 import { summarizePart } from "./content.js";
-import { probe, newOAuth, defaultTokenStore } from "./mcp2026/source.js";
 import { PendingError } from "./mcp2026/auth.js";
 export { Token, MemoryTokenStore } from "./mcp2026/auth.js";
+// Loaded on first use, not at import: the 2026 client is only needed once a config is loaded,
+// and the SDK's remote transports (streamable-HTTP, SSE) only when a remote server falls back.
+let mcp2026;
+const loadMcp2026 = () => (mcp2026 ??= import("./mcp2026/source.js"));
 // ---------------------------------------------------------------------------
 // MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
 // (a reverse-request). We map it onto the one `waitFor`: form mode → kind:"input",
@@ -410,6 +412,10 @@ async function connectTransport(client, cfg, auth) {
         const expanded = expandEnvHeaders(cfg.headers);
         const requestInit = expanded ? { headers: expanded } : undefined;
         const fetch = auth ? bearerFetch(cfg.url, auth) : undefined;
+        const [{ StreamableHTTPClientTransport }, { SSEClientTransport }] = await Promise.all([
+            import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+            import("@modelcontextprotocol/sdk/client/sse.js"),
+        ]);
         try {
             await client.connect(new StreamableHTTPClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }));
         }
@@ -469,6 +475,7 @@ function bearerFetch(resource, a) {
  * path, with the OAuth bearer attached for remote servers. Throws ⇒ the server failed.
  */
 async function connectServer(name, cfg, timeout, opts, store, sdkClient, onSdk) {
+    const { newOAuth, probe } = await loadMcp2026();
     const o = { waitFor: opts.waitFor, tokenStore: store, openUrl: opts.openUrl, signal: opts.signal, disableTools: opts.disableTools };
     const remote = isRemote(cfg);
     const oauth = remote ? newOAuth(cfg.auth, o, store) : undefined;
@@ -485,7 +492,10 @@ async function connectServer(name, cfg, timeout, opts, store, sdkClient, onSdk)
         return p;
     const client = sdkClient();
     onSdk(client);
-    await raceTimeout(connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined), timeout, opts.signal);
+    const connecting = p.reuse
+        ? client.connect(new AdoptedStdioTransport(p.reuse.child, p.reuse.leftover)) // §2.2a: same child, no respawn
+        : connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined);
+    await raceTimeout(connecting, timeout, opts.signal);
     const defs = await raceTimeout(paginateTools(client, timeout), timeout, opts.signal);
     return { kind: "sdk", client, defs };
 }
@@ -499,7 +509,7 @@ export async function loadMcp(input, opts) {
     const clients = [];
     const servers = new Map();
     const skills = [];
-    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
+    const store = (await loadMcp2026()).defaultTokenStore({ tokenStore: opts?.tokenStore });
     const waitFor = opts?.waitFor;
     const signal = opts?.signal;
     const onServer = opts?.onServer;
@@ -590,7 +600,7 @@ export async function listMcpTools(input, opts) {
     const toolsByServer = {};
     const status = {};
     const signal = opts?.signal;
-    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
+    const store = (await loadMcp2026()).defaultTokenStore({ tokenStore: opts?.tokenStore });
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";

package/dist/mcp2026/source.d.ts

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

package/dist/mcp2026/source.js

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

package/dist/mcp2026/stdio.d.ts

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

package/dist/mcp2026/stdio.js

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

package/dist/mcphandler.js

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

package/dist/mcpserve.js

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

package/dist/serve.js

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

package/dist/skill.d.ts

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

package/dist/skill.js

@@ -12,8 +12,16 @@
 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";
+// 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;
+function parseYaml(src) {
+    yamlParse ??= createRequire(import.meta.url)("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.
@@ -25,6 +33,8 @@ The skill name must match one of the skills listed in your system prompt.`;
  */
 export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions and workflows for specific tasks.\n" +
     "Use the skill tool to load a skill when a task matches its description.";
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export const SKILL_DESCRIPTION_MAX_CHARS = 1024;
 /**
  * Parse YAML frontmatter (between the leading `---` fences) with a real YAML parser, so folded
  * (`>`)/literal (`|`) block scalars, quoting and multi-line values all resolve correctly.
@@ -304,6 +314,24 @@ function collectCandidates(opts) {
         cands.push(...candidatesFromDefs(opts.skills));
     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) {
+    const out = [];
+    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) {
     const skills = {};
@@ -355,7 +383,8 @@ function applySkillsFilter(skills, filter) {
 export function listSkills(input) {
     const opts = 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. */
 export function loadSkills(input) {
@@ -364,6 +393,7 @@ export function loadSkills(input) {
     const merged = mergeCandidates(collectCandidates(opts));
     const skills = applySkillsFilter(merged.skills, opts.filter);
     const skipped = merged.skipped;
+    const warnings = describeWarnings(Object.values(skills));
     const tool = {
         name: "skill",
         description: SKILL_TOOL_DESCRIPTION,
@@ -426,6 +456,7 @@ export function loadSkills(input) {
         skills,
         tool,
         skipped,
+        warnings,
         prompt() {
             const described = Object.values(skills)
                 .filter((s) => s.description !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/acp-client.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts test/tool-concurrency.test.ts test/media.test.ts test/examples.test.ts test/mcphandler.test.ts test/mcphandler-conformance.test.ts test/mcp2026.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/classifier-backends.test.ts test/acp.test.ts test/acp-client.test.ts test/issues.test.ts test/host-boundary.test.ts test/judge.test.ts test/batteries.test.ts test/host-engine.test.ts test/host-turn-durability.test.ts test/host-engine-asks.test.ts test/tool-concurrency.test.ts test/media.test.ts test/examples.test.ts test/mcphandler.test.ts test/mcphandler-conformance.test.ts test/mcp2026.test.ts test/serve-mcp-conformance.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts",
     "example:judge": "node --experimental-strip-types examples/judge.ts",
     "example:multimodal": "node --experimental-strip-types examples/multimodal.ts",