@qvac/sdk 0.11.0 → 0.12.1

package/dist/client/api/vla.js

@@ -0,0 +1,109 @@
+import { vlaHparamsResponseSchema, vlaRunResponseSchema, } from "../../schemas/index.js";
+import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
+import { invokePlugin } from "./invoke-plugin.js";
+const VLA_RUN_HANDLER = "vlaRun";
+const VLA_HPARAMS_HANDLER = "vlaHparams";
+function bytesOf(arr) {
+    return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+function f32FromBase64(b64) {
+    const bytes = decodeBase64(b64);
+    // base64 round-trip produces a fresh Uint8Array whose buffer starts at 0
+    // and isn't shared, so the underlying ArrayBuffer is safe to reinterpret.
+    return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4);
+}
+/**
+ * Run SmolVLA inference on a loaded VLA model and return the produced action
+ * chunk plus per-stage timings.
+ *
+ * @param params - Inference inputs.
+ * @param params.modelId - Identifier of the loaded VLA model (returned by
+ *   `loadModel({ modelType: "vla", ... })`).
+ * @param params.images - One or more preprocessed camera frames; each is a
+ *   `Float32Array` of length `3 * imgWidth * imgHeight` in CHW layout, range
+ *   `[-1, 1]`. Use the addon's `preprocessImage()` (re-exported as
+ *   `vlaPreprocessImage`) to produce them.
+ * @param params.imgWidth - Width of each preprocessed image; must equal
+ *   `hparams.visionImageSize`.
+ * @param params.imgHeight - Height of each preprocessed image; must equal
+ *   `hparams.visionImageSize`.
+ * @param params.state - Robot end-effector / gripper state padded to
+ *   `hparams.maxStateDim` (use `vlaPadState`).
+ * @param params.tokens - Tokenized instruction (`Int32Array` of length
+ *   `hparams.tokenizerMaxLength`). Tokenize on the consumer side with the
+ *   SmolVLM2 tokenizer.
+ * @param params.mask - Token attention mask (`Uint8Array` matching `tokens`).
+ * @param params.noise - Optional seeded noise prior
+ *   (`Float32Array` of length `hparams.chunkSize * hparams.maxActionDim`).
+ *   When omitted the addon samples its own prior.
+ * @returns A `VlaClientRunResult` with the produced `actions` Float32Array
+ *   (length `chunkSize * actionDim`), the corresponding `chunkSize` /
+ *   `actionDim` returned by the addon, and optional per-stage `stats`.
+ *
+ * @example
+ * ```typescript
+ * import { loadModel, vla, vlaPreprocessImage, vlaPadState, vlaHparams } from "@qvac/sdk";
+ *
+ * const modelId = await loadModel({ modelSrc: "/path/to/smolvla.gguf", modelType: "vla" });
+ * const { hparams } = await vlaHparams({ modelId });
+ * const size = hparams.visionImageSize;
+ * const front = vlaPreprocessImage(frontPixels, frontW, frontH, { size });
+ * const wrist = vlaPreprocessImage(wristPixels, wristW, wristH, { size });
+ * const state = vlaPadState(robotState, hparams.maxStateDim);
+ * const tokens = new Int32Array(hparams.tokenizerMaxLength);
+ * const mask = new Uint8Array(hparams.tokenizerMaxLength);
+ * // ...tokenize the instruction into tokens/mask...
+ * const { actions } = await vla({
+ *   modelId, images: [front, wrist], imgWidth: size, imgHeight: size,
+ *   state, tokens, mask,
+ * });
+ * ```
+ */
+export async function vla(params) {
+    const wireRequest = {
+        type: "vlaRun",
+        modelId: params.modelId,
+        images: params.images.map((img) => encodeBase64(bytesOf(img))),
+        imgWidth: params.imgWidth,
+        imgHeight: params.imgHeight,
+        state: encodeBase64(bytesOf(params.state)),
+        tokens: encodeBase64(bytesOf(params.tokens)),
+        mask: encodeBase64(bytesOf(params.mask)),
+        ...(params.noise !== undefined && {
+            noise: encodeBase64(bytesOf(params.noise)),
+        }),
+    };
+    const result = await invokePlugin({
+        modelId: params.modelId,
+        handler: VLA_RUN_HANDLER,
+        params: wireRequest,
+    });
+    const parsed = vlaRunResponseSchema.parse(result);
+    return {
+        actions: f32FromBase64(parsed.actions),
+        actionDim: parsed.actionDim,
+        chunkSize: parsed.chunkSize,
+        ...(parsed.stats && { stats: parsed.stats }),
+    };
+}
+/**
+ * Fetch the loaded VLA model's hyperparameters and the active ggml backend
+ * name. Useful to size token / state / noise buffers before calling `vla()`.
+ *
+ * @param params - Identifier of the loaded VLA model.
+ * @returns The model's hparams and the human-readable backend name
+ *   (`"CPU"` / `"Vulkan"` / `"Metal"` / `"OpenCL"` / `null` if the addon
+ *   has not surfaced one).
+ */
+export async function vlaHparams(params) {
+    const wireRequest = {
+        type: "vlaHparams",
+        modelId: params.modelId,
+    };
+    const result = await invokePlugin({
+        modelId: params.modelId,
+        handler: VLA_HPARAMS_HANDLER,
+        params: wireRequest,
+    });
+    return vlaHparamsResponseSchema.parse(result);
+}

package/dist/client/config-loader/resolve-config.node.d.ts

@@ -1,4 +1,20 @@
 import { type QvacConfig } from "./config-utils";
+/** Config filenames searched under a project root (bundle/verify/commands). */
+export declare const CONFIG_CANDIDATES: readonly ["qvac.config.ts", "qvac.config.mjs", "qvac.config.js", "qvac.config.json"];
+/** Load and validate a config file at an explicit path (used by RPC init and commands). */
+export declare function loadConfigFromPath(configPath: string): Promise<QvacConfig>;
+/**
+ * Resolve a config file path under `projectRoot` (or an explicit relative/absolute path).
+ * Used by `bundleSdk` / `verifyBundle` when the caller supplies `projectRoot`.
+ */
+export declare function resolveConfigFileInProject(projectRoot: string, explicitPath?: string): Promise<string | null>;
+/**
+ * Load `qvac.config.*` for a known project directory (commands tooling API).
+ */
+export declare function resolveConfigForProject(projectRoot: string, explicitPath?: string): Promise<{
+    configPath: string | null;
+    config: QvacConfig;
+}>;
 /**
  * Resolution order for Node.js:
  * 1. QVAC_CONFIG_PATH environment variable

package/dist/client/config-loader/resolve-config.node.js

@@ -6,9 +6,16 @@ import { promises as fs } from "fs";
 import path from "path";
 import { pathToFileURL } from "url";
 import { validateConfig, parseJsonConfig, } from "./config-utils.js";
-import { ConfigFileParseFailedError } from "../../utils/errors-client.js";
+import { ConfigFileInvalidError, ConfigFileParseFailedError, } from "../../utils/errors-client.js";
 import { getClientLogger } from "../../logging/index.js";
 const logger = getClientLogger();
+/** Config filenames searched under a project root (bundle/verify/commands). */
+export const CONFIG_CANDIDATES = [
+    "qvac.config.ts",
+    "qvac.config.mjs",
+    "qvac.config.js",
+    "qvac.config.json",
+];
 async function findProjectRoot() {
     try {
         let currentDir = path.resolve(process.cwd());
@@ -65,20 +72,76 @@ async function loadJsConfig(filePath) {
         throw new ConfigFileParseFailedError(filePath, error instanceof Error ? error.message : String(error), error);
     }
 }
-async function findConfigFile(searchDir) {
-    const configFiles = [
-        { name: "qvac.config.ts", type: "ts" },
-        { name: "qvac.config.js", type: "js" },
-        { name: "qvac.config.json", type: "json" },
-    ];
-    for (const { name, type } of configFiles) {
+async function loadTsConfig(filePath) {
+    let tsxApiPath;
+    try {
+        const { createRequire } = await import("node:module");
+        const require = createRequire(import.meta.url);
+        tsxApiPath = require.resolve("tsx/esm/api");
+    }
+    catch (error) {
+        throw new ConfigFileInvalidError(filePath, "Loading a TypeScript qvac.config.ts requires the optional peer dependency `tsx`. Install it as a devDependency, or use qvac.config.mjs / qvac.config.js / qvac.config.json instead.", error);
+    }
+    try {
+        const tsxModule = (await import(tsxApiPath));
+        const mod = await tsxModule.tsImport(filePath, import.meta.url);
+        return validateConfig(mod.default ?? mod);
+    }
+    catch (error) {
+        throw new ConfigFileParseFailedError(filePath, error instanceof Error ? error.message : String(error), error);
+    }
+}
+/** Load and validate a config file at an explicit path (used by RPC init and commands). */
+export async function loadConfigFromPath(configPath) {
+    const ext = path.extname(configPath).toLowerCase();
+    if (ext === ".json") {
+        return loadJsonConfig(configPath);
+    }
+    if (ext === ".js" || ext === ".mjs") {
+        return loadJsConfig(configPath);
+    }
+    if (ext === ".ts") {
+        return loadTsConfig(configPath);
+    }
+    throw new ConfigFileInvalidError(configPath, `Unsupported config format: ${ext}. Use .json, .js, .mjs, or .ts`);
+}
+async function findConfigFileInDir(searchDir) {
+    for (const name of CONFIG_CANDIDATES) {
         const filePath = path.resolve(searchDir, name);
         if (await fileExists(filePath)) {
-            return { path: filePath, type };
+            return filePath;
         }
     }
     return undefined;
 }
+/**
+ * Resolve a config file path under `projectRoot` (or an explicit relative/absolute path).
+ * Used by `bundleSdk` / `verifyBundle` when the caller supplies `projectRoot`.
+ */
+export async function resolveConfigFileInProject(projectRoot, explicitPath) {
+    if (explicitPath) {
+        const absPath = path.isAbsolute(explicitPath)
+            ? explicitPath
+            : path.join(projectRoot, explicitPath);
+        if (await fileExists(absPath)) {
+            return absPath;
+        }
+        throw new ConfigFileInvalidError(absPath, "Config file not found at explicit path");
+    }
+    const found = await findConfigFileInDir(projectRoot);
+    return found ?? null;
+}
+/**
+ * Load `qvac.config.*` for a known project directory (commands tooling API).
+ */
+export async function resolveConfigForProject(projectRoot, explicitPath) {
+    const configPath = await resolveConfigFileInProject(projectRoot, explicitPath);
+    if (!configPath) {
+        return { configPath: null, config: {} };
+    }
+    const config = await loadConfigFromPath(configPath);
+    return { configPath, config };
+}
 function getResourcesPath() {
     const { resourcesPath } = process;
     return typeof resourcesPath === "string" ? resourcesPath : undefined;
@@ -111,14 +174,7 @@ export async function resolveConfig() {
     if (configPath) {
         const normalizedPath = path.resolve(configPath);
         if (await fileExists(normalizedPath)) {
-            const ext = normalizedPath.endsWith(".json")
-                ? "json"
-                : normalizedPath.endsWith(".ts")
-                    ? "ts"
-                    : "js";
-            const config = ext === "json"
-                ? await loadJsonConfig(normalizedPath)
-                : await loadJsConfig(normalizedPath);
+            const config = await loadConfigFromPath(normalizedPath);
             logger.info(`✅ Loaded config from: ${normalizedPath}`);
             return config;
         }
@@ -131,12 +187,10 @@ export async function resolveConfig() {
     }
     const projectRoot = await findProjectRoot();
     if (projectRoot) {
-        const configFile = await findConfigFile(projectRoot);
-        if (configFile) {
-            const config = configFile.type === "json"
-                ? await loadJsonConfig(configFile.path)
-                : await loadJsConfig(configFile.path);
-            logger.info(`✅ Loaded config from: ${configFile.path}`);
+        const configFilePath = await findConfigFileInDir(projectRoot);
+        if (configFilePath) {
+            const config = await loadConfigFromPath(configFilePath);
+            logger.info(`✅ Loaded config from: ${configFilePath}`);
             return config;
         }
     }

package/dist/client/plugins-factory.d.ts

@@ -0,0 +1,8 @@
+import * as hostApi from "./api/index";
+import type { QvacPlugin } from "../schemas/plugin";
+/**
+ * Register plugins and return the client host API. Designed for
+ * @qvac/bare-sdk consumers assembling explicit plugin subsets.
+ */
+export declare function plugins(pluginList: readonly QvacPlugin[]): typeof hostApi;
+//# sourceMappingURL=plugins-factory.d.ts.map

package/dist/client/plugins-factory.js

@@ -0,0 +1,10 @@
+import { registerPlugins } from "../server/plugins/index.js";
+import * as hostApi from "./api/index.js";
+/**
+ * Register plugins and return the client host API. Designed for
+ * @qvac/bare-sdk consumers assembling explicit plugin subsets.
+ */
+export function plugins(pluginList) {
+    registerPlugins(pluginList);
+    return hostApi;
+}

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

@@ -1,5 +1,6 @@
 import type { Request, Response } from "../../schemas/index";
 export declare function send<T extends Request>(request: T): Promise<Response>;
+export declare function getWorkerLifeSignal(): AbortSignal | null;
 export declare function getRPC(): Promise<{
     request(): {
         send(payload: string): void;

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

@@ -1,59 +1,27 @@
-import { normalizeModelType } from "../../schemas/index.js";
+import { normalizeModelType, PROFILING_KEY } from "../../schemas/index.js";
 import os from "bare-os";
-import { handlers } from "../../server/rpc/handlers/index.js";
 import { registry } from "../../server/rpc/handler-registry.js";
+import { handlerSupportsProgress, selectHandler, } from "../../server/rpc/handler-selection.js";
 import { createErrorResponse } from "../../schemas/index.js";
-import { PearWorkerEntryRequiredError, RPCNoHandlerError, RPCRequestNotSentError, } from "../../utils/errors-client.js";
+import { RPCNoHandlerError, RPCRequestNotSentError, } from "../../utils/errors-client.js";
 import { initializeConfig } from "../init-hooks.js";
 import { setSDKConfig } from "../../server/bare/registry/config-registry.js";
 import { setRuntimeContext } from "../../server/bare/registry/runtime-context-registry.js";
 import { resolveModelConfig } from "../../server/bare/registry/model-config-registry.js";
 import { resolveConfig } from "../config-loader/resolve-config.bare.js";
-import { getClientLogger } from "../../logging/index.js";
-import { getAllPlugins } from "../../server/plugins/index.js";
 import { initializeWorkerCore, shutdownBareDirectWorker, cleanupForTerminate, } from "../../server/worker-core.js";
 import { assertLifecycleAllowed } from "../../server/bare/runtime-lifecycle.js";
-const logger = getClientLogger();
-/**
- * Load worker entry to register plugins before any SDK calls.
- *
- * If plugins are already registered (e.g., by a Pear worker bootstrap),
- * skip loading the default worker but still initialize worker core.
- *
- * NOTE: For Pear apps, the fallback (loading default worker) cannot work.
- *
- * The default worker is intentionally excluded from `pear stage --compact`
- * to enable tree-shaking of unused built-in plugins. When a Pear app tries
- * to dynamically import it at runtime, the path resolves to a pear:// URL.
- * The default worker imports built-in plugins, which load native addons
- * (.bare files). Native addons cannot be loaded from pear:// URLs, causing
- * UNSUPPORTED_PROTOCOL errors.
- *
- * Instead, we detect Pear runtime and throw a clear error directing users
- * to use the generated worker entry (qvac/worker.pear.entry.mjs).
- *
- * The fallback only works in non-Pear environments.
- */
-async function loadWorkerEntry() {
+import { ensurePluginsRegistered } from "./ensure-worker-ready.js";
+async function ensureWorkerReady() {
     initializeWorkerCore();
-    if (getAllPlugins().length > 0) {
-        logger.info("📦 Plugins already registered, worker core initialized");
-        return;
-    }
-    const { isPear } = await import("which-runtime");
-    if (isPear) {
-        throw new PearWorkerEntryRequiredError("qvac/worker.pear.entry.mjs");
-    }
-    // Fallback: load default worker (all built-in plugins)
-    logger.info("📦 Loading default worker (all built-in plugins)");
-    const workerPath = "../../server/" + "worker.js";
-    await import(workerPath);
+    await ensurePluginsRegistered();
 }
-let workerEntryLoaded = false;
-// Get the handler for a request type
-function getHandler(type) {
-    const handler = handlers[type];
-    return typeof handler === "function" ? handler : undefined;
+function getHandlerEntry(type) {
+    const entry = registry[type];
+    if (!entry) {
+        throw new RPCNoHandlerError(type);
+    }
+    return entry;
 }
 function applyDeviceDefaultsToLoadModel(request) {
     if (request.type !== "loadModel" || !("modelSrc" in request)) {
@@ -70,16 +38,49 @@ function applyDeviceDefaultsToLoadModel(request) {
     const configWithDefaults = resolveModelConfig(canonicalType, rawConfig);
     return { ...request, modelConfig: configWithDefaults };
 }
-function supportsProgressStreaming(request) {
-    return ("withProgress" in request &&
-        request.withProgress &&
-        ["loadModel", "downloadAsset", "rag", "finetune"].includes(request.type));
+function getProfilingMetaFromRequest(request) {
+    if (PROFILING_KEY in request) {
+        return request[PROFILING_KEY];
+    }
+    return undefined;
+}
+function createDelegatedOptions(request, progressCallback) {
+    const profilingMeta = getProfilingMetaFromRequest(request);
+    if (!profilingMeta && !progressCallback) {
+        return undefined;
+    }
+    const options = {};
+    if (progressCallback) {
+        options.progressCallback = progressCallback;
+    }
+    if (profilingMeta) {
+        options.profilingMeta = profilingMeta;
+    }
+    return options;
+}
+function executeDirectHandler(request, handler, isDelegated) {
+    const directHandler = handler;
+    if (isDelegated) {
+        return directHandler(request, createDelegatedOptions(request));
+    }
+    return directHandler(request);
 }
-async function* streamWithProgress(request, handler) {
+function isAsyncGenerator(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        Symbol.asyncIterator in result);
+}
+async function* streamWithProgress(request, handler, isDelegated) {
     const queue = [];
     const errors = [];
     let done = false;
-    handler(request, (update) => queue.push(update))
+    function progressCallback(update) {
+        queue.push(update);
+    }
+    const directHandler = handler;
+    Promise.resolve(directHandler(request, isDelegated
+        ? createDelegatedOptions(request, progressCallback)
+        : progressCallback))
         .then((final) => {
         queue.push(final);
         done = true;
@@ -103,25 +104,23 @@ async function* streamWithProgress(request, handler) {
 }
 export async function send(request) {
     assertLifecycleAllowed(request);
-    const handler = getHandler(request.type);
-    if (!handler)
-        throw new RPCNoHandlerError(request.type);
     const processedRequest = applyDeviceDefaultsToLoadModel(request);
-    return (await handler(processedRequest));
+    const entry = getHandlerEntry(processedRequest.type);
+    const { handler, isDelegated } = selectHandler(entry, processedRequest);
+    return (await executeDirectHandler(processedRequest, handler, isDelegated));
 }
 async function* stream(request) {
     assertLifecycleAllowed(request);
-    const handler = getHandler(request.type);
-    if (!handler)
-        throw new RPCNoHandlerError(request.type);
-    if (supportsProgressStreaming(request)) {
-        const processedRequest = applyDeviceDefaultsToLoadModel(request);
-        yield* streamWithProgress(processedRequest, handler);
+    const processedRequest = applyDeviceDefaultsToLoadModel(request);
+    const entry = getHandlerEntry(processedRequest.type);
+    const { handler, isDelegated } = selectHandler(entry, processedRequest);
+    if (handlerSupportsProgress(entry, processedRequest)) {
+        yield* streamWithProgress(processedRequest, handler, isDelegated);
     }
     else {
-        const result = handler(request);
+        const result = executeDirectHandler(processedRequest, handler, isDelegated);
         // Check if the handler returns a Promise or AsyncGenerator
-        if (Symbol.asyncIterator in result) {
+        if (isAsyncGenerator(result)) {
             // It's an AsyncGenerator
             yield* result;
         }
@@ -194,11 +193,12 @@ function createMockRPCRequest() {
     };
 }
 let configInitialized = false;
+// No child worker on Bare-direct — `#rpc` interface stub.
+export function getWorkerLifeSignal() {
+    return null;
+}
 export async function getRPC() {
-    if (!workerEntryLoaded) {
-        await loadWorkerEntry();
-        workerEntryLoaded = true;
-    }
+    await ensureWorkerReady();
     const mockRPC = {
         request() {
             return createMockRPCRequest();

package/dist/client/rpc/ensure-worker-ready.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Throw if no plugins are registered before an SDK call. On Pear,
+ * point at the generated worker entry; otherwise raise a generic
+ * registration error. `isPear` is overridable for tests.
+ */
+export declare function ensurePluginsRegistered(opts?: {
+    isPear?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=ensure-worker-ready.d.ts.map

package/dist/client/rpc/ensure-worker-ready.js

@@ -0,0 +1,17 @@
+import { getAllPlugins } from "../../server/plugins/index.js";
+import { PearWorkerEntryRequiredError, WorkerPluginsNotRegisteredError, } from "../../utils/errors-client.js";
+const PEAR_WORKER_ENTRY_PATH = "qvac/worker.pear.entry.mjs";
+/**
+ * Throw if no plugins are registered before an SDK call. On Pear,
+ * point at the generated worker entry; otherwise raise a generic
+ * registration error. `isPear` is overridable for tests.
+ */
+export async function ensurePluginsRegistered(opts) {
+    if (getAllPlugins().length > 0)
+        return;
+    const isPear = opts?.isPear ?? (await import("which-runtime")).isPear;
+    if (isPear) {
+        throw new PearWorkerEntryRequiredError(PEAR_WORKER_ENTRY_PATH);
+    }
+    throw new WorkerPluginsNotRegisteredError();
+}

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

@@ -1,4 +1,5 @@
 import RPC from "bare-rpc";
+export declare function getWorkerLifeSignal(): AbortSignal | null;
 export declare function getRPC(): Promise<RPC>;
 export declare function close(): Promise<void>;
 export declare function createDuplexSession(payload: string, commandId: number): Promise<{

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

@@ -28,6 +28,10 @@ async function getRuntimeContext() {
     };
     return cachedRuntimeContext;
 }
+// No child-process exit on Expo (Worklet lifecycle) — `#rpc` interface stub.
+export function getWorkerLifeSignal() {
+    return null;
+}
 export async function getRPC() {
     if (rpcInstance) {
         return rpcInstance;

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

@@ -1,4 +1,5 @@
 import RPC from "bare-rpc";
+export declare function getWorkerLifeSignal(): AbortSignal | null;
 export declare function getRPC(): Promise<RPC>;
 export declare function createDuplexSession(payload: string, commandId: number): Promise<{
     requestStream: RPC.OutgoingStream;