toolnexus 0.9.4 → 0.10.0

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
 }
 
 /**
@@ -135,10 +155,14 @@ export interface RunResult {
   usage: Usage
   /** The model used. */
   model: string
-  /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
-  status: "done" | "pending"
+  /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10);
+   * "incomplete" iff a limit stopped the run loudly (§7D) — a maxTurns stop with no final
+   * text is never a silent "done". */
+  status: "done" | "pending" | "incomplete"
   /** The unresolved suspension — present iff status === "pending" (§10). */
   pending?: Request
+  /** The limit that stopped the run (e.g. "maxTurns") — present iff status === "incomplete". */
+  limit?: string
 }
 
 /** Events yielded by client.stream(). */
@@ -359,10 +383,11 @@ export class Client {
     this.opts.onMetric?.(ev)
   }
 
-  /** Emit the terminal `run` metric event and build the RunResult. */
-  private endRun(runStart: number, text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
+  /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
+   * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
+  private endRun(runStart: number, text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage, exhausted = false): RunResult {
     this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart })
-    return this.result(text, messages, toolCalls, turns, usage)
+    return this.result(text, messages, toolCalls, turns, usage, exhausted)
   }
 
   /** Emit a `run` error metric event (once, on a thrown run). */
@@ -439,21 +464,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)
       }
     }
@@ -568,15 +601,18 @@ export class Client {
           if (s.halted) return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage)
         }
       }
-      return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage)
+      return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true)
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e
     }
   }
 
-  private result(text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
-    return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" }
+  private result(text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage, exhausted = false): RunResult {
+    const incomplete = exhausted && text === ""
+    const r: RunResult = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: incomplete ? "incomplete" : "done" }
+    if (incomplete) r.limit = "maxTurns"
+    return r
   }
 
   /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
@@ -674,7 +710,7 @@ export class Client {
         messages.push({ role: "user", content })
         if (halted) return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage)
       }
-      return this.endRun(runStart, "", messages, toolCalls, turns, usage)
+      return this.endRun(runStart, "", messages, toolCalls, turns, usage, true)
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e
@@ -770,7 +806,7 @@ export class Client {
           yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError }
         }
       }
-      yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage) }
+      yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true) }
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e
@@ -863,7 +899,7 @@ export class Client {
         }
         messages.push({ role: "user", content: results })
       }
-      yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage) }
+      yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage, true) }
     } catch (e) {
       this.emitRunError(runStart, toolCalls, turns, usage, e)
       throw e

package/src/index.ts

@@ -10,3 +10,4 @@ export * from "./mcpserve.js"
 export * from "./adapters.js"
 export * from "./toolkit.js"
 export * from "./client.js"
+export * as agents from "./agents/index.js"

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[] {