@qvac/sdk 0.10.2 → 0.11.0

package/dist/client/api/transcribe.js

@@ -2,8 +2,10 @@ import { transcribeResponseSchema, transcribeStreamResponseSchema, } from "../..
 import { stream, duplex } from "../rpc/rpc-client.js";
 import { getClientLogger } from "../../logging/index.js";
 import { TranscriptionFailedError } from "../../utils/errors-client.js";
+import { decoratePromise } from "../../utils/decorate-promise.js";
+import { generateClientRequestId } from "./client-request-id.js";
 const logger = getClientLogger();
-function buildTranscribeRequest(params) {
+function buildTranscribeRequest(params, requestId) {
     return {
         type: "transcribe",
         modelId: params.modelId,
@@ -12,10 +14,21 @@ function buildTranscribeRequest(params) {
             : { type: "base64", value: params.audioChunk.toString("base64") },
         ...(params.prompt && { prompt: params.prompt }),
         ...(params.metadata === true && { metadata: true }),
+        requestId,
     };
 }
-export async function transcribe(params, options) {
-    const request = buildTranscribeRequest(params);
+export function transcribe(params, options) {
+    // Client-generated id surfaced synchronously on the returned promise
+    // — same shape as `loadModel` / `downloadAsset` / `completion`. The
+    // CLI cancel bridge in `qvac serve` binds `req.on('close')` to
+    // `cancel({ requestId })` immediately after the call returns so a
+    // client disconnect aborts the in-flight transcription.
+    const requestId = generateClientRequestId();
+    const inner = runTranscribe(params, requestId, options);
+    return decoratePromise(inner, { requestId });
+}
+async function runTranscribe(params, requestId, options) {
+    const request = buildTranscribeRequest(params, requestId);
     if (params.metadata === true) {
         const segments = [];
         for await (const response of stream(request, options)) {
@@ -54,6 +67,9 @@ export function transcribeStream(params, options) {
         return transcribeStreamWithAudio(params, options);
     }
     const streamParams = params;
+    if (streamParams.emitVadEvents === true) {
+        return transcribeStreamDuplexConversation(streamParams, options);
+    }
     if (streamParams.metadata === true) {
         return transcribeStreamDuplexMetadata(streamParams, options);
     }
@@ -64,7 +80,7 @@ export function transcribeStream(params, options) {
  * the value extracted from each response frame until `done` is seen.
  */
 async function* streamTranscribeValues(params, options, extract) {
-    const request = buildTranscribeRequest(params);
+    const request = buildTranscribeRequest(params, generateClientRequestId());
     for await (const response of stream(request, options)) {
         if (response.type === "transcribe") {
             const parsed = transcribeResponseSchema.parse(response);
@@ -88,6 +104,13 @@ function buildTranscribeStreamRequest(params) {
         modelId: params.modelId,
         ...(params.prompt && { prompt: params.prompt }),
         ...(params.metadata === true && { metadata: true }),
+        ...(params.emitVadEvents === true && { emitVadEvents: true }),
+        ...(params.endOfTurnSilenceMs !== undefined && {
+            endOfTurnSilenceMs: params.endOfTurnSilenceMs,
+        }),
+        ...(params.vadRunIntervalMs !== undefined && {
+            vadRunIntervalMs: params.vadRunIntervalMs,
+        }),
     };
 }
 /**
@@ -126,6 +149,10 @@ function transcribeStreamDuplex(params, options) {
 function transcribeStreamDuplexMetadata(params, options) {
     return createTranscribeStreamSession(params, options, processLineMetadata, "TranscribeStreamMetadataSession");
 }
+function transcribeStreamDuplexConversation(params, options) {
+    const wantsMetadata = params.metadata === true;
+    return createTranscribeStreamSession(params, options, (line) => processLineConversation(line, wantsMetadata), "TranscribeStreamConversationSession");
+}
 /**
  * Line-delimited parser: reads newline-separated frames from a duplex
  * response stream, passes each non-empty line through `process`, and yields
@@ -190,3 +217,30 @@ function processLine(line) {
 function processLineMetadata(line) {
     return processWith(line, (response) => response.segment);
 }
+function processLineConversation(line, wantsMetadata) {
+    return processWith(line, (response) => {
+        if (response.vad) {
+            return {
+                type: "vad",
+                speaking: response.vad.speaking,
+                probability: response.vad.probability,
+            };
+        }
+        if (response.endOfTurn) {
+            return {
+                type: "endOfTurn",
+                silenceDurationMs: response.endOfTurn.silenceDurationMs,
+            };
+        }
+        if (wantsMetadata) {
+            if (response.segment) {
+                return { type: "segment", segment: response.segment };
+            }
+            return undefined;
+        }
+        if (response.text && response.text.trim()) {
+            return { type: "text", text: response.text };
+        }
+        return undefined;
+    });
+}

package/dist/client/api/unload-model.d.ts

@@ -3,12 +3,15 @@ import { type UnloadModelParams } from "../../schemas/index";
  * Unloads a previously loaded model from the server.
  *
  * When the last model is unloaded (no more models remain), this function
- * automatically closes the RPC connection, allowing the process to exit
- * naturally without requiring manual cleanup.
+ * automatically closes the RPC connection on Node/Electron, allowing the
+ * process to exit naturally without requiring manual cleanup. On Bare the
+ * connection is left open by default so long-lived workers survive a routine
+ * unload; pass `autoClose: true` to opt in to closing.
  *
  * @param params - The parameters for unloading the model
  * @param params.modelId - The unique identifier of the model to unload
  * @param params.clearStorage - Whether to clear the storage for the model
+ * @param params.autoClose - Override the runtime-default auto-close behavior
  * @throws {QvacErrorBase} When the response type is invalid or when the unload operation fails
  */
 export declare function unloadModel(params: UnloadModelParams): Promise<void>;

package/dist/client/api/unload-model.js

@@ -1,3 +1,4 @@
+import { isBare } from "which-runtime";
 import {} from "../../schemas/index.js";
 import { send, close } from "../rpc/rpc-client.js";
 import { stopLoggingStreamForModel } from "../logging-stream-registry.js";
@@ -8,12 +9,15 @@ const logger = getClientLogger();
  * Unloads a previously loaded model from the server.
  *
  * When the last model is unloaded (no more models remain), this function
- * automatically closes the RPC connection, allowing the process to exit
- * naturally without requiring manual cleanup.
+ * automatically closes the RPC connection on Node/Electron, allowing the
+ * process to exit naturally without requiring manual cleanup. On Bare the
+ * connection is left open by default so long-lived workers survive a routine
+ * unload; pass `autoClose: true` to opt in to closing.
  *
  * @param params - The parameters for unloading the model
  * @param params.modelId - The unique identifier of the model to unload
  * @param params.clearStorage - Whether to clear the storage for the model
+ * @param params.autoClose - Override the runtime-default auto-close behavior
  * @throws {QvacErrorBase} When the response type is invalid or when the unload operation fails
  */
 export async function unloadModel(params) {
@@ -30,8 +34,9 @@ export async function unloadModel(params) {
         throw new ModelUnloadFailedError(params.modelId);
     }
     stopLoggingStreamForModel(params.modelId);
-    // Auto-close when no models remain AND no providers are active
-    if (response.hasActiveModels === false &&
+    const shouldAutoClose = params.autoClose ?? !isBare;
+    if (shouldAutoClose &&
+        response.hasActiveModels === false &&
         response.hasActiveProviders === false) {
         logger.info("🧹 No models or providers active, automatically closing RPC connection...");
         await close();

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

@@ -0,0 +1,45 @@
+import { type UpscaleClientParams, type UpscaleStats } from "../../schemas/sdcpp-config";
+interface UpscaleResult {
+    outputs: Promise<Uint8Array[]>;
+    stats: Promise<UpscaleStats | undefined>;
+}
+/**
+ * Runs standalone ESRGAN upscaling on an arbitrary PNG/JPEG image.
+ *
+ * The model must have been loaded with `modelType: "diffusion"` and
+ * `modelConfig.mode: "upscale"` — calling `upscale()` against a model
+ * loaded in default (`mode: "diffusion"`) mode throws
+ * `ModelOperationNotSupportedError` upfront.
+ *
+ * `outputs` always resolves to length 1: `repeats` runs N passes
+ * internally and emits a single final image at `source * scale^repeats`
+ * dimensions. The `Uint8Array[]` shape reserves headroom for future
+ * multi-output variants.
+ *
+ * @param params - `{ modelId, image, repeats? }`. `image` is raw PNG/JPEG
+ *   bytes; the client base64-encodes them on the wire.
+ * @returns `{ outputs, stats }` — `outputs` resolves to a single-element
+ *   array containing the final upscaled PNG; `stats` resolves to
+ *   addon-side stats (load/upscale ms, final width/height, repeats
+ *   actually executed, etc.).
+ * @throws {ModelOperationNotSupportedError} If the model was not loaded
+ *   with `mode: "upscale"`.
+ * @throws {StreamEndedError} If the RPC stream closes without emitting a
+ *   terminal `done` chunk.
+ *
+ * @example
+ * ```ts
+ * const modelId = await loadModel(REALESRGAN_X4PLUS_ANIME_6B, {
+ *   modelType: "diffusion",
+ *   modelConfig: { mode: "upscale", upscaler: { tile_size: 128 } },
+ * });
+ * const pngBytes = fs.readFileSync("input.png");
+ * const { outputs, stats } = upscale({ modelId, image: pngBytes, repeats: 2 });
+ * const [upscaledPng] = await outputs;
+ * fs.writeFileSync("upscaled.png", upscaledPng);
+ * console.log(await stats);
+ * ```
+ */
+export declare function upscale(params: UpscaleClientParams): UpscaleResult;
+export {};
+//# sourceMappingURL=upscale.d.ts.map

package/dist/client/api/upscale.js

@@ -0,0 +1,99 @@
+import { upscaleStreamResponseSchema, } from "../../schemas/sdcpp-config.js";
+import { stream as streamRpc } from "../rpc/rpc-client.js";
+import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
+import { StreamEndedError } from "../../utils/errors-client.js";
+/**
+ * Runs standalone ESRGAN upscaling on an arbitrary PNG/JPEG image.
+ *
+ * The model must have been loaded with `modelType: "diffusion"` and
+ * `modelConfig.mode: "upscale"` — calling `upscale()` against a model
+ * loaded in default (`mode: "diffusion"`) mode throws
+ * `ModelOperationNotSupportedError` upfront.
+ *
+ * `outputs` always resolves to length 1: `repeats` runs N passes
+ * internally and emits a single final image at `source * scale^repeats`
+ * dimensions. The `Uint8Array[]` shape reserves headroom for future
+ * multi-output variants.
+ *
+ * @param params - `{ modelId, image, repeats? }`. `image` is raw PNG/JPEG
+ *   bytes; the client base64-encodes them on the wire.
+ * @returns `{ outputs, stats }` — `outputs` resolves to a single-element
+ *   array containing the final upscaled PNG; `stats` resolves to
+ *   addon-side stats (load/upscale ms, final width/height, repeats
+ *   actually executed, etc.).
+ * @throws {ModelOperationNotSupportedError} If the model was not loaded
+ *   with `mode: "upscale"`.
+ * @throws {StreamEndedError} If the RPC stream closes without emitting a
+ *   terminal `done` chunk.
+ *
+ * @example
+ * ```ts
+ * const modelId = await loadModel(REALESRGAN_X4PLUS_ANIME_6B, {
+ *   modelType: "diffusion",
+ *   modelConfig: { mode: "upscale", upscaler: { tile_size: 128 } },
+ * });
+ * const pngBytes = fs.readFileSync("input.png");
+ * const { outputs, stats } = upscale({ modelId, image: pngBytes, repeats: 2 });
+ * const [upscaledPng] = await outputs;
+ * fs.writeFileSync("upscaled.png", upscaledPng);
+ * console.log(await stats);
+ * ```
+ */
+export function upscale(params) {
+    const request = {
+        modelId: params.modelId,
+        image: encodeBase64(params.image),
+        ...(params.repeats !== undefined && { repeats: params.repeats }),
+        type: "upscaleStream",
+    };
+    let statsResolver = () => { };
+    let statsRejecter = () => { };
+    const statsPromise = new Promise((resolve, reject) => {
+        statsResolver = resolve;
+        statsRejecter = reject;
+    });
+    statsPromise.catch(() => { });
+    let outputsResolver = () => { };
+    let outputsRejecter = () => { };
+    const outputsPromise = new Promise((resolve, reject) => {
+        outputsResolver = resolve;
+        outputsRejecter = reject;
+    });
+    outputsPromise.catch(() => { });
+    const collectedBuffers = [];
+    async function processResponses() {
+        let sawDone = false;
+        try {
+            for await (const response of streamRpc(request)) {
+                if (response &&
+                    typeof response === "object" &&
+                    "type" in response &&
+                    response.type === "upscaleStream") {
+                    const parsed = upscaleStreamResponseSchema.parse(response);
+                    if (parsed.data) {
+                        collectedBuffers.push(decodeBase64(parsed.data));
+                    }
+                    if (parsed.done) {
+                        sawDone = true;
+                        statsResolver(parsed.stats);
+                        outputsResolver(collectedBuffers);
+                    }
+                }
+            }
+            if (!sawDone) {
+                const error = new StreamEndedError();
+                statsRejecter(error);
+                outputsRejecter(error);
+            }
+        }
+        catch (error) {
+            statsRejecter(error);
+            outputsRejecter(error);
+        }
+    }
+    void processResponses();
+    return {
+        outputs: outputsPromise,
+        stats: statsPromise,
+    };
+}

package/dist/client/rpc/expo-rpc-client.js

@@ -195,6 +195,7 @@ export async function createDuplexSession(payload, commandId) {
     const req = rpc.request(commandId);
     const requestStream = req.createRequestStream();
     const responseStream = req.createResponseStream({ encoding: "utf-8" });
-    requestStream.write(payload, "utf-8");
+    // Pre-encode payload — RN/Hermes lacks a global `Buffer`, so `write(string, "utf-8")` would throw.
+    requestStream.write(new TextEncoder().encode(payload));
     return { requestStream, responseStream };
 }

package/dist/client/rpc/node-rpc-client.js

@@ -13,8 +13,6 @@ import { getClientLogger } from "../../logging/index.js";
 import { RPCInitTimeoutError } from "../../utils/errors-client.js";
 const RPC_INIT_TIMEOUT_MS = 30_000;
 const logger = getClientLogger();
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
 let rpcInstance = null;
 let rpcPromise = null;
 let bareWorkerProc = null;
@@ -56,14 +54,27 @@ function resolvePackagedWorkerPath() {
     return undefined;
 }
 /**
- * Get default worker path from SDK dist
+ * Resolve the SDK's default worker entry via bundler-visible asset references.
+ *
+ * `path.resolve(__dirname, ...)` is invisible to static analysis, so packaged
+ * consumers ship without worker.js. We use `import.meta.asset(<literal>)` on
+ * Bare (detected by bare-module-lexer) and fall back to
+ * `new URL(<literal>, import.meta.url)` elsewhere. Specs must be string
+ * literals at the call site.
  */
 function getDefaultWorkerPath() {
-    const packagedWorker = path.resolve(__dirname, "../../server/worker.js");
-    if (fs.existsSync(packagedWorker))
-        return packagedWorker;
+    const hasAsset = typeof import.meta.asset === "function";
+    const packagedUrl = hasAsset
+        ? new URL(import.meta.asset("../../server/worker.js"))
+        : new URL("../../server/worker.js", import.meta.url);
+    const packaged = fileURLToPath(packagedUrl);
+    if (fs.existsSync(packaged))
+        return packaged;
     // Dev/source layout fallback
-    return path.resolve(__dirname, "../../dist/server/worker.js");
+    const devUrl = hasAsset
+        ? new URL(import.meta.asset("../../dist/server/worker.js"))
+        : new URL("../../dist/server/worker.js", import.meta.url);
+    return fileURLToPath(devUrl);
 }
 /**
  * Resolve worker path with priority:

package/dist/client/rpc/rpc-client.d.ts

@@ -3,11 +3,11 @@ import { type Request, type Response, type RPCOptions } from "../../schemas/inde
 export declare function send<T extends Request>(request: T, options?: RPCOptions, rpc?: RPC): Promise<Response>;
 export declare function stream<T extends Request>(request: T, options?: RPCOptions, rpc?: RPC): AsyncGenerator<Response>;
 export interface DuplexWritable {
-    write(chunk: Buffer): void;
+    write(chunk: Uint8Array): void;
     end(): void;
     destroy(): void;
 }
-export interface DuplexReadable extends AsyncIterable<Buffer> {
+export interface DuplexReadable extends AsyncIterable<Buffer | string> {
     destroy(): void;
 }
 export interface DuplexSession {

package/dist/client/rpc/rpc-client.js

@@ -1,5 +1,5 @@
 import { requestSchema, responseSchema, PROFILING_TRAILER_KEY, } from "../../schemas/index.js";
-import { RPCError } from "./rpc-error.js";
+import { reconstructError } from "./rpc-error.js";
 import { withTimeout, withTimeoutStream } from "../../utils/withTimeout.js";
 import { getClientLogger, summarizeRequest } from "../../logging/index.js";
 import { getRPC, close as closeRPC, createDuplexSession } from "#rpc";
@@ -15,7 +15,12 @@ function getNextCommandId() {
 }
 function checkAndThrowError(response) {
     if (response.type === "error") {
-        throw new RPCError(response);
+        // Use the typed-error reconstructor map in `rpc-error.ts` so the
+        // original class (e.g. `RequestRejectedByPolicyError`) survives
+        // the RPC boundary intact and `err instanceof <Class>` works in
+        // consumer `catch` blocks. Unknown error names fall back to a
+        // plain `RPCError` wrapper inside `reconstructError`.
+        throw reconstructError(response);
     }
 }
 async function getRPCInstance() {
@@ -311,12 +316,13 @@ async function duplexProfiled(request, options = {}) {
                 }
                 if (outputParts.length > 0) {
                     timings.chunkCount += outputParts.length;
-                    yield Buffer.from(outputParts.join("\n") + "\n");
+                    // Yield strings (not Buffer) — RN/Hermes has no global `Buffer`; consumers call `.toString()` either way.
+                    yield outputParts.join("\n") + "\n";
                 }
             }
             if (lineBuffer.trim()) {
                 timings.chunkCount++;
-                yield Buffer.from(lineBuffer + "\n");
+                yield lineBuffer + "\n";
             }
         }
         catch (error) {

package/dist/client/rpc/rpc-error.d.ts

@@ -16,4 +16,13 @@ export declare class RPCError extends Error {
         isQvacError: boolean;
     };
 }
+/**
+ * Rebuild the original server-thrown typed error from its serialised
+ * envelope so consumer code can do
+ * `if (err instanceof RequestRejectedByPolicyError) { ... }` across
+ * the RPC boundary. Unknown error names fall through to the legacy
+ * `RPCError` wrapper, which preserves `name`/`code`/`message` for
+ * code-based predicates.
+ */
+export declare function reconstructError(response: ErrorResponse): Error;
 //# sourceMappingURL=rpc-error.d.ts.map

package/dist/client/rpc/rpc-error.js

@@ -1,3 +1,4 @@
+import { RequestIdConflictError, RequestNotFoundError, RequestRejectedByPolicyError, } from "../../utils/errors-server.js";
 export class RPCError extends Error {
     timestamp;
     remoteStack;
@@ -37,3 +38,94 @@ export class RPCError extends Error {
         };
     }
 }
+/**
+ * Attach the remote stack onto a reconstructed typed error so the
+ * client-side trace points at the consumer call site and the worker-
+ * side trace is preserved for debugging. Mirrors the behaviour
+ * `RPCError`'s constructor applies in the fall-through path.
+ */
+function attachRemoteContext(err, response) {
+    if (response.stack) {
+        err.remoteStack = response.stack;
+        err.stack = `${err.stack}\n--- Worker Stack ---\n${response.stack}`;
+    }
+    if (response.timestamp) {
+        err.timestamp = response.timestamp;
+    }
+    return err;
+}
+/** Read a string field from the `typedFields` envelope, defaulting to `fallback` if missing or non-string. */
+function readStringField(fields, key, fallback) {
+    const value = fields?.[key];
+    return typeof value === "string" ? value : fallback;
+}
+/**
+ * Map of server-thrown `QvacErrorBase` subclasses that need to survive
+ * the RPC boundary as their original class — `err instanceof
+ * RequestRejectedByPolicyError` on the consumer side must match the
+ * class re-exported from `@qvac/sdk`.
+ *
+ * **Key shape.** The key is the `name` value `QvacErrorBase` sets at
+ * construction time, which `createErrorResponse` forwards onto
+ * `response.name`. That value is the SCREAMING_SNAKE_CASE error-code
+ * name from `sdk-errors-server.ts` (`"REQUEST_REJECTED_BY_POLICY"`),
+ * **not** the JS class name (`"RequestRejectedByPolicyError"`). The
+ * mismatch was a 0.11.0 bring-up bug fixed alongside the reconstructor
+ * unit tests in `rpc-error-reconstruct.test.ts`.
+ *
+ * **Maintenance contract.** Every new cross-RPC server-thrown typed
+ * error class added in `errors-server.ts` adds a row here in the same
+ * PR, keyed by its `SDK_SERVER_ERROR_CODES.<NAME>` constant. The
+ * class must (a) implement `toErrorResponseFields(): Record<…>` so
+ * the wire envelope carries its named constructor arguments and (b)
+ * be re-exported from `@qvac/sdk` so consumers can `import` it.
+ * Forgetting either side means `instanceof` regresses for that class.
+ *
+ * Client-constructed typed errors (e.g. `InferenceCancelledError`
+ * built in `client/api/completion-stream.ts` from the aggregated
+ * partial state) are NOT registered here — they never round-trip the
+ * envelope, and adding a reconstructor for one would create a
+ * parallel construction path that fires whenever the server happens
+ * to throw the same class name.
+ */
+const RECONSTRUCTORS = {
+    REQUEST_ID_CONFLICT: (response) => {
+        return new RequestIdConflictError(readStringField(response.typedFields, "requestId", ""), response.cause);
+    },
+    REQUEST_NOT_FOUND: (response) => {
+        return new RequestNotFoundError(readStringField(response.typedFields, "requestId", ""), response.cause);
+    },
+    REQUEST_REJECTED_BY_POLICY: (response) => {
+        return new RequestRejectedByPolicyError(readStringField(response.typedFields, "requestId", ""), readStringField(response.typedFields, "kind", ""), readStringField(response.typedFields, "modelId", ""), readStringField(response.typedFields, "reason", response.message), response.cause);
+    },
+};
+/**
+ * Rebuild the original server-thrown typed error from its serialised
+ * envelope so consumer code can do
+ * `if (err instanceof RequestRejectedByPolicyError) { ... }` across
+ * the RPC boundary. Unknown error names fall through to the legacy
+ * `RPCError` wrapper, which preserves `name`/`code`/`message` for
+ * code-based predicates.
+ */
+export function reconstructError(response) {
+    const reconstructor = response.name
+        ? RECONSTRUCTORS[response.name]
+        : undefined;
+    if (!reconstructor) {
+        return new RPCError(response);
+    }
+    try {
+        return attachRemoteContext(reconstructor(response), response);
+    }
+    catch {
+        // Defensive fall-through: if a reconstructor throws (e.g. a
+        // future class adds a required constructor field and an older
+        // server doesn't ship `typedFields`), surface the original error
+        // via `RPCError` so consumers never see "couldn't reconstruct
+        // error" obscuring the real one. The reconstructors here are
+        // intentionally written to coerce missing fields to defensible
+        // defaults (`String(x ?? "")`), so reaching this branch is the
+        // edge case, not the norm.
+        return new RPCError(response);
+    }
+}

package/dist/examples/cancel-by-request-id.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cancel a specific in-flight completion by `requestId`.
+ *
+ * `completion(...)` exposes a stable `requestId` (UUIDv4, generated
+ * client-side) on the returned `CompletionRun`. Pass it to
+ * `cancel({ requestId })` to abort that exact run without affecting any
+ * other inference happening on the same model.
+ *
+ * Two cancel paths exist:
+ *
+ *  1. `cancel({ requestId })` — targeted cancel, the primary path
+ *     introduced in 0.11.0. The `requestId` is available synchronously
+ *     on the `CompletionRun`. Same-tick cancels (issued before the
+ *     server has registered the request) are recorded and applied
+ *     retroactively when `begin(...)` arrives, so they aren't silently
+ *     dropped.
+ *  2. `cancel({ operation: "inference", modelId })` — broad cancel
+ *     (escape hatch, kept indefinitely). Cancels every inference running
+ *     on the model. Useful for unload, app shutdown, admin sweeps when
+ *     the caller doesn't have a `requestId` to hand.
+ *
+ * --- Cancel outcomes (0.11.0+) ---
+ *
+ * A cancel surfaces on two channels:
+ *
+ *  - `run.events` ends *normally* with a `completionDone` event carrying
+ *    `stopReason: "cancelled"`. The loop exits cleanly, no thrown error.
+ *  - `run.text` / `run.final` / `run.stats` / `run.toolCalls` reject
+ *    with `InferenceCancelledError(requestId, partial)`, where `partial`
+ *    holds whatever the model produced before the cancel landed
+ *    (accumulated `text`, completed `toolCalls`, last-known `stats`).
+ *
+ * Pick the channel that matches how you consume the run: event-loop
+ * consumers don't need to catch anything; promise-aggregate consumers
+ * pattern-match on `instanceof InferenceCancelledError`.
+ */
+export {};
+//# sourceMappingURL=cancel-by-request-id.d.ts.map

package/dist/examples/cancel-by-request-id.js

@@ -0,0 +1,103 @@
+/**
+ * Cancel a specific in-flight completion by `requestId`.
+ *
+ * `completion(...)` exposes a stable `requestId` (UUIDv4, generated
+ * client-side) on the returned `CompletionRun`. Pass it to
+ * `cancel({ requestId })` to abort that exact run without affecting any
+ * other inference happening on the same model.
+ *
+ * Two cancel paths exist:
+ *
+ *  1. `cancel({ requestId })` — targeted cancel, the primary path
+ *     introduced in 0.11.0. The `requestId` is available synchronously
+ *     on the `CompletionRun`. Same-tick cancels (issued before the
+ *     server has registered the request) are recorded and applied
+ *     retroactively when `begin(...)` arrives, so they aren't silently
+ *     dropped.
+ *  2. `cancel({ operation: "inference", modelId })` — broad cancel
+ *     (escape hatch, kept indefinitely). Cancels every inference running
+ *     on the model. Useful for unload, app shutdown, admin sweeps when
+ *     the caller doesn't have a `requestId` to hand.
+ *
+ * --- Cancel outcomes (0.11.0+) ---
+ *
+ * A cancel surfaces on two channels:
+ *
+ *  - `run.events` ends *normally* with a `completionDone` event carrying
+ *    `stopReason: "cancelled"`. The loop exits cleanly, no thrown error.
+ *  - `run.text` / `run.final` / `run.stats` / `run.toolCalls` reject
+ *    with `InferenceCancelledError(requestId, partial)`, where `partial`
+ *    holds whatever the model produced before the cancel landed
+ *    (accumulated `text`, completed `toolCalls`, last-known `stats`).
+ *
+ * Pick the channel that matches how you consume the run: event-loop
+ * consumers don't need to catch anything; promise-aggregate consumers
+ * pattern-match on `instanceof InferenceCancelledError`.
+ */
+import { cancel, completion, loadModel, unloadModel, InferenceCancelledError, QWEN3_600M_INST_Q4, } from "@qvac/sdk";
+try {
+    const modelId = await loadModel({
+        modelSrc: QWEN3_600M_INST_Q4,
+        modelType: "llm",
+        modelConfig: { ctx_size: 4096 },
+    });
+    const run = completion({
+        modelId,
+        history: [
+            {
+                role: "user",
+                content: "Write a long, detailed essay about the history of the Roman Empire.",
+            },
+        ],
+        stream: true,
+    });
+    console.log(`requestId: ${run.requestId}`);
+    // Cancel after a short delay so we exercise the cancel-mid-decode path.
+    setTimeout(() => {
+        void cancel({ requestId: run.requestId });
+        console.log("(cancel issued)");
+    }, 250);
+    // Channel 1: the events stream ends normally on cancel. The
+    // `completionDone` event's `stopReason` tells you why the loop is
+    // about to exit ("eos" | "length" | "cancelled" | "error" | ...).
+    let tokenCount = 0;
+    let endReason;
+    for await (const event of run.events) {
+        if (event.type === "contentDelta") {
+            tokenCount++;
+            process.stdout.write(event.text);
+        }
+        else if (event.type === "completionDone") {
+            endReason = event.stopReason;
+        }
+    }
+    console.log(`\n\nstreamed ${tokenCount} content deltas, stopReason=${endReason}.`);
+    // Channel 2: promise-aggregates reject with InferenceCancelledError
+    // on cancel. The accumulated state up to the cancel point is preserved
+    // on `err.partial`.
+    try {
+        const text = await run.text;
+        console.log(`completed normally (${text.length} chars).`);
+    }
+    catch (err) {
+        if (err instanceof InferenceCancelledError) {
+            console.log(`run.text rejected: cancelled (requestId=${err.requestId})`);
+            console.log(`partial text length: ${(err.partial.text ?? "").length}`);
+            if (err.partial.stats?.tokensPerSecond !== undefined) {
+                console.log(`partial stats: ${err.partial.stats.tokensPerSecond.toFixed(1)} tok/s`);
+            }
+            if (err.partial.toolCalls && err.partial.toolCalls.length > 0) {
+                console.log(`partial tool calls: ${err.partial.toolCalls.length}`);
+            }
+        }
+        else {
+            throw err;
+        }
+    }
+    await unloadModel({ modelId });
+    process.exit(0);
+}
+catch (error) {
+    console.error("Error:", error);
+    process.exit(1);
+}