toolnexus 0.19.0 → 0.21.0

package/dist/client.d.ts

@@ -207,20 +207,24 @@ export declare class InMemoryConversationStore implements ConversationStore {
  * Lifecycle hooks around the agent loop. Each may observe, and (where noted)
  * mutate or short-circuit. All may be async.
  */
+/** The `beforeLLM` hook event. */
+export interface BeforeLLMEvent {
+    messages: any[];
+    tools: any[];
+    model: string;
+    turn: number;
+}
+/** What a `beforeLLM` hook may return. `model` (non-empty) applies to that turn only. */
+export interface LLMOverride {
+    messages?: any[];
+    tools?: any[];
+    model?: string | null;
+}
 export interface Hooks {
-    /** Before each model call. Return { messages?, tools? } to replace them. */
-    beforeLLM?(ev: {
-        messages: any[];
-        tools: any[];
-        model: string;
-        turn: number;
-    }): void | {
-        messages?: any[];
-        tools?: any[];
-    } | Promise<void | {
-        messages?: any[];
-        tools?: any[];
-    }>;
+    /** Before each model call. Return { messages?, tools? } to replace them, and { model } to send a
+     * different model for THIS turn only (request body + afterLLM event); absent/null/empty keeps the
+     * configured model verbatim (SPEC §8, e.g. a ModelRouterClassifier). */
+    beforeLLM?(ev: BeforeLLMEvent): void | LLMOverride | Promise<void | LLMOverride>;
     /** After each model call (observe: logging, cost, tracing). */
     afterLLM?(ev: {
         response: any;
@@ -412,7 +416,17 @@ export declare class Client {
     /** §0.10 system message. The toolkit is OPTIONAL — with none there is no skills prompt and
      *  the system message is the system prompt alone. This deref was issue #86 (ADR 0023). */
     private system;
-    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    /** Run-scoped timeout timers, cleared by `releaseSignal` when the run settles. */
+    private readonly runTimers;
+    /** Drop a run's timeout timer. Idempotent, and safe on a signal that never had one. */
+    private releaseSignal;
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal.
+     *
+     * The timer is deliberately NOT `unref()`d. An unref'd timer cannot keep the event loop
+     * alive, so a run whose only pending work is a request that never settles — an injected
+     * `fetch`, an in-process transport, a stalled stream — drains the loop and the timeout never
+     * fires at all, which is the one case `timeoutMs` exists for. It is RELEASED instead: the
+     * caller clears it however the run leaves, so a finished run holds nothing open. */
     private makeSignal;
     /** 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.
@@ -425,6 +439,10 @@ export declare class Client {
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     private llmCallJson;
     private runOpenAI;
+    private runAnthropic;
+    private streamOpenAI;
+    private streamAnthropic;
+    private runOpenAIWithSignal;
     private result;
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
     private pendingRun;
@@ -434,9 +452,9 @@ export declare class Client {
      * no `waitFor` is configured (the run should stop and surface the request).
      */
     private resolvePending;
-    private runAnthropic;
-    private streamOpenAI;
-    private streamAnthropic;
+    private runAnthropicWithSignal;
+    private streamOpenAIWithSignal;
+    private streamAnthropicWithSignal;
 }
 export declare function createClient(opts: ClientOptions): Client;
 /** One tool call an in-process model asks for. Flat on purpose: the nested

package/dist/client.js

@@ -254,8 +254,8 @@ export class Client {
     }
     /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
      * matches the pre-change body so a no-options call is byte-identical. */
-    openaiBody(messages, tools, stream) {
-        const b = { model: this.opts.model, messages: toOpenAIWire(messages, this.wireOpts()) };
+    openaiBody(messages, tools, stream, model = this.opts.model) {
+        const b = { model, messages: toOpenAIWire(messages, this.wireOpts()) };
         if (tools.length) {
             b.tools = tools;
             b.tool_choice = "auto";
@@ -267,8 +267,8 @@ export class Client {
         return this.finalizeBody(b);
     }
     /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
-    anthropicBody(system, messages, tools, stream) {
-        const b = { model: this.opts.model, max_tokens: 4096, system, messages: toAnthropicWire(messages, this.wireOpts()) };
+    anthropicBody(system, messages, tools, stream, model = this.opts.model) {
+        const b = { model, max_tokens: 4096, system, messages: toAnthropicWire(messages, this.wireOpts()) };
         if (tools.length)
             b.tools = tools;
         if (stream)
@@ -290,13 +290,13 @@ export class Client {
     }
     /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
      * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
-    endRun(runStart, text, messages, toolCalls, turns, usage, exhausted = false) {
-        this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
-        return this.result(text, messages, toolCalls, turns, usage, exhausted);
+    endRun(runStart, model, text, messages, toolCalls, turns, usage, exhausted = false) {
+        this.emit({ event: "run", model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
+        return this.result(model, text, messages, toolCalls, turns, usage, exhausted);
     }
     /** Emit a `run` error metric event (once, on a thrown run). */
-    emitRunError(runStart, toolCalls, turns, usage, e) {
-        this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart, error: e instanceof Error ? e.message : String(e) });
+    emitRunError(runStart, model, toolCalls, turns, usage, e) {
+        this.emit({ event: "run", model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart, error: e instanceof Error ? e.message : String(e) });
     }
     /**
      * Run the loop. `ctx` — and `ctx.toolkit` inside it — are OPTIONAL: an absent toolkit is a
@@ -334,14 +334,17 @@ export class Client {
         if (sys && !hasSystemMessage(messages))
             messages = [{ role: "system", content: sys }, ...messages];
         let tools = declared;
+        let turnModel = this.opts.model;
         if (this.opts.hooks?.beforeLLM) {
             const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 });
             if (ov?.messages)
                 messages = ov.messages;
             if (ov?.tools)
                 tools = ov.tools;
+            if (ov?.model)
+                turnModel = ov.model;
         }
-        const body = { model: this.opts.model, messages };
+        const body = { model: turnModel, messages };
         if (tools.length)
             body.tools = tools;
         if (req.toolChoice !== undefined)
@@ -349,14 +352,14 @@ export class Client {
         if (req.maxTokens)
             body.max_tokens = req.maxTokens;
         const signal = this.makeSignal(req.signal);
-        {
+        try {
             const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${key}`, ...this.opts.headers },
                 body: JSON.stringify(this.finalizeBody(body)),
-            }, signal, "openai");
+            }, signal, "openai", turnModel);
             if (this.opts.hooks?.afterLLM)
-                await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 });
+                await this.opts.hooks.afterLLM({ response: data, model: turnModel, turn: 0 });
             const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
             addUsage(usage, data.usage, "openai");
             const choice = data.choices?.[0];
@@ -370,10 +373,13 @@ export class Client {
                 toolCalls,
                 finishReason: choice?.finish_reason ?? finishReasonFor(toolCalls.length > 0),
                 usage,
-                model: this.opts.model,
+                model: turnModel,
                 raw: data,
             };
         }
+        finally {
+            this.releaseSignal(signal);
+        }
     }
     /** Anthropic-style upstream: the real translation. */
     async translateAnthropic(req) {
@@ -387,15 +393,18 @@ export class Client {
             ...(req.toolkit ? req.toolkit.toAnthropic() : []),
             ...openAIToolsToAnthropic(req.tools),
         ];
+        let turnModel = this.opts.model;
         if (this.opts.hooks?.beforeLLM) {
             const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn: 0 });
             if (ov?.messages)
                 messages = ov.messages;
             if (ov?.tools)
                 tools = ov.tools;
+            if (ov?.model)
+                turnModel = ov.model;
         }
         const body = {
-            model: this.opts.model,
+            model: turnModel,
             max_tokens: req.maxTokens && req.maxTokens > 0 ? req.maxTokens : 4096,
             messages,
         };
@@ -407,7 +416,7 @@ export class Client {
         if (tc)
             body.tool_choice = tc;
         const signal = this.makeSignal(req.signal);
-        {
+        try {
             const data = await this.llmCallJson(endpoint, {
                 method: "POST",
                 headers: {
@@ -417,9 +426,9 @@ export class Client {
                     ...this.opts.headers,
                 },
                 body: JSON.stringify(this.finalizeBody(body)),
-            }, signal, "anthropic");
+            }, signal, "anthropic", turnModel);
             if (this.opts.hooks?.afterLLM)
-                await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn: 0 });
+                await this.opts.hooks.afterLLM({ response: data, model: turnModel, turn: 0 });
             const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
             addUsage(usage, data.usage, "anthropic");
             const text = [];
@@ -440,10 +449,13 @@ export class Client {
                 toolCalls,
                 finishReason: finishReasonFor(toolCalls.length > 0, data.stop_reason),
                 usage,
-                model: this.opts.model,
+                model: turnModel,
                 raw: data,
             };
         }
+        finally {
+            this.releaseSignal(signal);
+        }
     }
     /**
      * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
@@ -508,12 +520,28 @@ export class Client {
     system(toolkit) {
         return [this.opts.systemPrompt ?? "", toolkit?.skillsPrompt() ?? ""].filter(Boolean).join("\n\n");
     }
-    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    /** Run-scoped timeout timers, cleared by `releaseSignal` when the run settles. */
+    runTimers = new WeakMap();
+    /** Drop a run's timeout timer. Idempotent, and safe on a signal that never had one. */
+    releaseSignal(signal) {
+        const t = this.runTimers.get(signal);
+        if (t !== undefined) {
+            clearTimeout(t);
+            this.runTimers.delete(signal);
+        }
+    }
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal.
+     *
+     * The timer is deliberately NOT `unref()`d. An unref'd timer cannot keep the event loop
+     * alive, so a run whose only pending work is a request that never settles — an injected
+     * `fetch`, an in-process transport, a stalled stream — drains the loop and the timeout never
+     * fires at all, which is the one case `timeoutMs` exists for. It is RELEASED instead: the
+     * caller clears it however the run leaves, so a finished run holds nothing open. */
     makeSignal(external) {
         const ctrl = new AbortController();
         if (this.opts.timeoutMs) {
             const t = setTimeout(() => ctrl.abort(new Error(`run timeout after ${this.opts.timeoutMs}ms`)), this.opts.timeoutMs);
-            t.unref?.();
+            this.runTimers.set(ctrl.signal, t);
         }
         if (external) {
             if (external.aborted)
@@ -596,7 +624,7 @@ export class Client {
         this.emit({ event: "tool", tool: name, source, isError: req ? false : result.isError, ms: Date.now() - t0, ...(req ? { pending: true } : {}) });
     }
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
-    async llmCallJson(url, init, signal, style) {
+    async llmCallJson(url, init, signal, style, model) {
         const t0 = Date.now();
         try {
             const res = await this.llmFetch(url, init, signal);
@@ -604,18 +632,55 @@ export class Client {
                 throw await llmHttpError(res);
             const data = await res.json();
             const tok = perCall(data.usage, style);
-            this.emit({ event: "llm", model: this.opts.model, status: "ok", ms: Date.now() - t0, promptTokens: tok.prompt, completionTokens: tok.completion });
+            this.emit({ event: "llm", model, status: "ok", ms: Date.now() - t0, promptTokens: tok.prompt, completionTokens: tok.completion });
             return data;
         }
         catch (e) {
-            this.emit({ event: "llm", model: this.opts.model, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
+            this.emit({ event: "llm", model, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
             throw e;
         }
     }
-    // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
+    // The run-scoped timeout timer is owned by these four wrappers, so it is cleared however the
+    // run leaves: return, throw, or a consumer abandoning the stream half-way.
     async runOpenAI(prompt, toolkit, external, history) {
-        const key = resolveKey(this.opts);
         const signal = this.makeSignal(external);
+        try {
+            return await this.runOpenAIWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async runAnthropic(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            return await this.runAnthropicWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async *streamOpenAI(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            yield* this.streamOpenAIWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async *streamAnthropic(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            yield* this.streamAnthropicWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
+    async runOpenAIWithSignal(signal, prompt, toolkit, history) {
+        const key = resolveKey(this.opts);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
         if (!messages.length) {
@@ -628,29 +693,35 @@ export class Client {
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
+        // The model of the last call this run made (a beforeLLM override when one applied) — §8.
+        let lastModel = this.opts.model;
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
+                let turnModel = this.opts.model;
                 if (this.opts.hooks?.beforeLLM) {
                     const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn });
                     if (ov?.messages)
                         messages = ov.messages;
                     if (ov?.tools)
                         tools = ov.tools;
+                    if (ov?.model)
+                        turnModel = ov.model;
                 }
+                lastModel = turnModel;
                 const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                     method: "POST",
                     headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-                    body: JSON.stringify(this.openaiBody(messages, tools, false)),
-                }, signal, "openai");
+                    body: JSON.stringify(this.openaiBody(messages, tools, false, turnModel)),
+                }, signal, "openai", turnModel);
                 addUsage(usage, data.usage, "openai");
                 if (this.opts.hooks?.afterLLM)
-                    await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn });
+                    await this.opts.hooks.afterLLM({ response: data, model: turnModel, turn });
                 const msg = data.choices[0].message;
                 messages.push(msg);
                 const calls = msg.tool_calls ?? [];
                 if (calls.length === 0)
-                    return this.endRun(runStart, msg.content ?? "", messages, toolCalls, turns, usage);
+                    return this.endRun(runStart, lastModel, msg.content ?? "", messages, toolCalls, turns, usage);
                 // execute all tool calls in this turn concurrently (true parallel tool calling)
                 const settled = await Promise.all(calls.map(async (call) => {
                     let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn);
@@ -670,27 +741,27 @@ export class Client {
                     toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
                     messages.push(toolMessage(s.call.id, s.call.function.name, s.result));
                     if (s.halted)
-                        return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage);
+                        return this.pendingRun(runStart, lastModel, s.halted, messages, toolCalls, turns, usage);
                 }
             }
-            return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true);
+            return this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true);
         }
         catch (e) {
-            this.emitRunError(runStart, toolCalls, turns, usage, e);
+            this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
             throw e;
         }
     }
-    result(text, messages, toolCalls, turns, usage, exhausted = false) {
+    result(model, text, messages, toolCalls, turns, usage, exhausted = false) {
         const incomplete = exhausted && text === "";
-        const r = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: incomplete ? "incomplete" : "done" };
+        const r = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model, status: incomplete ? "incomplete" : "done" };
         if (incomplete)
             r.limit = "maxTurns";
         return r;
     }
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
-    pendingRun(runStart, request, messages, toolCalls, turns, usage) {
-        this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
-        return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "pending", pending: request };
+    pendingRun(runStart, model, request, messages, toolCalls, turns, usage) {
+        this.emit({ event: "run", model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
+        return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model, status: "pending", pending: request };
     }
     /**
      * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
@@ -718,9 +789,8 @@ export class Client {
         return { result };
     }
     // ---- Anthropic-style: POST {baseUrl}/messages ----
-    async runAnthropic(prompt, toolkit, external, history) {
+    async runAnthropicWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
         const system = this.system(toolkit);
@@ -730,16 +800,22 @@ export class Client {
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
+        // The model of the last call this run made (a beforeLLM override when one applied) — §8.
+        let lastModel = this.opts.model;
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
+                let turnModel = this.opts.model;
                 if (this.opts.hooks?.beforeLLM) {
                     const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn });
                     if (ov?.messages)
                         messages = ov.messages;
                     if (ov?.tools)
                         tools = ov.tools;
+                    if (ov?.model)
+                        turnModel = ov.model;
                 }
+                lastModel = turnModel;
                 const data = await this.llmCallJson(endpoint, {
                     method: "POST",
                     headers: {
@@ -748,16 +824,16 @@ export class Client {
                         "Content-Type": "application/json",
                         ...this.opts.headers,
                     },
-                    body: JSON.stringify(this.anthropicBody(system, messages, tools, false)),
-                }, signal, "anthropic");
+                    body: JSON.stringify(this.anthropicBody(system, messages, tools, false, turnModel)),
+                }, signal, "anthropic", turnModel);
                 addUsage(usage, data.usage, "anthropic");
                 if (this.opts.hooks?.afterLLM)
-                    await this.opts.hooks.afterLLM({ response: data, model: this.opts.model, turn });
+                    await this.opts.hooks.afterLLM({ response: data, model: turnModel, turn });
                 messages.push({ role: "assistant", content: data.content });
                 const uses = (data.content ?? []).filter((b) => b.type === "tool_use");
                 if (uses.length === 0) {
                     const text = (data.content ?? []).filter((b) => b.type === "text").map((b) => b.text).join("");
-                    return this.endRun(runStart, text, messages, toolCalls, turns, usage);
+                    return this.endRun(runStart, lastModel, text, messages, toolCalls, turns, usage);
                 }
                 // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
                 const settled = await Promise.all(uses.map(async (use) => {
@@ -786,19 +862,18 @@ export class Client {
                 }
                 messages.push({ role: "user", content });
                 if (halted)
-                    return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
+                    return this.pendingRun(runStart, lastModel, halted, messages, toolCalls, turns, usage);
             }
-            return this.endRun(runStart, "", messages, toolCalls, turns, usage, true);
+            return this.endRun(runStart, lastModel, "", messages, toolCalls, turns, usage, true);
         }
         catch (e) {
-            this.emitRunError(runStart, toolCalls, turns, usage, e);
+            this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
             throw e;
         }
     }
     // ---- Streaming: OpenAI-style ----
-    async *streamOpenAI(prompt, toolkit, external, history) {
+    async *streamOpenAIWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
         if (!messages.length) {
@@ -811,16 +886,22 @@ export class Client {
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
+        // The model of the last call this run made (a beforeLLM override when one applied) — §8.
+        let lastModel = this.opts.model;
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
+                let turnModel = this.opts.model;
                 if (this.opts.hooks?.beforeLLM) {
                     const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn });
                     if (ov?.messages)
                         messages = ov.messages;
                     if (ov?.tools)
                         tools = ov.tools;
+                    if (ov?.model)
+                        turnModel = ov.model;
                 }
+                lastModel = turnModel;
                 const t0 = Date.now();
                 const beforeP = usage.promptTokens, beforeC = usage.completionTokens;
                 let content = "";
@@ -829,7 +910,7 @@ export class Client {
                     const res = await this.llmFetch(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                         method: "POST",
                         headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
-                        body: JSON.stringify(this.openaiBody(messages, tools, true)),
+                        body: JSON.stringify(this.openaiBody(messages, tools, true, turnModel)),
                     }, signal);
                     if (!res.ok || !res.body)
                         throw await llmHttpError(res);
@@ -861,17 +942,17 @@ export class Client {
                     }
                 }
                 catch (e) {
-                    this.emit({ event: "llm", model: this.opts.model, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
+                    this.emit({ event: "llm", model: turnModel, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
                     throw e;
                 }
-                this.emit({ event: "llm", model: this.opts.model, status: "ok", ms: Date.now() - t0, promptTokens: usage.promptTokens - beforeP, completionTokens: usage.completionTokens - beforeC });
+                this.emit({ event: "llm", model: turnModel, status: "ok", ms: Date.now() - t0, promptTokens: usage.promptTokens - beforeP, completionTokens: usage.completionTokens - beforeC });
                 if (this.opts.hooks?.afterLLM)
-                    await this.opts.hooks.afterLLM({ response: { streamed: true, usage }, model: this.opts.model, turn });
+                    await this.opts.hooks.afterLLM({ response: { streamed: true, usage }, model: turnModel, turn });
                 const calls = [...acc.values()];
                 if (calls.length === 0) {
                     messages.push({ role: "assistant", content });
                     yield { type: "usage", usage };
-                    yield { type: "done", result: this.endRun(runStart, content, messages, toolCalls, turns, usage) };
+                    yield { type: "done", result: this.endRun(runStart, lastModel, content, messages, toolCalls, turns, usage) };
                     return;
                 }
                 messages.push({ role: "assistant", content: content || null, tool_calls: calls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })) });
@@ -889,7 +970,7 @@ export class Client {
                         if (r.halted) {
                             toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                             messages.push(toolMessage(c.id, c.name, result));
-                            yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
+                            yield { type: "done", result: this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage) };
                             return;
                         }
                     }
@@ -898,17 +979,16 @@ export class Client {
                     yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
                 }
             }
-            yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true) };
+            yield { type: "done", result: this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
-            this.emitRunError(runStart, toolCalls, turns, usage, e);
+            this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
             throw e;
         }
     }
     // ---- Streaming: Anthropic-style ----
-    async *streamAnthropic(prompt, toolkit, external, history) {
+    async *streamAnthropicWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const runStart = Date.now();
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
@@ -918,16 +998,22 @@ export class Client {
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
+        // The model of the last call this run made (a beforeLLM override when one applied) — §8.
+        let lastModel = this.opts.model;
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
+                let turnModel = this.opts.model;
                 if (this.opts.hooks?.beforeLLM) {
                     const ov = await this.opts.hooks.beforeLLM({ messages, tools, model: this.opts.model, turn });
                     if (ov?.messages)
                         messages = ov.messages;
                     if (ov?.tools)
                         tools = ov.tools;
+                    if (ov?.model)
+                        turnModel = ov.model;
                 }
+                lastModel = turnModel;
                 const t0 = Date.now();
                 const beforeP = usage.promptTokens, beforeC = usage.completionTokens;
                 const blocks = new Map();
@@ -936,7 +1022,7 @@ export class Client {
                     const res = await this.llmFetch(endpoint, {
                         method: "POST",
                         headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "Content-Type": "application/json", ...this.opts.headers },
-                        body: JSON.stringify(this.anthropicBody(system, messages, tools, true)),
+                        body: JSON.stringify(this.anthropicBody(system, messages, tools, true, turnModel)),
                     }, signal);
                     if (!res.ok || !res.body)
                         throw await llmHttpError(res);
@@ -966,19 +1052,19 @@ export class Client {
                     }
                 }
                 catch (e) {
-                    this.emit({ event: "llm", model: this.opts.model, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
+                    this.emit({ event: "llm", model: turnModel, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
                     throw e;
                 }
-                this.emit({ event: "llm", model: this.opts.model, status: "ok", ms: Date.now() - t0, promptTokens: usage.promptTokens - beforeP, completionTokens: usage.completionTokens - beforeC });
+                this.emit({ event: "llm", model: turnModel, status: "ok", ms: Date.now() - t0, promptTokens: usage.promptTokens - beforeP, completionTokens: usage.completionTokens - beforeC });
                 if (this.opts.hooks?.afterLLM)
-                    await this.opts.hooks.afterLLM({ response: { streamed: true, usage }, model: this.opts.model, turn });
+                    await this.opts.hooks.afterLLM({ response: { streamed: true, usage }, model: turnModel, turn });
                 const content = [...blocks.values()].map((b) => b.type === "tool_use" ? { type: "tool_use", id: b.id, name: b.name, input: safeJson(b.json || "{}") } : { type: "text", text: b.text });
                 messages.push({ role: "assistant", content });
                 const uses = content.filter((b) => b.type === "tool_use");
                 if (stopReason !== "tool_use" || uses.length === 0) {
                     const text = content.filter((b) => b.type === "text").map((b) => b.text).join("");
                     yield { type: "usage", usage };
-                    yield { type: "done", result: this.endRun(runStart, text, messages, toolCalls, turns, usage) };
+                    yield { type: "done", result: this.endRun(runStart, lastModel, text, messages, toolCalls, turns, usage) };
                     return;
                 }
                 for (const u of uses)
@@ -997,7 +1083,7 @@ export class Client {
                             toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                             results.push(toolResultBlock(u.id, result));
                             messages.push({ role: "user", content: results });
-                            yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
+                            yield { type: "done", result: this.pendingRun(runStart, lastModel, r.halted, messages, toolCalls, turns, usage) };
                             return;
                         }
                     }
@@ -1007,10 +1093,10 @@ export class Client {
                 }
                 messages.push({ role: "user", content: results });
             }
-            yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage, true) };
+            yield { type: "done", result: this.endRun(runStart, lastModel, "", messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
-            this.emitRunError(runStart, toolCalls, turns, usage, e);
+            this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
             throw e;
         }
     }

package/dist/index.d.ts

@@ -16,3 +16,6 @@ export * from "./toolkit.js";
 export * from "./client.js";
 export * from "./classifier.js";
 export * as agents from "./agents/index.js";
+export * as judge from "./judge.js";
+export * from "./batteries.js";
+export { State, context, questionMap, ask, gate, decide, applyGate, applyPolicy, answersOf, staticClassifier, Tape, DEFAULT_BANDS, type NamedQuestion, type Band, type Bands, type Answers, type Rule, type GateOutcome, type Policy, } from "./judge.js";

package/dist/index.js

@@ -16,3 +16,9 @@ export * from "./toolkit.js";
 export * from "./client.js";
 export * from "./classifier.js";
 export * as agents from "./agents/index.js";
+// Simple judgments (§8B, add-judge-adapters). `judge.noul/choice/score` are the NAMED builders
+// (the bare `noul/choice/score` above stay the §8B wire builders); the rest is also top-level.
+export * as judge from "./judge.js";
+// Judge batteries (§8B "Batteries", add-judge-batteries): eight `*Classifier` values + latestUserText.
+export * from "./batteries.js";
+export { State, context, questionMap, ask, gate, decide, applyGate, applyPolicy, answersOf, staticClassifier, Tape, DEFAULT_BANDS, } from "./judge.js";