toolnexus 0.9.4 → 0.9.5

package/dist/client.d.ts

@@ -44,6 +44,24 @@ export interface ClientOptions {
     /** §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;
+    /** §8 Resilience. Classify each LLM-call failure into "retry" or "fail". Omit ⇒ the default
+     * classifier (retryable status/network within budget ⇒ retry, else fail) — byte-identical to
+     * today. A "retry" is always bounded by `retries`; the classifier cannot loop unbounded.
+     * There is no "suspend" tier — suspension (§10) stays a user-action pause, not an error path. */
+    onError?: (info: ErrorInfo) => ErrorTier;
+}
+/** §8 Resilience. What to do with a failed LLM call. */
+export type ErrorTier = "retry" | "fail";
+/** §8 Resilience. Context passed to `onError` for each failed LLM attempt. */
+export interface ErrorInfo {
+    /** The thrown network/transport error, when the failure was not an HTTP response. */
+    error?: unknown;
+    /** The HTTP status, when the failure was a non-ok response. */
+    status?: number;
+    /** Zero-based attempt index (0 = first try). */
+    attempt: number;
+    /** Whether `status`/the error is in the default retryable set (429/5xx/network). */
+    retryable: boolean;
 }
 /**
  * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
@@ -263,7 +281,8 @@ export declare class Client {
     private system;
     /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
     private makeSignal;
-    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal. */
+    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+     * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;

package/dist/client.js

@@ -291,16 +291,24 @@ export class Client {
         }
         return ctrl.signal;
     }
-    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal. */
+    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+     * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
     async llmFetch(url, init, signal) {
         const retries = this.opts.retries ?? 2;
         const base = this.opts.retryBaseMs ?? 500;
+        // Default classifier = today's behavior, expressed as an onError. A "retry" is always
+        // capped by the budget below (attempt === retries stops regardless of the classifier).
+        const classify = this.opts.onError ?? ((info) => (info.retryable ? "retry" : "fail"));
         let lastErr;
         for (let attempt = 0; attempt <= retries; attempt++) {
             try {
                 const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
-                if (res.ok || !RETRYABLE.has(res.status) || attempt === retries)
+                if (res.ok)
                     return res;
+                const retryable = RETRYABLE.has(res.status);
+                const tier = classify({ status: res.status, attempt, retryable });
+                if (tier === "fail" || attempt === retries)
+                    return res; // caller surfaces the non-ok status
                 const ra = Number(res.headers.get("retry-after"));
                 await delay(ra ? ra * 1000 : base * 2 ** attempt + Math.random() * 100, signal);
             }
@@ -308,7 +316,8 @@ export class Client {
                 if (signal.aborted)
                     throw e; // abort/timeout: don't retry
                 lastErr = e;
-                if (attempt === retries)
+                const tier = classify({ error: e, attempt, retryable: true });
+                if (tier === "fail" || attempt === retries)
                     throw e;
                 await delay(base * 2 ** attempt + Math.random() * 100, signal);
             }

package/dist/toolkit.d.ts

@@ -18,6 +18,13 @@ export interface ToolkitOptions {
     skillProvider?: () => SkillDef[] | Promise<SkillDef[]>;
     /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
     skillsFilter?: Record<string, boolean>;
+    /** Drop tools by their FINAL exposed name across every source (MCP `server_tool`, builtins,
+     * native, a2a, extras), applied after aggregation — the simple "just turn these off" list.
+     * Empty/undefined ⇒ nothing disabled. Composes with builtins/skillsFilter/server allowlists. */
+    disableTools?: string[];
+    /** Drop skills by name from the `skill` catalog — sugar over a drop-list in `skillsFilter`
+     * (each name folded in as `false`, without overriding an explicit filter entry). */
+    disableSkills?: string[];
     /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
     skillSampleLimit?: number;
     extraTools?: Tool[];

package/dist/toolkit.js

@@ -14,7 +14,9 @@ export class Toolkit {
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
     a2aConfig, 
     /** MCP serve profile read from a top-level `mcpServer` config block. */
-    mcpServerConfig) {
+    mcpServerConfig, 
+    /** Final-name drop-list (§4A) applied across every source after aggregation. */
+    disableTools = []) {
         this.mcp = mcp;
         this.skill = skill;
         this.a2aConfig = a2aConfig;
@@ -24,8 +26,11 @@ export class Toolkit {
         // front, then apply the normal first-wins dedupe for MCP/skill/agents/extras.
         const extraNames = new Set(extraTools.map((t) => t.name));
         const activeBuiltins = builtins.filter((b) => !extraNames.has(b.name));
+        const disabled = new Set(disableTools);
         const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...activeBuiltins, ...agents, ...extraTools];
         for (const t of all) {
+            if (disabled.has(t.name))
+                continue; // §4A drop-list by final exposed name
             if (this.byName.has(t.name)) {
                 console.warn(`[toolnexus] duplicate tool name "${t.name}" — keeping first`);
                 continue;
@@ -51,10 +56,15 @@ export class Toolkit {
                 }
             }
             const dataDefs = [...(opts.skills ?? []), ...providerDefs];
+            // disableSkills is sugar over a skillsFilter drop-list: fold each name in as false
+            // WITHOUT overriding an explicit skillsFilter entry (explicit entries win).
+            const filter = opts.disableSkills && opts.disableSkills.length > 0
+                ? { ...Object.fromEntries(opts.disableSkills.map((n) => [n, false])), ...opts.skillsFilter }
+                : opts.skillsFilter;
             skill = loadSkills({
                 dirs: opts.skillsDir,
                 skills: dataDefs.length > 0 ? dataDefs : undefined,
-                filter: opts.skillsFilter,
+                filter,
                 sampleLimit: opts.skillSampleLimit,
             });
         }
@@ -93,7 +103,7 @@ export class Toolkit {
         if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "mcpServer" in opts.mcpConfig) {
             mcpServerConfig = opts.mcpConfig.mcpServer;
         }
-        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig);
+        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig, opts.disableTools ?? []);
     }
     tools() {
         return [...this.byName.values()];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.ts

@@ -47,6 +47,26 @@ export interface ClientOptions {
   /** §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
+  /** §8 Resilience. Classify each LLM-call failure into "retry" or "fail". Omit ⇒ the default
+   * classifier (retryable status/network within budget ⇒ retry, else fail) — byte-identical to
+   * today. A "retry" is always bounded by `retries`; the classifier cannot loop unbounded.
+   * There is no "suspend" tier — suspension (§10) stays a user-action pause, not an error path. */
+  onError?: (info: ErrorInfo) => ErrorTier
+}
+
+/** §8 Resilience. What to do with a failed LLM call. */
+export type ErrorTier = "retry" | "fail"
+
+/** §8 Resilience. Context passed to `onError` for each failed LLM attempt. */
+export interface ErrorInfo {
+  /** The thrown network/transport error, when the failure was not an HTTP response. */
+  error?: unknown
+  /** The HTTP status, when the failure was a non-ok response. */
+  status?: number
+  /** Zero-based attempt index (0 = first try). */
+  attempt: number
+  /** Whether `status`/the error is in the default retryable set (429/5xx/network). */
+  retryable: boolean
 }
 
 /**
@@ -439,21 +459,29 @@ export class Client {
     return ctrl.signal
   }
 
-  /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal. */
+  /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+   * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
   private async llmFetch(url: string, init: RequestInit, signal: AbortSignal): Promise<Response> {
     const retries = this.opts.retries ?? 2
     const base = this.opts.retryBaseMs ?? 500
+    // Default classifier = today's behavior, expressed as an onError. A "retry" is always
+    // capped by the budget below (attempt === retries stops regardless of the classifier).
+    const classify = this.opts.onError ?? ((info: ErrorInfo): ErrorTier => (info.retryable ? "retry" : "fail"))
     let lastErr: unknown
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
         const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal })
-        if (res.ok || !RETRYABLE.has(res.status) || attempt === retries) return res
+        if (res.ok) return res
+        const retryable = RETRYABLE.has(res.status)
+        const tier = classify({ status: res.status, attempt, retryable })
+        if (tier === "fail" || attempt === retries) return res // caller surfaces the non-ok status
         const ra = Number(res.headers.get("retry-after"))
         await delay(ra ? ra * 1000 : base * 2 ** attempt + Math.random() * 100, signal)
       } catch (e) {
         if (signal.aborted) throw e // abort/timeout: don't retry
         lastErr = e
-        if (attempt === retries) throw e
+        const tier = classify({ error: e, attempt, retryable: true })
+        if (tier === "fail" || attempt === retries) throw e
         await delay(base * 2 ** attempt + Math.random() * 100, signal)
       }
     }

package/src/toolkit.ts

@@ -21,6 +21,13 @@ export interface ToolkitOptions {
   skillProvider?: () => SkillDef[] | Promise<SkillDef[]>
   /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
   skillsFilter?: Record<string, boolean>
+  /** Drop tools by their FINAL exposed name across every source (MCP `server_tool`, builtins,
+   * native, a2a, extras), applied after aggregation — the simple "just turn these off" list.
+   * Empty/undefined ⇒ nothing disabled. Composes with builtins/skillsFilter/server allowlists. */
+  disableTools?: string[]
+  /** Drop skills by name from the `skill` catalog — sugar over a drop-list in `skillsFilter`
+   * (each name folded in as `false`, without overriding an explicit filter entry). */
+  disableSkills?: string[]
   /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
   skillSampleLimit?: number
   extraTools?: Tool[]
@@ -52,14 +59,18 @@ export class Toolkit {
     private readonly a2aConfig: A2AConfig | undefined,
     /** MCP serve profile read from a top-level `mcpServer` config block. */
     private readonly mcpServerConfig: MCPServeConfig | undefined,
+    /** Final-name drop-list (§4A) applied across every source after aggregation. */
+    disableTools: string[] = [],
   ) {
     // Builtins are the lowest-precedence source: a host extraTools entry with
     // the same name shadows a builtin (SPEC §4). Drop shadowed builtins up
     // front, then apply the normal first-wins dedupe for MCP/skill/agents/extras.
     const extraNames = new Set(extraTools.map((t) => t.name))
     const activeBuiltins = builtins.filter((b) => !extraNames.has(b.name))
+    const disabled = new Set(disableTools)
     const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...activeBuiltins, ...agents, ...extraTools]
     for (const t of all) {
+      if (disabled.has(t.name)) continue // §4A drop-list by final exposed name
       if (this.byName.has(t.name)) {
         console.warn(`[toolnexus] duplicate tool name "${t.name}" — keeping first`)
         continue
@@ -85,10 +96,16 @@ export class Toolkit {
         }
       }
       const dataDefs = [...(opts.skills ?? []), ...providerDefs]
+      // disableSkills is sugar over a skillsFilter drop-list: fold each name in as false
+      // WITHOUT overriding an explicit skillsFilter entry (explicit entries win).
+      const filter =
+        opts.disableSkills && opts.disableSkills.length > 0
+          ? { ...Object.fromEntries(opts.disableSkills.map((n) => [n, false])), ...opts.skillsFilter }
+          : opts.skillsFilter
       skill = loadSkills({
         dirs: opts.skillsDir,
         skills: dataDefs.length > 0 ? dataDefs : undefined,
-        filter: opts.skillsFilter,
+        filter,
         sampleLimit: opts.skillSampleLimit,
       })
     }
@@ -137,7 +154,7 @@ export class Toolkit {
       mcpServerConfig = (opts.mcpConfig as { mcpServer?: MCPServeConfig }).mcpServer
     }
 
-    return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig)
+    return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig, opts.disableTools ?? [])
   }
 
   tools(): Tool[] {