toolnexus 0.17.0 → 0.18.0

package/src/client.ts

@@ -6,6 +6,7 @@
 import type { Toolkit } from "./toolkit.js"
 import type { ToolResult, Request, Answer } from "./types.js"
 import { pendingOf } from "./types.js"
+import { isRetryableStatus, retryAfterMs } from "./retry.js"
 import type { ContentPart, PromptInput, UnsupportedPartMode } from "./content.js"
 import { toOpenAIWire, toAnthropicWire, checkPromptParts, type WireOptions } from "./wire.js"
 import type { TranslateRequest, TranslateResult, TranslatedToolCall } from "./translate.js"
@@ -30,10 +31,20 @@ export interface ClientOptions {
   systemPrompt?: string
   maxTurns?: number
   hooks?: Hooks
-  /** Retries on transient LLM errors (429/5xx/network). Default 2. */
+  /** Retries on transient LLM errors (`429`/`500`/`502`/`503`/`504`/`529` + network). Default 2.
+   * Widen the status set with `retryableStatuses`. */
   retries?: number
   /** Base backoff in ms (exponential + jitter). Default 500. */
   retryBaseMs?: number
+  /**
+   * Extra HTTP statuses to treat as retryable, ADDED to the default set
+   * (`429`/`500`/`502`/`503`/`504`/`529`). It can only widen: a host cannot remove `429` and
+   * lose `Retry-After` handling with it. This sets the DEFAULT classification; `onError` still
+   * runs per attempt and has the final say, so `onError` returning `"fail"` overrides a status
+   * listed here. Example: a Cloudflare-fronted origin that answers `520`–`527`.
+   */
+  retryableStatuses?: readonly number[]
+
   /** Whole-run deadline in ms; aborts the run (and its in-flight request) when exceeded. */
   timeoutMs?: number
   /** Conversation provider for `ask(prompt, { id })`. Default: in-memory (process lifetime).
@@ -84,7 +95,8 @@ export interface ErrorInfo {
   status?: number
   /** Zero-based attempt index (0 = first try). */
   attempt: number
-  /** Whether `status`/the error is in the default retryable set (429/5xx/network). */
+  /** Whether `status`/the error is in the default retryable set
+   * (429/500/502/503/504/529/network, plus anything `retryableStatuses` added). */
   retryable: boolean
 }
 
@@ -97,6 +109,20 @@ export type MetricEvent =
   | { event: "llm"; model: string; status: "ok" | "error"; ms: number; promptTokens: number; completionTokens: number }
   | { event: "tool"; tool: string; source: string; isError: boolean; ms: number; pending?: boolean }
   | { event: "run"; model: string; turns: number; toolCalls: number; totalTokens: number; ms: number; error?: string }
+  // §8B. The classifier emits into this SAME sink. Neither event is folded into the Prometheus
+  // registry, so `client.metrics()` text stays byte-identical to a build with no classifier.
+  | {
+      event: "classifier.evaluate"
+      model: string
+      status: "ok" | "error"
+      ms: number
+      promptTokens: number
+      completionTokens: number
+      error?: string
+    }
+  // `warning`, never `error`: a degenerate-criteria report is advisory, and a consumer that
+  // counts "has an error" as a failure must not count this.
+  | { event: "classifier.warning"; question: string; warning: string }
 
 /**
  * Where `ask()` conversations are remembered — two methods. Ship the in-memory
@@ -121,30 +147,6 @@ export class InMemoryConversationStore implements ConversationStore {
   }
 }
 
-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: string | null | undefined): number | null {
-  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: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     const t = setTimeout(resolve, ms)
@@ -665,7 +667,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). */
   private async llmFetch(url: string, init: RequestInit, signal: AbortSignal): Promise<Response> {
     const retries = this.opts.retries ?? 2
@@ -678,7 +681,7 @@ export class Client {
       try {
         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
         const ra = retryAfterMs(res.headers.get("retry-after"))

package/src/index.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/src/retry.ts

@@ -0,0 +1,57 @@
+/**
+ * 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: string | null | undefined): number | null {
+  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: number, extra?: readonly number[] | null): boolean {
+  return RETRYABLE.has(status) || (extra != null && extra.includes(status))
+}