@qvac/sdk 0.9.1 → 0.10.0

package/NOTICE

@@ -83,46 +83,6 @@ Third-Party Model Licenses
     https://huggingface.co/personalizedrefrigerator/whisper-base-fr
   fr-tiny-ggml-model-f16
     https://huggingface.co/JaepaX/whisper-tiny-fr
-  ggml-opus-ar-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-ar-en
-  ggml-opus-de-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-de-en
-  ggml-opus-de-fr
-    https://huggingface.co/Helsinki-NLP/opus-mt-de-fr
-  ggml-opus-en-ar
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-ar
-  ggml-opus-en-es
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-es
-  ggml-opus-en-fr
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-fr
-  ggml-opus-en-it
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-it
-  ggml-opus-en-roa
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-roa
-  ggml-opus-en-ru
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-ru
-  ggml-opus-en-zh
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-zh
-  ggml-opus-es-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-es-en
-  ggml-opus-es-fr
-    https://huggingface.co/Helsinki-NLP/opus-mt-es-fr
-  ggml-opus-fr-de
-    https://huggingface.co/Helsinki-NLP/opus-mt-fr-de
-  ggml-opus-fr-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-fr-en
-  ggml-opus-fr-es
-    https://huggingface.co/Helsinki-NLP/opus-mt-fr-es
-  ggml-opus-it-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-it-en
-  ggml-opus-ja-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-ja-en
-  ggml-opus-mt-en-roa-f16
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-roa
-  ggml-opus-mt-roa-en-f16
-    https://huggingface.co/Helsinki-NLP/opus-mt-roa-en
-  ggml-opus-roa-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-roa-en
   gpt-oss-120b-Q4_K_M-00001-of-00002
     https://huggingface.co/unsloth/gpt-oss-120b-GGUF
   gpt-oss-20b-GGUF
@@ -216,14 +176,6 @@ Third-Party Model Licenses
     https://huggingface.co/nasedkinpv/parakeet-tdt-0.6b-v3-onnx-int8
   encoder-model
     https://huggingface.co/istupakov/parakeet-tdt-0.6b-v3-onnx
-  ggml-opus-en-de
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-de
-  ggml-opus-en-pt
-    https://huggingface.co/Helsinki-NLP/opus-mt-tc-big-en-pt
-  ggml-opus-ru-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-ru-en
-  ggml-opus-zh-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-zh-en
   parakeet-ctc-0.6b-ONNX
     https://huggingface.co/onnx-community/parakeet-ctc-0.6b-ONNX
   parakeet-rs
@@ -376,7 +328,7 @@ Third-Party Model Licenses
   model.enis.intgemm.alphas
     https://github.com/mozilla/firefox-translations-models/tree/main/models/base-memory/enis
   model.enit.intgemm.alphas
-    https://github.com/mozilla/firefox-translations-models/tree/main/models/tiny/enit
+    https://github.com/mozilla/firefox-translations-models/tree/main/models/base-memory/enit
   model.enja.intgemm.alphas
     https://github.com/mozilla/firefox-translations-models/tree/main/models/base-memory/enja
   model.enkn.intgemm.alphas
@@ -420,7 +372,7 @@ Third-Party Model Licenses
   model.enzh.intgemm.alphas
     https://github.com/mozilla/firefox-translations-models/tree/main/models/base-memory/enzh
   model.esen.intgemm.alphas
-    https://github.com/mozilla/firefox-translations-models/tree/main/models/tiny/esen
+    https://github.com/mozilla/firefox-translations-models/tree/main/models/base-memory/esen
   model.eten.intgemm.alphas
     https://github.com/mozilla/firefox-translations-models/tree/main/models/base-memory/eten
   model.faen.intgemm.alphas
@@ -542,26 +494,21 @@ JavaScript Dependencies
   @qvac/decoder-audio@0.3.7
     https://github.com/tetherto/qvac
   @qvac/diagnostics@0.1.1
-  @qvac/diffusion-cpp@0.1.3
+  @qvac/diffusion-cpp@0.3.0
     https://github.com/tetherto/qvac
-  @qvac/dl-base@0.2.1
-    https://github.com/tetherto/qvac
-  @qvac/dl-filesystem@0.2.1
-    https://github.com/tetherto/qvac
-  @qvac/dl-hyperdrive@0.2.1
-    https://github.com/tetherto/qvac
-  @qvac/embed-llamacpp@0.13.4
+  @qvac/dl-base@0.1.1
+  @qvac/dl-hyperdrive@0.1.1
+  @qvac/embed-llamacpp@0.14.0
     https://github.com/tetherto/qvac
   @qvac/error@0.1.1
   @qvac/infer-base@0.1.1
-  @qvac/infer-base@0.2.2
-  @qvac/infer-base@0.3.1
-    https://github.com/tetherto/qvac
   @qvac/infer-base@0.4.0
     https://github.com/tetherto/qvac
+  @qvac/infer-base@0.4.1
+    https://github.com/tetherto/qvac
   @qvac/langdetect-text@0.1.2
     https://github.com/tetherto/qvac
-  @qvac/llm-llamacpp@0.14.4
+  @qvac/llm-llamacpp@0.17.3
     https://github.com/tetherto/qvac
   @qvac/logging@0.1.0
   @qvac/ocr-onnx@0.4.2
@@ -570,7 +517,7 @@ JavaScript Dependencies
     https://github.com/tetherto/qvac
   @qvac/rag@0.4.4
     https://github.com/tetherto/qvac
-  @qvac/registry-client@0.4.0
+  @qvac/registry-client@0.4.1
     https://github.com/tetherto/qvac
   @qvac/registry-schema@0.1.2
   @qvac/response@0.1.2
@@ -578,9 +525,9 @@ JavaScript Dependencies
     https://github.com/tetherto/qvac
   @qvac/transcription-whispercpp@0.6.1
     https://github.com/tetherto/qvac
-  @qvac/translation-nmtcpp@0.6.10
-    https://github.com/tetherto/qvac-lib-infer-nmtcpp
-  @qvac/tts-onnx@0.8.2
+  @qvac/translation-nmtcpp@2.1.0
+    https://github.com/tetherto/qvac
+  @qvac/tts-onnx@0.8.5
     https://github.com/tetherto/qvac
   adaptive-timeout@1.0.1
     https://github.com/holepunchto/adaptive-timeout
@@ -630,9 +577,9 @@ JavaScript Dependencies
     https://github.com/holepunchto/bare-https
   bare-inspect@3.1.4
     https://github.com/holepunchto/bare-inspect
-  bare-lief@0.1.6
+  bare-lief@0.2.3
     https://github.com/holepunchto/bare-lief
-  bare-link@2.1.10
+  bare-link@3.2.1
     https://github.com/holepunchto/bare-link
   bare-module@6.1.3
     https://github.com/holepunchto/bare-module

package/dist/client/api/cancel.d.ts

@@ -28,7 +28,7 @@ import { type CancelParams } from "../../schemas/index";
  * await cancel({
  *   operation: "downloadAsset",
  *   downloadKey: "download-key",
- *   delegate: { topic: "topicHex", providerPublicKey: "peerHex" },
+ *   delegate: { providerPublicKey: "peerHex" },
  * });
  *
  * @example

package/dist/client/api/cancel.js

@@ -30,7 +30,7 @@ import { InvalidResponseError, CancelFailedError } from "../../utils/errors-clie
  * await cancel({
  *   operation: "downloadAsset",
  *   downloadKey: "download-key",
- *   delegate: { topic: "topicHex", providerPublicKey: "peerHex" },
+ *   delegate: { providerPublicKey: "peerHex" },
  * });
  *
  * @example

package/dist/client/api/completion-stream.d.ts

@@ -1,19 +1,50 @@
-import { type CompletionClientParams, type CompletionStats, type McpClientInput, type Tool, type ToolCallEvent, type ToolCallWithCall, type RPCOptions } from "../../schemas/index";
+import { type CompletionClientParams, type CompletionRun, type McpClientInput, type Tool, type RPCOptions } from "../../schemas/index";
 import { type ToolInput } from "../../utils/tool-helpers";
 type CompletionParams = Omit<CompletionClientParams, "tools"> & {
     tools?: Tool[] | ToolInput[];
     mcp?: McpClientInput[];
     rpcOptions?: RPCOptions;
+    captureThinking?: boolean;
+    emitRawDeltas?: boolean;
 };
 /**
  * Generates completion from a language model based on conversation history.
  *
+ * Returns a `CompletionRun` whose canonical surfaces are:
+ *
+ *  - `events`  — `AsyncIterable<CompletionEvent>` of ordered, typed events.
+ *  - `final`   — `Promise<CompletionFinal>` with aggregated results once the
+ *                stream ends (content, thinking, tool calls, stats, raw text).
+ *
+ * Legacy convenience fields (`tokenStream`, `text`, `toolCallStream`,
+ * `toolCalls`, `stats`) are still available but deprecated — they derive
+ * from `events` / `final` internally.
+ *
  * @param params - The completion parameters
  * @param params.modelId - The identifier of the model to use for completion
  * @param params.history - Array of conversation messages with role, content, and optional attachments
  * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true
  * @param params.tools - Optional array of tools (can be simple ToolInput with Zod schemas or full Tool objects)
  * @param params.mcp - Optional array of MCP client inputs for tool integration
+ * @param params.captureThinking - Best-effort parsing of `<think>` blocks into `thinkingDelta` events; `final.raw.fullText` always preserves the original output
+ * @param params.emitRawDeltas - When true, every raw model token is also emitted as a `rawDelta` event
+ * @param params.toolDialect - Override the SDK's name-based dialect detection. Use when your model emits a known format (`"hermes"`, `"pythonic"`, or `"json"`) the auto-router doesn't recognise. Drives both streaming frame detection and finalization parsing.
+ * Common override case: Llama 3.x tool-calling fine-tunes that emit the native pythonic header (`<|start_header_id|>tool_call<|end_header_id|>...<|eot_id|>`).
+ * @param params.responseFormat - Optional structured-output constraint applied to the model's output:
+ *   - `{ type: "text" }` — no constraint (default behavior)
+ *   - `{ type: "json_object" }` — output must be a JSON object
+ *   - `{ type: "json_schema", json_schema: { name, schema, description?, strict? } }` — output must validate against `schema`
+ *
+ *   The schema is converted to GBNF natively by llama.cpp and applied for the
+ *   duration of the request only. `json_schema.name` and `json_schema.description`
+ *   are accepted for OpenAI compatibility but only used at the API boundary —
+ *   they do not affect generation. **`json_schema.strict` is currently accepted
+ *   for compatibility but does NOT trigger OpenAI's auto-tightening semantics**
+ *   (implicit `additionalProperties: false`, all properties required). The
+ *   schema is forwarded to the addon as-is, so callers who want strict
+ *   validation must encode it explicitly in `schema`.
+ *
+ *   Cannot be combined with `tools` (tools already constrain output via their parameter schema).
  * @param params.kvCache - Optional KV cache configuration. Cache files are organized hierarchically:
  *   - Structure: `{kvCacheKey}/{modelId}/{configHash}.bin`
  *   - The configHash includes model config + system prompt to ensure cache isolation
@@ -22,17 +53,29 @@ type CompletionParams = Omit<CompletionClientParams, "tools"> & {
  *   - `false` or `undefined`: No caching
  *   - ⚡ Performance: When cache exists, only the last message is sent to the model (includes multimodal attachments)
  *   - 🗑️ Cleanup: Use `deleteCache({ kvCacheKey })` to remove cached sessions
- * @returns Object with tokenStream generator, toolCallStream generator, text promise, toolCalls promise (with call() method), and stats promise
+ *
+ *   **Auto-cache (`kvCache: true`) — assistant turn contract.** When
+ *   pushing the assistant turn back into `history` for the next call,
+ *   use `(await run.final).cacheableAssistantContent`. That's the exact
+ *   string the SDK persisted to the cache key on this turn, so re-using
+ *   it verbatim guarantees the next-turn lookup hits.
+ *   - Any post-processing of the assistant text (rewriting, summarizing,
+ *     stripping model stop tokens like `<|im_end|>`) before pushing it
+ *     back will miss the cache. Push the canonical string unchanged.
+ *   - `cacheableAssistantContent` is omitted on tool-call turns - those
+ *     can't be auto-cached today.
+ * @returns A CompletionRun — consume via `events` / `final`.
  * @example
  * ```typescript
  * import { z } from "zod";
  *
- * const result = completion({
+ * const run = completion({
  *   modelId: "llama-2",
  *   history: [
  *     { role: "user", content: "What's the weather in Tokyo?" }
  *   ],
  *   stream: true,
+ *   captureThinking: true,
  *   tools: [{
  *     name: "get_weather",
  *     description: "Get current weather",
@@ -45,10 +88,12 @@ type CompletionParams = Omit<CompletionClientParams, "tools"> & {
  *   }]
  * });
  *
- * for await (const token of result.tokenStream) {
- *   process.stdout.write(token);
+ * for await (const event of run.events) {
+ *   if (event.type === "contentDelta") process.stdout.write(event.text);
+ *   if (event.type === "toolCall") console.log(event.call.name, event.call.arguments);
  * }
  *
+ * const result = await run.final;
  * for (const toolCall of await result.toolCalls) {
  *   if (toolCall.invoke) {
  *     const toolResult = await toolCall.invoke();
@@ -57,12 +102,6 @@ type CompletionParams = Omit<CompletionClientParams, "tools"> & {
  * }
  * ```
  */
-export declare function completion(params: CompletionParams): {
-    tokenStream: AsyncGenerator<string>;
-    toolCallStream: AsyncGenerator<ToolCallEvent>;
-    stats: Promise<CompletionStats | undefined>;
-    text: Promise<string>;
-    toolCalls: Promise<ToolCallWithCall[]>;
-};
+export declare function completion(params: CompletionParams): CompletionRun;
 export {};
 //# sourceMappingURL=completion-stream.d.ts.map

package/dist/client/api/completion-stream.js

@@ -1,18 +1,49 @@
 import { stream as streamRpc } from "../rpc/rpc-client.js";
 import { getClientLogger } from "../../logging/index.js";
 import { completionStreamResponseSchema, } from "../../schemas/index.js";
+import { CompletionFailedError } from "../../utils/errors-server.js";
 import { getMcpToolsWithHandlers } from "../../utils/mcp-adapter.js";
-import { attachHandlersToToolCalls, validateTools, } from "../../utils/tool-helpers.js";
+import { validateTools, } from "../../utils/tool-helpers.js";
+import { buildFinalFromEvents } from "../../utils/aggregate-events.js";
 const logger = getClientLogger();
 /**
  * Generates completion from a language model based on conversation history.
  *
+ * Returns a `CompletionRun` whose canonical surfaces are:
+ *
+ *  - `events`  — `AsyncIterable<CompletionEvent>` of ordered, typed events.
+ *  - `final`   — `Promise<CompletionFinal>` with aggregated results once the
+ *                stream ends (content, thinking, tool calls, stats, raw text).
+ *
+ * Legacy convenience fields (`tokenStream`, `text`, `toolCallStream`,
+ * `toolCalls`, `stats`) are still available but deprecated — they derive
+ * from `events` / `final` internally.
+ *
  * @param params - The completion parameters
  * @param params.modelId - The identifier of the model to use for completion
  * @param params.history - Array of conversation messages with role, content, and optional attachments
  * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true
  * @param params.tools - Optional array of tools (can be simple ToolInput with Zod schemas or full Tool objects)
  * @param params.mcp - Optional array of MCP client inputs for tool integration
+ * @param params.captureThinking - Best-effort parsing of `<think>` blocks into `thinkingDelta` events; `final.raw.fullText` always preserves the original output
+ * @param params.emitRawDeltas - When true, every raw model token is also emitted as a `rawDelta` event
+ * @param params.toolDialect - Override the SDK's name-based dialect detection. Use when your model emits a known format (`"hermes"`, `"pythonic"`, or `"json"`) the auto-router doesn't recognise. Drives both streaming frame detection and finalization parsing.
+ * Common override case: Llama 3.x tool-calling fine-tunes that emit the native pythonic header (`<|start_header_id|>tool_call<|end_header_id|>...<|eot_id|>`).
+ * @param params.responseFormat - Optional structured-output constraint applied to the model's output:
+ *   - `{ type: "text" }` — no constraint (default behavior)
+ *   - `{ type: "json_object" }` — output must be a JSON object
+ *   - `{ type: "json_schema", json_schema: { name, schema, description?, strict? } }` — output must validate against `schema`
+ *
+ *   The schema is converted to GBNF natively by llama.cpp and applied for the
+ *   duration of the request only. `json_schema.name` and `json_schema.description`
+ *   are accepted for OpenAI compatibility but only used at the API boundary —
+ *   they do not affect generation. **`json_schema.strict` is currently accepted
+ *   for compatibility but does NOT trigger OpenAI's auto-tightening semantics**
+ *   (implicit `additionalProperties: false`, all properties required). The
+ *   schema is forwarded to the addon as-is, so callers who want strict
+ *   validation must encode it explicitly in `schema`.
+ *
+ *   Cannot be combined with `tools` (tools already constrain output via their parameter schema).
  * @param params.kvCache - Optional KV cache configuration. Cache files are organized hierarchically:
  *   - Structure: `{kvCacheKey}/{modelId}/{configHash}.bin`
  *   - The configHash includes model config + system prompt to ensure cache isolation
@@ -21,17 +52,29 @@ const logger = getClientLogger();
  *   - `false` or `undefined`: No caching
  *   - ⚡ Performance: When cache exists, only the last message is sent to the model (includes multimodal attachments)
  *   - 🗑️ Cleanup: Use `deleteCache({ kvCacheKey })` to remove cached sessions
- * @returns Object with tokenStream generator, toolCallStream generator, text promise, toolCalls promise (with call() method), and stats promise
+ *
+ *   **Auto-cache (`kvCache: true`) — assistant turn contract.** When
+ *   pushing the assistant turn back into `history` for the next call,
+ *   use `(await run.final).cacheableAssistantContent`. That's the exact
+ *   string the SDK persisted to the cache key on this turn, so re-using
+ *   it verbatim guarantees the next-turn lookup hits.
+ *   - Any post-processing of the assistant text (rewriting, summarizing,
+ *     stripping model stop tokens like `<|im_end|>`) before pushing it
+ *     back will miss the cache. Push the canonical string unchanged.
+ *   - `cacheableAssistantContent` is omitted on tool-call turns - those
+ *     can't be auto-cached today.
+ * @returns A CompletionRun — consume via `events` / `final`.
  * @example
  * ```typescript
  * import { z } from "zod";
  *
- * const result = completion({
+ * const run = completion({
  *   modelId: "llama-2",
  *   history: [
  *     { role: "user", content: "What's the weather in Tokyo?" }
  *   ],
  *   stream: true,
+ *   captureThinking: true,
  *   tools: [{
  *     name: "get_weather",
  *     description: "Get current weather",
@@ -44,10 +87,12 @@ const logger = getClientLogger();
  *   }]
  * });
  *
- * for await (const token of result.tokenStream) {
- *   process.stdout.write(token);
+ * for await (const event of run.events) {
+ *   if (event.type === "contentDelta") process.stdout.write(event.text);
+ *   if (event.type === "toolCall") console.log(event.call.name, event.call.arguments);
  * }
  *
+ * const result = await run.final;
  * for (const toolCall of await result.toolCalls) {
  *   if (toolCall.invoke) {
  *     const toolResult = await toolCall.invoke();
@@ -57,7 +102,6 @@ const logger = getClientLogger();
  * ```
  */
 export function completion(params) {
-    let stats;
     let statsResolver = () => { };
     let statsRejecter = () => { };
     const statsPromise = new Promise((resolve, reject) => {
@@ -65,7 +109,6 @@ export function completion(params) {
         statsRejecter = reject;
     });
     statsPromise.catch(() => { });
-    let toolCallsArray = [];
     let toolCallsResolver = () => { };
     let toolCallsRejecter = () => { };
     const toolCallsPromise = new Promise((resolve, reject) => {
@@ -73,14 +116,36 @@ export function completion(params) {
         toolCallsRejecter = reject;
     });
     toolCallsPromise.catch(() => { });
+    let finalResolver = () => { };
+    let finalRejecter = () => { };
+    const finalPromise = new Promise((resolve, reject) => {
+        finalResolver = resolve;
+        finalRejecter = reject;
+    });
+    finalPromise.catch(() => { });
     const tokenQueue = [];
     const toolEventQueue = [];
-    let tokenDone = false;
-    let toolDone = false;
+    const eventQueue = [];
+    let done = false;
     let tokenResolve = null;
     let toolResolve = null;
-    let textBuffer = "";
+    let eventResolve = null;
     let streamError = null;
+    const allEvents = [];
+    function notifyWaiters() {
+        if (tokenResolve) {
+            tokenResolve();
+            tokenResolve = null;
+        }
+        if (toolResolve) {
+            toolResolve();
+            toolResolve = null;
+        }
+        if (eventResolve) {
+            eventResolve();
+            eventResolve = null;
+        }
+    }
     const processResponses = async () => {
         try {
             let allTools = [];
@@ -113,6 +178,10 @@ export function completion(params) {
                 tools: allTools.length > 0 ? allTools : undefined,
                 stream: params.stream ?? true,
                 generationParams: params.generationParams,
+                captureThinking: params.captureThinking,
+                emitRawDeltas: params.emitRawDeltas,
+                toolDialect: params.toolDialect,
+                responseFormat: params.responseFormat,
             };
             const responses = streamRpc(request, params.rpcOptions);
             for await (const response of responses) {
@@ -121,43 +190,32 @@ export function completion(params) {
                     "type" in response &&
                     response.type === "completionStream") {
                     const streamResponse = completionStreamResponseSchema.parse(response);
-                    if (!streamResponse.done) {
-                        const token = streamResponse.token;
-                        if (token) {
-                            textBuffer += token;
-                            tokenQueue.push(token);
-                            if (tokenResolve) {
-                                tokenResolve();
-                                tokenResolve = null;
-                            }
+                    for (const event of streamResponse.events) {
+                        allEvents.push(event);
+                        eventQueue.push(event);
+                        if (event.type === "contentDelta") {
+                            tokenQueue.push(event.text);
                         }
-                        if (streamResponse.toolCallEvent) {
-                            toolEventQueue.push(streamResponse.toolCallEvent);
-                            if (toolResolve) {
-                                toolResolve();
-                                toolResolve = null;
-                            }
+                        else if (event.type === "toolCall") {
+                            toolEventQueue.push(event);
                         }
                     }
-                    else {
-                        if (streamResponse.token) {
-                            textBuffer += streamResponse.token;
-                        }
-                        stats = streamResponse.stats;
-                        statsResolver(stats);
-                        const rawToolCalls = streamResponse.toolCalls || [];
-                        toolCallsArray = attachHandlersToToolCalls(rawToolCalls, allHandlers);
-                        toolCallsResolver(toolCallsArray);
-                        tokenDone = true;
-                        toolDone = true;
-                        if (tokenResolve) {
-                            tokenResolve();
-                            tokenResolve = null;
+                    notifyWaiters();
+                    if (streamResponse.done) {
+                        const { final, error } = buildFinalFromEvents(allEvents, allHandlers);
+                        if (error) {
+                            const err = new CompletionFailedError(error.message, error);
+                            finalRejecter(err);
+                            statsRejecter(err);
+                            toolCallsRejecter(err);
                         }
-                        if (toolResolve) {
-                            toolResolve();
-                            toolResolve = null;
+                        else {
+                            finalResolver(final);
+                            statsResolver(final.stats);
+                            toolCallsResolver(final.toolCalls);
                         }
+                        done = true;
+                        notifyWaiters();
                     }
                 }
             }
@@ -166,31 +224,42 @@ export function completion(params) {
             streamError = error instanceof Error ? error : new Error(String(error));
             statsRejecter(error);
             toolCallsRejecter(error);
-            tokenDone = true;
-            toolDone = true;
-            if (tokenResolve) {
-                tokenResolve();
-                tokenResolve = null;
-            }
-            if (toolResolve) {
-                toolResolve();
-                toolResolve = null;
-            }
+            finalRejecter(error);
+            done = true;
+            notifyWaiters();
         }
     };
     void processResponses();
     const textPromise = (async () => {
-        await statsPromise;
-        return textBuffer;
+        const final = await finalPromise;
+        return final.contentText;
     })();
     textPromise.catch(() => { });
+    const eventStream = (async function* () {
+        while (true) {
+            if (eventQueue.length > 0) {
+                yield eventQueue.shift();
+            }
+            else if (done) {
+                if (streamError !== null) {
+                    throw streamError;
+                }
+                break;
+            }
+            else {
+                await new Promise((resolve) => {
+                    eventResolve = resolve;
+                });
+            }
+        }
+    })();
     if (params.stream) {
         const tokenStream = (async function* () {
             while (true) {
                 if (tokenQueue.length > 0) {
                     yield tokenQueue.shift();
                 }
-                else if (tokenDone) {
+                else if (done) {
                     if (streamError !== null) {
                         throw streamError;
                     }
@@ -208,7 +277,7 @@ export function completion(params) {
                 if (toolEventQueue.length > 0) {
                     yield toolEventQueue.shift();
                 }
-                else if (toolDone) {
+                else if (done) {
                     if (streamError !== null) {
                         throw streamError;
                     }
@@ -222,6 +291,8 @@ export function completion(params) {
             }
         })();
         return {
+            events: eventStream,
+            final: finalPromise,
             tokenStream,
             toolCallStream,
             text: textPromise,
@@ -237,6 +308,8 @@ export function completion(params) {
             //Empty generator for non-streaming mode
         })();
         return {
+            events: eventStream,
+            final: finalPromise,
             tokenStream,
             toolCallStream,
             text: textPromise,

package/dist/client/api/delete-cache.d.ts

@@ -6,6 +6,7 @@
  * @param params.kvCacheKey - The cache key to delete
  * @param params.modelId - Optional: specific model ID to delete within the cache key. If not provided, deletes entire cache key.
  * @returns Promise resolving to success status
+ * @throws {QvacErrorBase} When the cache parameters are invalid (`InvalidDeleteCacheParamsError`) or the server reports a delete failure (`DeleteCacheFailedError`).
  * @example
  * ```typescript
  * // Delete all caches

package/dist/client/api/delete-cache.js

@@ -8,6 +8,7 @@ import { InvalidDeleteCacheParamsError, DeleteCacheFailedError, } from "../../ut
  * @param params.kvCacheKey - The cache key to delete
  * @param params.modelId - Optional: specific model ID to delete within the cache key. If not provided, deletes entire cache key.
  * @returns Promise resolving to success status
+ * @throws {QvacErrorBase} When the cache parameters are invalid (`InvalidDeleteCacheParamsError`) or the server reports a delete failure (`DeleteCacheFailedError`).
  * @example
  * ```typescript
  * // Delete all caches

package/dist/client/api/diffusion.d.ts

@@ -10,15 +10,30 @@ interface DiffusionResult {
     stats: Promise<DiffusionStats | undefined>;
 }
 /**
- * Generate images using a loaded diffusion model.
+ * Generates images using a loaded diffusion model.
+ *
+ * @param params - Diffusion request parameters (model, prompt, dimensions, sampler, seed, etc.).
+ * @returns A result object exposing `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated image buffers), and `stats` (promise of generation statistics).
+ *
+ * Supports both txt2img (no `init_image`) and img2img (with `init_image`).
  *
  * @example
  * ```typescript
- * // Basic usage
+ * // txt2img
  * const { outputs, stats } = diffusion({ modelId, prompt: "a cat" });
  * const buffers = await outputs;
  * fs.writeFileSync("output.png", buffers[0]);
  *
+ * // img2img (SD/SDXL — SDEdit)
+ * const initImage = fs.readFileSync("input.png");
+ * const { outputs } = diffusion({ modelId, prompt: "oil painting style", init_image: initImage, strength: 0.7 });
+ *
+ * // img2img (FLUX.2 — in-context conditioning)
+ * // IMPORTANT: FLUX img2img requires `prediction: "flux2_flow"` to be set on the
+ * // model config at loadModel time (e.g. `loadModel(src, { modelType: "diffusion",
+ * // modelConfig: { prediction: "flux2_flow" } })`).
+ * const { outputs } = diffusion({ modelId, prompt: "turn into watercolor", init_image: initImage });
+ *
  * // With progress tracking
  * const { progressStream, outputs } = diffusion({ modelId, prompt: "a cat" });
  * for await (const { step, totalSteps } of progressStream) {