@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/server/rpc/profiling/profiler.js

@@ -0,0 +1,78 @@
+import { responseSchema, OPERATION_EVENT_KEY, PROFILING_TRAILER_KEY, nowMs } from '@qvac/inference/surface';
+import { createProfilingContext, injectProfilingIntoString } from './context.js';
+const noopProfiler = {
+    markRequestParsed: () => { },
+    markRequestValidated: () => { },
+    startHandler: () => { },
+    endHandler: () => { },
+    serialize: (response) => {
+        if (!response)
+            return '';
+        const extended = response;
+        const operation = extended[OPERATION_EVENT_KEY];
+        const json = JSON.stringify(responseSchema.parse(response));
+        if (operation) {
+            return injectProfilingIntoString(json, { operation });
+        }
+        return json;
+    },
+    serializeError: (json) => json,
+    getContext: () => undefined
+};
+function createActiveProfiler(meta) {
+    const ctx = createProfilingContext(meta);
+    let handlerStart = 0;
+    let handlerEnded = false;
+    let cachedOperation;
+    return {
+        markRequestParsed: (ms) => {
+            ctx.jsonParseMs = ms;
+        },
+        markRequestValidated: (ms) => {
+            ctx.zodValidationMs = ms;
+        },
+        startHandler: () => {
+            handlerStart = nowMs();
+            handlerEnded = false;
+        },
+        endHandler: () => {
+            if (handlerEnded)
+                return;
+            handlerEnded = true;
+            ctx.handlerExecutionMs = nowMs() - handlerStart;
+        },
+        serialize: (response, final = true) => {
+            if (!response) {
+                const opts = { ctx };
+                if (cachedOperation)
+                    opts.operation = cachedOperation;
+                return injectProfilingIntoString(`{"${PROFILING_TRAILER_KEY}":true}`, opts);
+            }
+            const extended = response;
+            const operation = extended[OPERATION_EVENT_KEY];
+            if (operation)
+                cachedOperation = operation;
+            const zodStart = nowMs();
+            const validated = responseSchema.parse(response);
+            ctx.responseZodValidationMs = (ctx.responseZodValidationMs ?? 0) + (nowMs() - zodStart);
+            const stringifyStart = nowMs();
+            const json = JSON.stringify(validated);
+            ctx.responseStringifyMs = (ctx.responseStringifyMs ?? 0) + (nowMs() - stringifyStart);
+            if (final) {
+                const opts = { ctx };
+                if (operation)
+                    opts.operation = operation;
+                return injectProfilingIntoString(json, opts);
+            }
+            return json;
+        },
+        serializeError: (json) => injectProfilingIntoString(json, { ctx }),
+        getContext: () => ctx
+    };
+}
+export function createServerProfiler(meta) {
+    if (meta?.includeServer && typeof meta.id === 'string' && meta.id.length > 0) {
+        return createActiveProfiler(meta);
+    }
+    return noopProfiler;
+}

package/dist/src/server/rpc/rpc-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function getNextCommandId(): number;
+export declare function isTerminalChunk<T>(value: T): value is T & {
+    done: true;
+};
+//# sourceMappingURL=rpc-utils.d.ts.map

package/dist/src/server/utils/qvac-paths.js

@@ -0,0 +1,5 @@
+import path from 'bare-path';
+import { getEnv } from '../env.js';
+export function getQvacPath(...subPaths) {
+    return path.join(getEnv().HOME_DIR, '.qvac', ...subPaths);
+}

package/dist/src/server/utils/worker-lock.js

@@ -0,0 +1,67 @@
+import fs from 'bare-fs';
+import path from 'bare-path';
+import os from 'bare-os';
+import { getServerLogger } from '../../logging/index.js';
+import { getQvacPath } from './qvac-paths.js';
+const logger = getServerLogger();
+const LOCK_FILENAME = '.worker.lock';
+function getLockFilePath() {
+    return getQvacPath(LOCK_FILENAME);
+}
+function isProcessAlive(pid) {
+    try {
+        os.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLockFile(lockPath) {
+    try {
+        if (!fs.existsSync(lockPath))
+            return null;
+        const raw = fs.readFileSync(lockPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function acquireWorkerLock() {
+    const lockPath = getLockFilePath();
+    const existing = readLockFile(lockPath);
+    if (existing) {
+        if (isProcessAlive(existing.pid)) {
+            logger.warn(`Another worker (PID ${existing.pid}) is still running — lock file exists at ${lockPath}`);
+        }
+        else {
+            logger.warn(`Stale lock file detected (PID ${existing.pid} is dead, started ${existing.startedAt}). Removing.`);
+        }
+    }
+    const content = {
+        pid: os.pid(),
+        startedAt: new Date().toISOString()
+    };
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+        fs.writeFileSync(lockPath, JSON.stringify(content));
+        logger.debug(`Worker lock acquired (PID ${os.pid()})`);
+    }
+    catch (error) {
+        logger.error('Failed to write worker lock file:', error instanceof Error ? error.message : String(error));
+    }
+}
+export function releaseWorkerLock() {
+    const lockPath = getLockFilePath();
+    try {
+        const existing = readLockFile(lockPath);
+        if (existing && existing.pid === os.pid()) {
+            fs.unlinkSync(lockPath);
+            logger.debug('Worker lock released');
+        }
+    }
+    catch {
+        // Best-effort — may already be gone
+    }
+}

package/dist/src/utils/aggregate-events.d.ts

@@ -0,0 +1,26 @@
+import type { CompletionError, CompletionEvent, CompletionFinal, CompletionStats, StopReason, ToolCall } from '@qvac/inference/surface';
+import { type ToolHandlerMap } from './tool-helpers.js';
+export type AggregatedEvents = {
+    contentText: string;
+    thinkingText: string;
+    stats: CompletionStats | undefined;
+    toolCalls: ToolCall[];
+    rawFullText: string | undefined;
+    error: CompletionError | undefined;
+    stopReason: StopReason | undefined;
+    /**
+     * True when the terminal `completionDone` carried
+     * `stopReason: "cancelled"`. The client wrapper rejects the
+     * promise-aggregates (`final` / `text` / `toolCalls` / `stats`) with
+     * `InferenceCancelledError` carrying the partial state when this is
+     * set; the `events` stream itself still ends normally.
+     */
+    cancelled: boolean;
+};
+export declare function aggregateEvents(events: CompletionEvent[]): AggregatedEvents;
+export declare function buildFinalFromEvents(events: CompletionEvent[], handlers: ToolHandlerMap): {
+    final: CompletionFinal;
+    error: CompletionError | undefined;
+    cancelled: boolean;
+};
+//# sourceMappingURL=aggregate-events.d.ts.map

package/dist/src/utils/aggregate-events.js

@@ -0,0 +1,73 @@
+import { normalizeAssistantCacheContent } from './cache-normalize.js';
+import { attachHandlersToToolCalls } from './tool-helpers.js';
+export function aggregateEvents(events) {
+    let contentText = '';
+    let thinkingText = '';
+    let stats;
+    let rawFullText;
+    let error;
+    let stopReason;
+    let cancelled = false;
+    const toolCalls = [];
+    for (const event of events) {
+        if (event.type === 'contentDelta') {
+            contentText += event.text;
+        }
+        else if (event.type === 'thinkingDelta') {
+            thinkingText += event.text;
+        }
+        else if (event.type === 'completionStats') {
+            stats = event.stats;
+        }
+        else if (event.type === 'toolCall') {
+            toolCalls.push(event.call);
+        }
+        else if (event.type === 'completionDone') {
+            if ('raw' in event && event.raw) {
+                rawFullText = event.raw.fullText;
+            }
+            // Error wins over cancelled if a wire event ever carries both
+            // signals: a mid-stream addon failure makes the partial state
+            // unsafe to expose, regardless of why the loop exited.
+            if (event.stopReason === 'error' && 'error' in event) {
+                error = event.error;
+            }
+            else {
+                if (event.stopReason !== undefined) {
+                    stopReason = event.stopReason;
+                }
+                if (event.stopReason === 'cancelled') {
+                    cancelled = true;
+                }
+            }
+        }
+    }
+    return {
+        contentText,
+        thinkingText,
+        stats,
+        toolCalls,
+        rawFullText,
+        error,
+        stopReason,
+        cancelled
+    };
+}
+export function buildFinalFromEvents(events, handlers) {
+    const { contentText, thinkingText, stats, toolCalls, rawFullText, error, stopReason, cancelled } = aggregateEvents(events);
+    const attachedToolCalls = attachHandlersToToolCalls(toolCalls, handlers);
+    const fullText = rawFullText ?? contentText;
+    const cacheableAssistantContent = attachedToolCalls.length === 0 ? normalizeAssistantCacheContent(fullText) : undefined;
+    const final = {
+        contentText,
+        ...(thinkingText && { thinkingText }),
+        toolCalls: attachedToolCalls,
+        ...(stats && { stats }),
+        raw: { fullText },
+        ...(cacheableAssistantContent !== undefined && {
+            cacheableAssistantContent
+        }),
+        ...(stopReason !== undefined && { stopReason })
+    };
+    return { final, error, cancelled };
+}

package/dist/src/utils/errors-client.d.ts

@@ -0,0 +1,181 @@
+import { QvacErrorBase } from '@qvac/error';
+export declare class InvalidResponseError extends QvacErrorBase {
+    constructor(expected: string, cause?: unknown);
+}
+export declare class InvalidOperationError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class StreamEndedError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class InvalidAudioChunkError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class InvalidToolsArrayError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class InvalidToolSchemaError extends QvacErrorBase {
+    constructor(details: string, cause?: unknown);
+}
+export declare class OCRFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class ModelTypeRequiredError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class ModelSrcTypeMismatchError extends QvacErrorBase {
+    constructor(inferred: string, resolved: string, cause?: unknown);
+}
+export declare class RPCNoHandlerError extends QvacErrorBase {
+    constructor(requestType: string, cause?: unknown);
+}
+export declare class RPCRequestNotSentError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class RPCResponseStreamNotCreatedError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class RPCConnectionFailedError extends QvacErrorBase {
+    constructor(details: string, cause?: unknown);
+}
+export declare class RPCInitTimeoutError extends QvacErrorBase {
+    constructor(timeoutMs: number, cause?: unknown);
+}
+export declare class WorkerCrashedError extends QvacErrorBase {
+    readonly exitCode: number | null;
+    readonly exitSignal: NodeJS.Signals | null;
+    constructor(exitCode: number | null, exitSignal: NodeJS.Signals | null, cause?: unknown);
+}
+/**
+ * A worker that failed before the IPC handshake, attached as the `cause` of
+ * `RPCInitTimeoutError`. `workerExited` separates a dead worker from a merely
+ * slow one; `exitCode` / `exitSignal` mirror what `WorkerCrashedError` carries
+ * on the post-handshake path.
+ */
+export declare class WorkerStartupError extends QvacErrorBase {
+    /** False while the process is still running and simply has not connected. */
+    readonly workerExited: boolean;
+    readonly exitCode: number | null;
+    readonly exitSignal: NodeJS.Signals | null;
+    /** Bounded tail of the worker's stderr; empty when it wrote nothing. */
+    readonly stderrTail: string;
+    constructor(details: string, exit: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null, stderrTail: string, cause?: unknown);
+}
+export declare class WorkerShutdownError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class SDKNotFoundInNodeModulesError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class MultipleSDKInstallationsError extends QvacErrorBase {
+    constructor(packages: string, cause?: unknown);
+}
+export declare class WorkerFileNotFoundError extends QvacErrorBase {
+    constructor(workerPath: string, cause?: unknown);
+}
+export declare class PearWorkerEntryRequiredError extends QvacErrorBase {
+    constructor(workerEntry: string, cause?: unknown);
+}
+export declare class WorkerPluginsNotRegisteredError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class BundleVerificationFailedError extends QvacErrorBase {
+    constructor(bundlePath: string, cause?: unknown);
+}
+export declare class BarePackNotInstalledError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class BarePackError extends QvacErrorBase {
+    constructor(exitCode: number, entryPath: string, outputPath: string, cause?: unknown);
+}
+export declare class InvalidPluginSpecifierError extends QvacErrorBase {
+    constructor(specifiers: string[], cause?: unknown);
+}
+export declare class BareImportsMapNotFoundError extends QvacErrorBase {
+    constructor(sdkName: string, expectedPath: string, cause?: unknown);
+}
+export declare class BareRuntimeBinaryNotFoundError extends QvacErrorBase {
+    constructor(platform: string, arch: string, cause?: unknown);
+}
+export declare class ConfigFileNotFoundError extends QvacErrorBase {
+    constructor(searchPaths: string, cause?: unknown);
+}
+export declare class ConfigFileInvalidError extends QvacErrorBase {
+    constructor(filePath: string, reason: string, cause?: unknown);
+}
+export declare class ConfigFileParseFailedError extends QvacErrorBase {
+    constructor(filePath: string, error: string, cause?: unknown);
+}
+export declare class ConfigValidationFailedError extends QvacErrorBase {
+    constructor(errors: string, cause?: unknown);
+}
+export declare class RequestValidationFailedError extends QvacErrorBase {
+    constructor(errors: string, cause?: unknown);
+}
+export declare class ModelUnloadFailedError extends QvacErrorBase {
+    constructor(modelId?: string, cause?: unknown);
+}
+export declare class EmbedFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class TranscriptionFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class TextToSpeechStreamFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class CancelFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class RAGChunkFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class RAGSaveFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class RAGSearchFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class RAGDeleteFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class RAGCloseWorkspaceFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class RAGListWorkspacesFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class DownloadAssetFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class DownloadCancelledError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class ChecksumValidationFailedError extends QvacErrorBase {
+    constructor(fileName: string, cause?: unknown);
+}
+export declare class HTTPError extends QvacErrorBase {
+    constructor(status: number, statusText: string, cause?: unknown);
+}
+export declare class ModelLoadFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class DeleteCacheFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class InvalidDeleteCacheParamsError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class SetConfigFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class ModelRegistryQueryFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
+export declare class ProfilerInvalidCapacityError extends QvacErrorBase {
+    constructor(minCapacity: number, cause?: unknown);
+}
+//# sourceMappingURL=errors-client.d.ts.map