toolnexus 0.26.0 → 0.28.0

package/dist/classifier.js

@@ -68,14 +68,47 @@ export const CLASSIFIER_BACKENDS = Object.freeze({
         imagesHeader: true,
         supports: () => ({ images: false }),
     },
+    openai: {
+        baseUrl: "https://api.openai.com/v1",
+        model: "gpt-6-luna",
+        apiKeyEnv: "OPENAI_API_KEY",
+        wire: "decisions",
+        imagesHeader: false,
+        supports: () => ({ images: true }),
+    },
     custom: {
         baseUrl: "",
         model: DEFAULT_CLASSIFIER_MODEL,
-        apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV,
+        apiKeyEnv: "",
         wire: "systemone",
         imagesHeader: true,
     },
 });
+/**
+ * The env var whose key may be sent to `baseUrl` (already `${NAME}`-expanded): the backend's own
+ * variable, and only when `baseUrl` is that backend's own host over https (OpenRouter also its
+ * subdomains). `""` when none may — `custom` has no preset key at all. A key is never sent to a
+ * host the caller did not name (#155, SPEC §8B).
+ */
+export function classifierKeyEnv(backend, baseUrl) {
+    const p = Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, backend) ? CLASSIFIER_BACKENDS[backend] : undefined;
+    if (!p || !p.apiKeyEnv || !p.baseUrl)
+        return "";
+    const hostOf = (u) => {
+        try {
+            const url = new URL(u);
+            return url.protocol === "https:" ? url.hostname.toLowerCase() : "";
+        }
+        catch {
+            return "";
+        }
+    };
+    const h = hostOf(baseUrl);
+    const own = hostOf(p.baseUrl);
+    if (!h || !own)
+        return "";
+    return h === own || (backend === "openrouter" && h.endsWith(".openrouter.ai")) ? p.apiKeyEnv : "";
+}
 /**
  * Raised BEFORE any network call when the backend table says the backend cannot take what the
  * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
@@ -380,6 +413,9 @@ export class Classifier {
     baseUrl;
     model;
     apiKeyEnv;
+    /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+     * and only to its own host (classifierKeyEnv, #155). */
+    explicitKeyEnv;
     timeoutMs;
     backend;
     preset;
@@ -393,7 +429,7 @@ export class Classifier {
         this.style = opts.style ?? "systemone";
         this.backend = opts.backend ?? "typesafe";
         if (!Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, this.backend)) {
-            throw new Error(`classifier: unknown backend "${this.backend}" (want "typesafe", "openrouter", "cloudflare", "vercel" or "custom")`);
+            throw new Error(`classifier: unknown backend "${this.backend}" (want "typesafe", "openrouter", "cloudflare", "vercel", "openai" or "custom")`);
         }
         const preset = CLASSIFIER_BACKENDS[this.backend];
         this.preset = preset;
@@ -403,6 +439,7 @@ export class Classifier {
         this.baseUrl = opts.baseUrl || preset.baseUrl;
         this.model = opts.model ?? preset.model;
         this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv;
+        this.explicitKeyEnv = opts.apiKeyEnv !== undefined;
         const mismatch = backendMismatch(this.baseUrl, this.model);
         if (mismatch)
             throw new Error(mismatch);
@@ -617,7 +654,10 @@ export class Classifier {
         for (const [key, q] of Object.entries(questions))
             qs[key] = questionWire(q);
         let body;
-        if (this.preset.wire === "cloudflare") {
+        if (this.preset.wire === "decisions") {
+            body = { model: this.model, input: decisionsInput(p), questions: decisionsQuestions(this.backend, this.model, questions) };
+        }
+        else if (this.preset.wire === "cloudflare") {
             const input = { questions: qs, state: p.state };
             if (p.images.length > 0)
                 input.images = p.images.map((im) => `data:image/${im.format};base64,${im.data}`);
@@ -694,6 +734,10 @@ export class Classifier {
             parsed = unwrapCloudflare(parsed);
             text = canonicalJson(parsed);
         }
+        else if (this.preset.wire === "decisions") {
+            text = decisionsReply(parsed, questions);
+            parsed = JSON.parse(text);
+        }
         const d = decodeDecision(parsed, this.model);
         const verr = validateDecision(questions, d);
         if (validate && verr)
@@ -718,7 +762,9 @@ export class Classifier {
         // `endpoint` is what errors name: the CONFIGURED base, ${ENV} unexpanded, so an account id in
         // a templated URL never reaches an error. `url` is what is dialled, expanded at call time.
         let endpoint = this.baseUrl.replace(/\/+$/, "");
-        if (this.preset.wire !== "cloudflare")
+        if (this.preset.wire === "decisions")
+            endpoint += "/decisions";
+        else if (this.preset.wire !== "cloudflare")
             endpoint += "/systemone";
         const url = endpoint.includes("${") ? expandEnv(endpoint) : endpoint;
         const retries = this.opts.retries ?? 2;
@@ -745,7 +791,7 @@ export class Classifier {
             try {
                 res = await doFetch(url, {
                     method: "POST",
-                    headers: this.requestHeaders(extraHeaders),
+                    headers: this.requestHeaders(extraHeaders, url),
                     body: payload,
                     signal: timer.signal,
                 });
@@ -781,9 +827,10 @@ export class Classifier {
         }
     }
     /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
-    requestHeaders(extra = {}) {
+    requestHeaders(extra, url) {
         const headers = { "Content-Type": "application/json" };
-        const key = process.env[this.apiKeyEnv];
+        const keyEnv = this.explicitKeyEnv ? this.apiKeyEnv : classifierKeyEnv(this.backend, url);
+        const key = keyEnv ? process.env[keyEnv] : undefined;
         if (key)
             headers["Authorization"] = `Bearer ${key}`;
         // The image opt-in header goes BEFORE host headers, which win.
@@ -1057,10 +1104,29 @@ function imageSize(format, b) {
     }
     return undefined;
 }
-/** The System One reply inside a Cloudflare `/ai/run` envelope. Its error list is never echoed. */
+/**
+ * `: <code> <message>` from errors[0] of a failed envelope (SPEC §8B), through the same redaction
+ * and cap as cause(). Cloudflare reports a missing balance, a bad model id and a malformed
+ * request alike as HTTP 200 + success:false, so this is the only thing that tells them apart.
+ * `""` when there is nothing to show.
+ */
+function cloudflareCause(env) {
+    const errs = env !== null && typeof env === "object" ? env.errors : undefined;
+    const e0 = Array.isArray(errs) ? errs[0] : undefined;
+    if (e0 === null || typeof e0 !== "object")
+        return "";
+    const parts = [];
+    if ((typeof e0.code === "number" || typeof e0.code === "string") && String(e0.code) !== "")
+        parts.push(String(e0.code));
+    if (typeof e0.message === "string" && e0.message !== "")
+        parts.push(e0.message);
+    const s = capErrorBody(redactErrorBody(parts.join(" ")));
+    return s ? ": " + s : "";
+}
+/** The System One reply inside a Cloudflare `/ai/run` envelope. Only errors[0] is ever echoed. */
 function unwrapCloudflare(env) {
     if (env === null || typeof env !== "object" || Array.isArray(env) || env.success !== true) {
-        throw new Error("classifier: cloudflare: envelope not successful");
+        throw new Error("classifier: cloudflare: envelope not successful" + cloudflareCause(env));
     }
     let result = env.result;
     if (result !== null && typeof result === "object" && !Array.isArray(result) && typeof result.state === "string") {
@@ -1228,3 +1294,103 @@ export function chunkQuestions(questions, size) {
     }
     return out;
 }
+// ---------------------------------------------------------------- the Decisions wire (#157)
+/** The Decisions API's per-request question cap. */
+export const MAX_DECISIONS_QUESTIONS = 400;
+/**
+ * Maps the question set to the Decisions API list, in ASCII key order. Caller keys are NOT sent
+ * (no `name`): §8B keys are addressing, not content, and answers come back in request order.
+ * Every check fires before any request.
+ */
+function decisionsQuestions(backend, model, questions) {
+    const keys = Object.keys(questions).sort();
+    if (keys.length > MAX_DECISIONS_QUESTIONS) {
+        throw new Error(`classifier: the decisions wire takes at most ${MAX_DECISIONS_QUESTIONS} questions, got ${keys.length}`);
+    }
+    return keys.map((k) => {
+        const q = questions[k];
+        if (isRawQuestion(q))
+            throw new ClassifierUnsupported(backend, model, `raw question type "${q.type}"`);
+        const m = q;
+        switch (m.type) {
+            case "noul": {
+                let instructions = m.instructions;
+                if (m.criteria !== undefined)
+                    instructions += `\n\nTrue means: ${m.criteria.true}\nFalse means: ${m.criteria.false}`;
+                return { type: "predicate", instructions };
+            }
+            case "choice": {
+                const ids = Object.keys(m.criteria ?? {}).sort();
+                if (ids.length < 2) {
+                    throw new Error(`classifier: question "${k}": the decisions wire needs 2..${MAX_CHOICE_OPTIONS} choice options, got ${ids.length}`);
+                }
+                const choices = ids.map((id) => (m.criteria[id] === "" ? { value: id } : { value: id, description: m.criteria[id] }));
+                return { type: "choice", instructions: m.instructions, choices };
+            }
+            case "score":
+                return { type: "score", instructions: m.instructions, levels: m.criteria.map((label) => ({ label })) };
+        }
+    });
+}
+/** The state as sent: a string verbatim, else canonical JSON text; with images, one user message. */
+function decisionsInput(p) {
+    const text = typeof p.state === "string" ? p.state : canonicalJson(p.state);
+    if (p.images.length === 0)
+        return text;
+    const content = [{ type: "input_text", text }];
+    for (const im of p.images)
+        content.push({ type: "input_image", image_url: `data:image/${im.format};base64,${im.data}` });
+    return [{ role: "user", content }];
+}
+/** A choice value or level index as the §8B key: string as written, boolean "true"/"false", number shortest. */
+function decisionsValue(v) {
+    return typeof v === "string" ? v : String(v);
+}
+/**
+ * Reads a Decisions API reply back into a System One-shaped body (canonical JSON), so decode,
+ * validation and the cache are the one path. `calibrated` is false. Exported for conformance tests.
+ */
+export function decisionsReply(reply, questions) {
+    const r = reply;
+    if (r === null || typeof r !== "object" || Array.isArray(r) || !Array.isArray(r.answers)) {
+        throw new Error("classifier: decisions: malformed reply");
+    }
+    const keys = Object.keys(questions).sort();
+    if (r.answers.length !== keys.length) {
+        throw new Error(`classifier: decisions: ${r.answers.length} answers for ${keys.length} questions`);
+    }
+    const num = (v) => (typeof v === "number" ? v : 0);
+    const want = { noul: "predicate", choice: "choice", score: "score" };
+    const answers = {};
+    keys.forEach((k, i) => {
+        const a = r.answers[i];
+        if (a === null || typeof a !== "object" || Array.isArray(a))
+            throw new Error("classifier: decisions: malformed reply");
+        if (a.type === "refusal")
+            throw new Error(`classifier: decisions: question "${k}" was refused`);
+        const q = questions[k];
+        const w = want[q.type] ?? "";
+        if (a.type !== w)
+            throw new Error(`classifier: decisions: answer "${k}" is a ${a.type} answer, not ${w}`);
+        const probs = {};
+        for (const p of Array.isArray(a.probabilities) ? a.probabilities : [])
+            probs[decisionsValue(p?.value)] = num(p?.probability);
+        if (q.type === "noul")
+            answers[k] = { type: "noul", noul: num(a.probability) };
+        else if (q.type === "choice") {
+            answers[k] = { type: "choice", choice: decisionsValue(a.choice), probabilities: probs, confidence: num(a.confidence) };
+        }
+        else {
+            const legend = {};
+            q.criteria.forEach((l, j) => (legend[String(j)] = l));
+            answers[k] = { type: "score", score: num(a.score), legend, probabilities: probs, confidence: num(a.confidence) };
+        }
+    });
+    const u = r.usage ?? {};
+    return canonicalJson({
+        answers,
+        calibrated: false,
+        model: typeof r.model === "string" ? r.model : "",
+        usage: { input_tokens: num(u.input_tokens), output_tokens: num(u.output_tokens) },
+    });
+}

package/dist/client.d.ts

@@ -26,11 +26,20 @@ export interface ClientOptions {
     headers?: Record<string, string>;
     systemPrompt?: string;
     maxTurns?: number;
+    /** SPEC §8 "Stop-reason recovery". Default false. On, an empty answer is nudged once, a
+     * `length`/`max_tokens` cut is continued (up to 3 times, text carried) and malformed tool-call
+     * arguments get one corrective turn — each an ordinary turn, only while a turn remains. */
+    stopRecovery?: boolean;
     /** Cap on concurrency-safe tool calls of one response running at once (SPEC §8 "Tool
      * scheduling"). Absent ⇒ env `TOOLNEXUS_MAX_TOOL_CONCURRENCY` when a positive integer, else 10.
      * Unsafe calls (anything not read-only) always run alone. */
     maxToolConcurrency?: number;
     hooks?: Hooks;
+    /** SPEC §7F.1 reactive compaction. Called (with the `beforeLLM` signature) when the provider
+     * rejects a call as a context overflow (`isContextOverflow`); strictly fewer `messages` replace
+     * the transcript and the same turn is re-sent. Breaker: 3 rapid compactions ⇒ `ContextOverflowError`.
+     * Absent ⇒ the overflow surfaces as `LlmHttpError`, unchanged. */
+    compactOnOverflow?: Hooks["beforeLLM"];
     /** Retries on transient LLM errors (`429`/`500`/`502`/`503`/`504`/`529` + network). Default 2.
      * Widen the status set with `retryableStatuses`. */
     retries?: number;
@@ -97,6 +106,11 @@ export interface ClientOptions {
      * 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. Ordered fallback model ids tried, with a fresh retry budget each, when the
+     * current model's retry budget ends on an overload (`503`/`529`). Chain = [turnModel, ...these];
+     * empty/duplicate entries skipped. `TOOLNEXUS_DISABLE_MODEL_FALLBACK=1|true` disables it.
+     * `stream` emits `{ type: "fallback", from, to }` before switching. Omit ⇒ byte-identical. */
+    fallbackModels?: readonly string[];
     /** §1B. Reject a content part carrying more than this many **decoded** bytes (never the
      * +33% base64 string). Unset ⇒ no limit, as today. */
     maxPartBytes?: number;
@@ -159,6 +173,26 @@ export declare class LlmHttpError extends Error {
 }
 /** Build the typed error from a non-2xx provider response (reads the body once). */
 export declare function llmHttpError(res: Response): Promise<LlmHttpError>;
+/** SPEC §7F.1: true iff `status` is 400/413 AND the (redacted) body names a context overflow. */
+export declare function isContextOverflow(status: number, body: string): boolean;
+/** SPEC §7F.1: reactive compaction could not make the prompt fit (breaker tripped, or the
+ *  `compactOnOverflow` hook made no progress). A failure, never a §10 pending. */
+export declare class ContextOverflowError extends Error {
+    /** Reactive compactions in the current rapid chain (3 when the breaker tripped). */
+    readonly compactions: number;
+    /** Status of the last provider error. */
+    readonly status: number;
+    /** Redacted body of the last provider error (same redaction as `LlmHttpError`). */
+    readonly body: string;
+    readonly name = "ContextOverflowError";
+    constructor(
+    /** Reactive compactions in the current rapid chain (3 when the breaker tripped). */
+    compactions: number, 
+    /** Status of the last provider error. */
+    status: number, 
+    /** Redacted body of the last provider error (same redaction as `LlmHttpError`). */
+    body: string);
+}
 /** §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. */
@@ -301,6 +335,21 @@ export interface Hooks {
     } | Promise<void | {
         result?: ToolResult;
     }>;
+    /** At each round boundary (SPEC §8, #192): after a round's tool results (final=false), or when the
+     * model stopped with a turn remaining (final=true, text = its answer). Each `inject` string is
+     * appended as a user message; a non-empty inject on a final round CONTINUES the loop. */
+    afterRound?(ev: AfterRoundEvent): void | RoundInjection | Promise<void | RoundInjection>;
+}
+/** The `afterRound` hook event. */
+export interface AfterRoundEvent {
+    turn: number;
+    final: boolean;
+    text: string;
+    messages: any[];
+}
+/** What an `afterRound` hook may return. */
+export interface RoundInjection {
+    inject?: string[];
 }
 /** A tool call the model made, plus its result + metadata. */
 export interface ToolCallRecord {
@@ -379,6 +428,15 @@ export type StreamEvent = {
     name: string;
     args: Record<string, unknown>;
     via?: "call_tool" | "acp";
+}
+/** An ACP agent's `tool_call_update` carrying `rawInput`: the call's arguments, known after
+ *  the initial `tool_call` (#188). Reported only; never executed by the loop. */
+ | {
+    type: "tool_call_args";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    via: "acp";
 } | {
     type: "tool_result";
     id: string;
@@ -390,9 +448,26 @@ export type StreamEvent = {
 } | {
     type: "usage";
     usage: Usage;
+}
+/** Only with `fallbackModels`: switching from model `from` to `to` after overload (§8). */
+ | {
+    type: "fallback";
+    from: string;
+    to: string;
 } | {
     type: "pending";
     request: Request;
+}
+/** Emitted just before each LLM retry wait (streaming only). `attempt` is 1-based (the
+ *  failed zero-based attempt + 1), `max` the configured `retries`, `delayMs` the exact wait,
+ *  `status` the HTTP status (absent on a network error), `reason` "HTTP <status>" | "network". */
+ | {
+    type: "retry";
+    attempt: number;
+    max: number;
+    delayMs: number;
+    status?: number;
+    reason: string;
 } | {
     type: "done";
     result: RunResult;
@@ -521,6 +596,20 @@ export declare class Client {
      * 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;
+    /** The retry loop behind `llmFetch`, as a generator: yields a `retry` StreamEvent just before
+     * each retry wait (its `delayMs` is the exact wait slept) and returns the final Response.
+     * The streaming generators consume it with `yield*`. */
+    private llmFetchEvents;
+    /** §8 fallbackModels: the per-call model chain — [turnModel, ...fallbackModels], empty and
+     * duplicate entries skipped; just [turnModel] when the option is absent or the kill switch is set. */
+    private modelChain;
+    /** llmFetch over the model chain: each model spends the full retry budget; only a budget that
+     * ends on 503/529 (not an onError "fail") advances to the next model. Returns the response and
+     * the model that produced it. `build` rebuilds the same request for a model. */
+    private llmFetchChain;
+    /** The fallback chain as a generator for the streaming loops: the #189 `retry` events of each
+     * model's attempts and a `fallback` event at each switch reach the stream as they happen. */
+    private llmFetchChainEvents;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;
     private runToolDirect;
@@ -550,11 +639,31 @@ export declare class Client {
     private emitTool;
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     private llmCallJson;
+    /**
+     * SPEC §7F.1: one LLM call with reactive compaction. `call(messages)` makes the request and
+     * throws on a non-2xx (as `LlmHttpError`). On a context overflow with `compactOnOverflow` set,
+     * the hook compacts and the SAME turn is re-sent (no beforeLLM, no turn consumed), guarded by
+     * the rapid-refill breaker. Returns the call's value and the (possibly compacted) transcript.
+     */
+    private callWithOverflow;
+    /** `callWithOverflow` for the streaming loops: `call` is a generator so the #189 `retry` events
+     * of every attempt (including one after a compaction) still reach the stream before each wait. */
+    private callWithOverflowEvents;
     private runOpenAI;
     private runAnthropic;
     private streamOpenAI;
     private streamAnthropic;
+    /**
+     * §8 stop-reason recovery: classify the response just appended to `messages` and, when a rule
+     * fires, remove (or keep) that assistant message, append the pinned user message, and return
+     * true — the caller then takes another turn. Never on the last permitted turn.
+     */
+    private recover;
+    private newRecovery;
     private runOpenAIWithSignal;
+    /** §8 afterRound: fire the round-boundary hook and append its injections as user messages.
+     * Returns true when something was appended. A final round fires only when a turn remains. */
+    private roundEnd;
     private result;
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
     private pendingRun;