@qvac/sdk 0.20.0 → 0.21.0

package/dist/src/client/api/transcribe.d.ts

@@ -1,5 +1,5 @@
-import { type TranscribeClientParams, type RPCOptions, type TranscribeSegment, type TranscribeStreamRequest, type TranscribeStreamClientParams, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeStreamConversationSession, type TranscribeStats } from '@qvac/inference/surface';
-import { duplex } from '../rpc/rpc-client.js';
+import { type TranscribeClientParams, type RPCOptions, type TranscribeSegment, type TranscribeStreamRequest, type TranscribeStreamClientParams, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeStreamConversationSession, type TranscribeStreamEvent, type TranscribeStats, type InferenceBackendDiagnostics } from '@qvac/inference/surface';
+import { stream, duplex } from '../rpc/rpc-client.js';
 type TranscribeDuplexFactory = (request: TranscribeStreamRequest, options?: RPCOptions) => ReturnType<typeof duplex>;
 /**
  * Transcribe audio and return the complete text. Accepts either a file
@@ -10,24 +10,27 @@ type TranscribeDuplexFactory = (request: TranscribeStreamRequest, options?: RPCO
  * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
  * @param params.prompt - Optional initial prompt to guide the transcription
  * @param params.metadata - When true, resolves to an array of transcript
- *                          segments (`{ text, startMs, endMs, append, id }`)
- *                          instead of joined text. Whisper engine only.
+ *                          segments (`{ text, startMs, endMs, append, id }`,
+ *                          plus `isEndOfTurn` and `startsWord` on parakeet)
+ *                          instead of joined text.
  * @param options - Optional RPC options including per-call profiling
  * @returns A promise (decorated with `requestId`) resolving to the
  *          complete transcribed text, or — when `metadata` is true —
  *          the list of transcript segments in emission order. The
  *          `requestId` is reachable synchronously so callers can target
  *          this in-flight transcription with `cancel({ requestId })`
- *          before `await` resolves.
+ *          before `await` resolves. `stats` resolves to the terminal engine
+ *          statistics, including Parakeet's per-run Core ML usage.
  */
-export declare function transcribe(params: TranscribeClientParams & {
-    metadata: true;
-}, options?: RPCOptions): Promise<TranscribeSegment[]> & {
-    requestId: string;
-};
-export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string> & {
+type TranscribeCall<T> = Promise<T> & {
     requestId: string;
+    stats: Promise<TranscribeStats | undefined>;
 };
+export declare function transcribe(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): TranscribeCall<TranscribeSegment[]>;
+export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): TranscribeCall<string>;
+export declare function createTranscribeCall(params: TranscribeClientParams, options?: RPCOptions, responseStream?: typeof stream): TranscribeCall<string | TranscribeSegment[]>;
 /**
  * @deprecated Pass audio via `transcribe()` instead. This overload will be
  * removed in the next major version.
@@ -57,8 +60,9 @@ export declare function transcribeStream(params: TranscribeClientParams, options
  * @param params.modelId - The loaded transcription model to use
  * @param params.prompt - Optional initial prompt to guide transcription
  * @param params.metadata - When true, the session yields transcript segment
- *                          objects (`{ text, startMs, endMs, append, id }`)
- *                          instead of plain text. Whisper engine only.
+ *                          objects (`{ text, startMs, endMs, append, id }`,
+ *                          plus `isEndOfTurn` and `startsWord` on parakeet)
+ *                          instead of plain text.
  * @param options - Optional RPC options including per-call profiling.
  * @returns A session object: call `write(audioChunk)` with a `Uint8Array`
  *          (Node `Buffer` is a `Uint8Array` subtype) to feed audio,
@@ -81,13 +85,15 @@ export declare function transcribeStream(params: TranscribeStreamClientParams, o
  * to surface strings or segments; `sessionName` is only used to label the
  * "already iterated" error so callers see the correct session type.
  */
-export declare function createTranscribeStreamSession<T>(params: TranscribeStreamClientParams, options: RPCOptions | undefined, process: (line: string, onStats: (stats: TranscribeStats | undefined) => void) => T | undefined | null, sessionName: string, duplexFactory?: TranscribeDuplexFactory): Promise<{
+export declare function createTranscribeStreamSession<T>(params: TranscribeStreamClientParams, options: RPCOptions | undefined, process: (line: string, onTerminal: (stats: TranscribeStats | undefined, diagnostics: InferenceBackendDiagnostics | undefined) => void) => T | undefined | null, sessionName: string, duplexFactory?: TranscribeDuplexFactory): Promise<{
     stats: Promise<TranscribeStats | undefined>;
+    diagnostics: Promise<InferenceBackendDiagnostics | undefined>;
     write(audioChunk: Uint8Array): void;
     end(): void;
     destroy(): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }>;
-export declare function processLine(line: string, onStats: (stats: TranscribeStats | undefined) => void): string | undefined | null;
+export declare function processLine(line: string, onTerminal: (stats: TranscribeStats | undefined, diagnostics: InferenceBackendDiagnostics | undefined) => void): string | undefined | null;
+export declare function processLineConversation(line: string, wantsMetadata: boolean, onTerminal: (stats: TranscribeStats | undefined, diagnostics: InferenceBackendDiagnostics | undefined) => void): TranscribeStreamEvent | undefined | null;
 export {};
 //# sourceMappingURL=transcribe.d.ts.map

package/dist/src/client/api/transcribe.js

@@ -18,26 +18,38 @@ function buildTranscribeRequest(params, requestId) {
     };
 }
 export function transcribe(params, options) {
+    return createTranscribeCall(params, options);
+}
+export function createTranscribeCall(params, options, responseStream = stream) {
     // 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 });
+    let resolveStats = () => { };
+    let rejectStats = () => { };
+    const stats = new Promise((resolve, reject) => {
+        resolveStats = resolve;
+        rejectStats = reject;
+    });
+    stats.catch(() => { });
+    const inner = runTranscribe(params, requestId, options, resolveStats, responseStream);
+    inner.then(() => resolveStats(undefined), rejectStats);
+    return decoratePromise(inner, { requestId, stats });
 }
-async function runTranscribe(params, requestId, options) {
+async function runTranscribe(params, requestId, options, onStats, responseStream) {
     const request = buildTranscribeRequest(params, requestId);
     if (params.metadata === true) {
         const segments = [];
-        for await (const response of stream(request, options)) {
+        for await (const response of responseStream(request, options)) {
             if (response.type === 'transcribe') {
                 const parsed = transcribeResponseSchema.parse(response);
                 if (parsed.segment) {
                     segments.push(parsed.segment);
                 }
                 if (parsed.done) {
+                    onStats(parsed.stats);
                     break;
                 }
             }
@@ -45,13 +57,14 @@ async function runTranscribe(params, requestId, options) {
         return segments;
     }
     let fullText = '';
-    for await (const response of stream(request, options)) {
+    for await (const response of responseStream(request, options)) {
         if (response.type === 'transcribe') {
             const parsed = transcribeResponseSchema.parse(response);
             if (parsed.text) {
                 fullText += parsed.text;
             }
             if (parsed.done) {
+                onStats(parsed.stats);
                 break;
             }
         }
@@ -144,16 +157,47 @@ export async function createTranscribeStreamSession(params, options, process, se
         statsSettled = true;
         rejectStatsPromise(error);
     }
-    function resolveEmptyStats() {
-        resolveStats(undefined);
+    // Settled from the same terminal frame as `stats`, and on the same paths:
+    // resolved empty when the stream closes without one, rejected on error.
+    let diagnosticsSettled = false;
+    let resolveDiagnosticsPromise = () => { };
+    let rejectDiagnosticsPromise = () => { };
+    const diagnostics = new Promise((resolve, reject) => {
+        resolveDiagnosticsPromise = resolve;
+        rejectDiagnosticsPromise = reject;
+    });
+    diagnostics.catch(() => { });
+    function resolveDiagnostics(value) {
+        if (diagnosticsSettled)
+            return;
+        diagnosticsSettled = true;
+        resolveDiagnosticsPromise(value);
+    }
+    function rejectDiagnostics(error) {
+        if (diagnosticsSettled)
+            return;
+        diagnosticsSettled = true;
+        rejectDiagnosticsPromise(error);
+    }
+    function resolveTerminal(statsValue, diagnosticsValue) {
+        resolveStats(statsValue);
+        resolveDiagnostics(diagnosticsValue);
+    }
+    function resolveEmptyTerminal() {
+        resolveTerminal(undefined, undefined);
+    }
+    function rejectTerminal(error) {
+        rejectStats(error);
+        rejectDiagnostics(error);
     }
     function processResponse(line) {
-        return process(line, resolveStats);
+        return process(line, resolveTerminal);
     }
-    const responses = parseLines(responseStream, processResponse, resolveEmptyStats, rejectStats);
+    const responses = parseLines(responseStream, processResponse, resolveEmptyTerminal, rejectTerminal);
     let consumed = false;
     return {
         stats,
+        diagnostics,
         write(audioChunk) {
             requestStream.write(audioChunk);
         },
@@ -161,7 +205,7 @@ export async function createTranscribeStreamSession(params, options, process, se
             requestStream.end();
         },
         destroy() {
-            resolveStats(undefined);
+            resolveEmptyTerminal();
             requestStream.destroy();
             responseStream.destroy();
         },
@@ -182,7 +226,7 @@ function transcribeStreamDuplexMetadata(params, options) {
 }
 function transcribeStreamDuplexConversation(params, options) {
     const wantsMetadata = params.metadata === true;
-    return createTranscribeStreamSession(params, options, (line, onStats) => processLineConversation(line, wantsMetadata, onStats), 'TranscribeStreamConversationSession');
+    return createTranscribeStreamSession(params, options, (line, onTerminal) => processLineConversation(line, wantsMetadata, onTerminal), 'TranscribeStreamConversationSession');
 }
 /**
  * Line-delimited parser: reads newline-separated frames from a duplex
@@ -241,31 +285,32 @@ function parseResponseLine(line) {
  * `undefined` for frames the caller should skip, or the value extracted from
  * the frame.
  */
-function processWith(line, extract, onStats) {
+function processWith(line, extract, onTerminal) {
     const response = parseResponseLine(line);
     if (response === null)
         return undefined;
     if (response.error)
         throw new TranscriptionFailedError(response.error);
     if (response.done) {
-        onStats(response.stats);
+        onTerminal(response.stats, response.diagnostics);
         return null;
     }
     return extract(response);
 }
-export function processLine(line, onStats) {
-    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined), onStats);
+export function processLine(line, onTerminal) {
+    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined), onTerminal);
 }
-function processLineMetadata(line, onStats) {
-    return processWith(line, (response) => response.segment, onStats);
+function processLineMetadata(line, onTerminal) {
+    return processWith(line, (response) => response.segment, onTerminal);
 }
-function processLineConversation(line, wantsMetadata, onStats) {
+export function processLineConversation(line, wantsMetadata, onTerminal) {
     return processWith(line, (response) => {
         if (response.vad) {
             return {
                 type: 'vad',
                 speaking: response.vad.speaking,
-                probability: response.vad.probability
+                probability: response.vad.probability,
+                ...(response.vad.source && { source: response.vad.source })
             };
         }
         if (response.endOfTurn) {
@@ -291,5 +336,5 @@ function processLineConversation(line, wantsMetadata, onStats) {
             return { type: 'text', text: response.text };
         }
         return undefined;
-    }, onStats);
+    }, onTerminal);
 }

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

@@ -1,4 +1,4 @@
-import { ContextOverflowError, RequestIdConflictError, RequestNotFoundError, RequestRejectedByPolicyError, TranslationFailedError } from '../../utils/errors-server.js';
+import { RpcServerOperationError, InferenceCancelledError, ContextOverflowError, RequestIdConflictError, RequestNotFoundError, RequestRejectedByPolicyError, TranslationFailedError } from '../../utils/errors-server.js';
 export class RPCError extends Error {
     timestamp;
     remoteStack;
@@ -93,14 +93,18 @@ function readOptionalStringField(fields, key) {
  * 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.
+ * Completion aggregators construct cancellation errors locally with partial
+ * output. RPC control operations also throw them in the worker, so cancellation
+ * errors support both paths.
  */
 const RECONSTRUCTORS = {
+    INFERENCE_CANCELLED: (response) => {
+        const partial = response.typedFields?.['partial'];
+        return new InferenceCancelledError(readStringField(response.typedFields, 'requestId', ''), partial && typeof partial === 'object' && !Array.isArray(partial)
+            ? partial
+            : {}, response.cause);
+    },
+    RPC_SERVER_OPERATION_FAILED: (response) => new RpcServerOperationError(readStringField(response.typedFields, 'operation', 'rpcServer'), readStringField(response.typedFields, 'details', response.message), response.cause),
     REQUEST_ID_CONFLICT: (response) => {
         return new RequestIdConflictError(readStringField(response.typedFields, 'requestId', ''), response.cause);
     },

package/dist/src/commands/bundle/entry-gen.d.ts

@@ -1,5 +1,5 @@
-export declare function generateWorkerEntry(pluginSpecifiers: string[], sdkName: string, resolveImport?: (specifier: string) => string): string;
-export declare function generateWorkerEntries(pluginSpecifiers: string[], sdkName: string, resolveBundleImport: (specifier: string) => string): {
+export declare function generateWorkerEntry(pluginSpecifiers: string[], sdkName: string, resolveImport?: (specifier: string) => string, rpcServerProvider?: string): string;
+export declare function generateWorkerEntries(pluginSpecifiers: string[], sdkName: string, resolveBundleImport: (specifier: string) => string, rpcServerProvider?: string): {
     runtimeEntry: string;
     bundleEntry: string;
 };

package/dist/src/commands/bundle/entry-gen.js

@@ -1,8 +1,12 @@
 import { parseBuiltinSpecifier } from './plugins.js';
-export function generateWorkerEntry(pluginSpecifiers, sdkName, resolveImport = (specifier) => specifier) {
+export function generateWorkerEntry(pluginSpecifiers, sdkName, resolveImport = (specifier) => specifier, rpcServerProvider) {
     const imports = [];
     const registrations = [];
     let varIndex = 0;
+    if (rpcServerProvider) {
+        imports.push(`import { registerRpcServerProvider } from ${JSON.stringify(resolveImport(`${sdkName}/rpc-server-provider`))};`, `import rpcServerProvider from ${JSON.stringify(resolveImport(rpcServerProvider))};`);
+        registrations.push('registerRpcServerProvider(rpcServerProvider);');
+    }
     for (const specifier of pluginSpecifiers) {
         const builtin = parseBuiltinSpecifier(specifier, sdkName);
         if (builtin) {
@@ -46,9 +50,9 @@ if (hasRPCConfig) {
 }
 `;
 }
-export function generateWorkerEntries(pluginSpecifiers, sdkName, resolveBundleImport) {
+export function generateWorkerEntries(pluginSpecifiers, sdkName, resolveBundleImport, rpcServerProvider) {
     return {
-        runtimeEntry: generateWorkerEntry(pluginSpecifiers, sdkName),
-        bundleEntry: generateWorkerEntry(pluginSpecifiers, sdkName, resolveBundleImport)
+        runtimeEntry: generateWorkerEntry(pluginSpecifiers, sdkName, undefined, rpcServerProvider),
+        bundleEntry: generateWorkerEntry(pluginSpecifiers, sdkName, resolveBundleImport, rpcServerProvider)
     };
 }

package/dist/src/commands/bundle/index.d.ts

@@ -1,3 +1,4 @@
+import { type HostPrebuildPackage } from '../host-prebuilds/index.js';
 export interface BundleSdkOptions {
     projectRoot?: string | undefined;
     configPath?: string | undefined;
@@ -6,6 +7,23 @@ export interface BundleSdkOptions {
     defer?: string[] | undefined;
     quiet?: boolean | undefined;
     verbose?: boolean | undefined;
+    /**
+     * Install the addon platform packages the bundle needs for its mobile hosts
+     * with the project's package manager (see `ensureHostPrebuilds`), then
+     * bundle again. Off by default: without it, bundling never changes
+     * package.json or node_modules. When the install is refused, the bundle and
+     * its manifest are still written before `HostPrebuildsInstallRefusedError`
+     * is thrown.
+     */
+    installMissingPrebuilds?: boolean | undefined;
+    /**
+     * Check the bundled packages' engines.bare against the Bare runtime of each
+     * host and warn on a mismatch. Defaults to true; callers that run
+     * `verifyBundle` on the result can turn it off.
+     */
+    checkEngines?: boolean | undefined;
+    /** Allow network lookups during the engines check. Defaults to true. */
+    network?: boolean | undefined;
 }
 export interface BundleSdkResult {
     bundlePath: string;
@@ -15,6 +33,8 @@ export interface BundleSdkResult {
         worker: string;
     };
     manifestPath: string;
+    /** Platform packages `installMissingPrebuilds` installed; empty when it is off. */
+    installedPrebuilds: HostPrebuildPackage[];
 }
 export declare function bundleSdk(options?: BundleSdkOptions): Promise<BundleSdkResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/commands/bundle/index.js

@@ -3,13 +3,18 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { DEFAULT_HOSTS, DEFAULT_SDK_NAME } from './constants.js';
 import { CONFIG_CANDIDATES, resolveConfigForProject } from '../../client/config-loader/resolve-config.node.js';
-import { getClientLogger } from '../../logging/index.js';
-import { BareImportsMapNotFoundError } from '../../utils/errors-client.js';
+import { createCommandLogger } from '../command-logger.js';
+import { BareImportsMapNotFoundError, HostPrebuildsInstallRefusedError } from '../../utils/errors-client.js';
 import { resolvePluginSpecifiers, parseBuiltinSpecifier } from './plugins.js';
 import { generateWorkerEntries } from './entry-gen.js';
 import { runBarePack } from './bare-pack.js';
 import { generateAddonsManifest } from './manifest.js';
 import { createSdkImportResolver } from './resolve-sdk-import.js';
+import { installMissingHostPrebuilds } from '../host-prebuilds/index.js';
+import { collectAddonsFromBundle } from '../verify/bundle-source.js';
+import { verifyBundle } from '../verify/index.js';
+import { formatRuntimeSource } from '../verify/abi.js';
+import { formatEnginesAdvice } from '../verify/engines-advice.js';
 const require = createRequire(import.meta.url);
 function resolveSdkPath(projectRoot, explicitSdkPath) {
     if (explicitSdkPath) {
@@ -49,14 +54,43 @@ function resolveImportsMapPath(sdkPath, sdkName) {
     }
     throw new BareImportsMapNotFoundError(sdkName, importsMapPath);
 }
-function createCommandLogger(options) {
-    if (options.quiet) {
-        return getClientLogger({ level: 'error', enableConsole: false });
+const ENGINES_ISSUE_CODES = new Set(['abi-mismatch', 'engines-mismatch']);
+async function checkBundleEngines(options) {
+    const { projectRoot, bundlePath, hosts, configPath, network, logger } = options;
+    logger.info('\n🔎 Checking engines.bare against the Bare runtime of each host...');
+    const result = await verifyBundle({
+        projectRoot,
+        addonsSource: bundlePath,
+        hosts,
+        ...(configPath !== undefined ? { configPath } : {}),
+        ...(network !== undefined ? { network } : {}),
+        onProgress: (message) => logger.info(`   ${message}`)
+    });
+    const checkedHosts = [];
+    for (const group of result.runtimes ?? []) {
+        const label = group.hosts.join(', ');
+        if (group.resolution.resolved) {
+            checkedHosts.push(...group.hosts);
+            logger.info(`   ${label}: Bare ${group.resolution.runtime.version} (from ${formatRuntimeSource(group.resolution.runtime)})`);
+        }
+        else {
+            logger.warn(`engines.bare not checked for ${label}: ${group.resolution.error.reason}`);
+        }
     }
-    if (options.verbose) {
-        return getClientLogger({ level: 'debug' });
+    const mismatches = result.issues.filter((issue) => ENGINES_ISSUE_CODES.has(issue.code) && issue.level === 'error');
+    if (mismatches.length === 0) {
+        if (checkedHosts.length > 0) {
+            logger.info(`   No engines.bare mismatches for ${checkedHosts.join(', ')}`);
+        }
+        return;
     }
-    return getClientLogger();
+    const lines = ['The bundle contains packages that require a newer Bare runtime:'];
+    for (const issue of mismatches)
+        lines.push(`  - ${issue.message}`);
+    lines.push('');
+    for (const advice of result.advice ?? [])
+        lines.push(...formatEnginesAdvice(advice));
+    logger.warn(lines.join('\n').trimEnd());
 }
 export async function bundleSdk(options = {}) {
     const startTime = Date.now();
@@ -94,7 +128,7 @@ export async function bundleSdk(options = {}) {
     await fsp.mkdir(outputDir, { recursive: true });
     logger.info('\n📝 Generating worker entry...');
     const resolveSdkImport = createSdkImportResolver(sdkPath, sdkName);
-    const { runtimeEntry, bundleEntry } = generateWorkerEntries(pluginSpecifiers, sdkName, resolveSdkImport);
+    const { runtimeEntry, bundleEntry } = generateWorkerEntries(pluginSpecifiers, sdkName, resolveSdkImport, config.rpcServerProvider);
     await fsp.writeFile(entryPath, runtimeEntry, 'utf8');
     logger.info(`   Created: ${path.relative(projectRoot, entryPath)}`);
     logger.info(`   Using: ${path.relative(projectRoot, importsMapPath)}`);
@@ -103,9 +137,11 @@ export async function bundleSdk(options = {}) {
     if (deferModules.length > 0) {
         logger.debug(`   Deferred: ${deferModules.join(', ')}`);
     }
+    let installedPrebuilds = [];
+    let installRefused;
     try {
         await fsp.writeFile(bundleEntryPath, bundleEntry, 'utf8');
-        await runBarePack({
+        const barePackOptions = {
             entryPath: bundleEntryPath,
             outputPath: bundlePath,
             hosts,
@@ -113,7 +149,34 @@ export async function bundleSdk(options = {}) {
             deferModules,
             quiet: options.quiet === true,
             logger
-        });
+        };
+        await runBarePack(barePackOptions);
+        if (options.installMissingPrebuilds === true) {
+            try {
+                const { installed } = await installMissingHostPrebuilds({
+                    projectRoot,
+                    hosts,
+                    addons: await collectAddonsFromBundle({ bundlePath, projectRoot, hosts }),
+                    quiet: options.quiet === true,
+                    logger
+                });
+                installedPrebuilds = installed;
+                // Where a platform package was missing, bare-pack resolved the addon's
+                // `#host-addon` import to its fallback module; bundle again to pick up
+                // the installed package.
+                if (installed.length > 0) {
+                    logger.info('\n🔨 Bundling again with the installed platform packages...');
+                    await runBarePack(barePackOptions);
+                }
+            }
+            catch (error) {
+                if (!(error instanceof HostPrebuildsInstallRefusedError))
+                    throw error;
+                // A refusal happens before anything is installed, so the bundle
+                // already written is final and only its manifest is left to write.
+                installRefused = error;
+            }
+        }
     }
     finally {
         await fsp.rm(bundleEntryPath, { force: true });
@@ -128,6 +191,18 @@ export async function bundleSdk(options = {}) {
         projectRoot,
         logger
     });
+    if (options.checkEngines !== false) {
+        await checkBundleEngines({
+            projectRoot,
+            bundlePath,
+            hosts,
+            configPath: configPath ?? undefined,
+            network: options.network,
+            logger
+        });
+    }
+    if (installRefused !== undefined)
+        throw installRefused;
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
     logger.info(`\n🎉 Done in ${elapsed}s!\n`);
     logger.info('Generated files:');
@@ -143,6 +218,7 @@ export async function bundleSdk(options = {}) {
         entryPaths: {
             worker: entryPath
         },
-        manifestPath: manifestResult.manifestPath
+        manifestPath: manifestResult.manifestPath,
+        installedPrebuilds
     };
 }

package/dist/src/commands/bundle/plugins.js

@@ -17,7 +17,7 @@ export function parseBuiltinSpecifier(specifier, sdkName) {
 }
 export function resolvePluginSpecifiers(config, sdkName, logger) {
     let plugins = config.plugins ?? [];
-    if (plugins.length === 0) {
+    if (plugins.length === 0 && !(config.rpcServerProvider && config.plugins !== undefined)) {
         const allBuiltins = BUILTIN_SUFFIXES.map((suffix) => buildBuiltinSpecifier(sdkName, suffix));
         logger.warn('No plugins specified — bundling ALL built-in plugins.');
         logger.info("   For smaller bundles, add a 'plugins' array to qvac.config.*\n");

package/dist/src/commands/command-logger.d.ts

@@ -0,0 +1,6 @@
+export interface CommandLoggerOptions {
+    quiet?: boolean | undefined;
+    verbose?: boolean | undefined;
+}
+export declare function createCommandLogger(options: CommandLoggerOptions): import("../logging/index.js").Logger;
+//# sourceMappingURL=command-logger.d.ts.map

package/dist/src/commands/command-logger.js

@@ -0,0 +1,12 @@
+import { getClientLogger } from '../logging/index.js';
+export function createCommandLogger(options) {
+    if (options.quiet) {
+        return getClientLogger({ level: 'error', enableConsole: false });
+    }
+    // The client logger keeps console output off unless asked; a command's
+    // progress and warnings are meant for the person running it.
+    if (options.verbose) {
+        return getClientLogger({ level: 'debug', enableConsole: true });
+    }
+    return getClientLogger({ enableConsole: true });
+}

package/dist/src/commands/host-prebuilds/index.d.ts

@@ -0,0 +1,71 @@
+import type { Logger } from '../../logging/types.js';
+import { type NativeAddon } from '../verify/addon-source.js';
+import { type PackageManagerName } from './package-manager.js';
+export type { PackageManagerName } from './package-manager.js';
+export interface EnsureHostPrebuildsOptions {
+    /** The package whose package.json receives the pins; its package manager installs them. */
+    projectRoot: string;
+    /** Bare hosts to cover. Only mobile hosts (`android-*`, `ios-*`) can need an install. */
+    hosts: string[];
+    /**
+     * Addon package names to cover. Defaults to every addon installed for the
+     * project: in its own node_modules or in that of a workspace root listing it.
+     */
+    addons?: string[] | undefined;
+    /** Install with this package manager instead of detecting the project's own. */
+    packageManager?: PackageManagerName | undefined;
+    quiet?: boolean | undefined;
+    verbose?: boolean | undefined;
+}
+export interface HostPrebuildPackage {
+    /** The platform package, e.g. `@qvac/tts-ggml-android-arm64`. */
+    name: string;
+    /** Always the addon's own version: platform packages are version-locked to it. */
+    version: string;
+    /** The addon the package ships prebuilds for. */
+    addon: string;
+    /** The requested hosts the package covers. */
+    hosts: string[];
+}
+export interface EnsureHostPrebuildsResult {
+    /** The packages this call installed; empty when every prebuild already resolved. */
+    installed: HostPrebuildPackage[];
+    /** The package manager that installed them, or null when nothing was missing. */
+    packageManager: PackageManagerName | null;
+}
+/**
+ * Installs the per-platform prebuild packages that addons need for mobile
+ * hosts and that the project does not have yet.
+ *
+ * A split addon names one platform package per host in the `#host-addon` map
+ * of its package.json (`<addon>-ios` covers every iOS host). Desktop platform
+ * packages install as the addon's os/cpu-filtered optionalDependencies, but a
+ * build host never reports a mobile os, so mobile ones have to be declared.
+ * This declares the missing ones in package.json, pinned to each addon's
+ * exact version, using the project's own package manager.
+ *
+ * A host whose prebuild already resolves is skipped: a local
+ * `prebuilds/<host>` in the addon (source builds) or its platform package at
+ * the addon's version. Throws `HostPrebuildsInstallRefusedError` when no
+ * supported package manager (npm 7+, pnpm, bun, Yarn Berry) is found, and
+ * `HostPrebuildsInstallFailedError` when the install does not produce the
+ * packages.
+ */
+export declare function ensureHostPrebuilds(options: EnsureHostPrebuildsOptions): Promise<EnsureHostPrebuildsResult>;
+export interface InstallMissingHostPrebuildsOptions {
+    projectRoot: string;
+    hosts: string[];
+    addons: NativeAddon[];
+    packageManager?: PackageManagerName | undefined;
+    quiet: boolean;
+    logger: Logger;
+}
+/** `ensureHostPrebuilds` for addons the caller has already located. */
+export declare function installMissingHostPrebuilds(options: InstallMissingHostPrebuildsOptions): Promise<EnsureHostPrebuildsResult>;
+/**
+ * The platform packages `addons` still need for the mobile hosts in `hosts`,
+ * one entry per package. Throws when two installed versions of one addon need
+ * the same platform package, since only one version of it can be installed.
+ */
+export declare function findMissingHostPrebuilds(addons: NativeAddon[], hosts: string[]): Promise<HostPrebuildPackage[]>;
+//# sourceMappingURL=index.d.ts.map