@qvac/harness 0.3.3 → 0.5.0

package/dist-lib/lib/connect.js

@@ -1,12 +1,14 @@
 import EventEmitter from 'events';
 import fs from 'fs';
+import { z } from 'zod';
 import { settleOnClose } from './rpc-session.js';
 import { harnessClient } from '../spec/calls.js';
 import HRPC from '../spec/hrpc/index.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
+import { readModelSourcePreview } from './capabilities/preview-model-source.js';
 import { hlog } from './log.js';
 import { assertEmbedDevice } from './models/embed-config.js';
-import { errorCode, errorMessage } from './error-fields.js';
+import { errorCode, errorMessage, isRecord } from './guards.js';
 import { pushQueue } from './queue.js';
 import { stageFile, sweepStaging } from './staging.js';
 import { readInstall, readSetup } from './tools/skills/manifest-parse.js';
@@ -18,9 +20,10 @@ export function connectHarness(transport) {
     return new RemoteHarness(transport);
 }
 export function readEmbeddingDeviceResponse(response) {
-    const device = typeof response === 'object' && response !== null ? Reflect.get(response, 'device') : undefined;
-    if (typeof device !== 'string')
+    const device = isRecord(response) ? response.device : undefined;
+    if (typeof device !== 'string') {
         throw new Error('invalid embedding device response');
+    }
     assertEmbedDevice(device);
     return device;
 }
@@ -35,8 +38,9 @@ export class RemoteHarness extends EventEmitter {
         this._transport = transport;
     }
     _ensure() {
-        if (this._closed)
+        if (this._closed) {
             return Promise.reject(died('harness closed'));
+        }
         if (this._session) {
             return this._session.dead
                 ? Promise.reject(died('harness is dead'))
@@ -71,8 +75,9 @@ export class RemoteHarness extends EventEmitter {
         });
         stream.on('close', () => {
             session.dead = true;
-            if (this._closed)
+            if (this._closed) {
                 return;
+            }
             this.emit('status', streamError ? { state: 'died', ...errorDetails(streamError) } : { state: 'died' });
         });
         this._session = session;
@@ -137,8 +142,9 @@ export class RemoteHarness extends EventEmitter {
         let closed = false;
         let received = 0;
         const reclaim = () => {
-            while (staged.length)
-                void fs.promises.unlink(staged.pop()).catch(noop);
+            for (const file of staged.splice(0).reverse()) {
+                void fs.promises.unlink(file).catch(noop);
+            }
         };
         const onAbort = () => duplex?.destroy();
         try {
@@ -156,18 +162,19 @@ export class RemoteHarness extends EventEmitter {
                 if (event.type !== 'content' && event.type !== 'thinking') {
                     hlog('client frame', { type: event.type, n: received });
                 }
-                if (event.type === 'done')
+                if (event.type === 'done') {
                     break;
+                }
                 if (event.type === 'approval-ask') {
                     const callId = event.callId;
                     void Promise.resolve()
                         .then(() => context.approve?.({
                         name: event.name ?? '',
-                        arguments: (event.arguments ?? {}),
+                        arguments: isRecord(event.arguments) ? event.arguments : {},
                         resource: event.resource ?? null,
                         effect: event.effect === 'read' ? 'read' : 'write',
                         intent: event.intent || null,
-                        display: event.display ?? null
+                        display: isToolCallDisplay(event.display) ? event.display : null
                     }))
                         .then((approved) => {
                         if (!closed) {
@@ -185,8 +192,9 @@ export class RemoteHarness extends EventEmitter {
                     const callId = event.callId;
                     void bridgeAttach(event, context.attach)
                         .then((frame) => {
-                        if (!closed)
+                        if (!closed) {
                             duplex.write({ ...frame, callId });
+                        }
                     }, (err) => {
                         if (!closed) {
                             duplex.write({
@@ -203,12 +211,14 @@ export class RemoteHarness extends EventEmitter {
                     const callId = event.callId;
                     void bridgeFetch(event, context, staged)
                         .then((frame) => {
-                        if (closed)
+                        if (closed) {
                             return reclaim();
+                        }
                         duplex.write({ ...frame, callId });
                     }, (err) => {
-                        if (closed)
+                        if (closed) {
                             return reclaim();
+                        }
                         duplex.write({ type: 'fetch-result', callId, message: errorMessage(err) });
                     })
                         .catch((err) => hlog('fetch reply failed', { callId, message: errorMessage(err) }));
@@ -218,11 +228,13 @@ export class RemoteHarness extends EventEmitter {
                     const callId = event.callId;
                     void bridgeDrive(event, context)
                         .then((frame) => {
-                        if (!closed)
+                        if (!closed) {
                             return duplex.write({ ...frame, callId });
+                        }
                         const stagedPath = frame.payload?.path;
-                        if (stagedPath)
+                        if (stagedPath) {
                             void fs.promises.unlink(stagedPath).catch(noop);
+                        }
                     }, (err) => {
                         if (!closed) {
                             duplex.write({
@@ -239,8 +251,9 @@ export class RemoteHarness extends EventEmitter {
                     const callId = event.callId;
                     void bridgeRag(event, context)
                         .then((frame) => {
-                        if (!closed)
+                        if (!closed) {
                             duplex.write({ ...frame, callId });
+                        }
                     }, (err) => {
                         if (!closed) {
                             duplex.write({
@@ -254,39 +267,14 @@ export class RemoteHarness extends EventEmitter {
                     continue;
                 }
                 if (event.type === 'question-ask') {
-                    const callId = event.callId;
-                    const askUser = context.askUser;
-                    if (!askUser) {
-                        if (!closed) {
-                            duplex.write({
-                                type: 'question-result',
-                                callId,
-                                message: 'the host cannot ask questions'
-                            });
-                        }
-                        continue;
-                    }
-                    void Promise.resolve()
-                        .then(() => askUser({
-                        question: event.question ?? '',
-                        ...(Array.isArray(event.options)
-                            ? { options: event.options.map(String) }
-                            : {})
-                    }))
-                        .then((answer) => {
-                        if (!closed) {
-                            duplex.write({ type: 'question-result', callId, answer: answer ?? '' });
-                        }
-                    }, (err) => {
-                        if (!closed) {
-                            duplex.write({
-                                type: 'question-result',
-                                callId,
-                                message: errorMessage(err)
-                            });
+                    answerQuestion(event, {
+                        askUser: context.askUser,
+                        reply: (frame) => {
+                            if (!closed) {
+                                duplex.write(frame);
+                            }
                         }
-                    })
-                        .catch((err) => hlog('question reply failed', { callId, message: errorMessage(err) }));
+                    });
                     continue;
                 }
                 if (event.type === 'progress') {
@@ -294,19 +282,21 @@ export class RemoteHarness extends EventEmitter {
                     continue;
                 }
                 const wire = fromWire(event);
-                if (wire.type === 'aborted')
+                if (wire.type === 'aborted') {
                     emittedAborted = true;
+                }
                 yield wire;
             }
             hlog('client wire ended', { received });
         }
         catch (err) {
             if (context.signal?.aborted) {
-                if (!emittedAborted)
+                if (!emittedAborted) {
                     yield { type: 'aborted' };
+                }
                 return;
             }
-            throw died(`harness died mid-run: ${err.message}`);
+            throw died(`harness died mid-run: ${errorMessage(err)}`);
         }
         finally {
             hlog('client run end', { received, aborted: Boolean(context.signal?.aborted) });
@@ -315,8 +305,9 @@ export class RemoteHarness extends EventEmitter {
             closed = true;
             reclaim();
         }
-        if (context.signal?.aborted && !emittedAborted)
+        if (context.signal?.aborted && !emittedAborted) {
             yield { type: 'aborted' };
+        }
     }
     async *download(context) {
         const { client } = await this._ensure();
@@ -337,25 +328,28 @@ export class RemoteHarness extends EventEmitter {
             context.signal?.addEventListener?.('abort', onAbort, { once: true });
             for await (const event of downloadFrames(stream)) {
                 const wire = fromDownloadWire(event);
-                if (wire.type === 'aborted')
+                if (wire.type === 'aborted') {
                     emittedAborted = true;
+                }
                 yield wire;
             }
         }
         catch (err) {
             if (context.signal?.aborted) {
-                if (!emittedAborted)
+                if (!emittedAborted) {
                     yield { type: 'aborted' };
+                }
                 return;
             }
-            throw died(`harness died mid-download: ${err.message}`);
+            throw died(`harness died mid-download: ${errorMessage(err)}`);
         }
         finally {
             context.signal?.removeEventListener?.('abort', onAbort);
             stream?.destroy();
         }
-        if (context.signal?.aborted && !emittedAborted)
+        if (context.signal?.aborted && !emittedAborted) {
             yield { type: 'aborted' };
+        }
     }
     async embed(context) {
         const { client } = await this._ensure();
@@ -389,8 +383,9 @@ export class RemoteHarness extends EventEmitter {
         const duplex = client.speakStream();
         const pump = (async () => {
             try {
-                for await (const fragment of context.text)
+                for await (const fragment of context.text) {
                     duplex.write({ text: fragment });
+                }
                 duplex.end();
             }
             catch {
@@ -399,12 +394,11 @@ export class RemoteHarness extends EventEmitter {
         })();
         try {
             for await (const frame of frames(duplex)) {
-                const chunk = frame;
-                yield { audio: chunk.audio, sampleRate: chunk.sampleRate };
+                yield { audio: frame.audio, sampleRate: frame.sampleRate };
             }
         }
         finally {
-            await pump.catch(() => { });
+            await pump.catch(noop);
         }
     }
     async getEmbeddingDevice() {
@@ -423,6 +417,10 @@ export class RemoteHarness extends EventEmitter {
         const { client } = await this._ensure();
         await client.setSkillSettings({ entries });
     }
+    async setModelIdleTimeout(ms) {
+        const { client } = await this._ensure();
+        await client.setModelIdleTimeout({ ms });
+    }
     async listManagedSkills() {
         const { client } = await this._ensure();
         const response = await client.listManagedSkills({});
@@ -462,6 +460,14 @@ export class RemoteHarness extends EventEmitter {
         const { client } = await this._ensure();
         await client.setCustomModels({ models: entries });
     }
+    async previewModelSource(context) {
+        const { client } = await this._ensure();
+        const response = await client.previewModelSource({
+            src: context.src,
+            mmprojSrc: context.mmprojSrc
+        });
+        return readModelSourcePreview(response);
+    }
     async skills(agentId, modelName, options) {
         const { client } = await this._ensure();
         const response = await client.skills({
@@ -482,7 +488,7 @@ export class RemoteHarness extends EventEmitter {
                             binary.bin,
                             {
                                 min: minVersion,
-                                ...(binary.command ? { command: binary.command } : {})
+                                command: binary.command || undefined
                             }
                         ]
                     ]
@@ -496,22 +502,20 @@ export class RemoteHarness extends EventEmitter {
                 allowList: skill.allowList ?? [],
                 platform: skill.platforms ?? [],
                 status: parseSkillState(skill.status),
-                ...(skill.requirements
+                requires: skill.requirements
                     ? {
-                        requires: {
-                            bins: binaries.map((binary) => binary.bin),
-                            ...(skill.requirements?.credentials?.length
-                                ? { credentials: skill.requirements.credentials }
-                                : {}),
-                            ...(Object.keys(binMinVersions).length > 0 ? { binMinVersions } : {})
-                        }
+                        bins: binaries.map((binary) => binary.bin),
+                        credentials: skill.requirements.credentials?.length
+                            ? skill.requirements.credentials
+                            : undefined,
+                        binMinVersions: Object.keys(binMinVersions).length > 0 ? binMinVersions : undefined
                     }
-                    : {}),
-                ...(install ? { install } : {}),
-                ...(setup ? { setup } : {}),
-                ...(skill.stub === true ? { stub: true } : {}),
-                ...(skill.minCapabilityProfile ? { minCapabilityProfile: skill.minCapabilityProfile } : {}),
-                ...(skill.emoji ? { emoji: skill.emoji } : {})
+                    : undefined,
+                install,
+                setup,
+                stub: skill.stub === true ? true : undefined,
+                minCapabilityProfile: skill.minCapabilityProfile || undefined,
+                emoji: skill.emoji || undefined
             };
         });
     }
@@ -533,24 +537,25 @@ export class RemoteHarness extends EventEmitter {
         const { client } = await this._ensure();
         await abortable(client.warmModel({
             model: context.model,
-            ...(context.agent ? { agent: knobs(context.agent) } : {})
+            agent: context.agent ? knobs(context.agent) : undefined
         }), context.signal);
     }
     async list(options = {}) {
         const { client } = await this._ensure();
-        const response = (await client.listModels({
+        const response = await client.listModels({
             type: options.type,
             cachedOnly: options.cachedOnly,
             fullRegistry: options.fullRegistry
-        }));
-        return (response.models ?? []).map(({ actualSize, ...row }) => ({
+        });
+        return (response.models ?? []).map(({ actualSize, label, ...row }) => ({
             ...row,
-            ...(actualSize ? { actualSize } : {})
+            actualSize: actualSize || undefined,
+            label: label || undefined
         }));
     }
     async deleteModel(name) {
         const { client } = await this._ensure();
-        const response = (await client.deleteModel({ name }));
+        const response = await client.deleteModel({ name });
         return { name: response.name, removed: response.removed, freedBytes: response.freedBytes };
     }
     async clearKvCache() {
@@ -563,11 +568,13 @@ export class RemoteHarness extends EventEmitter {
         try {
             const { client } = await this._ensure();
             const info = await client.describe({});
-            if (info.supportsKvCacheDeletion !== true)
+            if (info.supportsKvCacheDeletion !== true) {
                 return unsupportedKvCacheDeletion();
+            }
             const response = await call(client);
-            if (response.status === 'success')
+            if (response.status === 'success') {
                 return { status: 'success' };
+            }
             if (response.status === 'failure') {
                 return { status: 'failure', error: response.error ?? 'Harness cache deletion failed' };
             }
@@ -576,13 +583,13 @@ export class RemoteHarness extends EventEmitter {
         catch (error) {
             return {
                 status: 'failure',
-                error: error instanceof Error ? error.message : String(error)
+                error: errorMessage(error)
             };
         }
     }
     async infraModels(profile) {
         const { client } = await this._ensure();
-        const response = (await client.infraModels({ profile }));
+        const response = await client.infraModels({ profile });
         return response.models ?? [];
     }
     async capability() {
@@ -592,16 +599,14 @@ export class RemoteHarness extends EventEmitter {
         return {
             capabilityProfile: response.capabilityProfile,
             recommendedModelName: response.recommendedModelName,
-            ...(memoryBudget
+            memoryBudget: memoryBudget
                 ? {
-                    memoryBudget: {
-                        totalBytes: memoryBudget.totalBytes,
-                        availableBytes: memoryBudget.availableBytes,
-                        source: memoryBudget.source,
-                        ...(memoryBudget.gpuClass ? { gpuClass: memoryBudget.gpuClass } : {})
-                    }
+                    totalBytes: memoryBudget.totalBytes,
+                    availableBytes: memoryBudget.availableBytes,
+                    source: memoryBudget.source,
+                    gpuClass: memoryBudget.gpuClass || undefined
                 }
-                : {})
+                : undefined
         };
     }
     close() {
@@ -611,8 +616,9 @@ export class RemoteHarness extends EventEmitter {
     async describe() {
         const { client } = await this._ensure();
         const describe = client.describe;
-        if (!describe)
+        if (!describe) {
             return null;
+        }
         const info = await describe.call(client, {});
         return {
             toolNames: info?.toolNames ?? [],
@@ -623,12 +629,14 @@ export class RemoteHarness extends EventEmitter {
     }
     async fetchDiagnostics() {
         const session = this._session;
-        if (!session || session.dead)
+        if (!session || session.dead) {
             return null;
+        }
         const client = session.client;
         const diagnostics = client.diagnostics;
-        if (!diagnostics)
+        if (!diagnostics) {
             return null;
+        }
         const snapshot = await diagnostics.call(client, {});
         const device = snapshot?.device;
         return {
@@ -637,7 +645,7 @@ export class RemoteHarness extends EventEmitter {
             sdkLoaded: snapshot?.sdkLoaded ?? false,
             toolNames: snapshot?.toolNames ?? [],
             skills: snapshot?.skills ?? [],
-            ...(device ? { device } : {})
+            device: device || undefined
         };
     }
 }
@@ -647,10 +655,11 @@ function parseSkillState(value) {
 function errorDetails(err) {
     return { error: errorMessage(err), code: errorCode(err) };
 }
+function isToolCallDisplay(value) {
+    return isRecord(value) && typeof value.label === 'string';
+}
 function died(message) {
-    const err = new Error(message);
-    err.code = HARNESS_DIED;
-    return err;
+    return Object.assign(new Error(message), { code: HARNESS_DIED });
 }
 const noop = () => { };
 function abortable(promise, signal) {
@@ -691,8 +700,9 @@ function knobs(agent) {
 }
 async function bridgeAttach(event, attach) {
     try {
-        if (!attach)
+        if (!attach) {
             return { type: 'attach-result', message: 'the host cannot persist attachments' };
+        }
         const bytes = await fs.promises.readFile(event.path ?? '');
         const record = await attach({
             fileName: event.fileName ?? '',
@@ -711,11 +721,12 @@ async function bridgeAttach(event, attach) {
         };
     }
     catch (err) {
-        return { type: 'attach-result', message: err.message };
+        return { type: 'attach-result', message: errorMessage(err) };
     }
     finally {
-        if (event.path)
+        if (event.path) {
             void fs.promises.unlink(event.path).catch(noop);
+        }
     }
 }
 async function bridgeFetch(event, context, staged) {
@@ -726,11 +737,12 @@ async function bridgeFetch(event, context, staged) {
         const metaOnly = event.meta === true;
         const found = await context.fetchAttachment({
             attachmentId: event.attachmentId ?? undefined,
-            ...(metaOnly ? { meta: true } : {}),
+            meta: metaOnly ? true : undefined,
             signal: context.signal
         });
-        if (!found)
+        if (!found) {
             return { type: 'fetch-result' };
+        }
         const size = 'bytes' in found && found.bytes !== null ? found.bytes.byteLength : found.byteLength;
         if (metaOnly) {
             return {
@@ -757,20 +769,55 @@ async function bridgeFetch(event, context, staged) {
         };
     }
     catch (err) {
-        return { type: 'fetch-result', message: err.message };
+        return { type: 'fetch-result', message: errorMessage(err) };
     }
 }
+const DriveRequestSchema = z.discriminatedUnion('op', [
+    z.looseObject({ op: z.literal('entry'), driveKey: z.string(), key: z.string() }),
+    z.looseObject({ op: z.literal('get'), driveKey: z.string(), key: z.string() }),
+    z.looseObject({ op: z.literal('read'), driveKey: z.string(), key: z.string() }),
+    z.looseObject({
+        op: z.literal('list'),
+        driveKey: z.string(),
+        folder: z.string(),
+        skip: z.array(z.string()),
+        limit: z.number(),
+        cursor: z.string().nullable()
+    }),
+    z.looseObject({
+        op: z.literal('write'),
+        driveKey: z.string(),
+        key: z.string(),
+        path: z.string(),
+        executable: z.boolean().optional()
+    })
+]);
 async function bridgeDrive(event, context) {
-    if (!context.driveOp)
+    if (!context.driveOp) {
         return { type: 'drive-result', message: 'the host cannot proxy drives' };
+    }
     try {
-        const payload = await context.driveOp(event.payload);
+        const payload = await context.driveOp(DriveRequestSchema.parse(event.payload));
         return { type: 'drive-result', payload };
     }
     catch (err) {
-        return { type: 'drive-result', message: err instanceof Error ? err.message : String(err) };
+        return { type: 'drive-result', message: errorMessage(err) };
     }
 }
+function answerQuestion(event, { askUser, reply }) {
+    const callId = event.callId;
+    if (!askUser) {
+        reply({ type: 'question-result', callId, message: 'the host cannot ask questions' });
+        return;
+    }
+    void Promise.resolve()
+        .then(() => askUser({
+        question: event.question ?? '',
+        options: Array.isArray(event.options) ? event.options.map(String) : undefined
+    }))
+        .then((answer) => reply({ type: 'question-result', callId, answer: answer ?? '' }), (err) => reply({ type: 'question-result', callId, message: errorMessage(err) }))
+        .catch((err) => hlog('question reply failed', { callId, message: errorMessage(err) }));
+}
 async function bridgeRag(event, context) {
     if (!context.ragSearch) {
         return {
@@ -786,7 +833,7 @@ async function bridgeRag(event, context) {
         return { type: 'rag-result', result };
     }
     catch (err) {
-        return { type: 'rag-result', message: err instanceof Error ? err.message : String(err) };
+        return { type: 'rag-result', message: errorMessage(err) };
     }
 }
 async function* frames(stream) {
@@ -807,8 +854,9 @@ async function* frames(stream) {
         queue.end();
     });
     yield* queue;
-    if (error)
+    if (error) {
         throw error;
+    }
 }
 async function* downloadFrames(stream) {
     const queue = pushQueue();
@@ -821,6 +869,7 @@ async function* downloadFrames(stream) {
         queue.end();
     });
     yield* queue;
-    if (error)
+    if (error) {
         throw error;
+    }
 }