toolnexus 0.7.0 → 0.9.0

package/dist/client.d.ts

@@ -32,6 +32,18 @@ export interface ClientOptions {
      * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
      * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
     waitFor?: (request: Request) => Promise<Answer>;
+    /** §8 Gap 1. Extra top-level keys shallow-merged into EVERY LLM body after the client builds
+     * its own — a requestParams key WINS on collision (e.g. max_tokens overrides the anthropic
+     * default). `messages`/`tools`/`stream` are forbidden here (stripped + warned) — rewrite
+     * messages via bodyTransform. Applied on all four paths. Omit ⇒ body byte-identical to today. */
+    requestParams?: Record<string, unknown>;
+    /** §8 Gap 1. Receives the fully assembled body (after requestParams merge) just before marshal
+     * and returns the body to send — the escape hatch for provider-specific rewriting (e.g. tool-role
+     * message preprocessing) without a proxy. Returning a falsy value ⇒ unchanged. Runs on every call. */
+    bodyTransform?: (body: Record<string, any>) => Record<string, any> | undefined | void;
+    /** §8 Gap 2. HTTP transport for LLM requests (retries included). Omit ⇒ global fetch. Scope is the
+     * LLM path only; MCP transports use the SDK's own client. */
+    fetch?: typeof fetch;
 }
 /**
  * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
@@ -191,6 +203,23 @@ export declare class Client {
     /** Cumulative Prometheus registry fed by the same events `onMetric` sees. */
     private readonly registry;
     constructor(opts: ClientOptions);
+    /**
+     * §8 Gap 4. The client's conversation store — the exact instance passed in `opts.store`, else
+     * the default in-memory store the client created. Read (`get`) and write (`save`) it directly to
+     * share state with `ask`; no consumer needs a shadow copy.
+     */
+    conversationStore(): ConversationStore;
+    /**
+     * §8 Gap 1. Apply the request-shaping contract to an assembled body: strip forbidden keys from
+     * requestParams, shallow-merge requestParams (caller wins), then run bodyTransform last. Called at
+     * every LLM body-build site so the ordering contract holds identically on all four paths.
+     */
+    private finalizeBody;
+    /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
+     * matches the pre-change body so a no-options call is byte-identical. */
+    private openaiBody;
+    /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
+    private anthropicBody;
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */

package/dist/client.js

@@ -150,6 +150,60 @@ export class Client {
         this.opts = opts;
         this.store = opts.store ?? new InMemoryConversationStore();
     }
+    /**
+     * §8 Gap 4. The client's conversation store — the exact instance passed in `opts.store`, else
+     * the default in-memory store the client created. Read (`get`) and write (`save`) it directly to
+     * share state with `ask`; no consumer needs a shadow copy.
+     */
+    conversationStore() {
+        return this.store;
+    }
+    /**
+     * §8 Gap 1. Apply the request-shaping contract to an assembled body: strip forbidden keys from
+     * requestParams, shallow-merge requestParams (caller wins), then run bodyTransform last. Called at
+     * every LLM body-build site so the ordering contract holds identically on all four paths.
+     */
+    finalizeBody(body) {
+        const rp = this.opts.requestParams;
+        if (rp) {
+            for (const [k, v] of Object.entries(rp)) {
+                if (k === "messages" || k === "tools" || k === "stream") {
+                    console.warn(`[toolnexus] requestParams key "${k}" is not allowed — ignored (use bodyTransform)`);
+                    continue;
+                }
+                body[k] = v;
+            }
+        }
+        if (this.opts.bodyTransform) {
+            const out = this.opts.bodyTransform(body);
+            if (out)
+                return out;
+        }
+        return body;
+    }
+    /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
+     * matches the pre-change body so a no-options call is byte-identical. */
+    openaiBody(messages, tools, stream) {
+        const b = { model: this.opts.model, messages };
+        if (tools.length) {
+            b.tools = tools;
+            b.tool_choice = "auto";
+        }
+        if (stream) {
+            b.stream = true;
+            b.stream_options = { include_usage: true };
+        }
+        return this.finalizeBody(b);
+    }
+    /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
+    anthropicBody(system, messages, tools, stream) {
+        const b = { model: this.opts.model, max_tokens: 4096, system, messages };
+        if (tools.length)
+            b.tools = tools;
+        if (stream)
+            b.stream = true;
+        return this.finalizeBody(b);
+    }
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics() {
         return this.registry.render();
@@ -244,7 +298,7 @@ export class Client {
         let lastErr;
         for (let attempt = 0; attempt <= retries; attempt++) {
             try {
-                const res = await fetch(url, { ...init, signal });
+                const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
                 if (res.ok || !RETRYABLE.has(res.status) || attempt === retries)
                     return res;
                 const ra = Number(res.headers.get("retry-after"));
@@ -341,7 +395,7 @@ export class Client {
                 const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                     method: "POST",
                     headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-                    body: JSON.stringify({ model: this.opts.model, messages, tools, tool_choice: "auto" }),
+                    body: JSON.stringify(this.openaiBody(messages, tools, false)),
                 }, signal, "openai");
                 addUsage(usage, data.usage, "openai");
                 if (this.opts.hooks?.afterLLM)
@@ -442,7 +496,7 @@ export class Client {
                         "Content-Type": "application/json",
                         ...this.opts.headers,
                     },
-                    body: JSON.stringify({ model: this.opts.model, max_tokens: 4096, system, messages, tools }),
+                    body: JSON.stringify(this.anthropicBody(system, messages, tools, false)),
                 }, signal, "anthropic");
                 addUsage(usage, data.usage, "anthropic");
                 if (this.opts.hooks?.afterLLM)
@@ -523,7 +577,7 @@ export class Client {
                     const res = await this.llmFetch(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                         method: "POST",
                         headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-                        body: JSON.stringify({ model: this.opts.model, messages, tools, tool_choice: "auto", stream: true, stream_options: { include_usage: true } }),
+                        body: JSON.stringify(this.openaiBody(messages, tools, true)),
                     }, signal);
                     if (!res.ok || !res.body)
                         throw new Error(`LLM ${res.status}: ${await res.text()}`);
@@ -630,7 +684,7 @@ export class Client {
                     const res = await this.llmFetch(endpoint, {
                         method: "POST",
                         headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "Content-Type": "application/json", ...this.opts.headers },
-                        body: JSON.stringify({ model: this.opts.model, max_tokens: 4096, system, messages, tools, stream: true }),
+                        body: JSON.stringify(this.anthropicBody(system, messages, tools, true)),
                     }, signal);
                     if (!res.ok || !res.body)
                         throw new Error(`LLM ${res.status}: ${await res.text()}`);

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
-import { type Tool, type McpStatus, type Request, type Answer } from "./types.js";
+import { type JSONSchema, 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. */
@@ -13,6 +13,10 @@ export interface LocalServer {
     enabled?: boolean;
     disabled?: boolean;
     timeout?: number;
+    /** §2 Gap 7. Per-server tool allowlist keyed on ORIGINAL tool name; same semantics as the
+     * 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>;
 }
 export interface RemoteServer {
     type?: "remote";
@@ -21,6 +25,8 @@ export interface RemoteServer {
     enabled?: boolean;
     disabled?: boolean;
     timeout?: number;
+    /** §2 Gap 7. Per-server tool allowlist (see LocalServer.tools). */
+    tools?: Record<string, boolean>;
 }
 export type ServerConfig = LocalServer | RemoteServer;
 export type McpConfig = Record<string, ServerConfig>;
@@ -36,7 +42,29 @@ export interface McpSource {
     status: Record<string, McpStatus>;
     close(): Promise<void>;
 }
-/** Connect to every enabled server, list + convert tools. Failures are isolated. */
+/** Connect to every enabled server, list + convert tools. Failures are isolated.
+ *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
+ *  whole load promptly on parent cancellation. */
 export declare function loadMcp(input: string | object, opts?: {
     waitFor?: (request: Request) => Promise<Answer>;
+    signal?: AbortSignal;
 }): Promise<McpSource>;
+/** §2 Gap 6. One listed tool definition (original, unprefixed name). */
+export interface ToolInfo {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+/** §2 Gap 6. Result of a list-only pass over an MCP config. */
+export interface McpInventory {
+    /** server → its full listed tool defs, UNFILTERED by ServerConfig.tools (authors the allowlist). */
+    tools: Record<string, ToolInfo[]>;
+    status: Record<string, McpStatus>;
+}
+/**
+ * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
+ * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
+ */
+export declare function listMcpTools(input: string | object, opts?: {
+    signal?: AbortSignal;
+}): Promise<McpInventory>;

package/dist/mcp.js

@@ -99,6 +99,42 @@ function joinTextContent(content) {
         .flatMap((item) => (isTextContent(item) ? [item.text] : []))
         .join("\n");
 }
+/**
+ * §2 Gap 7. Apply a per-server tool allowlist to the listed defs. Same semantics as the builtins
+ * and skills filters: nil/empty ⇒ all; ≥1 true ⇒ allowlist (only true names); only-false ⇒ drop-list
+ * over all-on; unknown names ignored + warned once. Keyed on ORIGINAL tool name.
+ */
+function applyToolsFilter(server, defs, filter) {
+    if (!filter)
+        return defs;
+    const keys = Object.keys(filter);
+    if (keys.length === 0)
+        return defs;
+    const hasTrue = keys.some((k) => filter[k] === true);
+    const present = new Set(defs.map((d) => d.name));
+    for (const k of keys) {
+        if (!present.has(k))
+            console.warn(`[toolnexus] server "${server}" tools filter name "${k}" matched no tool`);
+    }
+    return defs.filter((d) => (hasTrue ? filter[d.name] === true : filter[d.name] !== false));
+}
+/**
+ * §2 Gap 3. Race a promise against a per-server timeout and the caller's abort signal, so a hung
+ * connect/list is bounded (the SSE fallback included) and a parent cancellation aborts promptly.
+ */
+function raceTimeout(p, ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { cleanup(); reject(signal?.reason ?? new Error("aborted")); };
+        const t = setTimeout(() => { cleanup(); reject(new Error("mcp connect/list timeout")); }, ms);
+        const cleanup = () => { clearTimeout(t); signal?.removeEventListener("abort", onAbort); };
+        if (signal) {
+            if (signal.aborted)
+                return onAbort();
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        p.then((v) => { cleanup(); resolve(v); }, (e) => { cleanup(); reject(e); });
+    });
+}
 async function paginateTools(client, timeout) {
     const result = [];
     const cursors = new Set();
@@ -144,50 +180,66 @@ function convertTool(server, def, client, timeout) {
         },
     };
 }
-/** Connect to every enabled server, list + convert tools. Failures are isolated. */
+/** Create a fresh (not-yet-connected) client, with the elicitation bridge attached if a waitFor
+ *  exists. Separated from connect so the caller ALWAYS holds a closeable reference — even if the
+ *  connect is later abandoned by a timeout/abort, `client.close()` still terminates any spawned
+ *  stdio child (no orphaned processes on cancellation). */
+function newMcpClient(waitFor) {
+    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))));
+    }
+    return client;
+}
+/** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
+async function connectTransport(client, cfg) {
+    if (isRemote(cfg)) {
+        const url = new URL(cfg.url);
+        const expanded = expandEnvHeaders(cfg.headers);
+        const requestInit = expanded ? { headers: expanded } : undefined;
+        try {
+            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
+        }
+        catch {
+            await client.connect(new SSEClientTransport(url, { requestInit }));
+        }
+    }
+    else {
+        const local = cfg;
+        const [cmd, ...args] = local.command;
+        await client.connect(new StdioClientTransport({
+            command: cmd,
+            args,
+            cwd: local.cwd,
+            env: { ...process.env, ...(local.environment ?? local.env ?? {}) },
+            stderr: "pipe",
+        }));
+    }
+}
+/** 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, opts) {
     const config = parseMcpConfig(input);
     const tools = [];
     const status = {};
     const clients = [];
     const waitFor = opts?.waitFor;
+    const signal = opts?.signal;
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        // 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))));
-        }
+        // 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);
         try {
-            if (isRemote(cfg)) {
-                const url = new URL(cfg.url);
-                const expanded = expandEnvHeaders(cfg.headers);
-                const requestInit = expanded ? { headers: expanded } : undefined;
-                try {
-                    await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
-                }
-                catch {
-                    await client.connect(new SSEClientTransport(url, { requestInit }));
-                }
-            }
-            else {
-                const local = cfg;
-                const [cmd, ...args] = local.command;
-                await client.connect(new StdioClientTransport({
-                    command: cmd,
-                    args,
-                    cwd: local.cwd,
-                    env: { ...process.env, ...(local.environment ?? local.env ?? {}) },
-                    stderr: "pipe",
-                }));
-            }
-            const defs = await paginateTools(client, timeout);
-            for (const def of defs)
+            await raceTimeout(connectTransport(client, cfg), timeout, signal);
+            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
+            const kept = applyToolsFilter(name, defs, cfg.tools);
+            for (const def of kept)
                 tools.push(convertTool(name, def, client, timeout));
             clients.push(client);
             status[name] = "connected";
@@ -195,7 +247,10 @@ export async function loadMcp(input, opts) {
         catch (e) {
             status[name] = "failed";
             await client.close().catch(() => { });
-            // one bad server never breaks the toolkit
+            // 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;
             console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }));
@@ -207,3 +262,48 @@ export async function loadMcp(input, opts) {
         },
     };
 }
+/**
+ * §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, opts) {
+    const config = parseMcpConfig(input);
+    const toolsByServer = {};
+    const status = {};
+    const signal = opts?.signal;
+    await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
+        if (!isEnabled(cfg)) {
+            status[name] = "disabled";
+            return;
+        }
+        const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
+        // Client created up front so an aborted/timed-out connect is still closed (no orphaned child).
+        const client = newMcpClient();
+        try {
+            await raceTimeout(connectTransport(client, cfg), timeout, signal);
+            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
+            toolsByServer[name] = defs.map((d) => ({
+                name: d.name,
+                description: d.description ?? "",
+                inputSchema: {
+                    ...d.inputSchema,
+                    type: "object",
+                    properties: (d.inputSchema?.properties ?? {}),
+                },
+            }));
+            status[name] = "connected";
+        }
+        catch (e) {
+            status[name] = "failed";
+            if (signal?.aborted) {
+                await client.close().catch(() => { });
+                throw e;
+            }
+            console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            await client.close().catch(() => { });
+        }
+    }));
+    return { tools: toolsByServer, status };
+}

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. */

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;