toolnexus 0.27.0 → 0.29.0

package/dist/client.js

@@ -1,10 +1,16 @@
+/**
+ * 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 { mediaPartPath } from "./media.js";
 import { pendingOf } from "./types.js";
 import { toOpenAI, toAnthropic } from "./adapters.js";
 import { applyPromptCache } from "./promptcache.js";
 import { buildToolPlan, toolSearch, unwrapCallTool } from "./tooltiers.js";
 import { isRetryableStatus, retryAfterMs } from "./retry.js";
 import { isConcurrencySafe, resolveMaxToolConcurrency, scheduleCalls } from "./toolconcurrency.js";
-import { toOpenAIWire, toAnthropicWire, checkPromptParts } from "./wire.js";
+import { toOpenAIWire, toAnthropicWire, checkPromptParts, modelParts } from "./wire.js";
 import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
 /**
  * The §8 CLIENT status vocabulary, as a value. It is a DIFFERENT, smaller closed set than the
@@ -75,6 +81,35 @@ export async function llmHttpError(res) {
     const body = res.status === 401 || res.status === 403 ? "" : redactErrorBody(raw);
     return new LlmHttpError(res.status, body, res.headers.get("retry-after") ?? undefined);
 }
+/** SPEC §7F.1 markers of a context-overflow rejection (matched lowercased). */
+const OVERFLOW_MARKERS = ["context_length_exceeded", "maximum context length", "prompt is too long", "prompt_too_long", "request_too_large", "context window"];
+/** SPEC §7F.1: true iff `status` is 400/413 AND the (redacted) body names a context overflow. */
+export function isContextOverflow(status, body) {
+    if (status !== 400 && status !== 413)
+        return false;
+    const b = (body ?? "").toLowerCase();
+    return OVERFLOW_MARKERS.some((m) => b.includes(m));
+}
+/** 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 class ContextOverflowError extends Error {
+    compactions;
+    status;
+    body;
+    name = "ContextOverflowError";
+    constructor(
+    /** Reactive compactions in the current rapid chain (3 when the breaker tripped). */
+    compactions, 
+    /** Status of the last provider error. */
+    status, 
+    /** Redacted body of the last provider error (same redaction as `LlmHttpError`). */
+    body) {
+        super(`context overflow: ${compactions} reactive compaction(s) did not make the prompt fit`);
+        this.compactions = compactions;
+        this.status = status;
+        this.body = body;
+    }
+}
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
@@ -110,13 +145,15 @@ function delay(ms, signal) {
 /** Model tool-call id of each record, kept off the record itself (§8 shape has no id). */
 const callIds = new WeakMap();
 /** RunResult.files: every non-text part of every tool call, in call order (§8). */
-function runFiles(toolCalls) {
+export function runFiles(toolCalls) {
     const out = [];
     for (const r of toolCalls) {
         for (const p of r.parts ?? []) {
             if (p.type === "text")
                 continue;
-            out.push({ ...p, from: r.name, callId: callIds.get(r) ?? "" });
+            // D20: a media file's local path rides on the run file, never on the part.
+            const local = mediaPartPath(p);
+            out.push({ ...p, ...(local !== undefined ? { path: local } : {}), from: r.name, callId: callIds.get(r) ?? "" });
         }
     }
     return out;
@@ -424,11 +461,13 @@ export class Client {
             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", turnModel);
+            const r = await this.llmCallJson((m) => [`${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, model: m })),
+                }], signal, "openai", turnModel);
+            const data = r.data;
+            turnModel = r.model;
             if (this.opts.hooks?.afterLLM)
                 await this.opts.hooks.afterLLM({ response: data, model: turnModel, turn: 0 });
             const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
@@ -488,16 +527,18 @@ export class Client {
             body.tool_choice = tc;
         const signal = this.makeSignal(req.signal);
         try {
-            const data = await this.llmCallJson(endpoint, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    "x-api-key": key,
-                    "anthropic-version": "2023-06-01",
-                    ...this.opts.headers,
-                },
-                body: JSON.stringify(this.finalizeBody(body)),
-            }, signal, "anthropic", turnModel);
+            const r = await this.llmCallJson((m) => [endpoint, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        "x-api-key": key,
+                        "anthropic-version": "2023-06-01",
+                        ...this.opts.headers,
+                    },
+                    body: JSON.stringify(this.finalizeBody({ ...body, model: m })),
+                }], signal, "anthropic", turnModel);
+            const data = r.data;
+            turnModel = r.model;
             if (this.opts.hooks?.afterLLM)
                 await this.opts.hooks.afterLLM({ response: data, model: turnModel, turn: 0 });
             const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
@@ -650,7 +691,19 @@ export class Client {
     /** 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). */
-    async llmFetch(url, init, signal) {
+    async llmFetch(url, init, signal, out) {
+        // Same loop as the streaming path; its retry events are simply dropped here.
+        const it = this.llmFetchEvents(url, init, signal, out);
+        for (;;) {
+            const r = await it.next();
+            if (r.done)
+                return r.value;
+        }
+    }
+    /** 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*`. */
+    async *llmFetchEvents(url, init, signal, out) {
         const retries = this.opts.retries ?? 2;
         const base = this.opts.retryBaseMs ?? 500;
         // Default classifier = today's behavior, expressed as an onError. A "retry" is always
@@ -658,17 +711,9 @@ export class Client {
         const classify = this.opts.onError ?? ((info) => (info.retryable ? "retry" : "fail"));
         let lastErr;
         for (let attempt = 0; attempt <= retries; attempt++) {
+            let res;
             try {
-                const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
-                if (res.ok)
-                    return res;
-                const retryable = isRetryableStatus(res.status, this.opts.retryableStatuses);
-                const tier = classify({ status: res.status, attempt, retryable });
-                if (tier === "fail" || attempt === retries)
-                    return res; // caller surfaces the non-ok status
-                const ra = retryAfterMs(res.headers.get("retry-after"));
-                // `?? `, not `|| `: Retry-After: 0 means "retry now", not "no opinion".
-                await delay(ra ?? base * 2 ** attempt + Math.random() * 100, signal);
+                res = await (this.opts.fetch ?? (await defaultFetch()))(url, { ...init, signal });
             }
             catch (e) {
                 if (signal.aborted)
@@ -677,11 +722,78 @@ export class Client {
                 const tier = classify({ error: e, attempt, retryable: true });
                 if (tier === "fail" || attempt === retries)
                     throw e;
-                await delay(base * 2 ** attempt + Math.random() * 100, signal);
+                const wait = base * 2 ** attempt + Math.random() * 100;
+                yield { type: "retry", attempt: attempt + 1, max: retries, delayMs: wait, reason: "network" };
+                await delay(wait, signal);
+                continue;
             }
+            if (res.ok)
+                return res;
+            let retryable = isRetryableStatus(res.status, this.opts.retryableStatuses);
+            // The provider's own verdict wins over the status set (SPEC 8 x-should-retry).
+            const sr = res.headers.get("x-should-retry")?.trim().toLowerCase();
+            if (sr === "true")
+                retryable = true;
+            else if (sr === "false")
+                retryable = false;
+            const tier = classify({ status: res.status, attempt, retryable });
+            if (tier === "fail" || attempt === retries) {
+                if (out)
+                    out.failed = tier === "fail";
+                return res; // caller surfaces the non-ok status
+            }
+            const ra = retryAfterMs(res.headers.get("retry-after"));
+            // `?? `, not `|| `: Retry-After: 0 means "retry now", not "no opinion".
+            const wait = ra ?? base * 2 ** attempt + Math.random() * 100;
+            yield { type: "retry", attempt: attempt + 1, max: retries, delayMs: wait, status: res.status, reason: `HTTP ${res.status}` };
+            await delay(wait, signal);
         }
         throw lastErr;
     }
+    /** §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. */
+    modelChain(turnModel) {
+        const fb = this.opts.fallbackModels;
+        if (!fb || fb.length === 0)
+            return [turnModel];
+        const kill = (typeof process !== "undefined" ? process.env?.TOOLNEXUS_DISABLE_MODEL_FALLBACK : undefined)?.trim().toLowerCase();
+        if (kill === "1" || kill === "true")
+            return [turnModel];
+        const chain = [turnModel];
+        for (const m of fb)
+            if (m && !chain.includes(m))
+                chain.push(m);
+        return chain;
+    }
+    /** 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. */
+    async llmFetchChain(model, build, signal) {
+        const it = this.llmFetchChainEvents(model, build, signal);
+        for (;;) {
+            const r = await it.next();
+            if (r.done)
+                return r.value;
+        }
+    }
+    /** 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. */
+    async *llmFetchChainEvents(model, build, signal) {
+        const chain = this.modelChain(model);
+        for (let i = 0;; i++) {
+            const m = chain[i];
+            const [url, init] = build(m);
+            const out = {};
+            const res = yield* this.llmFetchEvents(url, init, signal, out);
+            if (res.ok || out.failed || i + 1 >= chain.length || (res.status !== 503 && res.status !== 529))
+                return { res, model: m };
+            try {
+                await res.body?.cancel();
+            }
+            catch { /* ignore */ }
+            yield { type: "fallback", from: m, to: chain[i + 1] };
+        }
+    }
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     async runTool(toolkit, name, args, id, turn, signal) {
         if (this.opts.toolTiers && name === "tool_search") {
@@ -818,22 +930,66 @@ 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, model) {
+    async llmCallJson(build, signal, style, turnModel) {
         const t0 = Date.now();
+        let model = turnModel;
         try {
-            const res = await this.llmFetch(url, init, signal);
+            const r = await this.llmFetchChain(turnModel, build, signal);
+            model = r.model;
+            const res = r.res;
             if (!res.ok)
                 throw await llmHttpError(res);
             const data = await res.json();
             const tok = perCall(data.usage, style);
             this.emit({ event: "llm", model, status: "ok", ms: Date.now() - t0, promptTokens: tok.prompt, completionTokens: tok.completion });
-            return data;
+            return { data, model };
         }
         catch (e) {
             this.emit({ event: "llm", model, status: "error", ms: Date.now() - t0, promptTokens: 0, completionTokens: 0 });
             throw e;
         }
     }
+    /**
+     * 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.
+     */
+    async callWithOverflow(st, ev, call) {
+        const it = this.callWithOverflowEvents(st, ev, async function* (m) { return await call(m); });
+        for (;;) {
+            const r = await it.next();
+            if (r.done)
+                return r.value;
+        }
+    }
+    /** `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. */
+    async *callWithOverflowEvents(st, ev, call) {
+        let messages = ev.messages;
+        for (;;) {
+            try {
+                const value = yield* call(messages);
+                st.okSince++;
+                return { value, messages };
+            }
+            catch (e) {
+                const hook = this.opts.compactOnOverflow;
+                if (!hook || !(e instanceof LlmHttpError) || !isContextOverflow(e.status, e.body))
+                    throw e;
+                if (!(st.streak > 0 && st.okSince < 2))
+                    st.streak = 0;
+                if (st.streak === 3)
+                    throw new ContextOverflowError(3, e.status, e.body);
+                const ov = await hook({ messages, tools: ev.tools, model: ev.model, turn: ev.turn });
+                if (!ov?.messages || ov.messages.length >= messages.length)
+                    throw new ContextOverflowError(st.streak, e.status, e.body);
+                messages = ov.messages;
+                st.streak++;
+                st.okSince = 0;
+            }
+        }
+    }
     // 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, onInterrupt) {
@@ -872,6 +1028,42 @@ export class Client {
             this.releaseSignal(signal);
         }
     }
+    /**
+     * §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.
+     */
+    recover(rs, turn, messages, hasCalls, malformed, truncated, text) {
+        if (!rs || turn >= (this.opts.maxTurns ?? 10) - 1)
+            return false;
+        let msg;
+        if (hasCalls) {
+            if (!malformed || rs.corrected)
+                return false;
+            rs.corrected = true;
+            messages.pop();
+            msg = CORRECTIVE;
+        }
+        else if (truncated) {
+            if (rs.continues >= 3)
+                return false;
+            rs.continues++;
+            rs.carry += text;
+            msg = CONTINUE;
+        }
+        else {
+            if (text.trim() !== "" || rs.nudged)
+                return false;
+            rs.nudged = true;
+            messages.pop();
+            msg = NUDGE;
+        }
+        messages.push({ role: "user", content: msg });
+        return true;
+    }
+    newRecovery() {
+        return this.opts.stopRecovery ? { nudged: false, continues: 0, corrected: false, carry: "" } : undefined;
+    }
     // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
     async runOpenAIWithSignal(signal, prompt, toolkit, history, onInterrupt) {
         const key = resolveKey(this.opts);
@@ -891,6 +1083,8 @@ export class Client {
         let lastModel = this.opts.model;
         // Results finished in the current tool phase, by call id — what an interrupted save keeps.
         const done = new Map();
+        const rs = this.newRecovery();
+        const overflow = { okSince: 0, streak: 0 };
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -905,19 +1099,33 @@ export class Client {
                         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, turnModel)),
-                }, signal, "openai", turnModel);
+                const sent = await this.callWithOverflow(overflow, { messages, tools, model: turnModel, turn }, (msgs) => this.llmCallJson((m) => [`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                        method: "POST",
+                        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...this.opts.headers },
+                        body: JSON.stringify(this.openaiBody(msgs, tools, false, m)),
+                    }], signal, "openai", turnModel));
+                messages = sent.messages;
+                const data = sent.value.data;
+                turnModel = lastModel = sent.value.model;
                 addUsage(usage, data.usage, "openai");
                 if (this.opts.hooks?.afterLLM)
                     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, lastModel, msg.content ?? "", messages, toolCalls, turns, usage);
+                if (this.recover(rs, turn, messages, calls.length > 0, calls.some((c) => malformedArgs(c.function?.arguments)), data.choices[0].finish_reason === "length", typeof msg.content === "string" ? msg.content : ""))
+                    continue;
+                if (calls.length === 0) {
+                    const text = (rs?.carry ?? "") + (msg.content ?? "");
+                    if (await this.roundEnd(messages, turn, true, text)) {
+                        if (rs)
+                            rs.carry = "";
+                        continue;
+                    }
+                    return this.endRun(runStart, lastModel, text, messages, toolCalls, turns, usage);
+                }
+                if (rs)
+                    rs.carry = "";
                 // execute all tool calls in this turn concurrently (true parallel tool calling)
                 done.clear();
                 const settled = await untilAborted(signal, this.schedule(toolkit, calls, (call) => [call.function.name, safeJson(call.function.arguments)], async (call) => {
@@ -942,6 +1150,7 @@ export class Client {
                     if (s.halted)
                         return this.pendingRun(runStart, lastModel, s.halted, messages, toolCalls, turns, usage);
                 }
+                await this.roundEnd(messages, turn, false, "");
             }
             return this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true);
         }
@@ -951,6 +1160,24 @@ export class Client {
             throw e;
         }
     }
+    /** §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. */
+    async roundEnd(messages, turn, final, text) {
+        const h = this.opts.hooks?.afterRound;
+        if (!h)
+            return false;
+        if (final && turn + 1 >= (this.opts.maxTurns ?? 10))
+            return false;
+        const out = await h({ turn, final, text, messages });
+        let added = false;
+        for (const m of out?.inject ?? []) {
+            if (typeof m === "string" && m !== "") {
+                messages.push({ role: "user", content: m });
+                added = true;
+            }
+        }
+        return added;
+    }
     result(model, text, messages, toolCalls, turns, usage, exhausted = false) {
         const incomplete = exhausted && text === "";
         const r = { text, messages, toolCalls, files: runFiles(toolCalls), toolCallCount: toolCalls.length, turns, usage, model, status: incomplete ? "incomplete" : "done" };
@@ -1007,6 +1234,8 @@ export class Client {
         let lastModel = this.opts.model;
         // Results finished in the current tool phase, by call id — what an interrupted save keeps.
         const done = new Map();
+        const rs = this.newRecovery();
+        const overflow = { okSince: 0, streak: 0 };
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -1021,29 +1250,42 @@ export class Client {
                         turnModel = ov.model;
                 }
                 lastModel = turnModel;
-                const data = await this.llmCallJson(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, false, turnModel)),
-                }, signal, "anthropic", turnModel);
+                const sent = await this.callWithOverflow(overflow, { messages, tools, model: turnModel, turn }, (msgs) => this.llmCallJson((m) => [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, msgs, tools, false, m)),
+                    }], signal, "anthropic", turnModel));
+                messages = sent.messages;
+                const data = sent.value.data;
+                turnModel = lastModel = sent.value.model;
                 addUsage(usage, data.usage, "anthropic");
                 if (this.opts.hooks?.afterLLM)
                     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");
+                const text = (data.content ?? []).filter((b) => b.type === "text").map((b) => b.text).join("");
+                if (this.recover(rs, turn, messages, uses.length > 0, uses.some((u) => u.input !== undefined && !isObj(u.input)), data.stop_reason === "max_tokens", text))
+                    continue;
                 if (uses.length === 0) {
-                    const text = (data.content ?? []).filter((b) => b.type === "text").map((b) => b.text).join("");
-                    return this.endRun(runStart, lastModel, text, messages, toolCalls, turns, usage);
+                    const full = (rs?.carry ?? "") + text;
+                    if (await this.roundEnd(messages, turn, true, full)) {
+                        if (rs)
+                            rs.carry = "";
+                        continue;
+                    }
+                    return this.endRun(runStart, lastModel, full, messages, toolCalls, turns, usage);
                 }
+                if (rs)
+                    rs.carry = "";
                 // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
                 done.clear();
-                const settled = await untilAborted(signal, this.schedule(toolkit, uses, (use) => [use.name, use.input ?? {}], async (use) => {
-                    let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn, signal);
+                const settled = await untilAborted(signal, this.schedule(toolkit, uses, (use) => [use.name, objArgs(use.input)], async (use) => {
+                    let { args, result } = await this.runTool(toolkit, use.name, objArgs(use.input), use.id, turn, signal);
                     let halted;
                     const req = pendingOf(result);
                     if (req) {
@@ -1071,6 +1313,7 @@ export class Client {
                 messages.push({ role: "user", content });
                 if (halted)
                     return this.pendingRun(runStart, lastModel, halted, messages, toolCalls, turns, usage);
+                await this.roundEnd(messages, turn, false, "");
             }
             return this.endRun(runStart, lastModel, "", messages, toolCalls, turns, usage, true);
         }
@@ -1099,6 +1342,8 @@ export class Client {
         let lastModel = this.opts.model;
         // Results finished in the current tool phase, by call id — what an interrupted save keeps.
         const done = new Map();
+        const rs = this.newRecovery();
+        const overflow = { okSince: 0, streak: 0 };
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -1116,14 +1361,23 @@ export class Client {
                 const t0 = Date.now();
                 const beforeP = usage.promptTokens, beforeC = usage.completionTokens;
                 let content = "";
+                let finish = "";
                 const acc = new Map();
                 try {
-                    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, turnModel)),
-                    }, signal);
-                    if (!res.ok || !res.body)
+                    const sent = yield* this.callWithOverflowEvents(overflow, { messages, tools, model: turnModel, turn }, (msgs) => (async function* (self) {
+                        const r = yield* self.llmFetchChainEvents(turnModel, (m) => [`${self.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                                method: "POST",
+                                headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", ...self.opts.headers },
+                                body: JSON.stringify(self.openaiBody(msgs, tools, true, m)),
+                            }], signal);
+                        if (!r.res.ok || !r.res.body)
+                            throw await llmHttpError(r.res);
+                        return r;
+                    })(this));
+                    messages = sent.messages;
+                    const res = sent.value.res;
+                    turnModel = lastModel = sent.value.model;
+                    if (!res.body)
                         throw await llmHttpError(res);
                     for await (const line of sseLines(res.body)) {
                         if (!line.startsWith("data:"))
@@ -1143,6 +1397,8 @@ export class Client {
                             addUsage(usage, j.usage, "openai");
                         const choice = j?.choices?.[0];
                         const d = choice?.delta;
+                        if (choice?.finish_reason)
+                            finish = choice.finish_reason;
                         if (d?.content) {
                             content += d.content;
                             yield { type: "text", delta: d.content };
@@ -1167,13 +1423,23 @@ export class Client {
                 if (this.opts.hooks?.afterLLM)
                     await this.opts.hooks.afterLLM({ response: { streamed: true, usage }, model: turnModel, turn });
                 const calls = [...acc.values()];
+                messages.push(calls.length === 0
+                    ? { role: "assistant", content }
+                    : { role: "assistant", content: content || null, tool_calls: calls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })) });
+                if (this.recover(rs, turn, messages, calls.length > 0, calls.some((c) => malformedArgs(c.args)), finish === "length", content))
+                    continue;
                 if (calls.length === 0) {
-                    messages.push({ role: "assistant", content });
+                    if (await this.roundEnd(messages, turn, true, (rs?.carry ?? "") + content)) {
+                        if (rs)
+                            rs.carry = "";
+                        continue;
+                    }
                     yield { type: "usage", usage };
-                    yield { type: "done", result: this.endRun(runStart, lastModel, content, messages, toolCalls, turns, usage) };
+                    yield { type: "done", result: this.endRun(runStart, lastModel, (rs?.carry ?? "") + 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 } })) });
+                if (rs)
+                    rs.carry = "";
                 for (const c of calls)
                     yield this.callEvent(c.id, c.name, safeJson(c.args));
                 done.clear();
@@ -1202,6 +1468,7 @@ export class Client {
                     messages.push(toolMessage(c.id, c.name, result));
                     yield this.resultEvent(c.id, c.name, safeJson(c.args), result);
                 }
+                await this.roundEnd(messages, turn, false, "");
             }
             yield { type: "done", result: this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true) };
         }
@@ -1227,6 +1494,8 @@ export class Client {
         let lastModel = this.opts.model;
         // Results finished in the current tool phase, by call id — what an interrupted save keeps.
         const done = new Map();
+        const rs = this.newRecovery();
+        const overflow = { okSince: 0, streak: 0 };
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -1246,12 +1515,20 @@ export class Client {
                 const blocks = new Map();
                 let stopReason = "";
                 try {
-                    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, turnModel)),
-                    }, signal);
-                    if (!res.ok || !res.body)
+                    const sent = yield* this.callWithOverflowEvents(overflow, { messages, tools, model: turnModel, turn }, (msgs) => (async function* (self) {
+                        const r = yield* self.llmFetchChainEvents(turnModel, (m) => [endpoint, {
+                                method: "POST",
+                                headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "Content-Type": "application/json", ...self.opts.headers },
+                                body: JSON.stringify(self.anthropicBody(system, msgs, tools, true, m)),
+                            }], signal);
+                        if (!r.res.ok || !r.res.body)
+                            throw await llmHttpError(r.res);
+                        return r;
+                    })(this));
+                    messages = sent.messages;
+                    const res = sent.value.res;
+                    turnModel = lastModel = sent.value.model;
+                    if (!res.body)
                         throw await llmHttpError(res);
                     for await (const line of sseLines(res.body)) {
                         if (!line.startsWith("data:"))
@@ -1288,12 +1565,22 @@ export class Client {
                 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("");
+                const hasCalls = stopReason === "tool_use" && uses.length > 0;
+                const text = content.filter((b) => b.type === "text").map((b) => b.text).join("");
+                if (this.recover(rs, turn, messages, hasCalls, [...blocks.values()].some((b) => b.type === "tool_use" && malformedArgs(b.json)), stopReason === "max_tokens", text))
+                    continue;
+                if (!hasCalls) {
+                    if (await this.roundEnd(messages, turn, true, (rs?.carry ?? "") + text)) {
+                        if (rs)
+                            rs.carry = "";
+                        continue;
+                    }
                     yield { type: "usage", usage };
-                    yield { type: "done", result: this.endRun(runStart, lastModel, text, messages, toolCalls, turns, usage) };
+                    yield { type: "done", result: this.endRun(runStart, lastModel, (rs?.carry ?? "") + text, messages, toolCalls, turns, usage) };
                     return;
                 }
+                if (rs)
+                    rs.carry = "";
                 for (const u of uses)
                     yield this.callEvent(u.id, u.name, u.input);
                 done.clear();
@@ -1325,6 +1612,7 @@ export class Client {
                     yield this.resultEvent(u.id, u.name, u.input, result);
                 }
                 messages.push({ role: "user", content: results });
+                await this.roundEnd(messages, turn, false, "");
             }
             yield { type: "done", result: this.endRun(runStart, lastModel, "", messages, toolCalls, turns, usage, true) };
         }
@@ -1554,13 +1842,22 @@ function safeParse(s) {
         return undefined;
     }
 }
+const NUDGE = "Your previous response contained no answer. Continue and give your answer.";
+const CONTINUE = "Your previous response was cut off at the output token limit. Continue exactly where it stopped, without repeating anything.";
+const CORRECTIVE = "Your previous tool call could not be used: its arguments were not a valid JSON object. Call the tool again with arguments that are a single valid JSON object matching its input schema.";
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** A raw argument string that is non-empty (trimmed) and not a JSON object (§8). */
+function malformedArgs(s) {
+    return typeof s === "string" && s.trim() !== "" && !isObj(safeParse(s));
+}
+/** Tool-call arguments as an object: anything that is not a JSON object becomes `{}` (§8). */
 function safeJson(s) {
-    try {
-        return JSON.parse(s || "{}");
-    }
-    catch {
-        return {};
-    }
+    return objArgs(safeParse(s || "{}"));
+}
+function objArgs(v) {
+    return isObj(v) ? v : {};
 }
 /**
  * A canonical `tool` turn. With no parts this is byte-identical to the pre-0.17 message;
@@ -1569,17 +1866,19 @@ function safeJson(s) {
  */
 function toolMessage(id, name, result) {
     const m = { role: "tool", tool_call_id: id, content: result.output };
-    if (result.parts?.length) {
+    const parts = modelParts(result);
+    if (parts.length) {
         m.name = name;
-        m.parts = result.parts;
+        m.parts = parts;
     }
     return m;
 }
 /** A canonical Anthropic `tool_result` block; parts ride along and are emitted natively. */
 function toolResultBlock(id, result) {
     const b = { type: "tool_result", tool_use_id: id, content: result.output, is_error: result.isError };
-    if (result.parts?.length)
-        b.parts = result.parts;
+    const parts = modelParts(result);
+    if (parts.length)
+        b.parts = parts;
     return b;
 }
 const INTERRUPTED = { output: "interrupted: the turn ended before this tool returned. Whether its side effects happened is unknown. Do not re-run it automatically; check first.", isError: true };
@@ -1639,3 +1938,19 @@ function lastText(messages) {
     }
     return "";
 }
+/** The default LLM transport. On Node it is the keep-alive `node:http` transport in
+ * `nodefetch.ts` (loaded lazily so this module stays free of `node:` imports for browser
+ * bundles); on Bun, Deno, browsers, or if loading fails, it is the platform `fetch`. A
+ * caller-supplied `fetch` option always wins and never reaches here. */
+const platformFetch = globalThis.fetch;
+let defaultFetchP;
+function defaultFetch() {
+    // A host that replaced the global fetch (a stub, a proxy wrapper) keeps it.
+    if (globalThis.fetch !== platformFetch)
+        return Promise.resolve(globalThis.fetch);
+    const g = globalThis;
+    const onNode = !!g.process?.versions?.node && !g.Bun && !g.Deno;
+    if (!onNode)
+        return Promise.resolve((input, init) => globalThis.fetch(input, init));
+    return (defaultFetchP ??= import("./nodefetch.js").then((m) => m.nodeFetch, () => (input, init) => globalThis.fetch(input, init)));
+}