@qvac/sdk 0.11.0 → 0.12.1

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

@@ -10,7 +10,7 @@ import { fileURLToPath } from "node:url";
 import { initializeConfig } from "../init-hooks.js";
 import { resolveConfig } from "../config-loader/resolve-config.node.js";
 import { getClientLogger } from "../../logging/index.js";
-import { RPCInitTimeoutError } from "../../utils/errors-client.js";
+import { RPCInitTimeoutError, WorkerCrashedError, WorkerShutdownError, } from "../../utils/errors-client.js";
 const RPC_INIT_TIMEOUT_MS = 30_000;
 const logger = getClientLogger();
 let rpcInstance = null;
@@ -19,6 +19,11 @@ let bareWorkerProc = null;
 let ipcServer = null;
 let currentSocketPath = null;
 let closePromise = null;
+// Aborted when the worker dies (crash) or close() runs (planned). Used
+// to unblock in-flight `req.reply()` callers — bare-rpc's `_onerror`
+// does not iterate `_outgoingRequests`, so without this signal they
+// would hang on the dead socket.
+let workerLifeController = null;
 /**
  * Find project root by looking for package.json (sync version)
  * Safe to call at module load time
@@ -148,9 +153,42 @@ function snapshotAndResetState() {
     bareWorkerProc = null;
     ipcServer = null;
     currentSocketPath = null;
+    workerLifeController = null;
     return { workerToClose, serverToClose, socketPathToClose };
 }
+export function getWorkerLifeSignal() {
+    return workerLifeController?.signal ?? null;
+}
+// `spawn` carries this listener's own captured resources. Module-level
+// state may belong to a newer ensureRPC() by the time we fire.
+function handlePostHandshakeExit(code, exitSignal, spawn) {
+    if (spawn.controller.signal.aborted) {
+        // close() already handled teardown.
+        logger.debug(`Bare worker exited after planned shutdown (code=${code}, signal=${exitSignal})`);
+        return;
+    }
+    logger.info(`🪦 Bare worker exited post-handshake (code=${code}, signal=${exitSignal})`);
+    // Only clear module state if we're still the active spawn.
+    if (workerLifeController === spawn.controller) {
+        rpcInstance = null;
+        rpcPromise = null;
+        bareWorkerProc = null;
+        ipcServer = null;
+        currentSocketPath = null;
+        workerLifeController = null;
+    }
+    try {
+        spawn.server.close();
+    }
+    catch (err) {
+        logger.debug("Failed to close IPC server after worker crash", { err });
+    }
+    spawn.controller.abort(new WorkerCrashedError(code, exitSignal));
+    bestEffortUnlinkSocket(spawn.socketPath);
+}
 function closeSyncForExit() {
+    // Abort before kill so the exit handler sees planned intent.
+    workerLifeController?.abort(new WorkerShutdownError());
     const { workerToClose, serverToClose, socketPathToClose } = snapshotAndResetState();
     if (workerToClose) {
         try {
@@ -180,6 +218,9 @@ async function ensureRPC() {
     }
     const socketPath = createSocketPath();
     currentSocketPath = socketPath;
+    // Allocated here so the init race and exit handler share one controller.
+    const spawnController = new AbortController();
+    workerLifeController = spawnController;
     rpcPromise = new Promise((resolve, reject) => {
         let settled = false;
         const timer = setTimeout(() => {
@@ -191,6 +232,7 @@ async function ensureRPC() {
             bareWorkerProc = null;
             ipcServer = null;
             currentSocketPath = null;
+            workerLifeController = null;
             reject(new RPCInitTimeoutError(RPC_INIT_TIMEOUT_MS));
         }, RPC_INIT_TIMEOUT_MS);
         ipcServer = createServer((socket) => {
@@ -211,23 +253,35 @@ async function ensureRPC() {
             bareWorkerProc = null;
             ipcServer = null;
             currentSocketPath = null;
+            workerLifeController = null;
             reject(error);
         });
         ipcServer.listen(socketPath, () => {
+            const spawnResources = {
+                controller: spawnController,
+                server: ipcServer,
+                socketPath,
+            };
             bareWorkerProc = spawn("bare", {
                 args: [
                     WORKER_PATH,
                     JSON.stringify({
                         QVAC_IPC_SOCKET_PATH: socketPath,
-                        HOME_DIR: os.homedir(),
+                        // Snap's HOME can be revision-scoped; SNAP_USER_COMMON is stable.
+                        HOME_DIR: process.env["SNAP_USER_COMMON"]
+                            ? String(process.env["SNAP_USER_COMMON"])
+                            : os.homedir(),
                     }),
                 ],
                 stdio: ["inherit", "inherit", "inherit"],
             });
             if (bareWorkerProc) {
-                bareWorkerProc.on("exit", (code) => {
-                    if (settled)
+                bareWorkerProc.on("exit", (code, exitSignal) => {
+                    if (settled) {
+                        handlePostHandshakeExit(code, exitSignal, spawnResources);
                         return;
+                    }
+                    // Worker died before handshake — reject the init promise.
                     settled = true;
                     clearTimeout(timer);
                     rpcPromise = null;
@@ -235,6 +289,7 @@ async function ensureRPC() {
                     bareWorkerProc = null;
                     ipcServer = null;
                     currentSocketPath = null;
+                    workerLifeController = null;
                     reject(new RPCInitTimeoutError(RPC_INIT_TIMEOUT_MS, new Error(`Worker process exited with code ${code} before IPC connection was established`)));
                 });
             }
@@ -245,9 +300,25 @@ async function ensureRPC() {
         runtime: "node",
         platform: process.platform,
     };
-    await initializeConfig(rpc, resolveConfig, runtimeContext);
+    // init-hooks calls bare-rpc directly, bypassing rpc-client's race.
+    await Promise.race([
+        initializeConfig(rpc, resolveConfig, runtimeContext),
+        rejectOnAbort(spawnController.signal),
+    ]);
     return rpc;
 }
+function rejectOnAbort(signal) {
+    return new Promise((_, reject) => {
+        const fail = () => reject(signal.reason instanceof Error
+            ? signal.reason
+            : new WorkerCrashedError(null, null));
+        if (signal.aborted) {
+            fail();
+            return;
+        }
+        signal.addEventListener("abort", fail, { once: true });
+    });
+}
 export async function getRPC() {
     return ensureRPC();
 }
@@ -257,6 +328,24 @@ export async function createDuplexSession(payload, commandId) {
     const requestStream = req.createRequestStream();
     const responseStream = req.createResponseStream({ encoding: "utf-8" });
     requestStream.write(payload, "utf-8");
+    // Destroy on worker death so consumers' for-await throws instead of hangs.
+    const lifeSignal = workerLifeController?.signal;
+    if (lifeSignal && !lifeSignal.aborted) {
+        const onAbort = () => {
+            const err = lifeSignal.reason instanceof Error
+                ? lifeSignal.reason
+                : new WorkerCrashedError(null, null);
+            try {
+                requestStream.destroy?.(err);
+            }
+            catch { }
+            try {
+                responseStream.destroy?.(err);
+            }
+            catch { }
+        };
+        lifeSignal.addEventListener("abort", onAbort, { once: true });
+    }
     return { requestStream, responseStream };
 }
 export async function close() {
@@ -267,6 +356,9 @@ export async function close() {
     if (!rpcInstance && !rpcPromise && !bareWorkerProc && !ipcServer)
         return;
     logger.info("🧹 Closing RPC client");
+    // Abort before kill: exit handler sees planned intent; any in-flight
+    // caller (contract violators) rejects with WorkerShutdownError.
+    workerLifeController?.abort(new WorkerShutdownError());
     const { workerToClose, serverToClose, socketPathToClose } = snapshotAndResetState();
     closePromise = (async () => {
         if (workerToClose) {

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

@@ -2,7 +2,8 @@ import { requestSchema, responseSchema, PROFILING_TRAILER_KEY, } from "../../sch
 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";
+import { getRPC, close as closeRPC, createDuplexSession, getWorkerLifeSignal, } from "#rpc";
+import { WorkerCrashedError } from "../../utils/errors-client.js";
 import { nowMs, shouldProfile, shouldIncludeServerBreakdown, generateId as createProfileId, createProfilingMeta, createProfilingDisabledMeta, injectProfilingMetaIntoObject, extractProfilingMeta, stripProfilingMeta, recordFailure, } from "../../profiling/index.js";
 import { createClientTimings, createClientStreamTimings, recordClientEvents, recordClientStreamEvents, cacheConnectionTime, flushConnectionTime, resetConnectionTracking, } from "./profiling/index.js";
 const logger = getClientLogger();
@@ -13,6 +14,98 @@ function getNextCommandId() {
     commandCounter = (commandCounter + 1) % Number.MAX_SAFE_INTEGER;
     return commandCounter;
 }
+// Race in-flight reply/stream pulls against the worker-life signal —
+// bare-rpc's `_onerror` does not iterate `_outgoingRequests`, so without
+// this they hang on a dead socket.
+function lifeSignalAbortError(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    return new WorkerCrashedError(null, null);
+}
+async function awaitWithLifeSignal(p) {
+    // Null on Bare-direct / Expo and pre-spawn.
+    const lifeSignal = getWorkerLifeSignal();
+    if (!lifeSignal)
+        return p;
+    if (lifeSignal.aborted)
+        throw lifeSignalAbortError(lifeSignal);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            lifeSignal.removeEventListener("abort", onAbort);
+            reject(lifeSignalAbortError(lifeSignal));
+        };
+        lifeSignal.addEventListener("abort", onAbort, { once: true });
+        p.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            lifeSignal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (err) => {
+            if (settled)
+                return;
+            settled = true;
+            lifeSignal.removeEventListener("abort", onAbort);
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- forwarding upstream rejection as-is
+            reject(err);
+        });
+    });
+}
+async function* iterateWithLifeSignal(source) {
+    // Null on Bare-direct / Expo and pre-spawn.
+    const lifeSignal = getWorkerLifeSignal();
+    if (!lifeSignal) {
+        yield* source;
+        return;
+    }
+    if (lifeSignal.aborted)
+        throw lifeSignalAbortError(lifeSignal);
+    try {
+        while (true) {
+            const nextP = source.next();
+            const result = await new Promise((resolve, reject) => {
+                let settled = false;
+                const onAbort = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    lifeSignal.removeEventListener("abort", onAbort);
+                    reject(lifeSignalAbortError(lifeSignal));
+                };
+                lifeSignal.addEventListener("abort", onAbort, { once: true });
+                nextP.then((value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    lifeSignal.removeEventListener("abort", onAbort);
+                    resolve(value);
+                }, (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    lifeSignal.removeEventListener("abort", onAbort);
+                    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- forwarding upstream rejection as-is
+                    reject(err);
+                });
+            });
+            if (result.done)
+                return;
+            yield result.value;
+        }
+    }
+    finally {
+        // Fire-and-forget cleanup. If the source is suspended on a never-
+        // settling read (worker dead), `.return()` propagates an abrupt
+        // completion through the for-await chain so inner streams get
+        // destroyed. The `.catch` swallows the case where the underlying
+        // stream cannot honour `.return()` cleanly.
+        void source.return?.(undefined).catch(() => { });
+    }
+}
 function checkAndThrowError(response) {
     if (response.type === "error") {
         // Use the typed-error reconstructor map in `rpc-error.ts` so the
@@ -23,12 +116,28 @@ function checkAndThrowError(response) {
         throw reconstructError(response);
     }
 }
+function invalidateRPCInstance() {
+    rpcInstance = null;
+    firstConnectionPending = true;
+    resetConnectionTracking();
+}
 async function getRPCInstance() {
     if (rpcInstance)
         return { rpc: await rpcInstance };
     const connectionStart = firstConnectionPending ? nowMs() : null;
     rpcInstance = getRPC();
     const rpc = await rpcInstance;
+    // Drop the cache on worker death so the next call respawns and
+    // records connectionMs again as a "first" connection.
+    const lifeSignal = getWorkerLifeSignal();
+    if (lifeSignal?.aborted) {
+        invalidateRPCInstance();
+    }
+    else if (lifeSignal) {
+        lifeSignal.addEventListener("abort", invalidateRPCInstance, {
+            once: true,
+        });
+    }
     if (connectionStart !== null && firstConnectionPending) {
         firstConnectionPending = false;
         return { rpc, connectionMs: nowMs() - connectionStart };
@@ -63,7 +172,7 @@ async function sendBase(request, rpc, options, signalDisable = false) {
         : parsedRequest;
     const payload = JSON.stringify(payloadObj);
     req.send(payload, "utf-8");
-    const response = await withTimeout(req.reply("utf-8"), options?.timeout);
+    const response = await awaitWithLifeSignal(withTimeout(req.reply("utf-8"), options?.timeout));
     const resPayload = responseSchema.parse(JSON.parse(response?.toString() || "{}"));
     logger.debug("ResPayload", { type: resPayload.type });
     checkAndThrowError(resPayload);
@@ -87,7 +196,7 @@ async function sendProfiled(request, rpc, options) {
         timings.requestStringifyMs = nowMs() - stringifyStart;
         timings.sendStart = nowMs();
         req.send(payload, "utf-8");
-        const response = await withTimeout(req.reply("utf-8"), options?.timeout);
+        const response = await awaitWithLifeSignal(withTimeout(req.reply("utf-8"), options?.timeout));
         timings.firstResponseAt = nowMs();
         const parseStart = nowMs();
         const rawParsed = JSON.parse(response?.toString() || "{}");
@@ -140,7 +249,7 @@ async function* streamBase(request, rpc, options = {}, signalDisable = false) {
         }
     }
     const streamWithTimeout = withTimeoutStream(processStream(), options?.timeout);
-    for await (const chunk of streamWithTimeout) {
+    for await (const chunk of iterateWithLifeSignal(streamWithTimeout)) {
         buffer += chunk.toString();
         // Process complete lines (newline-delimited JSON)
         const lines = buffer.split("\n");
@@ -181,7 +290,7 @@ async function* streamProfiled(request, rpc, options = {}) {
             }
         }
         const streamWithTimeout = withTimeoutStream(processStream(), options?.timeout);
-        for await (const chunk of streamWithTimeout) {
+        for await (const chunk of iterateWithLifeSignal(streamWithTimeout)) {
             const chunkTime = nowMs();
             if (timings.firstChunkAt === undefined) {
                 timings.firstChunkAt = chunkTime;
@@ -361,8 +470,6 @@ async function duplexProfiled(request, options = {}) {
 export async function close() {
     if (!rpcInstance)
         return;
-    rpcInstance = null;
-    firstConnectionPending = true;
-    resetConnectionTracking();
+    invalidateRPCInstance();
     await closeRPC();
 }

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

@@ -1,4 +1,4 @@
-import { RequestIdConflictError, RequestNotFoundError, RequestRejectedByPolicyError, } from "../../utils/errors-server.js";
+import { ContextOverflowError, RequestIdConflictError, RequestNotFoundError, RequestRejectedByPolicyError, } from "../../utils/errors-server.js";
 export class RPCError extends Error {
     timestamp;
     remoteStack;
@@ -59,6 +59,16 @@ function readStringField(fields, key, fallback) {
     const value = fields?.[key];
     return typeof value === "string" ? value : fallback;
 }
+/** Read a number field from the `typedFields` envelope, returning `undefined` if missing or non-number. */
+function readOptionalNumberField(fields, key) {
+    const value = fields?.[key];
+    return typeof value === "number" ? value : undefined;
+}
+/** Read a string field, returning `undefined` (not a fallback string) if missing. */
+function readOptionalStringField(fields, key) {
+    const value = fields?.[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 /**
  * Map of server-thrown `QvacErrorBase` subclasses that need to survive
  * the RPC boundary as their original class — `err instanceof
@@ -98,6 +108,9 @@ const RECONSTRUCTORS = {
     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);
     },
+    CONTEXT_OVERFLOW: (response) => {
+        return new ContextOverflowError(readOptionalNumberField(response.typedFields, "promptTokens"), readOptionalNumberField(response.typedFields, "ctxSize"), readOptionalStringField(response.typedFields, "modelId"), response.cause);
+    },
 };
 /**
  * Rebuild the original server-thrown typed error from its serialised

package/dist/commands/bundle/bare-pack.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from "../../logging/types";
+interface RunBarePackOptions {
+    entryPath: string;
+    outputPath: string;
+    hosts: string[];
+    importsMapPath: string;
+    deferModules: string[];
+    quiet: boolean;
+    logger: Logger;
+}
+export declare function runBarePack(options: RunBarePackOptions): Promise<void>;
+export {};
+//# sourceMappingURL=bare-pack.d.ts.map

package/dist/commands/bundle/bare-pack.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { platform, execPath } from "node:process";
+import { BarePackNotInstalledError, BarePackError, } from "../../utils/errors-client.js";
+const require = createRequire(import.meta.url);
+function resolveBarePackBin() {
+    try {
+        const barePackPkgPath = require.resolve("bare-pack/package");
+        const barePackDir = path.dirname(barePackPkgPath);
+        return path.join(barePackDir, "bin.js");
+    }
+    catch {
+        return null;
+    }
+}
+export async function runBarePack(options) {
+    const { entryPath, outputPath, hosts, importsMapPath, deferModules, quiet, logger, } = options;
+    const barePackBin = resolveBarePackBin();
+    if (!barePackBin || !fs.existsSync(barePackBin)) {
+        throw new BarePackNotInstalledError();
+    }
+    return new Promise((resolve, reject) => {
+        const hostArgs = hosts.flatMap((h) => ["--host", h]);
+        const deferArgs = deferModules.flatMap((m) => ["--defer", m]);
+        const args = [
+            ...hostArgs,
+            "--linked",
+            "--imports",
+            importsMapPath,
+            ...deferArgs,
+            "--out",
+            outputPath,
+            entryPath,
+        ];
+        const isWindows = platform === "win32";
+        const command = isWindows ? execPath : barePackBin;
+        const spawnArgs = isWindows ? [barePackBin, ...args] : args;
+        logger.debug(`\n📦 Running: ${command} ${spawnArgs.join(" ")}`);
+        const proc = spawn(command, spawnArgs, {
+            stdio: quiet ? "ignore" : "inherit",
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new BarePackError(code ?? 1, entryPath, outputPath));
+            }
+        });
+        proc.on("error", reject);
+    });
+}

package/dist/commands/bundle/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const BUILTIN_PLUGINS: Record<string, {
+    exportName: string;
+}>;
+export declare const BUILTIN_SUFFIXES: string[];
+export declare const DEFAULT_HOSTS: string[];
+export declare const DEFAULT_SDK_NAME = "@qvac/sdk";
+//# sourceMappingURL=constants.d.ts.map

package/dist/commands/bundle/constants.js

@@ -0,0 +1,23 @@
+export const BUILTIN_PLUGINS = {
+    "llamacpp-completion": { exportName: "llmPlugin" },
+    "llamacpp-embedding": { exportName: "embeddingsPlugin" },
+    "whispercpp-transcription": { exportName: "whisperPlugin" },
+    "parakeet-transcription": { exportName: "parakeetPlugin" },
+    "nmtcpp-translation": { exportName: "nmtPlugin" },
+    "tts-ggml": { exportName: "ttsPlugin" },
+    "onnx-ocr": { exportName: "ocrPlugin" },
+    "sdcpp-generation": { exportName: "diffusionPlugin" },
+};
+export const BUILTIN_SUFFIXES = Object.keys(BUILTIN_PLUGINS);
+export const DEFAULT_HOSTS = [
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-arm64",
+    "linux-x64",
+    "win32-x64",
+    "android-arm64",
+    "ios-arm64",
+    "ios-arm64-simulator",
+    "ios-x64-simulator",
+];
+export const DEFAULT_SDK_NAME = "@qvac/sdk";

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

@@ -0,0 +1,2 @@
+export declare function generateWorkerEntry(pluginSpecifiers: string[], sdkName: string): string;
+//# sourceMappingURL=entry-gen.d.ts.map

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

@@ -0,0 +1,48 @@
+import { parseBuiltinSpecifier } from "./plugins.js";
+export function generateWorkerEntry(pluginSpecifiers, sdkName) {
+    const imports = [];
+    const registrations = [];
+    let varIndex = 0;
+    for (const specifier of pluginSpecifiers) {
+        const builtin = parseBuiltinSpecifier(specifier, sdkName);
+        if (builtin) {
+            imports.push(`import { ${builtin.exportName} } from "${sdkName}/${builtin.suffix}/plugin";`);
+            registrations.push(`registerPlugin(${builtin.exportName});`);
+        }
+        else {
+            const varName = `customPlugin${varIndex++}`;
+            imports.push(`import ${varName} from "${specifier}";`);
+            registrations.push(`registerPlugin(${varName});`);
+        }
+    }
+    const importsStr = imports.join("\n");
+    const registrationsStr = registrations.join("\n");
+    const pluginsList = pluginSpecifiers.map((p) => `*   - ${p}`).join("\n");
+    return `/**
+ * QVAC SDK Worker Entry (auto-generated)
+ * Generated by: @qvac/sdk/commands bundleSdk
+ * Plugins: ${pluginSpecifiers.length}
+ *
+${pluginsList}
+ */
+
+import { initializeWorkerCore, ensureRPCSetup } from "${sdkName}/worker-core";
+import { registerPlugin } from "${sdkName}/plugins";
+import { getServerLogger } from "${sdkName}/logging";
+
+${importsStr}
+
+const { hasRPCConfig } = initializeWorkerCore();
+
+const logger = getServerLogger();
+logger.info("🐻 QVAC Worker (custom bundle)");
+logger.info("📦 Plugins: ${pluginSpecifiers.length}");
+
+${registrationsStr}
+
+// Auto-setup RPC if config present
+if (hasRPCConfig) {
+  ensureRPCSetup();
+}
+`;
+}

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

@@ -0,0 +1,20 @@
+export interface BundleSdkOptions {
+    projectRoot?: string | undefined;
+    configPath?: string | undefined;
+    sdkPath?: string | undefined;
+    hosts?: string[] | undefined;
+    defer?: string[] | undefined;
+    quiet?: boolean | undefined;
+    verbose?: boolean | undefined;
+}
+export interface BundleSdkResult {
+    bundlePath: string;
+    plugins: string[];
+    addons: string[];
+    entryPaths: {
+        worker: string;
+    };
+    manifestPath: string;
+}
+export declare function bundleSdk(options?: BundleSdkOptions): Promise<BundleSdkResult>;
+//# sourceMappingURL=index.d.ts.map