toolnexus 0.17.0 → 0.18.0

package/dist/classifier.js

@@ -0,0 +1,630 @@
+import { retryAfterMs, isRetryableStatus } from "./retry.js";
+// ---------------------------------------------------------------- constants
+/** The System One endpoint base. */
+export const DEFAULT_CLASSIFIER_BASE_URL = "https://api.typesafe.ai/v1";
+/** The floating model alias. Pin it (e.g. `jev-1.13.0`) once thresholds are tuned. */
+export const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
+/** The NAME of the env var holding the credential — never the value. */
+export const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
+/** Bounds ONE request; a classifier has no loop to bound. */
+export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10_000;
+/** Client-side cap on a choice's named options (§8B). */
+export const MAX_CHOICE_OPTIONS = 255;
+/** Bounds of a score rubric (§8B). */
+export const MIN_SCORE_LEVELS = 2;
+export const MAX_SCORE_LEVELS = 10;
+/**
+ * The ABSOLUTE tolerance on `max|p - 1/n|`, compared INCLUSIVELY (§8B). Pinned across every
+ * port; `examples/judge/near-uniform.json` pins both sides at 0.0499 / 0.0501.
+ */
+export const NEAR_UNIFORM_TOLERANCE = 0.05;
+/** A noul question. Pass `criteria` only when you mean it — absent ≠ empty on the wire. */
+export function noul(instructions, criteria) {
+    return criteria === undefined ? { type: "noul", instructions } : { type: "noul", instructions, criteria };
+}
+/** A choice question. Every description must say what picking that option would MEAN. */
+export function choice(instructions, criteria) {
+    return { type: "choice", instructions, criteria: { ...criteria } };
+}
+/** A score question. The array order IS the level numbering and is never reordered. */
+export function score(instructions, criteria) {
+    return { type: "score", instructions, criteria: [...criteria] };
+}
+/**
+ * Build a choice from any (name, description) pairs — a Tool, a skill, an agent, an A2A card
+ * skill. The description must say what picking that option would MEAN; see the encoding
+ * obligation on `ChoiceQuestion`.
+ */
+export function choiceOver(instructions, items) {
+    return choice(instructions, items);
+}
+/** The wire form of one question — the object itself, minus an absent `criteria`. */
+function questionWire(q) {
+    switch (q.type) {
+        case "noul":
+            return q.criteria === undefined
+                ? { type: "noul", instructions: q.instructions }
+                : { type: "noul", instructions: q.instructions, criteria: { true: q.criteria.true, false: q.criteria.false } };
+        case "choice":
+            return { type: "choice", instructions: q.instructions, criteria: { ...q.criteria } };
+        case "score":
+            return { type: "score", instructions: q.instructions, criteria: [...q.criteria] };
+    }
+}
+/** Client-side limits, enforced BEFORE the request. The error names the key and the limit. */
+function validateQuestion(key, q) {
+    if (q.type === "choice") {
+        const n = Object.keys(q.criteria ?? {}).length;
+        if (n < 1 || n > MAX_CHOICE_OPTIONS) {
+            throw new Error(`classifier: question "${key}": a choice needs 1..${MAX_CHOICE_OPTIONS} options, got ${n}`);
+        }
+    }
+    else if (q.type === "score") {
+        const n = (q.criteria ?? []).length;
+        if (n < MIN_SCORE_LEVELS || n > MAX_SCORE_LEVELS) {
+            throw new Error(`classifier: question "${key}": a score needs ${MIN_SCORE_LEVELS}..${MAX_SCORE_LEVELS} ordered levels, got ${n}`);
+        }
+    }
+}
+// ---------------------------------------------------------------- the wire
+/**
+ * Canonical JSON: object keys sorted recursively in CODE-UNIT (ASCII) order, arrays NEVER
+ * reordered, compact separators, and `<>&'"` plus non-ASCII transmitted raw.
+ *
+ * Hand-rolled because `JSON.stringify` has no recursive key sort, and its `replacer` ARRAY form
+ * applies one key list at EVERY depth — it cannot express "sort whatever keys are here". The
+ * per-value escaping and number formatting ARE delegated to `JSON.stringify`, which emits the
+ * shortest round-tripping decimal (so 1.21 is "1.21" and integer 0 is "0", not "0.0") and does
+ * not escape `<`, `>`, `&` or non-ASCII.
+ *
+ * `undefined` is ABSENT, never `null`: an object key whose value is undefined is dropped.
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return "[" + value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",") + "]";
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        // `sort()` with no comparator compares UTF-16 code units — ASCII order, and NOT the
+        // culture-sensitive order `localeCompare` would give ("10_alpha" < "Alpha" < "beta" < "café").
+        const keys = Object.keys(obj)
+            .filter((k) => obj[k] !== undefined)
+            .sort();
+        return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJson(obj[k])).join(",") + "}";
+    }
+    const s = JSON.stringify(value);
+    return s === undefined ? "null" : s;
+}
+/**
+ * The bytes the byte-identity claim covers: `model` + `questions`.
+ *
+ * `state` is deliberately NOT here. It is transmitted verbatim as the host supplied it and is
+ * OUTSIDE the claim, because numbers do not canonicalise across languages (`-0.0` renders four
+ * ways across our own seven runtimes). Do not re-widen this: a caller who needs their state
+ * pinned canonicalises it themselves before handing it over.
+ */
+export function canonicalRequest(model, questions) {
+    const qs = {};
+    for (const [key, q] of Object.entries(questions)) {
+        if (!q)
+            throw new Error(`classifier: question "${key}" is missing`);
+        qs[key] = questionWire(q);
+    }
+    return canonicalJson({ model, questions: qs });
+}
+/** The legend in LEVEL order, which the map itself loses ("2" sorts before "10" as a level). */
+export function levels(answer) {
+    return Object.keys(answer.legend)
+        .sort((a, b) => (a.length !== b.length ? a.length - b.length : a < b ? -1 : a > b ? 1 : 0))
+        .map((k) => answer.legend[k]);
+}
+/**
+ * One answer per question, keyed by the CALLER's keys. The keys are addressing, not content:
+ * they are never transmitted, so a key may be a tool, skill or agent name verbatim.
+ */
+export class Decision {
+    model;
+    answers;
+    usage;
+    calibrated;
+    constructor(
+    /** What actually answered, which may be more specific than the model that was asked for. */
+    model, answers, usage, 
+    /**
+     * Whether the probabilities are calibrated. `systemone` reports true; `llm` reports false
+     * unless it derived them from provider token probabilities. A THRESHOLD TUNED AGAINST ONE
+     * BACKEND DOES NOT TRANSFER TO ANOTHER.
+     */
+    calibrated) {
+        this.model = model;
+        this.answers = answers;
+        this.usage = usage;
+        this.calibrated = calibrated;
+    }
+    /** Typed read. Throws (never returns undefined) on a wrong-type or absent key. */
+    noul(key) {
+        return this.typed(key, "noul");
+    }
+    choice(key) {
+        return this.typed(key, "choice");
+    }
+    score(key) {
+        return this.typed(key, "score");
+    }
+    typed(key, want) {
+        const a = this.answers[key];
+        if (a === undefined)
+            throw new Error(`classifier: no answer "${key}" in this decision`);
+        if (a.type !== want)
+            throw new Error(`classifier: answer "${key}" is a ${a.type} answer, not ${want}`);
+        return a;
+    }
+}
+/**
+ * Whether a choice answer's probability map is indistinguishable from flat (§8B):
+ *
+ *     nearUniform  ⇔  max over i of |p_i - 1/n|  <=  0.05
+ *
+ * `n` is the number of ENTRIES IN THE MAP and the values are taken AS RETURNED — not
+ * renormalised, not sorted, not rounded; an offered option absent from the map counts as 0 by
+ * not being an entry. The tolerance is ABSOLUTE (a relative band collapses below the wire's
+ * two-decimal rounding on a 255-option roster) and the comparison is INCLUSIVE. `n === 1` is
+ * trivially uniform. An empty map has no distribution at all and is reported false.
+ */
+export function nearUniform(probabilities) {
+    const values = Object.values(probabilities ?? {});
+    if (values.length === 0)
+        return false;
+    if (values.length === 1)
+        return true;
+    const target = 1 / values.length;
+    return values.every((p) => Math.abs(p - target) <= NEAR_UNIFORM_TOLERANCE);
+}
+/**
+ * Decode a backend response into a Decision. The discriminated decode is the single place
+ * `nearUniform` is derived. A malformed answer is an error, never a repaired one (ADR 0020).
+ */
+export function decodeDecision(raw, fallbackModel) {
+    if (raw === null || typeof raw !== "object")
+        throw new Error("classifier: response is not an object");
+    const body = raw;
+    const answers = {};
+    for (const [key, value] of Object.entries(body.answers ?? {})) {
+        if (value === null || typeof value !== "object")
+            throw new Error(`classifier: answer "${key}" is not an object`);
+        const a = value;
+        switch (a.type) {
+            case "noul":
+                answers[key] = { type: "noul", noul: num(a.noul) };
+                break;
+            case "choice":
+                answers[key] = {
+                    type: "choice",
+                    choice: String(a.choice ?? ""),
+                    probabilities: numbers(a.probabilities),
+                    confidence: num(a.confidence),
+                    nearUniform: nearUniform(numbers(a.probabilities)),
+                };
+                break;
+            case "score":
+                answers[key] = {
+                    type: "score",
+                    score: num(a.score),
+                    legend: strings(a.legend),
+                    probabilities: numbers(a.probabilities),
+                    confidence: num(a.confidence),
+                };
+                break;
+            default:
+                throw new Error(`classifier: answer "${key}": unknown type ${JSON.stringify(a.type)}`);
+        }
+    }
+    const usage = {
+        inputTokens: num(body.usage?.input_tokens),
+        outputTokens: num(body.usage?.output_tokens),
+    };
+    // Absent stays absent: a cost of 0 is a real cost and undefined is "not reported".
+    if (body.usage?.cost !== undefined)
+        usage.cost = num(body.usage.cost);
+    // Absent ⇒ true: the systemone wire reports calibration by being itself. A backend that is
+    // not calibrated says so explicitly.
+    return new Decision(String(body.model ?? fallbackModel), answers, usage, body.calibrated !== false);
+}
+function num(v) {
+    return typeof v === "number" ? v : 0;
+}
+/** A zero probability stays an ENTRY: the map is copied key-for-key, never filtered. */
+function numbers(v) {
+    const out = {};
+    for (const [k, p] of Object.entries((v ?? {})))
+        out[k] = num(p);
+    return out;
+}
+function strings(v) {
+    const out = {};
+    for (const [k, s] of Object.entries((v ?? {})))
+        out[k] = String(s);
+    return out;
+}
+// ---------------------------------------------------------------- classifier
+/** The whole seam: one verb. */
+export class Classifier {
+    opts;
+    style;
+    baseUrl;
+    model;
+    apiKeyEnv;
+    timeoutMs;
+    corpus = new Map();
+    /** The once-per-question-key set for the degenerate warning, so a per-turn judge does not
+     * flood the sink. */
+    warned = new Set();
+    constructor(opts) {
+        this.opts = opts;
+        this.style = opts.style ?? "systemone";
+        this.baseUrl = opts.baseUrl ?? DEFAULT_CLASSIFIER_BASE_URL;
+        this.model = opts.model ?? DEFAULT_CLASSIFIER_MODEL;
+        this.apiKeyEnv = opts.apiKeyEnv ?? DEFAULT_CLASSIFIER_API_KEY_ENV;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS;
+        switch (this.style) {
+            case "systemone":
+                break;
+            case "llm":
+                if (!opts.client)
+                    throw new Error('classifier: style "llm" requires `client`');
+                break;
+            case "custom":
+                if (!opts.evaluate)
+                    throw new Error('classifier: style "custom" requires `evaluate`');
+                break;
+            case "static":
+                for (const [i, rec] of (opts.decisions ?? []).entries()) {
+                    try {
+                        this.corpus.set(this.staticKey(rec.state, rec.questions), rec.response);
+                    }
+                    catch (e) {
+                        throw new Error(`classifier: recorded decision ${i}: ${e.message}`);
+                    }
+                }
+                break;
+            default: {
+                const unknown = this.style;
+                throw new Error(`classifier: unknown style ${JSON.stringify(unknown)}`);
+            }
+        }
+    }
+    /**
+     * The whole contract: a state plus typed questions in, a Decision out. Questions are
+     * INDEPENDENT — one answer is never context for another.
+     */
+    async evaluate(state, questions, signal) {
+        const start = Date.now();
+        const keys = Object.keys(questions ?? {}).sort();
+        if (keys.length === 0) {
+            const err = new Error("classifier: no questions to evaluate");
+            this.emitError(start, err);
+            throw err;
+        }
+        try {
+            // Limits are enforced CLIENT-SIDE, before the request: the caller finds out faster and
+            // more legibly than from the backend's own 400. Keys are walked in sorted order so the
+            // same malformed set always names the same key first.
+            for (const key of keys) {
+                const q = questions[key];
+                if (!q)
+                    throw new Error(`classifier: question "${key}" is missing`);
+                validateQuestion(key, q);
+            }
+        }
+        catch (e) {
+            this.emitError(start, e);
+            throw e;
+        }
+        // Detection, never repair (ADR 0020/0021): the request goes out BYTE-UNCHANGED and the
+        // warning is the entire observable effect.
+        this.reportDegenerate(keys, questions);
+        let decision;
+        try {
+            switch (this.style) {
+                case "custom":
+                    decision = await this.opts.evaluate(state, questions, signal);
+                    break;
+                case "static":
+                    decision = this.evaluateStatic(state, questions);
+                    break;
+                case "llm":
+                    decision = await this.evaluateLLM(state, questions, signal);
+                    break;
+                default:
+                    decision = await this.evaluateSystemOne(state, questions, signal);
+            }
+        }
+        catch (e) {
+            this.emitError(start, e);
+            throw e;
+        }
+        this.emit({
+            event: "classifier.evaluate",
+            model: decision.model,
+            status: "ok",
+            ms: Date.now() - start,
+            promptTokens: decision.usage.inputTokens,
+            completionTokens: decision.usage.outputTokens,
+        });
+        return decision;
+    }
+    // ---------------------------------------------------------------- degenerate
+    /**
+     * Emits ONE warning per degenerate question key per classifier, naming the key, and changes
+     * nothing about the request. Repairing would invent option descriptions the caller did not
+     * write, and the library has no way to know what the options mean.
+     */
+    reportDegenerate(keys, questions) {
+        for (const key of keys) {
+            const q = questions[key];
+            if (q.type !== "choice")
+                continue;
+            const reason = degenerateCriteria(q.criteria);
+            if (!reason || this.warned.has(key))
+                continue;
+            this.warned.add(key);
+            this.emit({
+                event: "classifier.warning",
+                question: key,
+                warning: `classifier: question "${key}" has degenerate criteria (${reason}) — every option reads ` +
+                    "the same to the model and the answer ranks at chance; describe what picking each " +
+                    "option would MEAN (SPEC.md §8B)",
+            });
+        }
+    }
+    // ---------------------------------------------------------------- backends
+    /**
+     * Assembles the request: the canonical model + questions, plus state VERBATIM as the host
+     * supplied it, then the §8 Gap 1 pipeline in §8 order (base → requestParams merge →
+     * bodyTransform → marshal).
+     */
+    body(state, questions) {
+        const qs = {};
+        for (const [key, q] of Object.entries(questions))
+            qs[key] = questionWire(q);
+        let body = { model: this.model, questions: qs, state };
+        // A requestParams key WINS on collision.
+        if (this.opts.requestParams)
+            body = { ...body, ...this.opts.requestParams };
+        if (this.opts.bodyTransform)
+            body = this.opts.bodyTransform(body) || body;
+        return canonicalJson(body);
+    }
+    /** Identifies a recorded decision by the canonical request AND the state. */
+    staticKey(state, questions) {
+        return canonicalRequest(this.model, questions) + "\u0000" + canonicalJson(state);
+    }
+    evaluateStatic(state, questions) {
+        const raw = this.corpus.get(this.staticKey(state, questions));
+        if (raw === undefined)
+            throw new Error("classifier: static: no recorded decision for this request+state");
+        return decodeDecision(raw, this.model);
+    }
+    async evaluateSystemOne(state, questions, signal) {
+        const text = await this.post(this.body(state, questions), signal);
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (e) {
+            throw new Error(`classifier: response was not JSON: ${e.message}`);
+        }
+        return decodeDecision(parsed, this.model);
+    }
+    /**
+     * The one POST, with the §8 retry budget, reusing the client's `ErrorInfo`/`ErrorTier`
+     * classifier and the `Retry-After` delay-seconds rule verbatim.
+     *
+     * NO CREDENTIAL VALUE AND NO EXPANDED HEADER VALUE APPEARS ON ANY PATH OUT OF HERE: an
+     * authentication failure names the status and the endpoint, nothing else, and a 401/403 body
+     * is never echoed back (a gateway happily reflects a bad Authorization header into its own
+     * 401 text).
+     */
+    async post(payload, signal) {
+        const endpoint = this.baseUrl.replace(/\/+$/, "") + "/systemone";
+        const retries = this.opts.retries ?? 2;
+        const base = this.opts.retryBaseMs ?? 500;
+        const classify = this.opts.onError ?? ((info) => (info.retryable ? "retry" : "fail"));
+        const doFetch = this.opts.fetch ?? fetch;
+        let lastErr;
+        for (let attempt = 0;; attempt++) {
+            const timer = new AbortController();
+            const t = setTimeout(() => timer.abort(new Error(`classifier: request timeout after ${this.timeoutMs}ms`)), this.timeoutMs);
+            t.unref?.();
+            const onOuter = () => timer.abort(signal.reason);
+            if (signal) {
+                if (signal.aborted) {
+                    clearTimeout(t);
+                    throw signal.reason ?? new Error("aborted");
+                }
+                signal.addEventListener("abort", onOuter, { once: true });
+            }
+            let res;
+            let thrown;
+            try {
+                res = await doFetch(endpoint, {
+                    method: "POST",
+                    headers: this.requestHeaders(),
+                    body: payload,
+                    signal: timer.signal,
+                });
+            }
+            catch (e) {
+                thrown = e;
+            }
+            finally {
+                clearTimeout(t);
+                signal?.removeEventListener("abort", onOuter);
+            }
+            if (res && res.ok)
+                return await res.text();
+            if (signal?.aborted)
+                throw signal.reason ?? new Error("aborted"); // caller cancellation is never retried
+            let retryAfter = null;
+            if (res) {
+                const text = await res.text().catch(() => "");
+                retryAfter = res.headers.get("retry-after");
+                lastErr = new Error(`classifier: POST ${endpoint}: HTTP ${res.status}${cause(res.status, text)}`);
+            }
+            else {
+                lastErr = new Error(`classifier: POST ${endpoint}: ${errText(thrown)}`);
+            }
+            const retryable = res ? res.status === 408 || isRetryableStatus(res.status, this.opts.retryableStatuses) : true;
+            if (attempt >= retries)
+                throw lastErr;
+            const tier = classify(res ? { status: res.status, attempt, retryable } : { error: thrown, attempt, retryable });
+            if (tier !== "retry")
+                throw lastErr;
+            // `??`, not `||`: Retry-After: 0 means "retry now", not "no opinion".
+            await sleep(retryAfterMs(retryAfter) ?? base * 2 ** attempt);
+        }
+    }
+    /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
+    requestHeaders() {
+        const headers = { "Content-Type": "application/json" };
+        const key = process.env[this.apiKeyEnv];
+        if (key)
+            headers["Authorization"] = `Bearer ${key}`;
+        for (const [k, v] of Object.entries(this.opts.headers ?? {}))
+            headers[k] = expandEnv(v);
+        return headers;
+    }
+    /**
+     * The three question types rendered as ONE structured-output call on any §8 Client — the
+     * vendor-neutral fallback, so a host with no System One credential runs the same questions on
+     * a cheap chat model. `calibrated` is FALSE: the numbers are the model's self-report, not
+     * token probabilities.
+     */
+    async evaluateLLM(state, questions, signal) {
+        const qs = {};
+        for (const [key, q] of Object.entries(questions))
+            qs[key] = questionWire(q);
+        const prompt = "Answer every question about the state below. Questions are INDEPENDENT: one answer is " +
+            "never context for another.\n\n" +
+            `STATE:\n${canonicalJson(state)}\n\nQUESTIONS:\n${canonicalJson(qs)}\n\n` +
+            "Reply with JSON only, no prose and no code fence, shaped exactly:\n" +
+            '{"answers":{"<key>":{"type":"noul","noul":0.0}}}\n' +
+            'A "noul" answer is {"type":"noul","noul":<0..1>}. A "choice" answer is ' +
+            '{"type":"choice","choice":"<one offered option id>","probabilities":{"<every offered option id>":<0..1>},"confidence":<0..1>}. ' +
+            'A "score" answer is {"type":"score","score":<a number within the rubric bounds, fractional allowed>,' +
+            '"legend":{"0":"<level 0>",…},"probabilities":{"0":<0..1>,…},"confidence":<0..1>}.';
+        const run = await this.opts.client.run(prompt, { toolkit: EMPTY_TOOLKIT, signal });
+        const payload = firstJsonObject(run.text);
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch (e) {
+            // Never repaired: an unparseable answer is no answer (ADR 0020).
+            throw new Error(`classifier: llm: ${e.message}`);
+        }
+        const d = decodeDecision(parsed, this.model);
+        return new Decision(d.model || this.model, d.answers, { inputTokens: run.usage.promptTokens, outputTokens: run.usage.completionTokens }, 
+        // The model reports no calibration and none is derived here (ADR 0020).
+        false);
+    }
+    // ---------------------------------------------------------------- metrics
+    emit(ev) {
+        this.opts.onMetric?.(ev);
+    }
+    emitError(start, e) {
+        this.emit({
+            event: "classifier.evaluate",
+            model: this.model,
+            status: "error",
+            ms: Date.now() - start,
+            promptTokens: 0,
+            completionTokens: 0,
+            error: errText(e),
+        });
+    }
+}
+/** Builds a Classifier, applying the §8B defaults and rejecting a style whose required option
+ * is missing before any call is made. */
+export function createClassifier(opts = {}) {
+    return new Classifier(opts);
+}
+// ---------------------------------------------------------------- helpers
+/**
+ * The §8B predicate. Degenerate ⇔ ANY of:
+ *   1. every value is empty (empty string or absent), or
+ *   2. every value equals its own key, or
+ *   3. every value is identical to every other value (n >= 2).
+ *
+ * A single-option choice (n === 1) is NEVER reported: there is nothing to differentiate. Returns
+ * the reason, or "" when the criteria are fine.
+ */
+export function degenerateCriteria(criteria) {
+    const entries = Object.entries(criteria ?? {});
+    if (entries.length < 2)
+        return "";
+    if (entries.every(([, v]) => (v ?? "") === ""))
+        return "every description is empty";
+    if (entries.every(([k, v]) => v === k))
+        return "every description is just its own option id";
+    const first = entries[0][1];
+    if (entries.every(([, v]) => v === first))
+        return "every description is identical";
+    return "";
+}
+/**
+ * Surfaces a backend's reported cause intact — EXCEPT on an authentication status: a 401/403
+ * body routinely reflects the credential or the header that was sent, so it never reaches a log,
+ * a metric, an error or a return value.
+ */
+function cause(status, body) {
+    if (status === 401 || status === 403)
+        return "";
+    const s = body.trim();
+    if (!s)
+        return "";
+    return ": " + (s.length > 200 ? s.slice(0, 200) + "…" : s);
+}
+/** `${ENV_VAR}` expands at call time; an unset var expands to the empty string, as §2. */
+function expandEnv(value) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => process.env[name] ?? "");
+}
+/** The outermost JSON object of a model reply, which may arrive wrapped in a fence or prose. */
+function firstJsonObject(s) {
+    const start = s.indexOf("{");
+    const end = s.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        throw new Error("classifier: llm: no JSON object in the reply");
+    return s.slice(start, end + 1);
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function sleep(ms) {
+    // NOT unref'd, unlike the timeout watchdog above. This timer is the retry
+    // backoff we are about to await, so it is real pending work: unref'ing it
+    // tells Node the process need not stay alive for it, and the loop can resolve
+    // before the retry ever happens. The §8 client's `delay` has never unref'd for
+    // the same reason. Caught on Node 22, where it cancelled every test after the
+    // first one to exercise a classifier retry ("Promise resolution is still
+    // pending but the event loop has already resolved"); Node 24 happened to hide it.
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * The `llm` style declares no tools — a classifier has no loop and executes nothing. The §8
+ * `run` takes a Toolkit, so this is the empty one; the cast is the price of not exposing a
+ * public "no tools" Toolkit constructor just for this path.
+ */
+const EMPTY_TOOLKIT = {
+    skillsPrompt: () => "",
+    toOpenAI: () => [],
+    toAnthropic: () => [],
+    toGemini: () => [],
+    get: () => undefined,
+    list: () => [],
+    execute: async () => {
+        throw new Error("classifier: the llm style declares no tools");
+    },
+    close: async () => { },
+};

package/dist/client.d.ts

@@ -17,10 +17,19 @@ 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).
@@ -69,7 +78,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;
 }
 /**
@@ -99,6 +109,18 @@ export type MetricEvent = {
     totalTokens: number;
     ms: number;
     error?: string;
+} | {
+    event: "classifier.evaluate";
+    model: string;
+    status: "ok" | "error";
+    ms: number;
+    promptTokens: number;
+    completionTokens: number;
+    error?: string;
+} | {
+    event: "classifier.warning";
+    question: string;
+    warning: string;
 };
 /**
  * Where `ask()` conversations are remembered — two methods. Ship the in-memory
@@ -319,7 +341,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 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 llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */