toolnexus 0.27.0 → 0.29.0

package/dist/classifier.js

@@ -68,6 +68,14 @@ 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,
@@ -421,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;
@@ -646,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}`);
@@ -723,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)
@@ -747,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;
@@ -1277,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

@@ -1,8 +1,3 @@
-/**
- * Unified LLM client — the host loop. Give it a plain base URL + a style
- * ("openai" | "anthropic"), and it runs the tool-calling agent loop against a
- * Toolkit. See ../../SPEC.md §8.
- */
 import type { Toolkit } from "./toolkit.js";
 import type { ToolHints, ToolResult, Request, Answer } from "./types.js";
 import { type PromptCacheOptions } from "./promptcache.js";
@@ -26,11 +21,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 +101,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 +168,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 +330,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 {
@@ -319,9 +363,12 @@ export type RunFile = {
     url?: string;
     data?: string;
     name?: string;
+    path?: string;
     from: string;
     callId: string;
 };
+/** RunResult.files: every non-text part of every tool call, in call order (§8). */
+export declare function runFiles(toolCalls: ToolCallRecord[]): RunFile[];
 /** Token usage, summed across every LLM round trip in the run. */
 export interface Usage {
     promptTokens: number;
@@ -379,6 +426,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 +446,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 +594,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 +637,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;