@qvac/sdk 0.6.1 → 0.7.1

package/dist/server/plugins/registry.js

@@ -0,0 +1,75 @@
+import { pluginDefinitionRuntimeSchema, } from "../../schemas/plugin.js";
+import { PluginAlreadyRegisteredError, PluginDefinitionInvalidError, PluginLoggingInvalidError, } from "../../utils/errors-server.js";
+import { createAddonLoggerCallback } from "../../logging/addon.js";
+const plugins = new Map();
+function getModelTypeForError(plugin) {
+    if (!plugin || typeof plugin !== "object")
+        return "(unknown)";
+    if (!("modelType" in plugin))
+        return "(unknown)";
+    const modelType = plugin.modelType;
+    return typeof modelType === "string" && modelType.length > 0
+        ? modelType
+        : "(unknown)";
+}
+function validatePluginDefinition(plugin) {
+    const result = pluginDefinitionRuntimeSchema.safeParse(plugin);
+    if (result.success)
+        return;
+    const details = result.error.issues
+        .map((i) => `${String(i.path.join("."))}: ${i.message}`)
+        .join(", ");
+    throw new PluginDefinitionInvalidError(getModelTypeForError(plugin), details);
+}
+export function registerPlugin(plugin) {
+    validatePluginDefinition(plugin);
+    if (plugins.has(plugin.modelType)) {
+        throw new PluginAlreadyRegisteredError(plugin.modelType);
+    }
+    // Validate logging module shape if provided
+    if (plugin.logging?.module) {
+        const loggingModule = plugin.logging.module;
+        if (typeof loggingModule["setLogger"] !== "function") {
+            throw new PluginLoggingInvalidError(plugin.modelType, "logging.module must have a setLogger(callback) function");
+        }
+    }
+    plugins.set(plugin.modelType, plugin);
+    if (plugin.logging?.module && plugin.logging?.namespace) {
+        const loggingModule = plugin.logging.module;
+        loggingModule.setLogger(createAddonLoggerCallback(plugin.logging.namespace));
+    }
+}
+export function getPlugin(modelType) {
+    return plugins.get(modelType);
+}
+export function getPluginHandler(modelType, handlerName) {
+    const plugin = plugins.get(modelType);
+    if (!plugin)
+        return undefined;
+    return plugin.handlers[handlerName];
+}
+export function hasPlugin(modelType) {
+    return plugins.has(modelType);
+}
+export function unregisterPlugin(modelType) {
+    const plugin = plugins.get(modelType);
+    if (!plugin)
+        return false;
+    if (plugin.logging?.module) {
+        const loggingModule = plugin.logging.module;
+        loggingModule.releaseLogger?.();
+    }
+    return plugins.delete(modelType);
+}
+export function getAllPlugins() {
+    return Array.from(plugins.values());
+}
+export function clearPlugins() {
+    for (const plugin of plugins.values()) {
+        if (plugin.logging?.module) {
+            const loggingModule = plugin.logging.module;
+            loggingModule.releaseLogger?.();
+        }
+    }
+    plugins.clear();
+}

package/dist/server/rpc/delegate-transport.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Server-side RPC transport for delegated requests.
+ *
+ * This module provides `send` and `stream` functions for server-side
+ * delegation to remote peers (via HyperSwarm RPC).
+ */
+import type RPC from "bare-rpc";
+import { type Request, type Response, type RPCOptions } from "../../schemas/index";
+export declare function send<T extends Request>(request: T, rpc: RPC, options?: RPCOptions): Promise<Response>;
+export declare function stream<T extends Request>(request: T, rpc: RPC, options?: RPCOptions): AsyncGenerator<Response>;
+//# sourceMappingURL=delegate-transport.d.ts.map

package/dist/server/rpc/delegate-transport.js

@@ -0,0 +1,60 @@
+/**
+ * Server-side RPC transport for delegated requests.
+ *
+ * This module provides `send` and `stream` functions for server-side
+ * delegation to remote peers (via HyperSwarm RPC).
+ */
+import { requestSchema, responseSchema, } from "../../schemas/index.js";
+import { withTimeout, withTimeoutStream } from "../../utils/withTimeout.js";
+import { getServerLogger } from "../../logging/index.js";
+import { DelegateProviderError } from "../../utils/errors-server.js";
+const logger = getServerLogger();
+let commandCounter = 0;
+function getNextCommandId() {
+    commandCounter = (commandCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return commandCounter;
+}
+function checkAndThrowError(response) {
+    if (response.type === "error") {
+        throw new DelegateProviderError(response.message || "Unknown provider error", response.code);
+    }
+}
+export async function send(request, rpc, options) {
+    const parsedRequest = requestSchema.parse(request);
+    const req = rpc.request(getNextCommandId());
+    logger.debug("[delegate-transport] Sending:", { type: request.type });
+    const payload = JSON.stringify(parsedRequest);
+    req.send(payload, "utf-8");
+    const response = await withTimeout(req.reply("utf-8"), options?.timeout);
+    const resPayload = responseSchema.parse(JSON.parse(response?.toString() || "{}"));
+    logger.debug("[delegate-transport] Response:", { type: resPayload.type });
+    checkAndThrowError(resPayload);
+    return resPayload;
+}
+export async function* stream(request, rpc, options = {}) {
+    const parsedRequest = requestSchema.parse(request);
+    const req = rpc.request(getNextCommandId());
+    logger.debug("[delegate-transport] Streaming:", { type: request.type });
+    req.send(JSON.stringify(parsedRequest), "utf-8");
+    const responseStream = req.createResponseStream({ encoding: "utf-8" });
+    let buffer = "";
+    async function* processStream() {
+        for await (const chunk of responseStream) {
+            yield chunk;
+        }
+    }
+    const streamWithTimeout = withTimeoutStream(processStream(), options?.timeout);
+    for await (const chunk of streamWithTimeout) {
+        buffer += chunk.toString();
+        // Process complete lines (newline-delimited JSON)
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || ""; // Keep incomplete line in buffer
+        for (const line of lines) {
+            if (line.trim()) {
+                const response = responseSchema.parse(JSON.parse(line));
+                checkAndThrowError(response);
+                yield response;
+            }
+        }
+    }
+}

package/dist/server/rpc/handle-request.d.ts

@@ -1,12 +1,3 @@
 import type RPC from "bare-rpc";
-export type BareRPCRequest = {
-    data: Buffer;
-    reply: (data: string, encoding: BufferEncoding) => void;
-    createResponseStream: () => {
-        write: (data: string, encoding: BufferEncoding) => void;
-        end: () => void;
-        [Symbol.asyncIterator]?: () => AsyncIterator<Buffer>;
-    };
-};
 export declare function handleRequest(req: RPC.IncomingRequest): Promise<void>;
 //# sourceMappingURL=handle-request.d.ts.map

package/dist/server/rpc/handle-request.js

@@ -1,336 +1,28 @@
-import { requestSchema, responseSchema, } from "../../schemas/index.js";
-import { handleCompletionStream } from "./handlers/completion-stream.js";
-import { handleDownloadAsset } from "./handlers/download-asset.js";
-import { handleLoadModel } from "./handlers/load-model/index.js";
-import { handleLoadModelDelegated } from "./handlers/load-model-delegated.js";
-import { handleCompletionStreamDelegated } from "./handlers/completion-stream-delegated.js";
-import { getModelEntry } from "../bare/registry/model-registry.js";
-import { setSDKConfig } from "../bare/registry/config-registry.js";
-import { setRuntimeContext } from "../bare/registry/runtime-context-registry.js";
-import { handleUnloadModel } from "./handlers/unload-model.js";
-import { handleTranscribeStream } from "./handlers/transcribe-stream.js";
-import { handleEmbed } from "./handlers/embed.js";
-import { handleTranslate } from "./handlers/translate.js";
-import { handleLoggingStream } from "./handlers/logging-stream.js";
-import { cancelHandler } from "./handlers/cancelHandler.js";
-import { provideHandler } from "./handlers/provideHandler.js";
-import { stopProvideHandler } from "./handlers/stopProvideHandler.js";
-import { handleRag } from "./handlers/rag.js";
-import { handleDeleteCache } from "./handlers/delete-cache.js";
-import { handleTextToSpeech } from "./handlers/text-to-speech.js";
-import { handleGetModelInfo } from "./handlers/get-model-info.js";
-import { handleOCRStream } from "./handlers/ocr-stream.js";
-import { sendErrorResponse, sendStreamErrorResponse, } from "../error-handlers.js";
-import { NoDataReceivedError, UnknownRequestTypeError, } from "../../utils/errors-client.js";
-import { normalizeModelType } from "../../schemas/index.js";
+import { requestSchema, normalizeModelType, } from "../../schemas/index.js";
 import { resolveModelConfig } from "../bare/registry/model-config-registry.js";
+import { sendErrorResponse } from "../error-handlers.js";
+import { RPCNoDataReceivedError, RPCUnknownRequestTypeError, } from "../../utils/errors-server.js";
+import { registry } from "./handler-registry.js";
+import { executeHandler, handleInitConfig, isInitConfigMessage, } from "./handler-utils.js";
 export async function handleRequest(req) {
     try {
         const rawData = req.data?.toString();
         if (!rawData) {
-            throw new NoDataReceivedError();
+            throw new RPCNoDataReceivedError();
         }
         const jsonData = JSON.parse(rawData);
-        // Handle special internal config initialization message
-        if (jsonData &&
-            typeof jsonData === "object" &&
-            "type" in jsonData &&
-            jsonData.type === "__init_config") {
-            try {
-                const initData = jsonData;
-                if (initData.config) {
-                    setSDKConfig(initData.config);
-                }
-                if (initData.runtimeContext) {
-                    setRuntimeContext(initData.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");
-            }
+        // Handle internal config initialization (bypasses schema)
+        if (isInitConfigMessage(jsonData)) {
+            handleInitConfig(req, jsonData);
             return;
         }
         const processedData = applyDeviceDefaultsToRequest(jsonData);
         const request = requestSchema.parse(processedData);
-        switch (request.type) {
-            case "downloadAsset": {
-                if (request.withProgress) {
-                    const stream = req.createResponseStream();
-                    try {
-                        const response = await handleDownloadAsset(request, (update) => {
-                            const data = JSON.stringify(responseSchema.parse(update));
-                            stream.write(data + "\n", "utf-8");
-                        });
-                        // Send final response
-                        const data = JSON.stringify(responseSchema.parse(response));
-                        stream.write(data + "\n", "utf-8");
-                        stream.end();
-                    }
-                    catch (error) {
-                        sendStreamErrorResponse(stream, error);
-                    }
-                }
-                else {
-                    try {
-                        const response = await handleDownloadAsset(request);
-                        req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                    }
-                    catch (error) {
-                        sendErrorResponse(req, error);
-                    }
-                }
-                break;
-            }
-            case "loadModel": {
-                if (request.withProgress) {
-                    const stream = req.createResponseStream();
-                    try {
-                        // Route to appropriate handler based on delegation
-                        let response;
-                        if (request.delegate) {
-                            response = await handleLoadModelDelegated(request, (update) => {
-                                const data = JSON.stringify(responseSchema.parse(update));
-                                stream.write(data + "\n", "utf-8");
-                            });
-                        }
-                        else {
-                            response = await handleLoadModel(request, (update) => {
-                                const data = JSON.stringify(responseSchema.parse(update));
-                                stream.write(data + "\n", "utf-8");
-                            });
-                        }
-                        // Send final response
-                        const data = JSON.stringify(responseSchema.parse(response));
-                        stream.write(data + "\n", "utf-8");
-                        stream.end();
-                    }
-                    catch (error) {
-                        sendStreamErrorResponse(stream, error);
-                    }
-                }
-                else if (request.delegate) {
-                    try {
-                        const response = await handleLoadModelDelegated(request);
-                        req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                    }
-                    catch (error) {
-                        sendErrorResponse(req, error);
-                    }
-                }
-                else {
-                    // Load without progress/delegate, or reload config
-                    try {
-                        const response = await handleLoadModel(request);
-                        req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                    }
-                    catch (error) {
-                        sendErrorResponse(req, error);
-                    }
-                }
-                break;
-            }
-            case "completionStream": {
-                const stream = req.createResponseStream();
-                try {
-                    // Check if the model is delegated and route accordingly
-                    const entry = getModelEntry(request.modelId);
-                    const handler = entry?.isDelegated
-                        ? handleCompletionStreamDelegated
-                        : handleCompletionStream;
-                    for await (const response of handler(request)) {
-                        const validatedResponse = responseSchema.parse(response);
-                        const data = JSON.stringify(validatedResponse);
-                        stream.write(data + "\n", "utf-8");
-                    }
-                    stream.end();
-                    break;
-                }
-                catch (error) {
-                    sendStreamErrorResponse(stream, error);
-                }
-                break;
-            }
-            case "unloadModel": {
-                const response = await handleUnloadModel(request);
-                req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                break;
-            }
-            case "transcribeStream": {
-                const stream = req.createResponseStream();
-                try {
-                    for await (const response of handleTranscribeStream(request)) {
-                        const validatedResponse = responseSchema.parse(response);
-                        const data = JSON.stringify(validatedResponse);
-                        stream.write(data + "\n", "utf-8");
-                    }
-                    stream.end();
-                }
-                catch (error) {
-                    sendStreamErrorResponse(stream, error);
-                    return;
-                }
-                break;
-            }
-            case "loggingStream": {
-                const stream = req.createResponseStream();
-                try {
-                    for await (const response of handleLoggingStream(request)) {
-                        const validatedResponse = responseSchema.parse(response);
-                        const data = JSON.stringify(validatedResponse);
-                        stream.write(data + "\n", "utf-8");
-                    }
-                    stream.end();
-                }
-                catch (error) {
-                    sendStreamErrorResponse(stream, error);
-                    return;
-                }
-                break;
-            }
-            case "ping": {
-                const res = {
-                    type: "pong",
-                    number: Math.random() * 100,
-                };
-                req.reply(JSON.stringify(res), "utf-8");
-                break;
-            }
-            case "embed": {
-                try {
-                    const response = await handleEmbed(request);
-                    req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                }
-                catch (error) {
-                    sendErrorResponse(req, error);
-                }
-                break;
-            }
-            case "translate": {
-                const stream = req.createResponseStream();
-                try {
-                    for await (const response of handleTranslate(request)) {
-                        const validatedResponse = responseSchema.parse(response);
-                        const data = JSON.stringify(validatedResponse);
-                        stream.write(data + "\n", "utf-8");
-                    }
-                    stream.end();
-                }
-                catch (error) {
-                    sendStreamErrorResponse(stream, error);
-                }
-                break;
-            }
-            case "cancel": {
-                try {
-                    const response = await cancelHandler(request);
-                    req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                }
-                catch (error) {
-                    sendErrorResponse(req, error);
-                }
-                break;
-            }
-            case "provide": {
-                const response = await provideHandler(request);
-                req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                break;
-            }
-            case "stopProvide": {
-                const response = stopProvideHandler(request);
-                req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                break;
-            }
-            case "rag": {
-                // Only ingest, saveEmbeddings, and reindex support progress
-                const supportsProgress = request.operation === "ingest" ||
-                    request.operation === "saveEmbeddings" ||
-                    request.operation === "reindex";
-                const withProgress = supportsProgress && request.withProgress;
-                if (withProgress) {
-                    const stream = req.createResponseStream();
-                    try {
-                        const response = await handleRag(request, (update) => {
-                            const data = JSON.stringify(responseSchema.parse(update));
-                            stream.write(data + "\n", "utf-8");
-                        });
-                        // Send final response
-                        const data = JSON.stringify(responseSchema.parse(response));
-                        stream.write(data + "\n", "utf-8");
-                        stream.end();
-                    }
-                    catch (error) {
-                        sendStreamErrorResponse(stream, error);
-                    }
-                }
-                else {
-                    try {
-                        const response = await handleRag(request);
-                        req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                    }
-                    catch (error) {
-                        sendErrorResponse(req, error);
-                    }
-                }
-                break;
-            }
-            case "deleteCache": {
-                try {
-                    const response = await handleDeleteCache(request);
-                    req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                }
-                catch (error) {
-                    sendErrorResponse(req, error);
-                }
-                break;
-            }
-            case "textToSpeech": {
-                const stream = req.createResponseStream();
-                try {
-                    for await (const response of handleTextToSpeech(request)) {
-                        const validatedResponse = responseSchema.parse(response);
-                        const data = JSON.stringify(validatedResponse);
-                        stream.write(data + "\n", "utf-8");
-                    }
-                    stream.end();
-                }
-                catch (error) {
-                    sendStreamErrorResponse(stream, error);
-                }
-                break;
-            }
-            case "getModelInfo": {
-                try {
-                    const response = await handleGetModelInfo(request);
-                    req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
-                }
-                catch (error) {
-                    sendErrorResponse(req, error);
-                }
-                break;
-            }
-            case "ocrStream": {
-                const stream = req.createResponseStream();
-                try {
-                    for await (const response of handleOCRStream(request)) {
-                        const validatedResponse = responseSchema.parse(response);
-                        const data = JSON.stringify(validatedResponse);
-                        stream.write(data + "\n", "utf-8");
-                    }
-                    stream.end();
-                }
-                catch (error) {
-                    sendStreamErrorResponse(stream, error);
-                }
-                break;
-            }
-            default: {
-                throw new UnknownRequestTypeError();
-            }
+        const entry = registry[request.type];
+        if (!entry) {
+            throw new RPCUnknownRequestTypeError(request.type);
         }
+        await executeHandler(req, request, entry);
     }
     catch (error) {
         sendErrorResponse(req, error);

package/dist/server/rpc/handler-registry.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerEntry } from "./handler-utils";
+export declare const registry: Record<string, HandlerEntry>;
+//# sourceMappingURL=handler-registry.d.ts.map

package/dist/server/rpc/handler-registry.js

@@ -0,0 +1,84 @@
+import {} from "../../schemas/index.js";
+import { handleCompletionStream } from "./handlers/completion-stream.js";
+import { handleDownloadAsset } from "./handlers/download-asset.js";
+import { handleLoadModel } from "./handlers/load-model/index.js";
+import { handleLoadModelDelegated } from "./handlers/load-model-delegated.js";
+import { handleCompletionStreamDelegated } from "./handlers/completion-stream-delegated.js";
+import { getModelEntry } from "../bare/registry/model-registry.js";
+import { handleUnloadModel } from "./handlers/unload-model.js";
+import { handleTranscribeStream } from "./handlers/transcribe-stream.js";
+import { handleEmbed } from "./handlers/embed.js";
+import { handleTranslate } from "./handlers/translate.js";
+import { handleLoggingStream } from "./handlers/logging-stream.js";
+import { cancelHandler } from "./handlers/cancelHandler.js";
+import { provideHandler } from "./handlers/provideHandler.js";
+import { stopProvideHandler } from "./handlers/stopProvideHandler.js";
+import { handleRag } from "./handlers/rag.js";
+import { handleDeleteCache } from "./handlers/delete-cache.js";
+import { handleTextToSpeech } from "./handlers/text-to-speech.js";
+import { handleGetModelInfo } from "./handlers/get-model-info.js";
+import { handleOCRStream } from "./handlers/ocr-stream.js";
+import { handlePing } from "./handlers/ping.js";
+import { handlePluginInvoke, handlePluginInvokeStream, } from "./handlers/plugin-invoke.js";
+import { handleModelRegistryList, handleModelRegistrySearch, handleModelRegistryGetModel, } from "./handlers/registry.js";
+function ragSupportsProgress(request) {
+    if (request.type !== "rag")
+        return false;
+    return ["ingest", "saveEmbeddings", "reindex"].includes(request.operation);
+}
+function isModelDelegated(request) {
+    if (!("modelId" in request))
+        return false;
+    const entry = getModelEntry(request.modelId);
+    return entry?.isDelegated ?? false;
+}
+export const registry = {
+    // Simple Reply handlers
+    ping: { type: "reply", handler: handlePing },
+    unloadModel: { type: "reply", handler: handleUnloadModel },
+    embed: { type: "reply", handler: handleEmbed },
+    cancel: { type: "reply", handler: cancelHandler },
+    provide: { type: "reply", handler: provideHandler },
+    stopProvide: { type: "reply", handler: stopProvideHandler },
+    deleteCache: { type: "reply", handler: handleDeleteCache },
+    getModelInfo: { type: "reply", handler: handleGetModelInfo },
+    pluginInvoke: { type: "reply", handler: handlePluginInvoke },
+    modelRegistryList: { type: "reply", handler: handleModelRegistryList },
+    modelRegistrySearch: { type: "reply", handler: handleModelRegistrySearch },
+    modelRegistryGetModel: {
+        type: "reply",
+        handler: handleModelRegistryGetModel,
+    },
+    // Simple Stream handlers
+    transcribeStream: { type: "stream", handler: handleTranscribeStream },
+    loggingStream: { type: "stream", handler: handleLoggingStream },
+    translate: { type: "stream", handler: handleTranslate },
+    textToSpeech: { type: "stream", handler: handleTextToSpeech },
+    ocrStream: { type: "stream", handler: handleOCRStream },
+    pluginInvokeStream: { type: "stream", handler: handlePluginInvokeStream },
+    // Handlers with delegation support
+    loadModel: {
+        type: "reply",
+        handler: handleLoadModel,
+        delegatedHandler: handleLoadModelDelegated,
+        isDelegated: (r) => r.type === "loadModel" && !!r.delegate,
+        supportsProgress: true,
+    },
+    completionStream: {
+        type: "stream",
+        handler: handleCompletionStream,
+        delegatedHandler: handleCompletionStreamDelegated,
+        isDelegated: isModelDelegated,
+    },
+    // Handlers with progress support
+    downloadAsset: {
+        type: "reply",
+        handler: handleDownloadAsset,
+        supportsProgress: true,
+    },
+    rag: {
+        type: "reply",
+        handler: handleRag,
+        supportsProgress: ragSupportsProgress,
+    },
+};

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

@@ -0,0 +1,22 @@
+import { type QvacConfig, type Request, type Response, type RuntimeContext } from "../../schemas/index";
+import type RPC from "bare-rpc";
+type ReplyHandler = (request: any) => Promise<Response> | Response;
+type StreamHandler = (request: any) => AsyncGenerator<Response>;
+type ProgressHandler = (request: any, onProgress?: (update: Response) => void) => Promise<Response>;
+export type HandlerEntry = {
+    type: "reply" | "stream";
+    handler: ReplyHandler | StreamHandler | ProgressHandler;
+    delegatedHandler?: ReplyHandler | StreamHandler | ProgressHandler;
+    isDelegated?: (request: Request) => boolean;
+    supportsProgress?: boolean | ((request: Request) => boolean);
+};
+export declare function executeHandler(req: RPC.IncomingRequest, request: Request, entry: HandlerEntry): Promise<void>;
+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;
+export {};
+//# sourceMappingURL=handler-utils.d.ts.map