@qvac/harness 0.3.3 → 0.5.0

package/dist-lib/lib/serve.js

@@ -1,12 +1,14 @@
 import { AbortController } from 'bare-abort-controller';
+import b4a from 'b4a';
 import fs from 'fs';
 import { settleOnClose } from './rpc-session.js';
 import { pipeline, Readable } from 'streamx';
 import { bindApi } from '../spec/bind.js';
 import HRPC from '../spec/hrpc/index.js';
 import { isCapability } from './capabilities/invoke.js';
+import { CUSTOM_TASK_TYPES } from './models/model-catalog.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
-import { errorMessage } from './error-fields.js';
+import { errorMessage } from './guards.js';
 import { hlog } from './log.js';
 import { pushQueue } from './queue.js';
 import { TextCoalescer } from './helpers/text-coalescer.js';
@@ -44,6 +46,10 @@ export function serveHarness(stream, harness) {
             await harness.setSkillSettings?.(entries ?? []);
             return { ok: true };
         },
+        setModelIdleTimeout: async ({ ms }) => {
+            await harness.setModelIdleTimeout?.(ms);
+            return { ok: true };
+        },
         listManagedSkills: async () => ({
             skills: (await harness.listManagedSkills?.()) ?? []
         }),
@@ -54,8 +60,9 @@ export function serveHarness(stream, harness) {
                 : { found: false, content: '', origin: '' };
         },
         writeSkillFile: async ({ name, content }) => {
-            if (!harness.writeSkillFile)
+            if (!harness.writeSkillFile) {
                 return { ok: false };
+            }
             return harness.writeSkillFile(name, content);
         },
         copySkillForEdit: async ({ name }) => ({
@@ -65,13 +72,32 @@ export function serveHarness(stream, harness) {
             removed: (await harness.deleteOverlaySkill?.(name))?.removed ?? false
         }),
         setCustomModels: async ({ models }) => {
-            await harness.setCustomModels?.((models ?? []).map(({ name, src, projectionSrc }) => ({
-                name,
-                src,
-                projectionSrc: projectionSrc ?? undefined
-            })));
+            await harness.setCustomModels?.((models ?? []).flatMap((model) => {
+                const { name, src, projectionSrc, taskType, expectedSize, label, contextLength } = model;
+                const known = CUSTOM_TASK_TYPES.find((task) => task === taskType);
+                if (taskType && !known) {
+                    return [];
+                }
+                return [
+                    {
+                        name,
+                        src,
+                        projectionSrc: projectionSrc ?? undefined,
+                        taskType: known,
+                        expectedSize: expectedSize || undefined,
+                        label: label || undefined,
+                        contextLength: contextLength || undefined
+                    }
+                ];
+            }));
             return { ok: true };
         },
+        previewModelSource: async ({ src, mmprojSrc }) => {
+            if (!harness.previewModelSource) {
+                throw new Error('harness does not support previewModelSource');
+            }
+            return harness.previewModelSource({ src: src ?? '', mmprojSrc: mmprojSrc ?? undefined });
+        },
         describe: async () => (await harness.describe?.()) ?? {
             toolNames: [],
             skills: [],
@@ -91,15 +117,17 @@ export function serveHarness(stream, harness) {
             return packVectors(await harness.embed({ model, texts: texts ?? [] }));
         },
         transcribe: async ({ model, audio }) => {
-            if (!harness.transcribe)
+            if (!harness.transcribe) {
                 throw new Error('harness does not support transcribe');
+            }
             return {
-                text: await harness.transcribe({ model: model ?? '', audio: audio ?? Buffer.alloc(0) })
+                text: await harness.transcribe({ model: model ?? '', audio: audio ?? b4a.alloc(0) })
             };
         },
         detectLanguage: async ({ text, topK }) => {
-            if (!harness.detectLanguage)
+            if (!harness.detectLanguage) {
                 throw new Error('harness does not support detectLanguage');
+            }
             const languages = await harness.detectLanguage({
                 text: text ?? '',
                 topK: topK ?? undefined
@@ -113,13 +141,15 @@ export function serveHarness(stream, harness) {
         },
         speakStream: speakStream(harness),
         getEmbeddingDevice: async () => {
-            if (!harness.getEmbeddingDevice)
+            if (!harness.getEmbeddingDevice) {
                 throw unsupportedEmbeddingDeviceControl();
+            }
             return { device: await harness.getEmbeddingDevice() };
         },
         setEmbeddingDevice: async ({ device }) => {
-            if (!harness.setEmbeddingDevice)
+            if (!harness.setEmbeddingDevice) {
                 throw unsupportedEmbeddingDeviceControl();
+            }
             await harness.setEmbeddingDevice(device);
             return { ok: true };
         },
@@ -134,7 +164,7 @@ export function serveHarness(stream, harness) {
         }),
         listModels: async (req) => ({
             models: (await harness.list?.({
-                type: (req?.type || undefined),
+                type: req?.type || undefined,
                 cachedOnly: req?.cachedOnly ?? undefined,
                 fullRegistry: req?.fullRegistry ?? undefined
             })) ?? []
@@ -149,13 +179,15 @@ export function serveHarness(stream, harness) {
             models: (await harness.infraModels?.(profile ?? '')) ?? []
         }),
         capability: async () => {
-            if (!harness.capability)
+            if (!harness.capability) {
                 throw new Error('harness does not support capability');
+            }
             return harness.capability();
         },
         warmModel: async ({ model, agent }) => {
-            if (!harness.warmModel)
+            if (!harness.warmModel) {
                 throw new Error('harness does not support warmModel');
+            }
             await harness.warmModel({ model, agent: agent ?? {} });
             return { ok: true };
         },
@@ -183,19 +215,15 @@ function toWireSkill(skill) {
         allowList: skill.allowList,
         platforms: skill.platform,
         status: skill.status,
-        ...(skill.requires
-            ? {
-                requirements: {
-                    binaries,
-                    credentials: skill.requires.credentials ?? []
-                }
-            }
-            : {}),
-        ...(skill.install ? { install: skill.install } : {}),
-        ...(skill.setup ? { setup: skill.setup, ...(setupV2 ? { setupV2 } : {}) } : {}),
-        ...(skill.stub !== undefined ? { stub: skill.stub } : {}),
-        ...(skill.minCapabilityProfile ? { minCapabilityProfile: skill.minCapabilityProfile } : {}),
-        ...(skill.emoji ? { emoji: skill.emoji } : {})
+        requirements: skill.requires
+            ? { binaries, credentials: skill.requires.credentials ?? [] }
+            : undefined,
+        install: skill.install || undefined,
+        setup: skill.setup || undefined,
+        setupV2,
+        stub: skill.stub,
+        minCapabilityProfile: skill.minCapabilityProfile || undefined,
+        emoji: skill.emoji || undefined
     };
 }
 function unsupportedEmbeddingDeviceControl() {
@@ -230,8 +258,9 @@ function modelEvents(harness) {
             catalogChanged,
             ...loaded.map((entry) => `${entry.model}:${entry.refs}`)
         ].join('\0');
-        if (key === last)
+        if (key === last) {
             return;
+        }
         last = key;
         const frame = {
             status: state.status,
@@ -269,16 +298,18 @@ function modelEvents(harness) {
 }
 function speakStream(harness) {
     return async function* (duplex) {
-        if (!harness.speakStream)
+        if (!harness.speakStream) {
             throw new Error('harness does not support speakStream');
+        }
         const text = pushQueue();
         const end = () => text.end();
         duplex.on('close', end);
         duplex.on('end', end);
         duplex.readStream?.on('close', end);
         duplex.on('data', (frame) => {
-            if (frame.text)
+            if (frame.text) {
                 text.push(frame.text);
+            }
         });
         for await (const chunk of harness.speakStream({ model: '', text })) {
             yield { audio: chunk.audio, sampleRate: chunk.sampleRate };
@@ -286,13 +317,15 @@ function speakStream(harness) {
     };
 }
 function runFrame(harness, frame, context) {
-    if (frame.type !== 'invoke')
+    if (frame.type !== 'invoke') {
         return harness.completion(context);
+    }
     if (!harness.invoke)
         throw new Error('harness does not support invoke');
     const capability = frame.capability ?? '';
-    if (!isCapability(capability))
+    if (!isCapability(capability)) {
         throw new Error(`unknown capability: ${capability}`);
+    }
     return harness.invoke({
         capability,
         args: frame.arguments ?? {},
@@ -318,26 +351,31 @@ function completion(harness) {
         let started = false;
         const gone = () => {
             controller.abort('client gone');
-            for (const resolve of pending.values())
+            for (const resolve of pending.values()) {
                 resolve(false);
+            }
             pending.clear();
             for (const { reject, staged } of pendingAttach.values()) {
                 void fs.promises.unlink(staged).catch(noop);
                 reject(new Error('client gone'));
             }
             pendingAttach.clear();
-            for (const { reject } of pendingFetch.values())
+            for (const { reject } of pendingFetch.values()) {
                 reject(new Error('client gone'));
+            }
             pendingFetch.clear();
-            for (const { reject } of pendingRag.values())
+            for (const { reject } of pendingRag.values()) {
                 reject(new Error('client gone'));
+            }
             pendingRag.clear();
-            for (const { resolve } of pendingQuestion.values())
+            for (const { resolve } of pendingQuestion.values()) {
                 resolve(null);
+            }
             pendingQuestion.clear();
             for (const { reject, path } of pendingDrive.values()) {
-                if (path)
+                if (path) {
                     void fs.promises.unlink(path).catch(noop);
+                }
                 reject(new Error('client gone'));
             }
             pendingDrive.clear();
@@ -348,35 +386,43 @@ function completion(harness) {
         duplex.readStream?.on('close', gone);
         duplex.on('data', (frame) => {
             if (frame.type === 'decision') {
-                if (typeof frame.callId !== 'string')
+                if (typeof frame.callId !== 'string') {
                     return;
+                }
                 pending.get(frame.callId)?.(frame.approved === true);
                 pending.delete(frame.callId);
                 return;
             }
             if (frame.type === 'attach-result') {
-                if (typeof frame.callId !== 'string')
+                if (typeof frame.callId !== 'string') {
                     return;
+                }
                 const waiter = pendingAttach.get(frame.callId);
                 pendingAttach.delete(frame.callId);
-                if (!waiter)
+                if (!waiter) {
                     return;
+                }
                 void fs.promises.unlink(waiter.staged).catch(noop);
-                if (frame.attachment)
+                if (frame.attachment) {
                     waiter.resolve(frame.attachment);
-                else
+                }
+                else {
                     waiter.reject(new Error(frame.message || 'the host failed to store the attachment'));
+                }
                 return;
             }
             if (frame.type === 'fetch-result') {
-                if (typeof frame.callId !== 'string')
+                if (typeof frame.callId !== 'string') {
                     return;
+                }
                 const waiter = pendingFetch.get(frame.callId);
                 pendingFetch.delete(frame.callId);
-                if (!waiter)
+                if (!waiter) {
                     return;
-                if (frame.message)
+                }
+                if (frame.message) {
                     return waiter.reject(new Error(frame.message));
+                }
                 const staged = frame.path;
                 const { fileName, mimeType, attachmentId, size } = frame;
                 if (frame.meta === true) {
@@ -387,8 +433,9 @@ function completion(harness) {
                         byteLength: typeof size === 'number' ? size : 0
                     });
                 }
-                if (!staged)
+                if (!staged) {
                     return waiter.resolve(null);
+                }
                 fs.promises.readFile(staged).then((bytes) => waiter.resolve({
                     id: attachmentId ?? '',
                     fileName: fileName ?? '',
@@ -399,42 +446,52 @@ function completion(harness) {
                 return;
             }
             if (frame.type === 'rag-result') {
-                if (typeof frame.callId !== 'string')
+                if (typeof frame.callId !== 'string') {
                     return;
+                }
                 const waiter = pendingRag.get(frame.callId);
                 pendingRag.delete(frame.callId);
-                if (!waiter)
+                if (!waiter) {
                     return;
-                if (frame.message)
+                }
+                if (frame.message) {
                     return waiter.reject(new Error(frame.message));
+                }
                 waiter.resolve(frame.result ?? { enabled: false, indexEmpty: true, hasKnowledge: false, hits: [] });
             }
             if (frame.type === 'question-result') {
-                if (typeof frame.callId !== 'string')
+                if (typeof frame.callId !== 'string') {
                     return;
+                }
                 const waiter = pendingQuestion.get(frame.callId);
                 pendingQuestion.delete(frame.callId);
-                if (!waiter)
+                if (!waiter) {
                     return;
-                if (frame.message)
+                }
+                if (frame.message) {
                     hlog('question failed', { callId: frame.callId, message: frame.message });
+                }
                 waiter.resolve(frame.answer || null);
                 return;
             }
             if (frame.type === 'drive-result') {
-                if (typeof frame.callId !== 'string')
+                if (typeof frame.callId !== 'string') {
                     return;
+                }
                 const waiter = pendingDrive.get(frame.callId);
                 pendingDrive.delete(frame.callId);
-                if (!waiter)
+                if (!waiter) {
                     return;
-                if (frame.message)
+                }
+                if (frame.message) {
                     return waiter.reject(new Error(frame.message));
-                waiter.resolve((frame.payload ?? {}));
+                }
+                waiter.resolve(frame.payload ?? {});
                 return;
             }
-            if (started || (frame.type !== 'start' && frame.type !== 'invoke'))
+            if (started || (frame.type !== 'start' && frame.type !== 'invoke')) {
                 return;
+            }
             started = true;
             const context = {
                 model: frame.model ?? '',
@@ -447,9 +504,9 @@ function completion(harness) {
                 messages: (frame.messages ?? []).map(({ role, content, attachments }) => ({
                     role,
                     content,
-                    ...(attachments?.length
-                        ? { attachments: attachments.map(({ path: file }) => ({ path: file })) }
-                        : {})
+                    attachments: attachments?.length
+                        ? attachments.map(({ path: file }) => ({ path: file }))
+                        : undefined
                 })),
                 toolConfigs: frame.toolConfigs ?? undefined,
                 grantedDirs: frame.grantedDirs ?? undefined,
@@ -467,7 +524,7 @@ function completion(harness) {
                             pendingDrive.set(callId, {
                                 resolve,
                                 reject,
-                                ...(request.op === 'write' ? { path: request.path } : {})
+                                path: request.op === 'write' ? request.path : undefined
                             });
                             events.push({ type: 'drive-ask', callId, op: request.op, payload: request });
                         })
@@ -516,7 +573,7 @@ function completion(harness) {
                             type: 'fetch-ask',
                             callId,
                             attachmentId,
-                            ...(meta === true ? { meta: true } : {})
+                            meta: meta === true ? true : undefined
                         });
                     }),
                 ragSearch: ({ query, limit }) => controller.signal.aborted
@@ -611,6 +668,13 @@ function downloadStream(harness, req) {
             pendingProgress = null;
             lastProgressAt = at;
         };
+        const queueProgress = (wire) => {
+            const now = Date.now();
+            pendingProgress = wire;
+            if (lastProgressAt === 0 || now - lastProgressAt >= DOWNLOAD_PROGRESS_INTERVAL_MS) {
+                flushProgress(now);
+            }
+        };
         try {
             for await (const event of harness.download({
                 model: req.model,
@@ -620,11 +684,7 @@ function downloadStream(harness, req) {
             })) {
                 const wire = toDownloadWire(event);
                 if (wire.type === 'progress') {
-                    const now = Date.now();
-                    pendingProgress = wire;
-                    if (lastProgressAt === 0 || now - lastProgressAt >= DOWNLOAD_PROGRESS_INTERVAL_MS) {
-                        flushProgress(now);
-                    }
+                    queueProgress(wire);
                     continue;
                 }
                 flushProgress();

package/dist-lib/lib/spawn.js

@@ -3,8 +3,9 @@ import { connectHarness } from './connect.js';
 import { setHarnessLog } from './log.js';
 import { createEmbedConfig } from './models/embed-config.js';
 export function harnessChild(entry, opts) {
-    if (opts.logger)
+    if (opts.logger) {
         setHarnessLog(true);
+    }
     const { runner, skillsDir, gpuStats, wheelsDir, sdkStorage, embedDevice, embedGpuLayers, embedBatchSize, imageModel, imageClamps, musicModel, musicClamps, llm, onIpc, logger = null, ...spec } = opts;
     const embedConfig = createEmbedConfig({
         device: embedDevice,
@@ -36,8 +37,9 @@ export function harnessChild(entry, opts) {
 }
 export function spawnHarness(opts) {
     const logger = opts.logger ?? null;
-    if (logger)
+    if (logger) {
         setHarnessLog(true);
+    }
     const embedConfig = createEmbedConfig({
         device: opts.embedDevice,
         gpuLayers: opts.embedGpuLayers,
@@ -45,7 +47,7 @@ export function spawnHarness(opts) {
     });
     return connectHarness(async () => {
         const { default: Sidecar } = await import('bare-sidecar');
-        const { wrap } = (await import('bare-stow/host'));
+        const { wrap } = await import('bare-stow/host');
         const sidecar = new Sidecar(opts.entry, [
             opts.skillsDir ?? '',
             JSON.stringify(opts.sdkStorage),
@@ -66,8 +68,9 @@ export function spawnHarness(opts) {
             sidecar.once('exit', (code) => resolve(`harness exited (${code}) before ready`));
         });
         const failure = await Promise.race([ipc.ready.then(() => null), died]);
-        if (failure)
+        if (failure) {
             throw new Error(failure);
+        }
         return ipc;
     });
 }

package/dist-lib/lib/tmp-path.d.ts

@@ -1,7 +1,8 @@
-export type UserTmpOptions = {
-    readonly readOwner?: () => {
-        uid: number;
-        username: string;
-    };
-};
+export interface TmpOwner {
+    uid: number;
+    username: string;
+}
+export interface UserTmpOptions {
+    readonly readOwner?: () => TmpOwner;
+}
 export declare function userTmpPath(name: string, opts?: UserTmpOptions): string;

package/dist-lib/lib/tool-call-display.d.ts

@@ -1,8 +1,8 @@
-export type ToolCallDisplay = {
+export interface ToolCallDisplay {
     readonly label: string;
     readonly description?: string;
     readonly iconEmoji?: string;
-};
+}
 export type ToolExecutionOutcome = {
     readonly kind: 'success';
 } | {

package/dist-lib/lib/tools/create-documents.js

@@ -1,19 +1,25 @@
 import { canonicalDenyRoots, defaultRealpath, resolveKey } from './fs/scope.js';
 import { writeText } from './fs/write.js';
+import { errorMessage } from '../guards.js';
 function documentRequests(raw) {
     if (!Array.isArray(raw) || raw.length === 0)
         return null;
     const documents = [];
     for (const entry of raw) {
-        const record = entry;
-        if (typeof record?.path !== 'string' || !record.path.trim())
+        if (!isDocumentRequest(entry))
             return null;
-        if (typeof record.content !== 'string')
-            return null;
-        documents.push({ path: record.path, content: record.content });
+        documents.push({ path: entry.path, content: entry.content });
     }
     return documents;
 }
+function isDocumentRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('path' in value) || typeof value.path !== 'string' || !value.path.trim()) {
+        return false;
+    }
+    return 'content' in value && typeof value.content === 'string';
+}
 export function createCreateDocumentsTool({ realpath = defaultRealpath, deniedRoots } = {}) {
     return {
         name: 'create_documents',
@@ -48,8 +54,9 @@ export function createCreateDocumentsTool({ realpath = defaultRealpath, deniedRo
         },
         resource(args) {
             const documents = documentRequests(args.documents);
-            if (!documents)
+            if (!documents) {
                 return null;
+            }
             const bytes = documents.reduce((sum, doc) => sum + doc.content.length, 0);
             const first = documents[0];
             const suffix = documents.length > 1 ? ` (+${documents.length - 1} more)` : '';
@@ -58,13 +65,14 @@ export function createCreateDocumentsTool({ realpath = defaultRealpath, deniedRo
         async execute(rawArgs, ctx) {
             const roots = ctx?.fsWriteRoots ?? [];
             const documents = documentRequests(rawArgs.documents);
-            if (!documents)
+            if (!documents) {
                 return { error: 'documents must be a non-empty array of { path, content }' };
+            }
             const created = [];
             const failed = [];
             const deny = await canonicalDenyRoots(deniedRoots, realpath);
             for (const doc of documents) {
-                const resolved = await resolveKey(doc.path, roots, realpath, deny);
+                const resolved = await resolveKey(doc.path, roots, { realpath, deny });
                 if ('error' in resolved) {
                     failed.push({ path: doc.path, error: resolved.error });
                     continue;
@@ -78,10 +86,10 @@ export function createCreateDocumentsTool({ realpath = defaultRealpath, deniedRo
                     created.push(doc.path);
                 }
                 catch (err) {
-                    failed.push({ path: doc.path, error: err.message });
+                    failed.push({ path: doc.path, error: errorMessage(err) });
                 }
             }
-            return { created, ...(failed.length ? { failed } : {}) };
+            return { created, failed: failed.length ? failed : undefined };
         }
     };
 }

package/dist-lib/lib/tools/edit-documents.js

@@ -1,28 +1,36 @@
 import b4a from 'b4a';
 import { canonicalDenyRoots, defaultRealpath, resolveKey } from './fs/scope.js';
 import { writeText } from './fs/write.js';
+import { errorMessage } from '../guards.js';
 function editRequests(raw) {
     if (!Array.isArray(raw) || raw.length === 0)
         return null;
     const edits = [];
     for (const entry of raw) {
-        const record = entry;
-        if (typeof record?.path !== 'string' || !record.path.trim())
+        if (!isEditRequest(entry))
             return null;
-        if (typeof record.search !== 'string' || record.search.length === 0)
-            return null;
-        if (typeof record.replace !== 'string')
-            return null;
-        edits.push({ path: record.path, search: record.search, replace: record.replace });
+        edits.push({ path: entry.path, search: entry.search, replace: entry.replace });
     }
     return edits;
 }
+function isEditRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('path' in value) || typeof value.path !== 'string' || !value.path.trim()) {
+        return false;
+    }
+    if (!('search' in value) || typeof value.search !== 'string' || !value.search) {
+        return false;
+    }
+    return 'replace' in value && typeof value.replace === 'string';
+}
 function applyEdits(content, edits) {
     let next = content;
     for (const edit of edits) {
         const first = next.indexOf(edit.search);
-        if (first === -1)
+        if (first === -1) {
             return { error: 'search text not found' };
+        }
         if (next.indexOf(edit.search, first + edit.search.length) !== -1) {
             return { error: 'search text is ambiguous (matches more than once)' };
         }
@@ -66,8 +74,9 @@ export function createEditDocumentsTool({ realpath = defaultRealpath, deniedRoot
         },
         resource(args) {
             const edits = editRequests(args.edits);
-            if (!edits)
+            if (!edits) {
                 return null;
+            }
             const paths = [...new Set(edits.map((edit) => edit.path))];
             const label = paths.slice(0, 3).join(', ');
             return {
@@ -78,8 +87,9 @@ export function createEditDocumentsTool({ realpath = defaultRealpath, deniedRoot
         async execute(rawArgs, ctx) {
             const roots = ctx?.fsWriteRoots ?? [];
             const edits = editRequests(rawArgs.edits);
-            if (!edits)
+            if (!edits) {
                 return { error: 'edits must be a non-empty array of { path, search, replace }' };
+            }
             const byPath = new Map();
             for (const edit of edits) {
                 const list = byPath.get(edit.path) ?? [];
@@ -90,7 +100,7 @@ export function createEditDocumentsTool({ realpath = defaultRealpath, deniedRoot
             const failed = [];
             const deny = await canonicalDenyRoots(deniedRoots, realpath);
             for (const [file, fileEdits] of byPath) {
-                const resolved = await resolveKey(file, roots, realpath, deny);
+                const resolved = await resolveKey(file, roots, { realpath, deny });
                 if ('error' in resolved) {
                     failed.push({ path: file, error: resolved.error });
                     continue;
@@ -113,10 +123,10 @@ export function createEditDocumentsTool({ realpath = defaultRealpath, deniedRoot
                     edited.push(file);
                 }
                 catch (err) {
-                    failed.push({ path: file, error: err.message });
+                    failed.push({ path: file, error: errorMessage(err) });
                 }
             }
-            return { edited, ...(failed.length ? { failed } : {}) };
+            return { edited, failed: failed.length ? failed : undefined };
         }
     };
 }