toolnexus 0.17.0 → 0.18.0

package/dist/client.js

@@ -1,4 +1,5 @@
 import { pendingOf } from "./types.js";
+import { isRetryableStatus, retryAfterMs } from "./retry.js";
 import { toOpenAIWire, toAnthropicWire, checkPromptParts } from "./wire.js";
 import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
@@ -12,29 +13,6 @@ export class InMemoryConversationStore {
         this.map.set(id, [...messages]);
     }
 }
-const RETRYABLE = new Set([429, 500, 502, 503, 504]);
-/** ~68 years; the widest whole-second count all seven ports represent exactly. */
-const RETRY_AFTER_MAX_SECONDS = 2147483647;
-/**
- * Honour `Retry-After` only in its delay-seconds form: a run of ASCII digits
- * (RFC 9110 §10.2.3) in 0…2147483647, returned in milliseconds.
- *
- * `Number()` is far too permissive for this — it accepts `"0.5"`, `"-5"`, `"1e3"`
- * and `" "` (as 0), which is how this port came to wait for fractional seconds
- * that five of the other six rejected outright. Fractional, signed, HTTP-date and
- * out-of-range values are not delays we can honour, so the caller falls back to
- * backoff rather than guessing. `0` is a real answer, so it returns `0`, not
- * `null`, and callers must use `??` rather than `||`.
- */
-function retryAfterMs(raw) {
-    if (raw == null)
-        return null;
-    const s = raw.trim();
-    if (!/^[0-9]+$/.test(s))
-        return null;
-    const secs = Number(s);
-    return secs <= RETRY_AFTER_MAX_SECONDS ? secs * 1000 : null;
-}
 function delay(ms, signal) {
     return new Promise((resolve, reject) => {
         const t = setTimeout(resolve, ms);
@@ -468,7 +446,8 @@ 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 the default retryable set (429/500/502/503/504/529)
+     * plus network errors and anything `retryableStatuses` added, 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;
@@ -482,7 +461,7 @@ export class Client {
                 const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
                 if (res.ok)
                     return res;
-                const retryable = RETRYABLE.has(res.status);
+                const retryable = isRetryableStatus(res.status, this.opts.retryableStatuses);
                 const tier = classify({ status: res.status, attempt, retryable });
                 if (tier === "fail" || attempt === retries)
                     return res; // caller surfaces the non-ok status

package/dist/index.d.ts

@@ -13,4 +13,5 @@ export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * from "./classifier.js";
 export * as agents from "./agents/index.js";

package/dist/index.js

@@ -13,4 +13,5 @@ export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * from "./classifier.js";
 export * as agents from "./agents/index.js";

package/dist/retry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The ONE §8 retry policy — the retryable-status set and the `Retry-After` rule.
+ *
+ * INTERNAL to the package. This module is deliberately NOT re-exported from
+ * `index.ts`: `client.ts` and `classifier.ts` (§8B) both need the policy, and a
+ * second copy is exactly the drift this file exists to prevent — but sharing it
+ * is an implementation detail, not npm API. Nothing here is in the parity-checked
+ * option surface, and nothing here may be added to `index.ts`.
+ */
+/**
+ * Honour `Retry-After` only in its delay-seconds form: a run of ASCII digits
+ * (RFC 9110 §10.2.3) in 0…2147483647, returned in milliseconds.
+ *
+ * `Number()` is far too permissive for this — it accepts `"0.5"`, `"-5"`, `"1e3"`
+ * and `" "` (as 0), which is how this port came to wait for fractional seconds
+ * that five of the other six rejected outright. Fractional, signed, HTTP-date and
+ * out-of-range values are not delays we can honour, so the caller falls back to
+ * backoff rather than guessing. `0` is a real answer, so it returns `0`, not
+ * `null`, and callers must use `??` rather than `||`.
+ */
+export declare function retryAfterMs(raw: string | null | undefined): number | null;
+/**
+ * Whether a status is retryable by default, optionally widened by a host's `retryableStatuses`.
+ *
+ * `extra` is ADDITIVE: it can only make more statuses retryable, never fewer, so a host cannot
+ * accidentally drop `429` and lose `Retry-After` handling with it. It decides the DEFAULT
+ * classification only — `onError` still runs afterwards and has the final say on every attempt,
+ * so `onError` returning `"fail"` overrides a status the host itself listed here.
+ */
+export declare function isRetryableStatus(status: number, extra?: readonly number[] | null): boolean;

package/dist/retry.js

@@ -0,0 +1,55 @@
+/**
+ * The ONE §8 retry policy — the retryable-status set and the `Retry-After` rule.
+ *
+ * INTERNAL to the package. This module is deliberately NOT re-exported from
+ * `index.ts`: `client.ts` and `classifier.ts` (§8B) both need the policy, and a
+ * second copy is exactly the drift this file exists to prevent — but sharing it
+ * is an implementation detail, not npm API. Nothing here is in the parity-checked
+ * option surface, and nothing here may be added to `index.ts`.
+ */
+/** ~68 years; the widest whole-second count all seven ports represent exactly. */
+const RETRY_AFTER_MAX_SECONDS = 2147483647;
+/**
+ * Honour `Retry-After` only in its delay-seconds form: a run of ASCII digits
+ * (RFC 9110 §10.2.3) in 0…2147483647, returned in milliseconds.
+ *
+ * `Number()` is far too permissive for this — it accepts `"0.5"`, `"-5"`, `"1e3"`
+ * and `" "` (as 0), which is how this port came to wait for fractional seconds
+ * that five of the other six rejected outright. Fractional, signed, HTTP-date and
+ * out-of-range values are not delays we can honour, so the caller falls back to
+ * backoff rather than guessing. `0` is a real answer, so it returns `0`, not
+ * `null`, and callers must use `??` rather than `||`.
+ */
+export function retryAfterMs(raw) {
+    if (raw == null)
+        return null;
+    const s = raw.trim();
+    if (!/^[0-9]+$/.test(s))
+        return null;
+    const secs = Number(s);
+    return secs <= RETRY_AFTER_MAX_SECONDS ? secs * 1000 : null;
+}
+/**
+ * The default retryable set: `429` plus the 5xx worth another try — and `529 Overloaded`,
+ * which TypeSafe documents as "retry with backoff" and which an enumeration made terminal.
+ *
+ * It is an ENUMERATION on purpose. "Any 5xx" would sweep in permanently-broken statuses
+ * (`501 Not Implemented`, `505 HTTP Version Not Supported`) and change the retry behaviour of
+ * every existing host without asking. A backend with its own transient status — a Cloudflare
+ * origin answering `520`–`527`, say — opts in declaratively through `retryableStatuses`, which
+ * ADDS to this set and cannot remove from it.
+ *
+ * Shared with §8B's classifier, which adds `408` to it rather than inventing a second policy.
+ */
+const RETRYABLE = new Set([429, 500, 502, 503, 504, 529]);
+/**
+ * Whether a status is retryable by default, optionally widened by a host's `retryableStatuses`.
+ *
+ * `extra` is ADDITIVE: it can only make more statuses retryable, never fewer, so a host cannot
+ * accidentally drop `429` and lose `Retry-After` handling with it. It decides the DEFAULT
+ * classification only — `onError` still runs afterwards and has the final say on every attempt,
+ * so `onError` returning `"fail"` overrides a status the host itself listed here.
+ */
+export function isRetryableStatus(status, extra) {
+    return RETRYABLE.has(status) || (extra != null && extra.includes(status));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,8 +17,10 @@
   ],
   "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/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts",
-    "example": "node --experimental-strip-types examples/basic.ts"
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.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",
+    "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"
   },
   "keywords": [
     "mcp",

package/src/agents/loop.ts

@@ -72,6 +72,18 @@ export function guardedHooks(guardrails: Guardrail[] | undefined, hooks: Hooks |
     beforeTool: async (ev) => {
       for (const g of guardrails) {
         const verdict = g(ev)
+        // A guardrail is SYNCHRONOUS by contract. An async one returns a Promise,
+        // which is truthy and !== "allow", so it would silently DENY every call
+        // with `denied: [object Promise]`. Fail loudly instead, and say where
+        // asynchronous work belongs.
+        if (verdict != null && typeof verdict !== "string") {
+          const what = typeof (verdict as { then?: unknown }).then === "function" ? "a Promise" : typeof verdict
+          throw new TypeError(
+            `guardrail returned ${what}: a guardrail must return a string synchronously ` +
+              `("" or "allow" to permit, any other string to deny). ` +
+              `Do asynchronous work in hooks.beforeTool, which is awaited.`,
+          )
+        }
         if (verdict && verdict !== "allow") {
           return { result: { output: `denied: ${verdict}`, isError: true } }
         }