@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/lib/serve.js

@@ -5,18 +5,21 @@ 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 { encode } from '../spec/hrpc/messages.js';
+import { checkGoal } from './capabilities/tool-turns.js';
 import { isCapability } from './capabilities/invoke.js';
 import { CUSTOM_TASK_TYPES } from './models/model-catalog.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
-import { validateEngineBoot } from './run-log-protocol.js';
+import { RunLog } from './run-log/index.js';
 import { errorMessage, isRecord } from './guards.js';
 import { hlog } from './log.js';
 import { pushQueue } from './queue.js';
 import { TextCoalescer } from './helpers/text-coalescer.js';
 import { prepareOpenclCache } from './models/opencl-cache.js';
 import { stageFile, sweepStaging } from './staging.js';
+import { sweepSpill } from './spill.js';
 import { readSetup, toWireSetup } from './tools/skills/manifest-parse.js';
-import { packVectors, toDownloadWire, toWire } from './wire.js';
+import { fromKnowledgeUpsertWire, packVectors, toDownloadWire, toKnowledgeUpsertResultWire, toWire } from './wire.js';
 const MODEL_STATUSES = new Set([
     'loading',
     'downloading',
@@ -42,7 +45,7 @@ function isEngineBoot(value) {
         return false;
     }
     try {
-        validateEngineBoot(value);
+        RunLog.validateEngineBoot(value);
         return true;
     }
     catch {
@@ -56,7 +59,7 @@ function isEngineBootEnvelope(value) {
     const counter = (name) => typeof value[name] === 'number' && Number.isSafeInteger(value[name]) && value[name] >= 0;
     const metadata = value.metadata;
     const hasMetadata = metadata === null ||
-        (isRecord(metadata) && metadata.version === 5 && metadata.type === 'metadata');
+        (isRecord(metadata) && metadata.version === RunLog.VERSION && metadata.type === 'metadata');
     return (value.protocolVersion === 1 &&
         counter('length') &&
         counter('nextSeq') &&
@@ -82,6 +85,19 @@ const EMPTY_IDENTITY_FIELDS = new Set([
     'agent.name',
     'agent.bio'
 ]);
+function optionalNumber(value) {
+    return value === undefined || typeof value === 'number';
+}
+function goalFrom(value) {
+    const { objective, rounds, ms, tokens } = value;
+    if (typeof objective !== 'string' ||
+        !optionalNumber(rounds) ||
+        !optionalNumber(ms) ||
+        !optionalNumber(tokens)) {
+        throw new TypeError('Invalid goal');
+    }
+    return { objective, rounds, ms, tokens };
+}
 function startPayloadFrom(value) {
     if (!isRecord(value)) {
         return {};
@@ -130,6 +146,22 @@ function startPayloadFrom(value) {
             throw new TypeError('Invalid run recovery resolution');
         });
     }
+    if (isRecord(value.knowledge)) {
+        const { scopes } = value.knowledge;
+        if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === 'string')) {
+            throw new TypeError('Invalid knowledge grant');
+        }
+        payload.knowledge = { scopes };
+    }
+    if (value.planMode === true) {
+        payload.planMode = true;
+    }
+    if (typeof value.parentRunId === 'string') {
+        payload.parentRunId = value.parentRunId;
+    }
+    if (isRecord(value.goal)) {
+        payload.goal = goalFrom(value.goal);
+    }
     if (value.runLog === null) {
         payload.runLog = null;
     }
@@ -191,6 +223,12 @@ function normalizeAgentKnobs(agent) {
     if (normalized.bio === null || normalized.bio === undefined) {
         delete normalized.bio;
     }
+    if (normalized.handoffs === null || normalized.handoffs === undefined) {
+        delete normalized.handoffs;
+    }
+    if (normalized.model === null || normalized.model === undefined) {
+        delete normalized.model;
+    }
     return normalized;
 }
 function tick() {
@@ -198,6 +236,7 @@ function tick() {
 }
 export function serveHarness(stream, harness) {
     sweepStaging();
+    sweepSpill();
     prepareOpenclCache();
     const rpc = settleOnClose(new HRPC(stream));
     bindApi(rpc, {
@@ -366,6 +405,30 @@ export function serveHarness(stream, harness) {
             }
             return harness.unloadModel({ model });
         },
+        knowledgeUpsert: async (req) => {
+            if (!harness.knowledgeUpsert) {
+                throw unsupportedKnowledge();
+            }
+            return toKnowledgeUpsertResultWire(await harness.knowledgeUpsert(fromKnowledgeUpsertWire(req)));
+        },
+        knowledgeRemove: async ({ artifactId }) => {
+            if (!harness.knowledgeRemove) {
+                throw unsupportedKnowledge();
+            }
+            return harness.knowledgeRemove(artifactId);
+        },
+        knowledgeSearch: async ({ text, scopes, k }) => {
+            if (!harness.knowledgeSearch) {
+                throw unsupportedKnowledge();
+            }
+            return { hits: await harness.knowledgeSearch({ text, scopes, k: k || undefined }) };
+        },
+        knowledgeStatus: async () => {
+            if (!harness.knowledgeStatus) {
+                throw unsupportedKnowledge();
+            }
+            return harness.knowledgeStatus();
+        },
         modelEvents: () => modelEvents(harness),
         completion: completion(harness)
     });
@@ -401,6 +464,9 @@ function toWireSkill(skill) {
         emoji: skill.emoji || undefined
     };
 }
+function unsupportedKnowledge() {
+    return new Error('harness does not support knowledge');
+}
 function unsupportedEmbeddingDeviceControl() {
     return new Error('harness does not support embedding device control');
 }
@@ -437,7 +503,7 @@ function modelEvents(harness) {
             return;
         }
         last = key;
-        const frame = {
+        const frame = encodableModelEvent({
             status: state.status,
             model: state.model,
             percentage,
@@ -446,9 +512,9 @@ function modelEvents(harness) {
             message: state.message,
             catalogChanged,
             loaded
-        };
+        });
         const now = Date.now();
-        if (state.status === 'downloading') {
+        if (frame.status === 'downloading') {
             pendingProgress = frame;
             if (lastProgressAt === 0 || now - lastProgressAt >= DOWNLOAD_PROGRESS_INTERVAL_MS) {
                 flushProgress(now);
@@ -471,6 +537,15 @@ function modelEvents(harness) {
     });
     return stream;
 }
+function encodableModelEvent(frame) {
+    try {
+        encode('@harness/model-event', frame);
+        return frame;
+    }
+    catch (err) {
+        return { status: 'error', message: `cannot encode model event: ${errorMessage(err)}` };
+    }
+}
 function speakStream(harness) {
     return async function* (duplex) {
         if (!harness.speakStream) {
@@ -487,7 +562,14 @@ function speakStream(harness) {
             }
         });
         for await (const chunk of harness.speakStream({ model: '', text })) {
-            yield { audio: chunk.audio, sampleRate: chunk.sampleRate };
+            const frame = { audio: chunk.audio, sampleRate: chunk.sampleRate };
+            try {
+                encode('@harness/speak-response', frame);
+            }
+            catch (err) {
+                throw new Error(`cannot encode speak frame: ${errorMessage(err)}`);
+            }
+            yield frame;
         }
     };
 }
@@ -518,10 +600,10 @@ function completion(harness) {
         const pending = new Map();
         const pendingAttach = new Map();
         const pendingFetch = new Map();
-        const pendingRag = new Map();
         const pendingQuestion = new Map();
         const pendingDrive = new Map();
         const pendingRunLog = new Map();
+        const input = pushQueue();
         const controller = new AbortController();
         let calls = 0;
         let started = false;
@@ -542,10 +624,6 @@ function completion(harness) {
                 reject(new Error('client gone'));
             }
             pendingFetch.clear();
-            for (const { reject } of pendingRag.values()) {
-                reject(new Error('client gone'));
-            }
-            pendingRag.clear();
             for (const { resolve } of pendingQuestion.values()) {
                 resolve(null);
             }
@@ -561,6 +639,7 @@ function completion(harness) {
                 reject(new Error('client gone'));
             }
             pendingRunLog.clear();
+            input.end();
             events.end();
         };
         duplex.on('close', gone);
@@ -627,20 +706,6 @@ function completion(harness) {
                 }), (err) => waiter.reject(err));
                 return;
             }
-            if (frame.type === 'rag-result') {
-                if (typeof frame.callId !== 'string') {
-                    return;
-                }
-                const waiter = pendingRag.get(frame.callId);
-                pendingRag.delete(frame.callId);
-                if (!waiter) {
-                    return;
-                }
-                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') {
                     return;
@@ -675,6 +740,14 @@ function completion(harness) {
                 controller.abort('paused');
                 return;
             }
+            if (frame.type === 'steer' || frame.type === 'follow-up') {
+                void input.push({
+                    mode: frame.type,
+                    text: frame.messages?.[0]?.content ?? '',
+                    id: frame.callId || undefined
+                });
+                return;
+            }
             if (frame.type === 'run-log-result') {
                 if (typeof frame.callId !== 'string') {
                     return;
@@ -697,6 +770,9 @@ function completion(harness) {
             let startPayload;
             try {
                 startPayload = startPayloadFrom(frame.payload);
+                if (startPayload.goal) {
+                    checkGoal(startPayload.goal, frame.responseFormat);
+                }
                 assertEmptyIdentityMarkersMatchFrame(frame, startPayload.explicitEmptyIdentity ?? []);
             }
             catch (err) {
@@ -750,12 +826,21 @@ function completion(harness) {
                 generationParams: frame.generationParams ?? undefined,
                 responseFormat: frame.responseFormat ?? undefined,
                 captureInferenceCalls: frame.captureInferenceCalls ?? undefined,
-                messages: (frame.messages ?? []).map(({ role, content, attachments }) => ({
+                maxToolRounds: frame.maxToolRounds || undefined,
+                knowledge: startPayload.knowledge,
+                planMode: startPayload.planMode,
+                parentRunId: startPayload.parentRunId,
+                goal: startPayload.goal,
+                messages: (frame.messages ?? []).map(({ role, content, attachments, toolCalls, toolCallId, name, id }) => ({
                     role,
                     content,
                     attachments: attachments?.length
                         ? attachments.map(({ path: file }) => ({ path: file }))
-                        : undefined
+                        : undefined,
+                    toolCalls: toolCalls ?? undefined,
+                    toolCallId: toolCallId ?? undefined,
+                    name: name ?? undefined,
+                    id: id || undefined
                 })),
                 toolConfigs: frame.toolConfigs ?? undefined,
                 grantedDirs: frame.grantedDirs ?? undefined,
@@ -780,6 +865,7 @@ function completion(harness) {
                     : undefined,
                 grantedWriteDirs: frame.grantedWriteDirs ?? undefined,
                 signal: controller.signal,
+                input,
                 approve: (call) => new Promise((resolve) => {
                     const callId = String(calls++);
                     pending.set(callId, resolve);
@@ -791,7 +877,8 @@ function completion(harness) {
                         resource: call.resource ?? undefined,
                         effect: call.effect,
                         intent: call.intent ?? undefined,
-                        display: call.display ?? undefined
+                        display: call.display ?? undefined,
+                        question: call.quote ?? undefined
                     };
                     if (call.callId !== undefined || call.round !== undefined) {
                         frame.payload = { callId: call.callId, round: call.round };
@@ -829,13 +916,6 @@ function completion(harness) {
                             meta: meta === true ? true : undefined
                         });
                     }),
-                ragSearch: ({ query, limit }) => controller.signal.aborted
-                    ? Promise.reject(new Error('client gone'))
-                    : new Promise((resolve, reject) => {
-                        const callId = String(calls++);
-                        pendingRag.set(callId, { resolve, reject });
-                        events.push({ type: 'rag-ask', callId, query, limit });
-                    }),
                 progress: (update) => {
                     events.push(update
                         ? { type: 'progress', percentage: update.percentage }
@@ -922,18 +1002,39 @@ function completion(harness) {
                     await text.flush();
                     events.push({ type: 'error', message: errorMessage(err) });
                 }
+                input.end();
                 events.push({ type: 'done' });
                 hlog('wire end', { produced, frames });
                 events.end();
             })();
         });
         for await (const event of events) {
+            try {
+                encode('@harness/completion-event', event);
+            }
+            catch (err) {
+                yield { type: 'error', message: `cannot encode ${event.type} event: ${errorMessage(err)}` };
+                await tick();
+                yield { type: 'done' };
+                await tick();
+                gone();
+                return;
+            }
             yield event;
             await tick();
         }
         hlog('wire handed off');
     };
 }
+function encodableDownloadEvent(wire) {
+    try {
+        encode('@harness/download-event', wire);
+    }
+    catch (err) {
+        throw new Error(`cannot encode ${wire.type} event: ${errorMessage(err)}`);
+    }
+    return wire;
+}
 async function accumulateTextFrame(wire, identity, text) {
     if ((wire.type !== 'content' && wire.type !== 'thinking') || !wire.text) {
         return false;
@@ -990,7 +1091,7 @@ function downloadStream(harness, req) {
                 seed: req.seed,
                 signal: controller.signal
             })) {
-                const wire = toDownloadWire(event);
+                const wire = encodableDownloadEvent(toDownloadWire(event));
                 if (wire.type === 'progress') {
                     queueProgress(wire);
                     continue;

package/dist-lib/lib/skills-host/index.d.ts

@@ -0,0 +1,59 @@
+import type { CompletionSkillEntry } from '../capabilities/skill-entry.ts';
+import type { SkillReadiness, ToolDefinition, ToolExecuteContext } from '../contract/index.ts';
+import type { CredentialEntry, SkillsOptions, SkillWriteResult } from '../contract-types.ts';
+import type { CredentialStoreFn, CredentialStoreValue } from '../tools/skills/auth-resolver.ts';
+import { type ResolvedSkillCatalogEntry } from '../tools/skills/catalog.ts';
+import { type CopyBaseResult, type DeleteOverlayResult, type ManagedSkill, type SkillFileContent } from '../tools/skills/overlay-crud.ts';
+import { type SkillSettingEntry } from '../tools/skills/skill-settings.ts';
+export interface HarnessSkillsOptions extends SkillsOptions {
+    readonly skipBinProbe?: boolean;
+}
+export interface SkillsHostOptions {
+    skillsDir?: string;
+    platform?: string;
+    credentialStore?: CredentialStoreFn;
+    tools(): readonly ToolDefinition[];
+    startPlugins(): Promise<void>;
+}
+export declare class SkillsHost {
+    static readonly BIN_VERSION_PROBE_TTL_MS = 45000;
+    private readonly _skillsDir?;
+    private readonly _platform?;
+    private readonly _credentialStore?;
+    private readonly _tools;
+    private readonly _startPlugins;
+    private _watcher;
+    private _allSkills;
+    private _supportedSkills;
+    private _credentials;
+    private _settings;
+    private _readiness;
+    private _deviceSharedKeys;
+    private _binVersionCache;
+    private _binVersionInflight;
+    constructor(opts: SkillsHostOptions);
+    get names(): string[];
+    open(): Promise<void>;
+    close(): void;
+    publish(skills: readonly SkillReadiness[]): void;
+    setCredentials(entries: ReadonlyArray<CredentialEntry>): void;
+    setSkillSettings(entries: ReadonlyArray<SkillSettingEntry>): void;
+    skillSettings(skill: string, agentId?: string | null): Record<string, string>;
+    listManagedSkills(): Promise<ManagedSkill[]>;
+    readSkillFile(name: string): Promise<SkillFileContent | null>;
+    writeSkillFile(name: string, content: string): Promise<SkillWriteResult>;
+    copyBaseForEdit(name: string): Promise<CopyBaseResult>;
+    deleteOverlaySkill(name: string): Promise<DeleteOverlayResult>;
+    resolveCredential(key: string, ctx?: ToolExecuteContext): Promise<CredentialStoreValue> | CredentialStoreValue;
+    statuses(agentId?: string | null, modelName?: string | null, options?: HarnessSkillsOptions): Promise<ResolvedSkillCatalogEntry[]>;
+    completionSkills(agentId: string | null, model: string): Promise<CompletionSkillEntry[]>;
+    private _currentPlatform;
+    private _installedTools;
+    private _baseDir;
+    private _overlayDir;
+    private _reload;
+    private _filter;
+    private _watch;
+    private _probeBinVersions;
+    private _runBinVersionProbes;
+}