@qvac/sdk 0.15.0 → 0.16.0

package/dist/server/rpc/handlers/completion-orchestrate.js

@@ -0,0 +1,190 @@
+import { toolCallbackResultSchema } from '../../../schemas/completion-stream.js';
+import { aggregateEvents } from '../../../utils/aggregate-events.js';
+import { CompletionFailedError } from '../../../utils/errors-server.js';
+import { dispatchPluginStream } from './plugin-dispatch.js';
+const DEFAULT_MAX_TOOL_TURNS = 8;
+// Generous ceiling on one client-side tool execution: long enough for a slow
+// MCP round trip, short enough that a client that stopped reading can't pin a
+// model slot forever.
+const TOOL_RESULT_TIMEOUT_MS = 5 * 60 * 1000;
+// A single tool result is small JSON; anything past this without a newline is a
+// malformed/hostile client trying to grow the buffer without bound. Fail loudly
+// instead of accumulating forever.
+const MAX_TOOL_RESULT_LINE_BYTES = 16 * 1024 * 1024;
+/**
+ * Reads newline-delimited JSON tool results off the duplex request stream
+ * and resolves per-callId waiters. Chunk boundaries don't align with lines,
+ * so a partial tail is buffered until its newline arrives.
+ *
+ * The pump is torn down by `close()` (called from a `finally` when
+ * orchestration ends, however it ends) so the upstream iterator is returned
+ * and the reader stops holding the request stream open.
+ */
+export class ToolResultReader {
+    buffer = '';
+    results = new Map();
+    waiters = new Map();
+    failed;
+    closed = false;
+    iterator;
+    constructor(inputStream) {
+        this.iterator = inputStream[Symbol.asyncIterator]();
+        void this.pump();
+    }
+    async pump() {
+        try {
+            while (!this.closed) {
+                const next = await this.iterator.next();
+                if (next.done)
+                    break;
+                this.buffer += next.value.toString();
+                let nl;
+                while ((nl = this.buffer.indexOf('\n')) !== -1) {
+                    const line = this.buffer.slice(0, nl);
+                    this.buffer = this.buffer.slice(nl + 1);
+                    if (line.trim())
+                        this.accept(line);
+                }
+                if (this.buffer.length > MAX_TOOL_RESULT_LINE_BYTES) {
+                    throw new CompletionFailedError('tool result frame exceeds the maximum size');
+                }
+            }
+            if (!this.closed && this.buffer.trim())
+                this.accept(this.buffer);
+        }
+        catch (error) {
+            this.failWaiters(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    failWaiters(error) {
+        this.failed = error;
+        // Wake every waiter; each rethrows via waitFor's failure check.
+        for (const [callId, resolve] of this.waiters) {
+            this.waiters.delete(callId);
+            resolve({ callId, error: error.message });
+        }
+    }
+    accept(line) {
+        const parsed = toolCallbackResultSchema.parse(JSON.parse(line));
+        const waiter = this.waiters.get(parsed.callId);
+        if (waiter) {
+            this.waiters.delete(parsed.callId);
+            waiter(parsed);
+        }
+        else {
+            this.results.set(parsed.callId, parsed);
+        }
+    }
+    async waitFor(callId, timeoutMs = TOOL_RESULT_TIMEOUT_MS) {
+        const buffered = this.results.get(callId);
+        if (buffered) {
+            this.results.delete(callId);
+            return buffered;
+        }
+        if (this.failed)
+            throw this.failed;
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.waiters.delete(callId);
+                reject(new CompletionFailedError(`tool callback ${callId} timed out`));
+            }, timeoutMs);
+            this.waiters.set(callId, (result) => {
+                clearTimeout(timer);
+                resolve(result);
+            });
+        });
+    }
+    /**
+     * Stop the pump and release the upstream iterator. Idempotent. Pending
+     * waiters are failed so a caller blocked in `waitFor` can't hang after the
+     * stream is torn down.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.buffer = '';
+        this.results.clear();
+        if (!this.failed)
+            this.failWaiters(new CompletionFailedError('tool result stream closed'));
+        void this.iterator.return?.();
+    }
+}
+/**
+ * The orchestration core, pure over its collaborators so it unit-tests
+ * without the plugin registry: runs completion turns, forwards their events
+ * downstream, and when a turn requests tool calls, emits `toolCallback`
+ * frames and blocks on the client's results before starting the next turn
+ * with the extended history.
+ */
+export async function* orchestrateCompletion(request, runTurn, reader) {
+    // Pull the loop bound out of the per-turn base; everything else (including
+    // `requestId`) flows into each inner completionStream turn. Threading the
+    // orchestrate `requestId` down is what makes `cancel({ requestId })` reach
+    // the turn that's currently generating — the expensive part a Stop button
+    // targets. Turns run strictly sequentially: turn N's request-registry entry
+    // is disposed (on the `for await` break below) before turn N+1 calls
+    // `begin(...)`, so reusing the id can't collide in `entries`. A cancel that
+    // lands between turns (during a tool-result wait) is caught by the
+    // registry's cancel-before-begin tripwire and aborts the next turn's
+    // `begin(...)`. Each turn's `history` and `type` are set below.
+    const { maxToolTurns, ...turnBase } = request;
+    const maxTurns = maxToolTurns ?? DEFAULT_MAX_TOOL_TURNS;
+    let history = [...request.history];
+    for (let turn = 0; turn < maxTurns; turn++) {
+        const turnEvents = [];
+        const innerRequest = {
+            ...turnBase,
+            history,
+            type: 'completionStream'
+        };
+        for await (const response of runTurn(innerRequest)) {
+            turnEvents.push(...response.events);
+            yield { type: 'completionOrchestrate', turn, events: response.events };
+            if (response.done)
+                break;
+        }
+        const { toolCalls, rawFullText, contentText, error, cancelled } = aggregateEvents(turnEvents);
+        // Terminal turn: the model answered (or failed/was cancelled) without
+        // requesting tools — the client folds the forwarded events itself.
+        if (error || cancelled || toolCalls.length === 0) {
+            yield { type: 'completionOrchestrate', done: true };
+            return;
+        }
+        // The assistant's tool-call turn goes back verbatim so the model sees
+        // its own call syntax; each result follows as a `tool` message.
+        history = [...history, { role: 'assistant', content: rawFullText ?? contentText }];
+        for (const call of toolCalls) {
+            yield {
+                type: 'completionOrchestrate',
+                turn,
+                toolCallback: { callId: call.id, name: call.name, arguments: call.arguments }
+            };
+            const result = await reader.waitFor(call.id);
+            const content = result.error !== undefined
+                ? JSON.stringify({ error: result.error })
+                : JSON.stringify(result.result ?? null);
+            history = [...history, { role: 'tool', content }];
+        }
+    }
+    // Turn cap reached without a natural end. Emit a terminal done frame with a
+    // stopReason so the client can tell this was truncated (the model still
+    // wanted a tool) rather than a natural finish; the last turn's events carry
+    // whatever the model produced.
+    yield { type: 'completionOrchestrate', done: true, stopReason: 'maxToolTurns' };
+}
+export async function* handleCompletionOrchestrate(request, inputStream) {
+    const reader = new ToolResultReader(inputStream);
+    const runTurn = async function* (innerRequest) {
+        yield* dispatchPluginStream(innerRequest.modelId, 'completionStream', innerRequest);
+    };
+    try {
+        yield* orchestrateCompletion(request, runTurn, reader);
+    }
+    finally {
+        // Tear the reader down however orchestration ends -- natural finish, turn
+        // cap, error, or the client abandoning the stream -- so the pump stops and
+        // the request stream isn't held open.
+        reader.close();
+    }
+}

package/dist/server/rpc/handlers/get-loaded-model-info.js

@@ -1,5 +1,6 @@
 import { getModelEntry } from '../../bare/registry/model-registry.js';
 import { getPlugin } from '../../plugins/registry.js';
+import { detectToolDialectFromName } from '../../utils/tools/index.js';
 import { ModelNotFoundError } from '../../../utils/errors-server.js';
 import { getServerLogger } from '../../../logging/index.js';
 const logger = getServerLogger();
@@ -24,16 +25,21 @@ export function handleGetLoadedModelInfo(request) {
     if (!plugin) {
         logger.warn(`getLoadedModelInfo: no plugin registered for modelType "${entry.local.modelType}" on loaded model "${modelId}"`);
     }
+    const handlers = plugin ? Object.keys(plugin.handlers) : [];
     const info = {
         modelId: entry.id,
         isDelegated: false,
         modelType: entry.local.modelType,
-        handlers: plugin ? Object.keys(plugin.handlers) : [],
+        handlers,
         loadedAt: entry.local.loadedAt,
         ...(plugin && { displayName: plugin.displayName }),
         ...(plugin && { addonPackage: plugin.addonPackage }),
         ...(entry.local.name && { name: entry.local.name }),
-        ...(entry.local.path && { path: entry.local.path })
+        ...(entry.local.path && { path: entry.local.path }),
+        // Same detection the completion normalizer uses, so callers see the dialect it parses.
+        ...(handlers.includes('completionStream') && {
+            toolDialect: detectToolDialectFromName(entry.local.name, entry.local.path)
+        })
     };
     return { type: 'getLoadedModelInfo', info };
 }

package/dist/server/rpc/handlers/index.d.ts

@@ -1,4 +1,5 @@
 import { handleBatchCompletionStream } from './batch-completion-stream';
+import { handleCompletionOrchestrate } from './completion-orchestrate';
 import { handleCompletionStream } from './completion-stream';
 import { handleDownloadAsset } from './download-asset';
 import { handleLoadModel } from './load-model/index';
@@ -34,6 +35,7 @@ export declare const handlers: {
     heartbeat: typeof handleHeartbeat;
     batchCompletionStream: typeof handleBatchCompletionStream;
     completionStream: typeof handleCompletionStream;
+    completionOrchestrate: typeof handleCompletionOrchestrate;
     downloadAsset: typeof handleDownloadAsset;
     deleteCache: typeof handleDeleteCache;
     loadModel: typeof handleLoadModel;

package/dist/server/rpc/handlers/index.js

@@ -1,4 +1,5 @@
 import { handleBatchCompletionStream } from './batch-completion-stream.js';
+import { handleCompletionOrchestrate } from './completion-orchestrate.js';
 import { handleCompletionStream } from './completion-stream.js';
 import { handleDownloadAsset } from './download-asset.js';
 import { handleLoadModel } from './load-model/index.js';
@@ -34,6 +35,7 @@ export const handlers = {
     heartbeat: handleHeartbeat,
     batchCompletionStream: handleBatchCompletionStream,
     completionStream: handleCompletionStream,
+    completionOrchestrate: handleCompletionOrchestrate,
     downloadAsset: handleDownloadAsset,
     deleteCache: handleDeleteCache,
     loadModel: handleLoadModel,

package/dist/server/rpc/method-shapes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Call shape of every RPC method, keyed by the request `type` literal.
+ *
+ * This module must stay free of handler imports: the contract export
+ * (`scripts/export-contract.ts`) loads it under Node, where the handler
+ * graph's native bare-* modules cannot be required. `handler-registry.ts`
+ * is type-bound to this map, so a registry entry whose key or `type`
+ * diverges from it fails to compile.
+ */
+export declare const methodShapes: {
+    readonly batchCompletionStream: "stream";
+    readonly bciTranscribe: "stream";
+    readonly bciTranscribeStream: "duplex";
+    readonly cancel: "reply";
+    readonly classify: "stream";
+    readonly completionOrchestrate: "duplex";
+    readonly completionStream: "stream";
+    readonly deleteCache: "reply";
+    readonly diffusionStream: "stream";
+    readonly downloadAsset: "reply";
+    readonly embed: "reply";
+    readonly finetune: "reply";
+    readonly getLoadedModelInfo: "reply";
+    readonly getModelInfo: "reply";
+    readonly heartbeat: "reply";
+    readonly loadModel: "reply";
+    readonly loggingStream: "stream";
+    readonly modelRegistryGetModel: "reply";
+    readonly modelRegistryList: "reply";
+    readonly modelRegistrySearch: "reply";
+    readonly ocrStream: "stream";
+    readonly pluginInvoke: "reply";
+    readonly pluginInvokeStream: "stream";
+    readonly provide: "reply";
+    readonly rag: "reply";
+    readonly resume: "reply";
+    readonly state: "reply";
+    readonly stopProvide: "reply";
+    readonly suspend: "reply";
+    readonly textToSpeech: "stream";
+    readonly textToSpeechStream: "duplex";
+    readonly transcribe: "stream";
+    readonly transcribeStream: "duplex";
+    readonly translate: "stream";
+    readonly unloadModel: "reply";
+    readonly upscaleStream: "stream";
+    readonly videoStream: "stream";
+};
+export type MethodName = keyof typeof methodShapes;
+export type MethodCallShape = (typeof methodShapes)[MethodName];
+//# sourceMappingURL=method-shapes.d.ts.map

package/dist/server/rpc/method-shapes.js

@@ -0,0 +1,48 @@
+/**
+ * Call shape of every RPC method, keyed by the request `type` literal.
+ *
+ * This module must stay free of handler imports: the contract export
+ * (`scripts/export-contract.ts`) loads it under Node, where the handler
+ * graph's native bare-* modules cannot be required. `handler-registry.ts`
+ * is type-bound to this map, so a registry entry whose key or `type`
+ * diverges from it fails to compile.
+ */
+export const methodShapes = {
+    batchCompletionStream: 'stream',
+    bciTranscribe: 'stream',
+    bciTranscribeStream: 'duplex',
+    cancel: 'reply',
+    classify: 'stream',
+    completionOrchestrate: 'duplex',
+    completionStream: 'stream',
+    deleteCache: 'reply',
+    diffusionStream: 'stream',
+    downloadAsset: 'reply',
+    embed: 'reply',
+    finetune: 'reply',
+    getLoadedModelInfo: 'reply',
+    getModelInfo: 'reply',
+    heartbeat: 'reply',
+    loadModel: 'reply',
+    loggingStream: 'stream',
+    modelRegistryGetModel: 'reply',
+    modelRegistryList: 'reply',
+    modelRegistrySearch: 'reply',
+    ocrStream: 'stream',
+    pluginInvoke: 'reply',
+    pluginInvokeStream: 'stream',
+    provide: 'reply',
+    rag: 'reply',
+    resume: 'reply',
+    state: 'reply',
+    stopProvide: 'reply',
+    suspend: 'reply',
+    textToSpeech: 'stream',
+    textToSpeechStream: 'duplex',
+    transcribe: 'stream',
+    transcribeStream: 'duplex',
+    translate: 'stream',
+    unloadModel: 'reply',
+    upscaleStream: 'stream',
+    videoStream: 'stream'
+};

package/dist/server/rpc/profiling/operation-metrics.js

@@ -233,6 +233,16 @@ registerOperationMetrics({
         const gauges = {};
         if (res.stats.generationMs !== undefined)
             gauges['generationMs'] = res.stats.generationMs;
+        if (res.stats.conditionerMs !== undefined)
+            gauges['conditionerMs'] = res.stats.conditionerMs;
+        if (res.stats.denoiseMs !== undefined)
+            gauges['denoiseMs'] = res.stats.denoiseMs;
+        if (res.stats.vaeMs !== undefined)
+            gauges['vaeMs'] = res.stats.vaeMs;
+        if (res.stats.postProcessMs !== undefined)
+            gauges['postProcessMs'] = res.stats.postProcessMs;
+        if (res.stats.stepsPerSecond !== undefined)
+            gauges['stepsPerSecond'] = res.stats.stepsPerSecond;
         if (res.stats.totalSteps !== undefined)
             gauges['totalSteps'] = res.stats.totalSteps;
         if (res.stats.totalImages !== undefined)
@@ -252,6 +262,16 @@ registerOperationMetrics({
         const gauges = {};
         if (res.stats.generationMs !== undefined)
             gauges['generationMs'] = res.stats.generationMs;
+        if (res.stats.conditionerMs !== undefined)
+            gauges['conditionerMs'] = res.stats.conditionerMs;
+        if (res.stats.denoiseMs !== undefined)
+            gauges['denoiseMs'] = res.stats.denoiseMs;
+        if (res.stats.vaeMs !== undefined)
+            gauges['vaeMs'] = res.stats.vaeMs;
+        if (res.stats.postProcessMs !== undefined)
+            gauges['postProcessMs'] = res.stats.postProcessMs;
+        if (res.stats.stepsPerSecond !== undefined)
+            gauges['stepsPerSecond'] = res.stats.stepsPerSecond;
         if (res.stats.totalSteps !== undefined)
             gauges['totalSteps'] = res.stats.totalSteps;
         if (res.stats.totalVideos !== undefined)

package/dist/server/utils/cache/auto-history.js

@@ -1,22 +1,26 @@
 import { normalizeAssistantCacheContent } from '../../../utils/cache-normalize.js';
-function normalizeAssistantMessage(message) {
-    if (message.role !== 'assistant') {
-        return message;
+function normalizeCacheMessage(message) {
+    const { attachments, ...normalized } = message;
+    if (message.role === 'assistant') {
+        normalized.content = normalizeAssistantCacheContent(message.content);
     }
-    return { ...message, content: normalizeAssistantCacheContent(message.content) };
+    return {
+        ...normalized,
+        ...(attachments && attachments.length > 0 ? { attachments } : {})
+    };
 }
 export function getAutoCacheLookupHistory(currentHistory) {
     if (currentHistory.length <= 1) {
         return [];
     }
-    return currentHistory.slice(0, -1).map(normalizeAssistantMessage);
+    return currentHistory.slice(0, -1).map(normalizeCacheMessage);
 }
 export function buildAutoCacheSaveHistory(currentHistory, assistantResponse) {
     return [
-        ...currentHistory,
-        {
+        ...currentHistory.map(normalizeCacheMessage),
+        normalizeCacheMessage({
             role: 'assistant',
-            content: normalizeAssistantCacheContent(assistantResponse)
-        }
+            content: assistantResponse
+        })
     ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -194,29 +194,31 @@
     "bare:ensureprebuilds": "bun run bare:ensureprebuilds:llamacpp && bun run bare:ensureprebuilds:whispercpp && bun run bare:ensureprebuilds:embeddings",
     "prepare:husky": "bun run husky",
     "bare:example": "bare ./scripts/bare-bootstrap.js",
+    "contract:export": "tsx ./scripts/export-contract.ts",
+    "contract:check": "tsx ./scripts/export-contract.ts --check",
     "check-models": "tsx ./models/update-models/index.ts --check",
     "check-models:hook": "tsx ./models/update-models/index.ts --check --non-blocking",
-    "update-models": "tsx ./models/update-models/index.ts",
+    "update-models": "tsx ./models/update-models/index.ts && bun run contract:export",
     "changelog:generate": "node ../../scripts/sdk/generate-changelog-sdk-pod.cjs --package=sdk && prettier --write changelog"
   },
   "dependencies": {
-    "@qvac/bci-whispercpp": "^0.4.1",
-    "@qvac/classification-ggml": "^0.10.2",
+    "@qvac/bci-whispercpp": "^0.5.0",
+    "@qvac/classification-ggml": "^0.13.0",
     "@qvac/decoder-audio": "^0.5.0",
-    "@qvac/diffusion-cpp": "^0.13.3",
-    "@qvac/embed-llamacpp": "^0.26.2",
+    "@qvac/diffusion-cpp": "^0.15.0",
+    "@qvac/embed-llamacpp": "^0.28.0",
     "@qvac/error": "^0.1.1",
     "@qvac/langdetect-text": "^0.1.2",
-    "@qvac/llm-llamacpp": "^0.36.3",
+    "@qvac/llm-llamacpp": "^0.38.0",
     "@qvac/logging": "^0.1.0",
-    "@qvac/ocr-ggml": "^0.10.2",
+    "@qvac/ocr-ggml": "^0.12.1",
     "@qvac/rag": "^0.6.4",
     "@qvac/registry-client": "^0.6.1",
-    "@qvac/transcription-parakeet": "^0.9.1",
-    "@qvac/transcription-whispercpp": "^0.11.1",
-    "@qvac/translation-nmtcpp": "^7.2.2",
-    "@qvac/tts-ggml": "^0.4.2",
-    "@qvac/vla-ggml": "^0.11.2",
+    "@qvac/transcription-parakeet": "^0.10.0",
+    "@qvac/transcription-whispercpp": "^0.12.0",
+    "@qvac/translation-nmtcpp": "^8.1.0",
+    "@qvac/tts-ggml": "^0.5.0",
+    "@qvac/vla-ggml": "^0.14.0",
     "bare-abort-controller": "^1.0.0",
     "bare-crypto": "^1.15.0",
     "bare-env": "^3.0.0",
@@ -251,6 +253,7 @@
     "@types/node": "^24.2.1",
     "@types/semver": "^7.7.1",
     "@types/tar-stream": "^3.1.4",
+    "ajv": "8.20.0",
     "bare-process": "^4.4.1",
     "bare-readline": "^1.2.0",
     "bare-stdio": "^1.0.2",