toolnexus 0.21.0 → 0.22.0

package/dist/client.js

@@ -1,4 +1,7 @@
 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 { toOpenAIWire, toAnthropicWire, checkPromptParts } from "./wire.js";
 import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
@@ -74,13 +77,28 @@ export async function llmHttpError(res) {
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
+    updated = new Map();
     async get(id) {
         const m = this.map.get(id);
         return m ? [...m] : undefined;
     }
     async save(id, messages) {
         this.map.set(id, [...messages]);
+        this.updated.set(id, new Date());
     }
+    /** Every stored conversation, newest first (ties by id ascending). */
+    async list() {
+        return sortEntries([...this.updated].map(([id, updatedAt]) => ({ id, updatedAt })));
+    }
+    /** Remove a conversation; absent ids are not an error. */
+    async delete(id) {
+        this.map.delete(id);
+        this.updated.delete(id);
+    }
+}
+/** @internal Newest first, ties by id ascending (SPEC.md "Conversation memory"). */
+export function sortEntries(entries) {
+    return entries.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime() || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 function delay(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -91,12 +109,19 @@ function delay(ms, signal) {
 function addUsage(acc, raw, style) {
     if (!raw)
         return;
+    const cache = (key, n) => {
+        if (typeof n === "number" && n > 0)
+            acc[key] = (acc[key] ?? 0) + n;
+    };
     if (style === "anthropic") {
         acc.promptTokens += raw.input_tokens ?? 0;
         acc.completionTokens += raw.output_tokens ?? 0;
         acc.totalTokens += (raw.input_tokens ?? 0) + (raw.output_tokens ?? 0);
+        cache("cacheReadTokens", raw.cache_read_input_tokens);
+        cache("cacheWriteTokens", raw.cache_creation_input_tokens);
     }
     else {
+        cache("cacheReadTokens", raw.prompt_tokens_details?.cached_tokens);
         acc.promptTokens += raw.prompt_tokens ?? 0;
         acc.completionTokens += raw.completion_tokens ?? 0;
         acc.totalTokens += raw.total_tokens ?? (raw.prompt_tokens ?? 0) + (raw.completion_tokens ?? 0);
@@ -110,18 +135,45 @@ function perCall(raw, style) {
         return { prompt: raw.input_tokens ?? 0, completion: raw.output_tokens ?? 0 };
     return { prompt: raw.prompt_tokens ?? 0, completion: raw.completion_tokens ?? 0 };
 }
-function resolveKey(opts) {
+/**
+ * Pick the API key (SPEC 4C, security). An explicit `apiKey` is used as-is; else `apiKeyEnv`;
+ * else ONLY the env var that belongs to the `baseUrl` host. There is no cross-provider fallback:
+ * any other host needs `apiKey` or `apiKeyEnv`. The value is never logged.
+ */
+export function resolveKey(opts) {
     if (opts.apiKey)
         return opts.apiKey;
-    const env = process.env;
-    const key = env.OPENROUTER_API_KEY ||
-        (opts.style === "anthropic" ? env.ANTHROPIC_API_KEY : env.OPENAI_API_KEY) ||
-        env.OPENAI_API_KEY ||
-        env.ANTHROPIC_API_KEY;
+    const envName = opts.apiKeyEnv || keyEnvForBaseUrl(opts.baseUrl);
+    if (!envName) {
+        throw new Error(`No API key: set apiKey or apiKeyEnv (provider env vars are only used for https://api.openai.com, https://api.anthropic.com and https://openrouter.ai, never for ${JSON.stringify(opts.baseUrl)})`);
+    }
+    const key = process.env[envName];
     if (!key)
-        throw new Error("No API key: set apiKey or OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY");
+        throw new Error(`No API key: set apiKey or ${envName}`);
     return key;
 }
+/** The env var whose key may be sent to `baseUrl`'s host, or "" when none may. */
+export function keyEnvForBaseUrl(baseUrl) {
+    const h = hostOf(baseUrl);
+    if (h === "api.openai.com")
+        return "OPENAI_API_KEY";
+    if (h === "api.anthropic.com")
+        return "ANTHROPIC_API_KEY";
+    if (h === "openrouter.ai" || h.endsWith(".openrouter.ai"))
+        return "OPENROUTER_API_KEY";
+    return "";
+}
+function hostOf(baseUrl) {
+    try {
+        const u = new URL(baseUrl);
+        if (u.protocol !== "https:")
+            return ""; // a provider key is never sent over plain http
+        return u.hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
 // ---- Prometheus metrics registry (zero-dependency; §8 Observability) ----
 /** FIXED across all ports for byte-parity of `..._duration_seconds` histograms. Seconds. */
 const DURATION_BUCKETS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
@@ -217,6 +269,8 @@ export class Client {
     store;
     /** Cumulative Prometheus registry fed by the same events `onMetric` sees. */
     registry = new MetricsRegistry();
+    /** The frozen ToolTiers plan per toolkit (SPEC 8 Tool tiers). */
+    tierPlans = new WeakMap();
     constructor(opts) {
         this.opts = opts;
         this.store = opts.store ?? new InMemoryConversationStore();
@@ -235,6 +289,8 @@ export class Client {
      * every LLM body-build site so the ordering contract holds identically on all four paths.
      */
     finalizeBody(body) {
+        if (this.opts.promptCache)
+            applyPromptCache(body, this.opts.style, this.opts.promptCache);
         const rp = this.opts.requestParams;
         if (rp) {
             for (const [k, v] of Object.entries(rp)) {
@@ -489,9 +545,24 @@ export class Client {
         }
         if (!ctx?.id)
             return this.run(prompt, { toolkit: ctx?.toolkit, signal: ctx?.signal });
-        const history = (await this.store.get(ctx.id)) ?? [];
-        const result = await this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal, history });
-        await this.store.save(ctx.id, result.messages);
+        checkPromptParts(prompt, this.wireOpts());
+        const id = ctx.id;
+        const history = (await this.store.get(id)) ?? [];
+        // §8: an interrupted turn is saved too — the loop hands back its transcript, repaired.
+        let partial;
+        const onInterrupt = (m) => { partial = m; };
+        let result;
+        try {
+            result = this.opts.style === "anthropic"
+                ? await this.runAnthropic(prompt, ctx.toolkit, ctx.signal, history, onInterrupt)
+                : await this.runOpenAI(prompt, ctx.toolkit, ctx.signal, history, onInterrupt);
+        }
+        catch (e) {
+            if (partial)
+                await this.store.save(id, partial);
+            throw e;
+        }
+        await this.store.save(id, result.messages);
         return result;
     }
     /** A stateful multi-turn conversation that retains history across sends. */
@@ -506,13 +577,23 @@ export class Client {
     async *stream(prompt, ctx) {
         checkPromptParts(prompt, this.wireOpts());
         const history = ctx?.id ? (await this.store.get(ctx.id)) ?? [] : undefined;
+        // §8: with an id, an interrupted stream saves its repaired transcript before the error surfaces.
+        let partial;
+        const onInterrupt = ctx?.id ? (m) => { partial = m; } : undefined;
         const gen = this.opts.style === "anthropic"
-            ? this.streamAnthropic(prompt, ctx?.toolkit, ctx?.signal, history)
-            : this.streamOpenAI(prompt, ctx?.toolkit, ctx?.signal, history);
-        for await (const ev of gen) {
-            if (ev.type === "done" && ctx?.id)
-                await this.store.save(ctx.id, ev.result.messages);
-            yield ev;
+            ? this.streamAnthropic(prompt, ctx?.toolkit, ctx?.signal, history, onInterrupt)
+            : this.streamOpenAI(prompt, ctx?.toolkit, ctx?.signal, history, onInterrupt);
+        try {
+            for await (const ev of gen) {
+                if (ev.type === "done" && ctx?.id)
+                    await this.store.save(ctx.id, ev.result.messages);
+                yield ev;
+            }
+        }
+        catch (e) {
+            if (partial && ctx?.id)
+                await this.store.save(ctx.id, partial);
+            throw e;
         }
     }
     /** §0.10 system message. The toolkit is OPTIONAL — with none there is no skills prompt and
@@ -587,13 +668,32 @@ export class Client {
         throw lastErr;
     }
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
-    async runTool(toolkit, name, args, id, turn) {
+    async runTool(toolkit, name, args, id, turn, signal) {
+        if (this.opts.toolTiers && name === "tool_search") {
+            // Engine-internal and read-only: no hooks (SPEC 8 Tool tiers).
+            const t0 = Date.now();
+            const result = toolSearch(toolkit?.tools() ?? [], (n) => toolkit?.get(n), args ?? {});
+            this.emitTool(name, "builtin", result, t0);
+            return { args, result };
+        }
+        // call_tool is unwrapped HERE, so hooks, hints and permission gates see the real tool. The
+        // returned args keep the wrapper shape (with any beforeTool rewrite inside), so a 10
+        // re-run unwraps the same way.
+        const inner = this.unwrapCall(name, args);
+        if (inner) {
+            const r = await this.runToolDirect(toolkit, inner.name, inner.args, id, turn, signal);
+            return { args: { name: inner.name, arguments: r.args }, result: r.result };
+        }
+        return this.runToolDirect(toolkit, name, args, id, turn, signal);
+    }
+    async runToolDirect(toolkit, name, args, id, turn, signal) {
         const h = this.opts.hooks;
-        const source = toolkit?.get(name)?.source ?? "custom";
+        const tool = toolkit?.get(name);
+        const source = tool?.source ?? "custom";
         const t0 = Date.now();
         let a = args;
         if (h?.beforeTool) {
-            const ov = await h.beforeTool({ name, args: a, id, turn });
+            const ov = await h.beforeTool({ name, args: a, id, turn, ...(tool?.hints ? { hints: tool.hints } : {}) });
             if (ov?.result) {
                 // short-circuit (deny/cache/dry-run, or a guard-raised suspension — path B); still a tool
                 // call for metrics, but a suspension is classified pending, never an error.
@@ -605,7 +705,7 @@ export class Client {
         }
         // No toolkit ⇒ nothing was declared, so a tool call is the provider inventing one.
         let result = toolkit
-            ? await toolkit.execute(name, a)
+            ? await toolkit.execute(name, a, { ...(signal ? { signal } : {}), ...(id ? { callId: id } : {}) })
             : { output: `unknown tool: ${name}`, isError: true };
         // A suspension (§10) is not a real result: skip afterTool's failure path on it — the resolved
         // result (post-waitFor) still flows through afterTool in resolvePending — and never count it as
@@ -618,6 +718,60 @@ export class Client {
         this.emitTool(name, source, result, t0);
         return { args: a, result };
     }
+    /** ToolTiers `call_tool {name, arguments}` -> the real call; undefined when tiers are off. */
+    unwrapCall(name, args) {
+        return this.opts.toolTiers ? unwrapCallTool(name, args) : undefined;
+    }
+    /** The stream's tool_call event, naming the real tool for a `call_tool` call. */
+    callEvent(id, name, args) {
+        const inner = this.unwrapCall(name, args);
+        return inner ? { type: "tool_call", id, name: inner.name, args: inner.args, via: "call_tool" } : { type: "tool_call", id, name, args };
+    }
+    resultEvent(id, name, args, result) {
+        const inner = this.unwrapCall(name, args);
+        return {
+            type: "tool_result", id, name: inner ? inner.name : name, output: result.output, isError: result.isError,
+            ...(result.metadata ? { metadata: result.metadata } : {}),
+            ...(inner ? { via: "call_tool" } : {}),
+        };
+    }
+    plan(toolkit) {
+        if (!this.opts.toolTiers || !toolkit)
+            return undefined;
+        let p = this.tierPlans.get(toolkit);
+        if (!p) {
+            p = buildToolPlan(this.opts.toolTiers, toolkit.tools());
+            this.tierPlans.set(toolkit, p);
+        }
+        return p;
+    }
+    /** The tools array for a request: core tools (sorted) then tool_search and call_tool. Without
+     * tiers it is every tool, as before. */
+    requestTools(toolkit) {
+        if (!toolkit)
+            return [];
+        const p = this.plan(toolkit);
+        if (!p)
+            return toolkit.tools();
+        const out = [];
+        for (const n of p.core) {
+            const t = toolkit.get(n);
+            if (t)
+                out.push(t);
+        }
+        return [...out, p.search, p.call];
+    }
+    /** The frozen tier plan for `toolkit` (built on first use): tool name -> tier. Undefined when
+     * `toolTiers` is not set. For a host UI or log. */
+    toolTierPlan(toolkit) {
+        const p = this.plan(toolkit);
+        return p ? Object.fromEntries(p.tier) : undefined;
+    }
+    /** Forget `toolkit`'s plan so the next request rebuilds it - call at a new session start.
+     * Mid-session it breaks the cached prefix. */
+    resetToolTiers(toolkit) {
+        this.tierPlans.delete(toolkit);
+    }
     /** Emit the `tool` metric, classifying a §10 suspension as `pending` (isError:false), not a failure. */
     emitTool(name, source, result, t0) {
         const req = pendingOf(result);
@@ -642,44 +796,44 @@ export class Client {
     }
     // 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) {
+    async runOpenAI(prompt, toolkit, external, history, onInterrupt) {
         const signal = this.makeSignal(external);
         try {
-            return await this.runOpenAIWithSignal(signal, prompt, toolkit, history);
+            return await this.runOpenAIWithSignal(signal, prompt, toolkit, history, onInterrupt);
         }
         finally {
             this.releaseSignal(signal);
         }
     }
-    async runAnthropic(prompt, toolkit, external, history) {
+    async runAnthropic(prompt, toolkit, external, history, onInterrupt) {
         const signal = this.makeSignal(external);
         try {
-            return await this.runAnthropicWithSignal(signal, prompt, toolkit, history);
+            return await this.runAnthropicWithSignal(signal, prompt, toolkit, history, onInterrupt);
         }
         finally {
             this.releaseSignal(signal);
         }
     }
-    async *streamOpenAI(prompt, toolkit, external, history) {
+    async *streamOpenAI(prompt, toolkit, external, history, onInterrupt) {
         const signal = this.makeSignal(external);
         try {
-            yield* this.streamOpenAIWithSignal(signal, prompt, toolkit, history);
+            yield* this.streamOpenAIWithSignal(signal, prompt, toolkit, history, onInterrupt);
         }
         finally {
             this.releaseSignal(signal);
         }
     }
-    async *streamAnthropic(prompt, toolkit, external, history) {
+    async *streamAnthropic(prompt, toolkit, external, history, onInterrupt) {
         const signal = this.makeSignal(external);
         try {
-            yield* this.streamAnthropicWithSignal(signal, prompt, toolkit, history);
+            yield* this.streamAnthropicWithSignal(signal, prompt, toolkit, history, onInterrupt);
         }
         finally {
             this.releaseSignal(signal);
         }
     }
     // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
-    async runOpenAIWithSignal(signal, prompt, toolkit, history) {
+    async runOpenAIWithSignal(signal, prompt, toolkit, history, onInterrupt) {
         const key = resolveKey(this.opts);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
@@ -689,12 +843,14 @@ export class Client {
                 messages.push({ role: "system", content: system });
         }
         messages.push({ role: "user", content: prompt });
-        let tools = toolkit?.toOpenAI() ?? [];
+        let tools = toOpenAI(this.requestTools(toolkit));
         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;
+        // Results finished in the current tool phase, by call id — what an interrupted save keeps.
+        const done = new Map();
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -723,17 +879,20 @@ export class Client {
                 if (calls.length === 0)
                     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);
+                done.clear();
+                const settled = await untilAborted(signal, Promise.all(calls.map(async (call) => {
+                    let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn, signal);
                     let halted;
                     const req = pendingOf(result);
                     if (req) {
-                        const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn);
+                        const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn, signal);
                         result = r.result;
                         halted = r.halted;
                     }
+                    if (!halted && call.id)
+                        done.set(call.id, result);
                     return { call, args, result, halted };
-                }));
+                })));
                 // Record in tool-call order; on the FIRST durable halt, surface it and stop — deterministic,
                 // and the later suspensions' placeholder results never enter the transcript (they re-suspend
                 // on resume). Mirrors the streaming path.
@@ -748,6 +907,7 @@ export class Client {
         }
         catch (e) {
             this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
+            onInterrupt?.(interruptedTranscript(messages, this.opts.style === "anthropic", done));
             throw e;
         }
     }
@@ -768,15 +928,18 @@ export class Client {
      * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
      * no `waitFor` is configured (the run should stop and surface the request).
      */
-    async resolvePending(toolkit, name, args, request, id, turn) {
+    async resolvePending(toolkit, name, args, request, id, turn, signal) {
+        const inner = this.unwrapCall(name, args);
+        if (inner)
+            ({ name, args } = inner);
         if (!this.opts.waitFor)
             return { result: { output: request.prompt, isError: true }, halted: request };
-        const answer = await this.opts.waitFor(request);
+        const answer = await this.opts.waitFor(request, { signal: signal ?? new AbortController().signal });
         if (!answer?.ok)
             return { result: { output: `declined/expired: ${request.prompt}`, isError: true } };
         const t0 = Date.now();
         let result = toolkit
-            ? await toolkit.execute(name, args, { answer })
+            ? await toolkit.execute(name, args, { answer, ...(signal ? { signal } : {}), ...(id ? { callId: id } : {}) })
             : { output: `unknown tool: ${name}`, isError: true };
         if (this.opts.hooks?.afterTool) {
             const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn });
@@ -789,19 +952,21 @@ export class Client {
         return { result };
     }
     // ---- Anthropic-style: POST {baseUrl}/messages ----
-    async runAnthropicWithSignal(signal, prompt, toolkit, history) {
+    async runAnthropicWithSignal(signal, prompt, toolkit, history, onInterrupt) {
         const key = resolveKey(this.opts);
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
         const system = this.system(toolkit);
         const runStart = Date.now();
         let messages = history && history.length ? [...history, { role: "user", content: prompt }] : [{ role: "user", content: prompt }];
-        let tools = toolkit?.toAnthropic() ?? [];
+        let tools = toAnthropic(this.requestTools(toolkit));
         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;
+        // Results finished in the current tool phase, by call id — what an interrupted save keeps.
+        const done = new Map();
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -836,17 +1001,20 @@ export class Client {
                     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) => {
-                    let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn);
+                done.clear();
+                const settled = await untilAborted(signal, Promise.all(uses.map(async (use) => {
+                    let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn, signal);
                     let halted;
                     const req = pendingOf(result);
                     if (req) {
-                        const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn);
+                        const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn, signal);
                         result = r.result;
                         halted = r.halted;
                     }
+                    if (!halted && use.id)
+                        done.set(use.id, result);
                     return { use, args, result, halted };
-                }));
+                })));
                 // Record in tool-call order; on the FIRST durable halt, include that tool_result block, stop
                 // building the content, and surface it — deterministic (G3), later suspensions re-suspend on
                 // resume. Mirrors the OpenAI path and the streaming loops.
@@ -868,11 +1036,12 @@ export class Client {
         }
         catch (e) {
             this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
+            onInterrupt?.(interruptedTranscript(messages, this.opts.style === "anthropic", done));
             throw e;
         }
     }
     // ---- Streaming: OpenAI-style ----
-    async *streamOpenAIWithSignal(signal, prompt, toolkit, history) {
+    async *streamOpenAIWithSignal(signal, prompt, toolkit, history, onInterrupt) {
         const key = resolveKey(this.opts);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
@@ -882,12 +1051,14 @@ export class Client {
                 messages.push({ role: "system", content: system });
         }
         messages.push({ role: "user", content: prompt });
-        let tools = toolkit?.toOpenAI() ?? [];
+        let tools = toOpenAI(this.requestTools(toolkit));
         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;
+        // Results finished in the current tool phase, by call id — what an interrupted save keeps.
+        const done = new Map();
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -957,15 +1128,21 @@ export class Client {
                 }
                 messages.push({ role: "assistant", content: content || null, tool_calls: calls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })) });
                 for (const c of calls)
-                    yield { type: "tool_call", id: c.id, name: c.name, args: safeJson(c.args) };
-                const settled = await Promise.all(calls.map((c) => this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn)));
+                    yield this.callEvent(c.id, c.name, safeJson(c.args));
+                done.clear();
+                const settled = await untilAborted(signal, Promise.all(calls.map(async (c) => {
+                    const r = await this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn, signal);
+                    if (!pendingOf(r.result) && c.id)
+                        done.set(c.id, r.result);
+                    return r;
+                })));
                 for (let i = 0; i < calls.length; i++) {
                     const c = calls[i];
                     let { args, result } = settled[i];
                     const req = pendingOf(result);
                     if (req) {
                         yield { type: "pending", request: req }; // surface BEFORE waitFor so a channel can push the link
-                        const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn);
+                        const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn, signal);
                         result = r.result;
                         if (r.halted) {
                             toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
@@ -976,30 +1153,33 @@ export class Client {
                     }
                     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: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
+                    yield this.resultEvent(c.id, c.name, safeJson(c.args), result);
                 }
             }
             yield { type: "done", result: this.endRun(runStart, lastModel, lastText(messages), messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
             this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
+            onInterrupt?.(interruptedTranscript(messages, this.opts.style === "anthropic", done));
             throw e;
         }
     }
     // ---- Streaming: Anthropic-style ----
-    async *streamAnthropicWithSignal(signal, prompt, toolkit, history) {
+    async *streamAnthropicWithSignal(signal, prompt, toolkit, history, onInterrupt) {
         const key = resolveKey(this.opts);
         const runStart = Date.now();
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
         const system = this.system(toolkit);
         let messages = history && history.length ? [...history, { role: "user", content: prompt }] : [{ role: "user", content: prompt }];
-        let tools = toolkit?.toAnthropic() ?? [];
+        let tools = toAnthropic(this.requestTools(toolkit));
         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;
+        // Results finished in the current tool phase, by call id — what an interrupted save keeps.
+        const done = new Map();
         try {
             for (let turn = 0; turn < (this.opts.maxTurns ?? 10); turn++) {
                 turns++;
@@ -1068,8 +1248,14 @@ export class Client {
                     return;
                 }
                 for (const u of uses)
-                    yield { type: "tool_call", id: u.id, name: u.name, args: u.input };
-                const settled = await Promise.all(uses.map((u) => this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn)));
+                    yield this.callEvent(u.id, u.name, u.input);
+                done.clear();
+                const settled = await untilAborted(signal, Promise.all(uses.map(async (u) => {
+                    const r = await this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn, signal);
+                    if (!pendingOf(r.result) && u.id)
+                        done.set(u.id, r.result);
+                    return r;
+                })));
                 const results = [];
                 for (let i = 0; i < uses.length; i++) {
                     const u = uses[i];
@@ -1077,7 +1263,7 @@ export class Client {
                     const req = pendingOf(result);
                     if (req) {
                         yield { type: "pending", request: req };
-                        const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn);
+                        const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn, signal);
                         result = r.result;
                         if (r.halted) {
                             toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
@@ -1089,7 +1275,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));
-                    yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError };
+                    yield this.resultEvent(u.id, u.name, u.input, result);
                 }
                 messages.push({ role: "user", content: results });
             }
@@ -1097,6 +1283,7 @@ export class Client {
         }
         catch (e) {
             this.emitRunError(runStart, lastModel, toolCalls, turns, usage, e);
+            onInterrupt?.(interruptedTranscript(messages, this.opts.style === "anthropic", done));
             throw e;
         }
     }
@@ -1276,6 +1463,56 @@ function toolResultBlock(id, result) {
         b.parts = result.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 };
+/** Settle with `p`, or reject with the abort reason as soon as `signal` aborts. */
+function untilAborted(signal, p) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason ?? new Error("aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then((v) => { signal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { signal.removeEventListener("abort", onAbort); reject(e); });
+    });
+}
+/**
+ * §8 "Interrupted turns are saved": a copy of `messages` in which every tool call of the LAST
+ * assistant message has a result — the finished one from `done`, else `interrupted` (isError) —
+ * in the dialect's own shape, so the saved transcript replays on either API.
+ */
+function interruptedTranscript(messages, anthropic, done) {
+    const out = [...messages];
+    let ai = -1;
+    for (let i = out.length - 1; i >= 0; i--)
+        if (out[i]?.role === "assistant") {
+            ai = i;
+            break;
+        }
+    if (ai < 0)
+        return out;
+    const resultFor = (id) => done.get(id) ?? INTERRUPTED;
+    if (!anthropic) {
+        const calls = out[ai].tool_calls ?? [];
+        const have = new Set(out.slice(ai + 1).filter((m) => m?.role === "tool").map((m) => m.tool_call_id));
+        for (const c of calls)
+            if (!have.has(c.id))
+                out.push(toolMessage(c.id, c.function?.name ?? "", resultFor(c.id)));
+        return out;
+    }
+    const uses = Array.isArray(out[ai].content) ? out[ai].content.filter((b) => b?.type === "tool_use") : [];
+    if (!uses.length)
+        return out;
+    const next = out[ai + 1];
+    const blocks = next?.role === "user" && Array.isArray(next.content) ? [...next.content] : [];
+    const have = new Set(blocks.filter((b) => b?.type === "tool_result").map((b) => b.tool_use_id));
+    for (const u of uses)
+        if (!have.has(u.id))
+            blocks.push(toolResultBlock(u.id, resultFor(u.id)));
+    if (next?.role === "user" && Array.isArray(next.content))
+        out[ai + 1] = { ...next, content: blocks };
+    else
+        out.splice(ai + 1, 0, { role: "user", content: blocks });
+    return out;
+}
 function lastText(messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
         if (messages[i].role === "assistant" && typeof messages[i].content === "string")

package/dist/index.d.ts

@@ -14,8 +14,13 @@ export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * from "./store.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";
+export * from "./promptcache.js";
+export * from "./tooltiers.js";
+export * from "./models.js";
+export * from "./builtin_extras.js";