toolnexus 0.6.0 → 0.8.0

package/dist/builtin.js

@@ -11,6 +11,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import { existsSync, readdirSync } from "node:fs";
 import path from "node:path";
+import { pending } from "./types.js";
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP:
  * `disabled:true` wins, else `enabled:false` disables, otherwise enabled.
@@ -388,8 +389,25 @@ function webfetchTool() {
         }
     });
 }
+/**
+ * Render the questions into a human-readable `Request.prompt` (§10). Byte-identical across ports:
+ * each question's text in order, `" (options: a, b, c)"` appended when it has non-empty options,
+ * joined by "\n" (no trailing newline). `header` is not rendered — it survives in `data.questions`.
+ */
+function renderQuestionPrompt(questions) {
+    return questions
+        .map((q) => {
+        const item = q;
+        let line = typeof item?.question === "string" ? item.question : "";
+        const opts = Array.isArray(item?.options) ? item.options : [];
+        if (opts.length > 0)
+            line += ` (options: ${opts.join(", ")})`;
+        return line;
+    })
+        .join("\n");
+}
 function questionTool() {
-    return builtin("question", "Ask the host one or more questions. Returns the questions as structured output for the host to answer.", {
+    return builtin("question", "Ask the host one or more questions. Suspends via a kind:\"question\" Request (§10); the host's waitFor resolves it and the answer is returned to the model.", {
         type: "object",
         properties: {
             questions: {
@@ -409,9 +427,14 @@ function questionTool() {
         },
         required: ["questions"],
         additionalProperties: false,
-    }, async (args) => {
+    }, async (args, ctx) => {
         const questions = Array.isArray(args.questions) ? args.questions : [];
-        return ok(JSON.stringify(questions), { questions });
+        // Re-executed after the host's waitFor resolved (§10 loop rule): the resolution IS the
+        // answer, as with kind:"input" — forward it verbatim to the model.
+        if (ctx?.answer)
+            return ok(JSON.stringify(ctx.answer.data ?? {}));
+        // First call: suspend. A question is just a §10 Request with kind:"question".
+        return pending({ kind: "question", prompt: renderQuestionPrompt(questions), data: { questions } });
     });
 }
 function todowriteTool() {

package/dist/client.d.ts

@@ -51,6 +51,7 @@ export type MetricEvent = {
     source: string;
     isError: boolean;
     ms: number;
+    pending?: boolean;
 } | {
     event: "run";
     model: string;
@@ -237,6 +238,8 @@ export declare class Client {
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;
+    /** Emit the `tool` metric, classifying a §10 suspension as `pending` (isError:false), not a failure. */
+    private emitTool;
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     private llmCallJson;
     private runOpenAI;

package/dist/client.js

@@ -98,7 +98,7 @@ class MetricsRegistry {
             observe(this.llmDuration, labelStr([["model", ev.model]]), ev.ms / 1000);
         }
         else if (ev.event === "tool") {
-            inc(this.toolCalls, labelStr([["tool", ev.tool], ["source", ev.source], ["is_error", String(ev.isError)]]));
+            inc(this.toolCalls, labelStr([["tool", ev.tool], ["source", ev.source], ["is_error", String(ev.isError)], ["pending", String(ev.pending ?? false)]]));
             observe(this.toolDuration, labelStr([["tool", ev.tool]]), ev.ms / 1000);
         }
         else if (ev.event === "run") {
@@ -270,22 +270,31 @@ export class Client {
         if (h?.beforeTool) {
             const ov = await h.beforeTool({ name, args: a, id, turn });
             if (ov?.result) {
-                // short-circuit (deny/cache/dry-run) — still a tool call for metrics purposes
-                this.emit({ event: "tool", tool: name, source, isError: ov.result.isError, ms: Date.now() - t0 });
+                // short-circuit (deny/cache/dry-run, or a guard-raised suspension — path B); still a tool
+                // call for metrics, but a suspension is classified pending, never an error.
+                this.emitTool(name, source, ov.result, t0);
                 return { args: a, result: ov.result };
             }
             if (ov?.args)
                 a = ov.args;
         }
         let result = await toolkit.execute(name, a);
-        if (h?.afterTool) {
+        // A suspension (§10) is not a real result: skip afterTool's failure path on it — the resolved
+        // result (post-waitFor) still flows through afterTool in resolvePending — and never count it as
+        // a tool error.
+        if (h?.afterTool && !pendingOf(result)) {
             const ov = await h.afterTool({ name, args: a, result, id, turn });
             if (ov?.result)
                 result = ov.result;
         }
-        this.emit({ event: "tool", tool: name, source, isError: result.isError, ms: Date.now() - t0 });
+        this.emitTool(name, source, result, t0);
         return { args: a, result };
     }
+    /** Emit the `tool` metric, classifying a §10 suspension as `pending` (isError:false), not a failure. */
+    emitTool(name, source, result, t0) {
+        const req = pendingOf(result);
+        this.emit({ event: "tool", tool: name, source, isError: req ? false : result.isError, ms: Date.now() - t0, ...(req ? { pending: true } : {}) });
+    }
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     async llmCallJson(url, init, signal, style) {
         const t0 = Date.now();
@@ -343,22 +352,26 @@ export class Client {
                 if (calls.length === 0)
                     return this.endRun(runStart, msg.content ?? "", messages, toolCalls, turns, usage);
                 // execute all tool calls in this turn concurrently (true parallel tool calling)
-                let halted;
-                const results = await Promise.all(calls.map(async (call) => {
+                const settled = await Promise.all(calls.map(async (call) => {
                     let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn);
+                    let halted;
                     const req = pendingOf(result);
                     if (req) {
                         const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn);
                         result = r.result;
-                        if (r.halted)
-                            halted = r.halted;
+                        halted = r.halted;
                     }
-                    toolCalls.push({ name: call.function.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                    return { role: "tool", tool_call_id: call.id, content: result.output };
+                    return { call, args, result, halted };
                 }));
-                messages.push(...results);
-                if (halted)
-                    return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
+                // Record in tool-call order; on the FIRST durable halt, surface it and stop — deterministic,
+                // and the later suspensions' placeholder results never enter the transcript (they re-suspend
+                // on resume). Mirrors the streaming path.
+                for (const s of settled) {
+                    toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
+                    messages.push({ role: "tool", tool_call_id: s.call.id, content: s.result.output });
+                    if (s.halted)
+                        return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage);
+                }
             }
             return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage);
         }
@@ -393,7 +406,7 @@ export class Client {
             if (ov?.result)
                 result = ov.result;
         }
-        this.emit({ event: "tool", tool: name, source: toolkit.get(name)?.source ?? "custom", isError: result.isError, ms: Date.now() - t0 });
+        this.emitTool(name, toolkit.get(name)?.source ?? "custom", result, t0);
         if (pendingOf(result))
             result = { output: `unresolved: ${request.prompt}`, isError: true }; // never loop forever
         return { result };
@@ -441,20 +454,31 @@ export class Client {
                     return this.endRun(runStart, text, messages, toolCalls, turns, usage);
                 }
                 // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
-                let halted;
-                const results = await Promise.all(uses.map(async (use) => {
+                const settled = await Promise.all(uses.map(async (use) => {
                     let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn);
+                    let halted;
                     const req = pendingOf(result);
                     if (req) {
                         const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn);
                         result = r.result;
-                        if (r.halted)
-                            halted = r.halted;
+                        halted = r.halted;
                     }
-                    toolCalls.push({ name: use.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                    return { type: "tool_result", tool_use_id: use.id, content: result.output, is_error: result.isError };
+                    return { use, args, result, halted };
                 }));
-                messages.push({ role: "user", content: results });
+                // Record in tool-call order; on the FIRST durable halt, include that tool_result block, stop
+                // building the content, and surface it — deterministic (G3), later suspensions re-suspend on
+                // resume. Mirrors the OpenAI path and the streaming loops.
+                const content = [];
+                let halted;
+                for (const s of settled) {
+                    toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
+                    content.push({ type: "tool_result", tool_use_id: s.use.id, content: s.result.output, is_error: s.result.isError });
+                    if (s.halted) {
+                        halted = s.halted;
+                        break;
+                    }
+                }
+                messages.push({ role: "user", content });
                 if (halted)
                     return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
             }

package/dist/mcp.d.ts

@@ -1,4 +1,9 @@
-import { type Tool, type McpStatus } from "./types.js";
+import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
+import { type Tool, type McpStatus, type Request, type Answer } from "./types.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. */
+export declare function answerToElicitResult(answer: Answer): ElicitResult;
 export interface LocalServer {
     type?: "local";
     command: string[];
@@ -32,4 +37,6 @@ export interface McpSource {
     close(): Promise<void>;
 }
 /** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export declare function loadMcp(input: string | object): Promise<McpSource>;
+export declare function loadMcp(input: string | object, opts?: {
+    waitFor?: (request: Request) => Promise<Answer>;
+}): Promise<McpSource>;

package/dist/mcp.js

@@ -8,7 +8,35 @@ 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 { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.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",
+// URL mode → kind:"authorization". The two mappings are pure + byte-parity-tested.
+// ---------------------------------------------------------------------------
+let _elcSeq = 0;
+/** Map an MCP `elicitation/create` request onto a §10 `Request`. */
+export function elicitationToRequest(params) {
+    const p = params;
+    const isUrl = p.mode === "url";
+    const req = {
+        id: `elc-${Date.now().toString(36)}-${++_elcSeq}`,
+        kind: isUrl ? "authorization" : "input",
+        prompt: String(p.message ?? ""),
+    };
+    if (isUrl && p.url)
+        req.url = p.url;
+    if (!isUrl && p.requestedSchema)
+        req.data = { schema: p.requestedSchema };
+    return req;
+}
+/** Map a resolved §10 `Answer` back onto an MCP `ElicitResult`. ok→accept; declined→decline; else→cancel. */
+export function answerToElicitResult(answer) {
+    if (answer.ok)
+        return { action: "accept", content: (answer.data ?? {}) };
+    return { action: answer.reason === "declined" ? "decline" : "cancel" };
+}
 const DEFAULT_TIMEOUT = 30_000;
 const MAX_LIST_PAGES = 1_000;
 function isRemote(cfg) {
@@ -117,18 +145,24 @@ function convertTool(server, def, client, timeout) {
     };
 }
 /** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export async function loadMcp(input) {
+export async function loadMcp(input, opts) {
     const config = parseMcpConfig(input);
     const tools = [];
     const status = {};
     const clients = [];
+    const waitFor = opts?.waitFor;
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: {} });
+        // Advertise elicitation + register the bridge ONLY when a waitFor exists to satisfy it —
+        // a waitFor-less host degrades cleanly (the server won't elicit). (§10 elicitation bridge)
+        const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} });
+        if (waitFor) {
+            client.setRequestHandler(ElicitRequestSchema, async (request) => answerToElicitResult(await waitFor(elicitationToRequest(request.params))));
+        }
         try {
             if (isRemote(cfg)) {
                 const url = new URL(cfg.url);

package/dist/serve.js

@@ -50,7 +50,13 @@ export class FileTaskStore {
         }
     }
     async save(task) {
-        fs.writeFileSync(this.file(task.id), JSON.stringify(task));
+        // Atomic write: a concurrent get() must never read a half-written file (that
+        // would surface as a spurious "Task not found" mid-poll). Write a temp file in
+        // the same dir, then rename over the target.
+        const target = this.file(task.id);
+        const tmp = `${target}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(task));
+        fs.renameSync(tmp, target);
     }
 }
 /** Map a `store` selector to a concrete TaskStore. `"file:<dir>"` → FileTaskStore. */
@@ -239,12 +245,23 @@ async function fulfil(id, text, store, runTask, onTask, contextId) {
         // contextId groups a peer's turns into one conversation — thread it so the
         // client's ConversationStore remembers across tasks in the same context.
         result = await runTask(text, contextId);
-        const artifact = {
-            artifactId: randomUUID(),
-            parts: [{ kind: "text", text: result.text }],
-        };
-        task = { id, status: { state: "completed" }, artifacts: [artifact] };
-        state = "completed";
+        if (result.status === "pending" && result.pending) {
+            // §10 suspension over A2A: the run halted waiting on out-of-band input. Surface the
+            // protocol's `input-required` state carrying the request prompt — never a false `completed`.
+            task = {
+                id,
+                status: { state: "input-required", message: { role: "agent", parts: [{ kind: "text", text: result.pending.prompt }] } },
+            };
+            state = "input-required";
+        }
+        else {
+            const artifact = {
+                artifactId: randomUUID(),
+                parts: [{ kind: "text", text: result.text }],
+            };
+            task = { id, status: { state: "completed" }, artifacts: [artifact] };
+            state = "completed";
+        }
     }
     catch (e) {
         const detail = e instanceof Error ? e.message : String(e);

package/dist/skill.d.ts

@@ -10,6 +10,42 @@ export interface SkillInfo {
     description?: string;
     location: string;
     content: string;
+    /** Internal origin discriminator; "fs" ⇒ on-disk (default), "logical" ⇒ data. */
+    origin?: "fs" | "logical";
+    /** Logical resource list (data-sourced skills only). */
+    resources?: string[];
+    /** Logical base, e.g. skill://name/ (data-sourced skills only). */
+    base?: string;
+}
+/** A skill supplied directly as data, bypassing the filesystem (SPEC.md §3, S1). */
+export interface SkillDef {
+    name: string;
+    description?: string;
+    content: string;
+    /** Optional logical resource names surfaced in the invoke-time <skill_files> block. */
+    resources?: string[];
+    /** Optional logical base; defaults to `skill://<name>/`. */
+    base?: string;
+}
+/** Why a candidate SKILL.md did not become a skill (SPEC.md §3, S3). */
+export type SkillSkipReason = "missing-name" | "malformed-frontmatter" | "duplicate-name" | "unreadable";
+export interface SkillSkip {
+    location: string;
+    reason: SkillSkipReason;
+}
+/** Result of a list-only validate pass (SPEC.md §3, S3). */
+export interface SkillInventory {
+    skills: SkillInfo[];
+    skipped: SkillSkip[];
+}
+/** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
+export interface LoadSkillsOptions {
+    dirs?: string | string[];
+    skills?: SkillDef[];
+    /** Per-agent allowlist keyed on skill name; same semantics as the MCP tools filter. */
+    filter?: Record<string, boolean>;
+    /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files>. */
+    sampleLimit?: number;
 }
 export interface SkillSource {
     skills: Record<string, SkillInfo>;
@@ -17,5 +53,11 @@ export interface SkillSource {
     /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
     prompt(): string;
 }
-/** Discover skills under one or more roots and build the `skill` loader tool. */
-export declare function loadSkills(dirs: string | string[]): SkillSource;
+/**
+ * Discover + validate skills from the same sources loadSkills accepts, returning
+ * parsed skills plus typed skip reasons — no toolkit wired (SPEC.md §3, S3). The
+ * inventory is UNFILTERED (it exists to author/validate the allowlist).
+ */
+export declare function listSkills(input: string | string[] | LoadSkillsOptions): SkillInventory;
+/** Discover skills (dirs and/or data) and build the `skill` loader tool. */
+export declare function loadSkills(input: string | string[] | LoadSkillsOptions): SkillSource;

package/dist/skill.js

@@ -3,6 +3,11 @@
  * discover **\/SKILL.md, parse frontmatter, and expose ONE `skill` tool that
  * loads a skill's instructions + sampled resources on demand (progressive
  * disclosure).
+ *
+ * Beyond on-disk discovery the source also accepts skills supplied as data
+ * (`SkillDef`) — SPEC.md §3. Directory-sourced skills keep the exact `file://`
+ * base + on-disk sibling sampling (byte-identical); data-sourced skills use a
+ * logical `skill://name/` base + a supplied resource list and never touch disk.
  */
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
@@ -23,18 +28,25 @@ export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions a
  * 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. Scalar values are coerced to strings.
+ *
+ * `malformed` is true only when fences are present but the YAML fails to parse —
+ * distinguishing a malformed header from a body with no frontmatter, so the
+ * inventory (S3) can report the right skip reason. loadSkills' behavior is
+ * unchanged: a malformed header yields no name and the skill is skipped.
  */
 function parseFrontmatter(text) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!match)
-        return { data: {}, content: text };
+        return { data: {}, content: text, malformed: false };
     const data = {};
     let parsed;
+    let malformed = false;
     try {
         parsed = parseYaml(match[1]);
     }
     catch {
         parsed = null;
+        malformed = true;
     }
     if (parsed && typeof parsed === "object") {
         for (const [key, value] of Object.entries(parsed)) {
@@ -45,7 +57,7 @@ function parseFrontmatter(text) {
             }
         }
     }
-    return { data, content: match[2] };
+    return { data, content: match[2], malformed };
 }
 function walkSkillFiles(root) {
     const out = [];
@@ -150,45 +162,130 @@ function sampleSiblingFiles(dir, limit = 10) {
     }
     return out;
 }
-/** Discover skills under one or more roots and build the `skill` loader tool. */
-export function loadSkills(dirs) {
-    const roots = Array.isArray(dirs) ? dirs : [dirs];
-    const skills = {};
-    for (const root of roots) {
-        let isDir = false;
+/** Discover candidates under one on-disk root (order = discovery order). */
+function candidatesFromDir(root) {
+    const out = [];
+    let isDir = false;
+    try {
+        isDir = statSync(root).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        console.warn(`[toolnexus] skills dir not found: ${root}`);
+        return out;
+    }
+    for (const file of walkSkillFiles(root)) {
+        let text;
         try {
-            isDir = statSync(root).isDirectory();
+            text = readFileSync(file, "utf8");
         }
         catch {
-            isDir = false;
+            out.push({ skip: { location: file, reason: "unreadable" } });
+            continue;
         }
-        if (!isDir) {
-            console.warn(`[toolnexus] skills dir not found: ${root}`);
+        const { data, content, malformed } = parseFrontmatter(text);
+        if (malformed) {
+            out.push({ skip: { location: file, reason: "malformed-frontmatter" } });
             continue;
         }
-        for (const file of walkSkillFiles(root)) {
-            let text;
-            try {
-                text = readFileSync(file, "utf8");
-            }
-            catch {
-                continue;
-            }
-            const { data, content } = parseFrontmatter(text);
-            if (!data.name)
-                continue;
-            if (skills[data.name]) {
-                console.warn(`[toolnexus] duplicate skill name "${data.name}" (${file}) — keeping first`);
-                continue;
-            }
-            skills[data.name] = {
-                name: data.name,
-                description: data.description,
-                location: file,
-                content,
-            };
+        if (!data.name) {
+            out.push({ skip: { location: file, reason: "missing-name" } });
+            continue;
         }
+        out.push({ info: { name: data.name, description: data.description, location: file, content, origin: "fs" } });
     }
+    return out;
+}
+/** Turn data-supplied skill defs into candidates (logical origin). */
+function candidatesFromDefs(defs) {
+    return defs.map((d) => {
+        if (!d.name)
+            return { skip: { location: d.base ?? "skill://", reason: "missing-name" } };
+        const base = d.base && d.base.length > 0 ? d.base : `skill://${d.name}/`;
+        return {
+            info: {
+                name: d.name,
+                description: d.description,
+                location: base,
+                content: d.content ?? "",
+                origin: "logical",
+                resources: d.resources ?? [],
+                base,
+            },
+        };
+    });
+}
+/** Collect ordered candidates from dirs then data defs. */
+function collectCandidates(opts) {
+    const roots = opts.dirs === undefined ? [] : Array.isArray(opts.dirs) ? opts.dirs : [opts.dirs];
+    const cands = [];
+    for (const root of roots)
+        cands.push(...candidatesFromDir(root));
+    if (opts.skills)
+        cands.push(...candidatesFromDefs(opts.skills));
+    return cands;
+}
+/** Dedupe candidates by name (first-wins); later duplicates become skips. */
+function mergeCandidates(cands) {
+    const skills = {};
+    const skipped = [];
+    for (const c of cands) {
+        if (c.skip) {
+            skipped.push(c.skip);
+            continue;
+        }
+        const info = c.info;
+        if (skills[info.name]) {
+            console.warn(`[toolnexus] duplicate skill name "${info.name}" (${info.location}) — keeping first`);
+            skipped.push({ location: info.location, reason: "duplicate-name" });
+            continue;
+        }
+        skills[info.name] = info;
+    }
+    return { skills, skipped };
+}
+/**
+ * Apply the per-agent skill allowlist (S2), semantics identical to the MCP
+ * per-server tools filter and builtins: nil/empty ⇒ all; ≥1 true ⇒ allowlist
+ * (only true-mapped names); only-false ⇒ drop-list over all-on; unknown names
+ * are ignored and warned once.
+ */
+function applySkillsFilter(skills, filter) {
+    if (!filter)
+        return skills;
+    const keys = Object.keys(filter);
+    if (keys.length === 0)
+        return skills;
+    const hasTrue = keys.some((k) => filter[k] === true);
+    for (const k of keys) {
+        if (!(k in skills))
+            console.warn(`[toolnexus] skill filter name "${k}" matched no skill`);
+    }
+    const out = {};
+    for (const [name, info] of Object.entries(skills)) {
+        if (hasTrue ? filter[name] === true : filter[name] !== false)
+            out[name] = info;
+    }
+    return out;
+}
+/**
+ * Discover + validate skills from the same sources loadSkills accepts, returning
+ * parsed skills plus typed skip reasons — no toolkit wired (SPEC.md §3, S3). The
+ * inventory is UNFILTERED (it exists to author/validate the allowlist).
+ */
+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 };
+}
+/** Discover skills (dirs and/or data) and build the `skill` loader tool. */
+export function loadSkills(input) {
+    const opts = typeof input === "string" || Array.isArray(input) ? { dirs: input } : input;
+    const sampleLimit = opts.sampleLimit ?? 0;
+    const merged = mergeCandidates(collectCandidates(opts));
+    const skills = applySkillsFilter(merged.skills, opts.filter);
     const tool = {
         name: "skill",
         description: SKILL_TOOL_DESCRIPTION,
@@ -208,10 +305,30 @@ export function loadSkills(dirs) {
                     isError: true,
                 };
             }
-            const dir = path.dirname(info.location);
-            const base = pathToFileURL(dir).href;
-            const files = sampleSiblingFiles(dir);
-            const output = [
+            // effLimit: 0 ⇒ default 10 (byte-identical to today), n>0 ⇒ cap, -1 ⇒ omit.
+            const effLimit = sampleLimit === 0 ? 10 : sampleLimit;
+            let base;
+            let files;
+            let metaDir;
+            // Emit the <skill_files> block: always for fs skills (byte-identical, even
+            // when empty), only when a data skill actually carries resources (an
+            // instruction-only data skill omits it). Never when sampling is disabled.
+            let emitFiles = effLimit !== -1;
+            if (info.origin === "logical") {
+                base = info.base ?? `skill://${info.name}/`;
+                const res = info.resources ?? [];
+                if (res.length === 0)
+                    emitFiles = false;
+                files = effLimit > 0 ? res.slice(0, effLimit) : res;
+                metaDir = base;
+            }
+            else {
+                const dir = path.dirname(info.location);
+                base = pathToFileURL(dir).href;
+                files = effLimit === -1 ? [] : sampleSiblingFiles(dir, effLimit);
+                metaDir = dir;
+            }
+            const lines = [
                 `<skill_content name="${info.name}">`,
                 `# Skill: ${info.name}`,
                 "",
@@ -219,14 +336,12 @@ export function loadSkills(dirs) {
                 "",
                 `Base directory for this skill: ${base}`,
                 "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
-                "Note: file list is sampled.",
-                "",
-                "<skill_files>",
-                files.map((f) => `<file>${f}</file>`).join("\n"),
-                "</skill_files>",
-                "</skill_content>",
-            ].join("\n");
-            return { output, isError: false, metadata: { name: info.name, dir } };
+            ];
+            if (emitFiles) {
+                lines.push("Note: file list is sampled.", "", "<skill_files>", files.map((f) => `<file>${f}</file>`).join("\n"), "</skill_files>");
+            }
+            lines.push("</skill_content>");
+            return { output: lines.join("\n"), isError: false, metadata: { name: info.name, dir: metaDir } };
         },
     };
     return {