@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/utils/mcp-adapter.js

@@ -0,0 +1,96 @@
+import { mapValues } from './object.js';
+const VALID_TYPES = ['string', 'number', 'integer', 'boolean', 'object', 'array'];
+function isValidType(value) {
+    return typeof value === 'string' && VALID_TYPES.includes(value);
+}
+function convertMcpToolToTool(mcpTool) {
+    const inputSchema = mcpTool.inputSchema;
+    const properties = inputSchema.properties ?? {};
+    const required = inputSchema.required ?? [];
+    const convertedProperties = mapValues(properties, (prop) => {
+        const { type, description, enum: enumVal } = prop;
+        return {
+            type: isValidType(type) ? type : 'string',
+            ...(description && { description }),
+            ...(enumVal && { enum: enumVal })
+        };
+    });
+    return {
+        type: 'function',
+        name: mcpTool.name,
+        description: mcpTool.description ?? '',
+        parameters: {
+            type: 'object',
+            properties: convertedProperties,
+            required: required.length > 0 ? required : undefined
+        }
+    };
+}
+function createMcpToolHandler(client, toolName) {
+    return async (args) => {
+        return client.callTool({ name: toolName, arguments: args });
+    };
+}
+export async function getMcpToolsWithHandlers(clients) {
+    const allTools = [];
+    const handlers = new Map();
+    for (const { client, includeResources } of clients) {
+        const { tools: mcpTools } = await client.listTools();
+        for (const mcpTool of mcpTools) {
+            allTools.push(convertMcpToolToTool(mcpTool));
+            handlers.set(mcpTool.name, createMcpToolHandler(client, mcpTool.name));
+        }
+        if (includeResources !== false && client.listResources) {
+            allTools.push({
+                type: 'function',
+                name: 'list_resources',
+                description: 'List available resources from MCP server',
+                parameters: {
+                    type: 'object',
+                    properties: {}
+                }
+            });
+            handlers.set('list_resources', async () => {
+                if (!client.listResources) {
+                    return { resources: [] };
+                }
+                const result = await client.listResources();
+                return {
+                    type: 'text',
+                    text: JSON.stringify(result.resources, null, 2)
+                };
+            });
+            if (client.readResource) {
+                allTools.push({
+                    type: 'function',
+                    name: 'read_resource',
+                    description: 'Read content of a specific resource by URI',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            uri: {
+                                type: 'string',
+                                description: 'The URI of the resource to read'
+                            }
+                        },
+                        required: ['uri']
+                    }
+                });
+                handlers.set('read_resource', async (args) => {
+                    if (!client.readResource) {
+                        return { error: 'readResource not available' };
+                    }
+                    const result = await client.readResource({
+                        uri: args['uri']
+                    });
+                    return result.contents[0];
+                });
+            }
+        }
+    }
+    return { tools: allTools, handlers };
+}
+export async function getMcpTools(clients) {
+    const { tools } = await getMcpToolsWithHandlers(clients);
+    return tools;
+}

package/dist/src/utils/tool-helpers.d.ts

@@ -0,0 +1,25 @@
+import type { z } from 'zod';
+import { type Tool, type ToolCall, type ToolCallWithCall } from '@qvac/inference/surface';
+type ZodObjectType = z.ZodObject<z.ZodRawShape>;
+export type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+export type ToolInput<T extends ZodObjectType = ZodObjectType> = {
+    name: string;
+    description: string;
+    parameters: T;
+    handler?: ToolHandler;
+};
+export declare function convertToolInput(input: ToolInput): Tool;
+export declare function convertTools(inputs: ToolInput[]): Tool[];
+/**
+ * Validates and converts tools from either ToolInput (with Zod schemas) or full Tool format.
+ * Returns validated Tool[] array.
+ */
+export type ToolHandlerMap = Map<string, ToolHandler>;
+export type ValidateToolsResult = {
+    tools: Tool[];
+    handlers: ToolHandlerMap;
+};
+export declare function validateTools(tools: Tool[] | ToolInput[]): ValidateToolsResult;
+export declare function attachHandlersToToolCalls(toolCalls: ToolCall[], handlers: ToolHandlerMap): ToolCallWithCall[];
+export {};
+//# sourceMappingURL=tool-helpers.d.ts.map

package/dist/src/utils/tool-helpers.js

@@ -0,0 +1,111 @@
+import { toolSchema } from '@qvac/inference/surface';
+import { InvalidToolsArrayError, InvalidToolSchemaError } from './errors-client.js';
+function zodTypeToJsonSchemaType(type) {
+    switch (type) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'object':
+            return 'object';
+        case 'array':
+            return 'array';
+        case 'optional':
+        default:
+            return 'string';
+    }
+}
+export function convertToolInput(input) {
+    const zodSchema = input.parameters;
+    // Try both shape and def.shape for Zod v4 compatibility
+    const shape = zodSchema.shape || (typeof zodSchema.def?.shape === 'object' ? zodSchema.def.shape : {});
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const field = value;
+        const fieldType = field.type || field.def?.type || 'string';
+        const isOptional = fieldType === 'optional';
+        let actualType = isOptional ? 'string' : fieldType;
+        let actualDescription = field.description;
+        if (isOptional && field.def?.innerType) {
+            const innerType = field.def.innerType;
+            actualType = innerType.type || innerType.def?.type || 'string';
+            // Get description from inner type if not on wrapper
+            if (!actualDescription && innerType.description) {
+                actualDescription = innerType.description;
+            }
+        }
+        properties[key] = {
+            type: zodTypeToJsonSchemaType(actualType)
+        };
+        if (actualDescription) {
+            properties[key].description = actualDescription;
+        }
+        if (field.def?.values) {
+            properties[key].enum = field.def.values;
+        }
+        if (!isOptional) {
+            required.push(key);
+        }
+    }
+    const tool = {
+        type: 'function',
+        name: input.name,
+        description: input.description,
+        parameters: {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined
+        }
+    };
+    return toolSchema.parse(tool);
+}
+export function convertTools(inputs) {
+    return inputs.map(convertToolInput);
+}
+export function validateTools(tools) {
+    if (tools.length === 0) {
+        return { tools: [], handlers: new Map() };
+    }
+    const firstTool = tools[0];
+    if (!firstTool) {
+        throw new InvalidToolsArrayError();
+    }
+    const handlers = new Map();
+    const parseResult = toolSchema.safeParse(firstTool);
+    if (parseResult.success) {
+        const validatedTools = [];
+        for (const tool of tools) {
+            const result = toolSchema.safeParse(tool);
+            if (!result.success) {
+                throw new InvalidToolSchemaError(result.error.message, result.error);
+            }
+            validatedTools.push(result.data);
+        }
+        return { tools: validatedTools, handlers };
+    }
+    else {
+        const toolInputs = tools;
+        const convertedTools = convertTools(toolInputs);
+        for (const toolInput of toolInputs) {
+            if (toolInput.handler) {
+                handlers.set(toolInput.name, toolInput.handler);
+            }
+        }
+        return { tools: convertedTools, handlers };
+    }
+}
+export function attachHandlersToToolCalls(toolCalls, handlers) {
+    return toolCalls.map((toolCall) => {
+        const handler = handlers.get(toolCall.name);
+        if (handler) {
+            return {
+                ...toolCall,
+                invoke: async () => await handler(toolCall.arguments)
+            };
+        }
+        return toolCall;
+    });
+}

package/dist/src/worker/create-server.js

@@ -0,0 +1,46 @@
+import RPC from 'bare-rpc';
+import { connect } from 'bare-net';
+import { handleRequest } from './handle-request.js';
+import { getServerLogger } from '../logging/index.js';
+const logger = getServerLogger();
+export function createBareKitRPCServer() {
+    const { IPC } = globalThis.BareKit;
+    return new RPC(IPC, handleRequest);
+}
+/**
+ * Dial the client's IPC endpoint. Two encodings cross the handshake:
+ *
+ * - `tcp://host:port` — a loopback TCP endpoint. Used by clients whose
+ *   runtime has no portable server for filesystem sockets, notably the
+ *   Python `asyncio` transport (`start_unix_server` is Unix-only, and
+ *   asyncio has no cross-platform named-pipe server). One code path on
+ *   every OS, so Windows dials the same way Linux/macOS do.
+ * - anything else — a filesystem path: a Unix domain socket, or a
+ *   `\\.\pipe\...` named pipe on Windows, as the Node client (`node:net`)
+ *   creates.
+ */
+function connectToEndpoint(endpoint) {
+    if (endpoint.startsWith('tcp://')) {
+        const hostPort = endpoint.slice('tcp://'.length);
+        const sep = hostPort.lastIndexOf(':');
+        const host = hostPort.slice(0, sep);
+        const port = Number(hostPort.slice(sep + 1));
+        return connect(port, host);
+    }
+    return connect(endpoint);
+}
+export function createIPCClient(socketPath, options) {
+    logger.info(`Connecting to IPC socket at ${socketPath}`);
+    const socket = connectToEndpoint(socketPath);
+    socket.on('connect', () => {
+        logger.info('Connected to IPC server');
+    });
+    socket.on('error', (err) => {
+        logger.error('IPC client connection error:', err);
+    });
+    socket.on('close', () => {
+        logger.warn('IPC socket closed — parent process likely terminated');
+        options?.onDisconnect?.();
+    });
+    return new RPC(socket, handleRequest);
+}

package/dist/src/worker/handle-request.js

@@ -0,0 +1,180 @@
+import { PROFILING_KEY, nowMs } from '@qvac/inference/surface';
+import { send, stream, duplex, dispatchTransport } from '@qvac/inference/engine';
+import { sendErrorResponse, sendStreamErrorResponse } from '../server/error-handlers.js';
+import { PluginHandlerTypeMismatchError } from '../utils/errors-server.js';
+import { handleInitConfig, isInitConfigMessage, handleShutdown, isShutdownMessage } from './handler-utils.js';
+import { createServerProfiler } from '../server/rpc/profiling/index.js';
+import { isTerminalChunk } from '../server/rpc/rpc-utils.js';
+import { createProgressThrottle } from '../server/rpc/progress-throttle.js';
+export async function handleRequest(req) {
+    let profiler;
+    let transport;
+    try {
+        const rawData = req.data?.toString();
+        // Duplex stream request: metadata arrives as the first chunk on the
+        // request stream (client used createRequestStream instead of send).
+        if (!rawData) {
+            await handleDuplexRequest(req);
+            return;
+        }
+        // Timing runs unconditionally since we can't know if the client
+        // requested profiling until after parsing.
+        const parseStart = nowMs();
+        const jsonData = JSON.parse(rawData);
+        const jsonParseMs = nowMs() - parseStart;
+        // Internal control messages bypass the engine.
+        if (isInitConfigMessage(jsonData)) {
+            handleInitConfig(req, jsonData);
+            return;
+        }
+        if (isShutdownMessage(jsonData)) {
+            await handleShutdown(req);
+            return;
+        }
+        const { data: cleanData, profilingMeta } = extractProfilingMeta(jsonData);
+        profiler = createServerProfiler(profilingMeta);
+        profiler.markRequestParsed(jsonParseMs);
+        // The engine validates, defaults, and gates the request; the worker only
+        // frames the reply. Profiling meta rides on a symbol key the engine reads.
+        const request = cleanData;
+        attachProfilingMetaToRequest(request, profilingMeta);
+        transport = dispatchTransport(request);
+        if (transport === 'stream' || transport === 'progress') {
+            await streamToWire(req, request, profiler, transport === 'progress');
+        }
+        else if (transport === 'duplex') {
+            throw new PluginHandlerTypeMismatchError(request.type, 'reply or stream', 'duplex');
+        }
+        else {
+            profiler.startHandler();
+            const response = await send(request);
+            profiler.endHandler();
+            req.reply(profiler.serialize(response, true), 'utf-8');
+        }
+    }
+    catch (error) {
+        if (transport === 'stream' || transport === 'progress') {
+            sendStreamErrorResponse(req.createResponseStream(), error, profiler);
+        }
+        else {
+            sendErrorResponse(req, error, profiler);
+        }
+    }
+}
+async function streamToWire(req, request, profiler, throttleProgress) {
+    const wire = req.createResponseStream();
+    profiler.startHandler();
+    let sentFinalChunk = false;
+    // A progress stream (a reply op that streams because of `withProgress`) can
+    // emit hundreds of updates, so batch them on a time window before writing to
+    // keep IPC and UI churn down. Native data streams like completion tokens pass
+    // through immediately and are never throttled.
+    const throttle = throttleProgress
+        ? createProgressThrottle((updates) => {
+            wire.write(updates.map((u) => profiler.serialize(u, false)).join('\n') + '\n', 'utf-8');
+        })
+        : undefined;
+    try {
+        for await (const response of stream(request)) {
+            if (isTerminalChunk(response)) {
+                throttle?.flush();
+                profiler.endHandler();
+                wire.write(profiler.serialize(response, true) + '\n', 'utf-8');
+                sentFinalChunk = true;
+            }
+            else if (throttle) {
+                throttle.push(response);
+            }
+            else {
+                wire.write(profiler.serialize(response, false) + '\n', 'utf-8');
+            }
+        }
+        if (!sentFinalChunk) {
+            throttle?.flush();
+            profiler.endHandler();
+            const trailer = profiler.serialize();
+            if (trailer) {
+                wire.write(trailer + '\n', 'utf-8');
+            }
+        }
+        wire.end();
+    }
+    catch (error) {
+        throttle?.flush();
+        profiler.endHandler();
+        sendStreamErrorResponse(wire, error, profiler);
+    }
+}
+async function handleDuplexRequest(req) {
+    const rpcInput = req.createRequestStream();
+    const rpcOutput = req.createResponseStream();
+    let profiler;
+    try {
+        const firstChunk = await new Promise((resolve, reject) => {
+            const onData = (data) => {
+                rpcInput.off('error', onError);
+                rpcInput.pause();
+                resolve(data);
+            };
+            const onError = (err) => {
+                rpcInput.off('data', onData);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            };
+            rpcInput.once('data', onData);
+            rpcInput.once('error', onError);
+        });
+        const parseStart = nowMs();
+        const jsonData = JSON.parse(firstChunk.toString());
+        const jsonParseMs = nowMs() - parseStart;
+        const { data: cleanData, profilingMeta } = extractProfilingMeta(jsonData);
+        profiler = createServerProfiler(profilingMeta);
+        profiler.markRequestParsed(jsonParseMs);
+        const request = cleanData;
+        attachProfilingMetaToRequest(request, profilingMeta);
+        const session = await duplex(request);
+        // Feed the remaining RPC input into the engine's input stream, and forward
+        // the engine's newline-framed responses back out to the wire.
+        rpcInput.on('data', (chunk) => session.requestStream.write(chunk));
+        rpcInput.on('end', () => session.requestStream.end());
+        rpcInput.on('error', () => session.requestStream.destroy());
+        rpcInput.resume();
+        profiler.startHandler();
+        for await (const chunk of session.responseStream) {
+            rpcOutput.write(chunk, 'utf-8');
+        }
+        profiler.endHandler();
+        // Emit the profiler trailer on its own line after @qvac/inference's newline-framed
+        // responses, so the client's duplexProfiled sees server metadata like the
+        // reply and stream paths do.
+        const trailer = profiler.serialize();
+        if (trailer) {
+            rpcOutput.write(trailer + '\n', 'utf-8');
+        }
+        rpcOutput.end();
+    }
+    catch (error) {
+        rpcInput.destroy();
+        sendStreamErrorResponse(rpcOutput, error, profiler);
+    }
+}
+function attachProfilingMetaToRequest(request, profilingMeta) {
+    if (!profilingMeta)
+        return;
+    Object.defineProperty(request, PROFILING_KEY, {
+        value: profilingMeta,
+        enumerable: false,
+        configurable: true,
+        writable: false
+    });
+}
+function extractProfilingMeta(data) {
+    if (!data || typeof data !== 'object' || !(PROFILING_KEY in data)) {
+        return { data, profilingMeta: undefined };
+    }
+    const obj = data;
+    const { [PROFILING_KEY]: meta, ...rest } = obj;
+    return {
+        data: rest,
+        profilingMeta: meta
+    };
+}

package/dist/src/worker/handler-utils.d.ts

@@ -0,0 +1,16 @@
+import { type QvacConfig, type RuntimeContext } from '@qvac/inference/surface';
+import type RPC from 'bare-rpc';
+type InitConfigMessage = {
+    type: '__init_config';
+    config: QvacConfig;
+    runtimeContext?: RuntimeContext;
+};
+export declare function isInitConfigMessage(data: unknown): data is InitConfigMessage;
+export declare function handleInitConfig(req: RPC.IncomingRequest, data: InitConfigMessage): void;
+type ShutdownMessage = {
+    type: '__shutdown__';
+};
+export declare function isShutdownMessage(data: unknown): data is ShutdownMessage;
+export declare function handleShutdown(req: RPC.IncomingRequest): Promise<void>;
+export {};
+//# sourceMappingURL=handler-utils.d.ts.map

package/dist/src/worker/handler-utils.js

@@ -0,0 +1,41 @@
+import {} from '@qvac/inference/surface';
+import { setConfig, setRuntimeContext } from '@qvac/inference/engine';
+export function isInitConfigMessage(data) {
+    return (typeof data === 'object' && data !== null && 'type' in data && data.type === '__init_config');
+}
+export function handleInitConfig(req, data) {
+    try {
+        if (data.config) {
+            setConfig(data.config);
+        }
+        if (data.runtimeContext) {
+            setRuntimeContext(data.runtimeContext);
+        }
+        req.reply(JSON.stringify({ success: true }), 'utf-8');
+    }
+    catch (error) {
+        req.reply(JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+        }), 'utf-8');
+    }
+}
+export function isShutdownMessage(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'type' in data &&
+        data.type === '__shutdown__');
+}
+export async function handleShutdown(req) {
+    try {
+        const { cleanupForTerminate } = await import('./lifecycle.js');
+        await cleanupForTerminate();
+        req.reply(JSON.stringify({ success: true }), 'utf-8');
+    }
+    catch (error) {
+        req.reply(JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+        }), 'utf-8');
+    }
+}

package/dist/src/worker/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Default worker entry point that registers ALL built-in plugins.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/worker/index.js

@@ -0,0 +1,45 @@
+/**
+ * Default worker entry point that registers ALL built-in plugins.
+ */
+import { initializeWorker, ensureRPCSetup } from './lifecycle.js';
+import { getServerLogger } from '../logging/index.js';
+import { registerPlugins } from '@qvac/inference/plugins';
+import { llmPlugin } from '@qvac/inference/llamacpp-completion/plugin';
+import { embeddingsPlugin } from '@qvac/inference/llamacpp-embedding/plugin';
+import { whisperPlugin } from '@qvac/inference/whispercpp-transcription/plugin';
+import { bciPlugin } from '@qvac/inference/bci-whispercpp-transcription/plugin';
+import { parakeetPlugin } from '@qvac/inference/parakeet-transcription/plugin';
+import { nmtPlugin } from '@qvac/inference/nmtcpp-translation/plugin';
+import { ttsPlugin } from '@qvac/inference/tts-ggml/plugin';
+import { ocrPlugin } from '@qvac/inference/ggml-ocr/plugin';
+import { diffusionPlugin } from '@qvac/inference/sdcpp-generation/plugin';
+import { audioGenPlugin } from '@qvac/inference/audiogen-ggml/plugin';
+import { vlaPlugin } from '@qvac/inference/ggml-vla/plugin';
+import { classificationPlugin } from '@qvac/inference/ggml-classification/plugin';
+const { hasRPCConfig } = initializeWorker();
+const logger = getServerLogger();
+logger.info('🐻 Hello from Bare');
+registerPlugins([
+    llmPlugin,
+    embeddingsPlugin,
+    whisperPlugin,
+    bciPlugin,
+    parakeetPlugin,
+    nmtPlugin,
+    ttsPlugin,
+    ocrPlugin,
+    diffusionPlugin,
+    audioGenPlugin,
+    vlaPlugin,
+    classificationPlugin
+]);
+logger.info(hasRPCConfig
+    ? 'Parsed RPC configuration from arguments'
+    : 'Using default configuration (direct mode)');
+// Auto-setup RPC only if we successfully parsed RPC configuration
+if (hasRPCConfig) {
+    ensureRPCSetup();
+}
+else {
+    logger.info('Running in direct mode - RPC setup will be lazy');
+}

package/dist/src/worker/legacy-worker-entry.d.ts

@@ -0,0 +1,2 @@
+import './index.js';
+//# sourceMappingURL=legacy-worker-entry.d.ts.map

package/dist/src/worker/legacy-worker-entry.js

@@ -0,0 +1,3 @@
+import './index.js';
+import { deprecate } from '../deprecate.js';
+deprecate('worker-entry', "'@qvac/sdk/dist/server/worker.js' is deprecated; use '@qvac/sdk/dist/src/worker/index.js'.");

package/dist/src/worker/lifecycle.d.ts

@@ -0,0 +1,23 @@
+export declare function initializeWorker(): {
+    hasRPCConfig: boolean;
+};
+export declare function ensureRPCSetup(): void;
+export declare function isWorkerInitialized(): boolean;
+export type WorkerShutdownReason = 'signal' | 'rpc-close' | 'uncaught-exception' | 'unhandled-rejection' | 'ipc-disconnect';
+/**
+ * Pre-terminate cleanup, callable while the worker is still alive.
+ *
+ * On platforms where the worker lives in the same OS process as the JS host
+ * (i.e. mobile via react-native-bare-kit Worklet), `Bare.exit()` would kill the
+ * entire app. This path runs the engine's cleanup (models, swarm, RAG,
+ * downloads, registry client, plugin/addon registries) without releasing the
+ * worker lock or exiting, leaving the caller (typically the SDK client about to
+ * call `worklet.terminate()`) responsible for tearing the worker down.
+ *
+ * Critical for clean termination: addons hold static state with js_ref_t
+ * handles into the current V8 isolate; without this cleanup, those refs survive
+ * into the next worklet's isolate and crash on first access.
+ */
+export declare function cleanupForTerminate(): Promise<void>;
+export declare function shutdownWorker(reason: WorkerShutdownReason): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map