@qvac/harness 0.8.9 → 0.8.10

package/dist-lib/lib/capabilities/completion.js

@@ -1,4 +1,5 @@
 import process from 'process';
+import { HarnessError } from '../errors.js';
 import { contextCandidates } from '../context-window.js';
 import { errorCode, errorMessage, isRecord } from '../guards.js';
 import { bufferBurst } from '../helpers/buffer-burst.js';
@@ -12,7 +13,7 @@ import { clipRawCall, hasMarkupCall, normalizeToolArgs, recoverMarkupToolCalls,
 import { INTENT_PARAM, INTENT_PARAM_DESCRIPTION, takeToolIntent } from '../helpers/tool-intent.js';
 import { HookPipeline } from '../hooks/pipeline.js';
 import { fallbackToolLabel } from '../helpers/tool-label.js';
-import { hlog } from '../log.js';
+import { log } from '../log.js';
 import { resolveLlmGenerationParams } from '../models/llm-presets.js';
 import { toolDialectFor } from '../models/model-catalog.js';
 import { isContextOverflowError, isGrammarOverrunError, isSdkModelWedgedError } from '../models/sdk-faults.js';
@@ -55,7 +56,7 @@ function runWallClockBudgetMs() {
     const ms = Number(process.env.QVAC_RUN_BUDGET_MS);
     return ms > 0 ? ms : RUN_WALL_CLOCK_BUDGET_MS;
 }
-export const CONTEXT_OVERFLOW_MESSAGE = 'This message is too large for the model context window.';
+export { CONTEXT_OVERFLOW_MESSAGE } from '../errors.js';
 const MAX_MUTE_ROUNDS = 1;
 const NARRATED_INTENT = /\b(I['’]ll|I will|Now I|Let me(?! know)|Next,? I)\b[^.!?]*[.!?]?\s*$/i;
 const MAX_WEB_SEARCHES_PER_TURN = 3;
@@ -282,7 +283,7 @@ function deniedCall() {
 async function executeCall(tool, args, { ctx, approve, signal, denied, sources = [], effect: classified, skipApprovals, onToolActivity, intent, display }) {
     const validationError = tool.validate?.(args, ctx);
     if (validationError) {
-        hlog('tool rejected: arguments failed validation', { tool: tool.name });
+        log.info('tool rejected: arguments failed validation', { tool: tool.name });
         return guidanceResult(validationError);
     }
     const refusal = guardToolCall(tool.name, args, {
@@ -290,7 +291,7 @@ async function executeCall(tool, args, { ctx, approve, signal, denied, sources =
         externalWrite: tool.externalWrite === true
     });
     if (refusal) {
-        hlog('tool refused: unverifiable value in payload', { tool: tool.name });
+        log.info('tool refused: unverifiable value in payload', { tool: tool.name });
         onToolActivity?.({
             type: 'tool-activity',
             name: tool.name,
@@ -303,13 +304,13 @@ async function executeCall(tool, args, { ctx, approve, signal, denied, sources =
     }
     const key = callKey(tool.name, args);
     if (denied?.has(key)) {
-        hlog('tool denied already, not asking again', { tool: tool.name });
+        log.info('tool denied already, not asking again', { tool: tool.name });
         return deniedCall();
     }
     const effect = classified ?? tool.effect(args, ctx);
     const resource = tool.resource?.(args, ctx) ?? null;
     const autoRun = effect === 'read' || tool.autoApprove === true || skipApprovals === true;
-    hlog('tool decision', {
+    log.info('tool decision', {
         tool: tool.name,
         effect,
         auto: autoRun,
@@ -326,7 +327,7 @@ async function executeCall(tool, args, { ctx, approve, signal, denied, sources =
                 display: display ?? null
             }), signal)
             : false);
-    hlog(`tool ${approved ? 'approved' : 'denied'}`, { tool: tool.name });
+    log.info(`tool ${approved ? 'approved' : 'denied'}`, { tool: tool.name });
     const decision = toolDecision({
         auto: tool.autoApprove === true || effect === 'read',
         skipAll: skipApprovals === true,
@@ -348,11 +349,11 @@ async function executeCall(tool, args, { ctx, approve, signal, denied, sources =
     let outcome = { kind: 'success' };
     try {
         output = await tool.execute(args, { ...ctx, signal, approval: decision });
-        hlog('tool done', { tool: tool.name });
+        log.debug('tool done', { tool: tool.name });
     }
     catch (err) {
         const message = errorMessage(err);
-        hlog('tool failed', { tool: tool.name, err: message });
+        log.warn('tool failed', { tool: tool.name, err: message });
         output = { error: message, code: errorCode(err) };
         outcome = { kind: 'error', message, error: err };
     }
@@ -524,7 +525,7 @@ async function* runRoundTokens(result, state, { sdk, signal, startInThink = fals
         if (state.overrun) {
             throw state.overrun;
         }
-        hlog('stream ended', { events: tokenEvents, stopToken: state.stopToken });
+        log.info('stream ended', { events: tokenEvents, stopToken: state.stopToken });
         if (state.stopToken) {
             cancelThisRound();
         }
@@ -642,7 +643,7 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
                 };
             }
             const replay = unprovenReplay(state, final);
-            hlog('final', {
+            log.debug('final', {
                 stopReason: final.stopReason,
                 toolCalls: final.toolCalls?.length ?? 0,
                 stopToken: state.stopToken,
@@ -678,7 +679,7 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
                 };
             }
             if (recovered) {
-                hlog('grammar overrun recovered', { round: args.round });
+                log.info('grammar overrun recovered', { round: args.round });
                 return {
                     contentText,
                     final: acceptedFinal(state.rawContentText, state.rawText),
@@ -692,13 +693,13 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
                 throw err;
             }
             if (emitted) {
-                throw new Error(CONTEXT_OVERFLOW_MESSAGE, { cause: err });
+                throw new HarnessError('CONTEXT_WINDOW_EXCEEDED', [], { cause: err });
             }
             lastOverflow = err;
         }
     }
     if (lastOverflow) {
-        throw new Error(CONTEXT_OVERFLOW_MESSAGE, { cause: lastOverflow });
+        throw new HarnessError('CONTEXT_WINDOW_EXCEEDED', [], { cause: lastOverflow });
     }
     throw new Error('context recovery produced no completion candidate');
 }
@@ -997,7 +998,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 promptParts = promptUsageParts({ system, toolSchemas: sdkTools });
                 logSelection();
             }
-            hlog('round start', {
+            log.debug('round start', {
                 round,
                 turns: history.length,
                 tools: sdkTools?.length ?? 0,
@@ -1025,7 +1026,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             }
             history = recovered.history;
             collectStats(stats, final.stats, final.stopReason);
-            hlog('round stats', { round, wallMs: Date.now() - roundStarted, ...final.stats });
+            log.debug('round stats', { round, wallMs: Date.now() - roundStarted, ...final.stats });
             const markup = stripToolResponseBlocks(truncateAtControlToken(final.raw.fullText) || recovered.unproven || '');
             let toolCalls = final.toolCalls?.length
                 ? final.toolCalls
@@ -1040,7 +1041,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                     toolCalls = rescued;
                 }
                 if (toolCalls.length) {
-                    hlog('recovered printed skill load', { round });
+                    log.info('recovered printed skill load', { round });
                 }
             }
             if (!toolCalls.length && enabled.some((tool) => tool.name === SKILL_TOOL_NAME)) {
@@ -1051,7 +1052,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                     nudgedSkills.add(unquoteArg(call.arguments.name));
                 }
                 if (toolCalls.length) {
-                    hlog('recovered skill-named call', { round });
+                    log.info('recovered skill-named call', { round });
                 }
             }
             if (!toolCalls.length) {
@@ -1061,7 +1062,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 }
                 const spoken = recovered.contentText.trim();
                 if (enabled.length && !narrated && !replay && NARRATED_INTENT.test(spoken)) {
-                    hlog('round narrated a tool call instead of making it', { round });
+                    log.info('round narrated a tool call instead of making it', { round });
                     narrated = true;
                     history = [
                         ...history,
@@ -1075,7 +1076,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                     outcome = 'answered';
                     break;
                 }
-                hlog('round produced no answer', { round, mute });
+                log.info('round produced no answer', { round, mute });
                 history = [
                     ...history,
                     { role: 'assistant', content: spoken },
@@ -1090,7 +1091,10 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             mute = 0;
             narrated = false;
             if (toolCalls.length > MAX_CALLS_PER_ROUND) {
-                hlog('round over the call cap; the rest are dropped', { round, calls: toolCalls.length });
+                log.info('round over the call cap; the rest are dropped', {
+                    round,
+                    calls: toolCalls.length
+                });
                 toolCalls = toolCalls.slice(0, MAX_CALLS_PER_ROUND);
             }
             const resolved = await resolveToolCalls(toolCalls, {
@@ -1161,7 +1165,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 let execution;
                 if (priorFailure) {
                     blockedRepeats++;
-                    hlog('repeat of a call that already failed; answered without running it', {
+                    log.info('repeat of a call that already failed; answered without running it', {
                         tool: call.name,
                         blockedRepeats
                     });
@@ -1169,7 +1173,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 }
                 else if (priorSuccess) {
                     blockedRepeats++;
-                    hlog('repeat of a read that already answered; not run again', {
+                    log.info('repeat of a read that already answered; not run again', {
                         tool: call.name,
                         blockedRepeats
                     });
@@ -1241,7 +1245,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 runOutcomes.record(output, executionOutcome);
                 if (searchCapped) {
                     cappedCalls++;
-                    hlog('web_search capped', { searches: webSearches });
+                    log.info('web_search capped', { searches: webSearches });
                 }
                 else if (tool?.name === WEB_SEARCH_TOOL_NAME &&
                     !rejection &&
@@ -1362,7 +1366,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         }
         said = `${recovered.contentText}\n${answer}`;
         if (!said.trim()) {
-            hlog('degenerate wrap-up', { outcome });
+            log.info('degenerate wrap-up', { outcome });
             yield {
                 type: 'content',
                 text: degenerateAnswer(outcome, history, runOutcomes.facts())

package/dist-lib/lib/capabilities/tool-prompt-log.js

@@ -1,8 +1,8 @@
-import { harnessLogEnabled, hlog } from '../log.js';
+import { log, logEnabled } from '../log.js';
 export function logToolPrompt({ promptPrefix, modelId, cacheKey, agentId, messageCount, responseFormat, tools = [], definitions, activeSkills, skillsSelected, enabledSkills, mentionedSkill, loadedSkills, toolOps }) {
-    if (!harnessLogEnabled())
+    if (!logEnabled('debug'))
         return;
-    hlog('sdk tool definitions', {
+    log.debug('sdk tool definitions', {
         promptPrefix,
         modelId,
         cacheKey: cacheKey ?? null,

package/dist-lib/lib/capabilities/voice.js

@@ -1,7 +1,8 @@
 import b4a from 'b4a';
+import { HarnessError } from '../errors.js';
 import { errorMessage } from '../guards.js';
 import { AbortedError } from '../helpers/race-abort.js';
-import { hlog } from '../log.js';
+import { log } from '../log.js';
 import { buildWavBuffer } from '../wav-encode.js';
 import { normalizeForSpeech } from './speech-text.js';
 export const SUPERTONIC_SAMPLE_RATE = 44100;
@@ -82,7 +83,7 @@ async function readHead(seconds, signal) {
         }
     }
     catch (err) {
-        hlog('audio decode/resample failed', { error: errorMessage(err) });
+        log.warn('audio decode/resample failed', { error: errorMessage(err) });
         return null;
     }
     return head;
@@ -190,7 +191,7 @@ export async function* speakStreamOnce(sdk, modelId, text) {
             session.end();
         }
         catch (err) {
-            hlog('tts stream input failed', { err: errorMessage(err) });
+            log.warn('tts stream input failed', { err: errorMessage(err) });
             inputError = err;
             destroyQuietly(session);
         }
@@ -208,7 +209,7 @@ export async function* speakStreamOnce(sdk, modelId, text) {
             throw inputError;
         }
         if (wrotePronounceable && !yieldedAudio) {
-            throw new Error('Text-to-speech returned no audio.');
+            throw new HarnessError('TTS_NO_AUDIO');
         }
     }
     catch (err) {
@@ -236,7 +237,7 @@ function writeSpeakable(session, fragment) {
 export function speakable(text) {
     const { text: spoken, dropped } = normalizeForSpeech(text);
     if (dropped.length) {
-        hlog('tts dropped unspeakable characters', { chars: [...new Set(dropped)].join('') });
+        log.info('tts dropped unspeakable characters', { chars: [...new Set(dropped)].join('') });
     }
     return spoken;
 }
@@ -251,7 +252,7 @@ export async function speakOnce(sdk, modelId, text) {
         samples.push(sample);
     }
     if (!(await result.done)) {
-        throw new Error('tts synthesis did not complete');
+        throw new HarnessError('TTS_INCOMPLETE');
     }
     return samples;
 }

package/dist-lib/lib/connect.js

@@ -1,12 +1,13 @@
 import EventEmitter from 'events';
 import fs from 'fs';
 import { z } from 'zod';
+import { HarnessError } from './errors.js';
 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 { log } from './log.js';
 import { assertEmbedDevice } from './models/embed-config.js';
 import { addonTaskType } from './models/model-task.js';
 import { errorCode, errorMessage, isRecord } from './guards.js';
@@ -91,7 +92,7 @@ export class RemoteHarness extends EventEmitter {
                 await session.client.setCustomModels({ models: this._customModels });
             }
             catch (err) {
-                hlog('custom model restore failed', { message: errorMessage(err) });
+                log.warn('custom model restore failed', { message: errorMessage(err) });
             }
         }
         return session;
@@ -159,11 +160,11 @@ export class RemoteHarness extends EventEmitter {
                 return;
             }
             context.signal?.addEventListener?.('abort', onAbort, { once: true });
-            hlog('client wire open', { model: context.model, capability: open.capability });
+            log.debug('client wire open', { model: context.model, capability: open.capability });
             for await (const event of frames(duplex)) {
                 received++;
                 if (event.type !== 'content' && event.type !== 'thinking') {
-                    hlog('client frame', { type: event.type, n: received });
+                    log.debug('client frame', { type: event.type, n: received });
                 }
                 if (event.type === 'done') {
                     break;
@@ -188,7 +189,7 @@ export class RemoteHarness extends EventEmitter {
                             duplex.write({ type: 'decision', callId, approved: false });
                         }
                     })
-                        .catch((err) => hlog('approval reply failed', { callId, message: errorMessage(err) }));
+                        .catch((err) => log.warn('approval reply failed', { callId, message: errorMessage(err) }));
                     continue;
                 }
                 if (event.type === 'attach-ask') {
@@ -207,7 +208,7 @@ export class RemoteHarness extends EventEmitter {
                             });
                         }
                     })
-                        .catch((err) => hlog('attach reply failed', { callId, message: errorMessage(err) }));
+                        .catch((err) => log.warn('attach reply failed', { callId, message: errorMessage(err) }));
                     continue;
                 }
                 if (event.type === 'fetch-ask') {
@@ -224,7 +225,7 @@ export class RemoteHarness extends EventEmitter {
                         }
                         duplex.write({ type: 'fetch-result', callId, message: errorMessage(err) });
                     })
-                        .catch((err) => hlog('fetch reply failed', { callId, message: errorMessage(err) }));
+                        .catch((err) => log.warn('fetch reply failed', { callId, message: errorMessage(err) }));
                     continue;
                 }
                 if (event.type === 'drive-ask') {
@@ -247,7 +248,7 @@ export class RemoteHarness extends EventEmitter {
                             });
                         }
                     })
-                        .catch((err) => hlog('drive reply failed', { callId, message: errorMessage(err) }));
+                        .catch((err) => log.warn('drive reply failed', { callId, message: errorMessage(err) }));
                     continue;
                 }
                 if (event.type === 'rag-ask') {
@@ -266,7 +267,7 @@ export class RemoteHarness extends EventEmitter {
                             });
                         }
                     })
-                        .catch((err) => hlog('rag reply failed', { callId, message: errorMessage(err) }));
+                        .catch((err) => log.warn('rag reply failed', { callId, message: errorMessage(err) }));
                     continue;
                 }
                 if (event.type === 'question-ask') {
@@ -290,7 +291,7 @@ export class RemoteHarness extends EventEmitter {
                 }
                 yield wire;
             }
-            hlog('client wire ended', { received });
+            log.info('client wire ended', { received });
         }
         catch (err) {
             if (context.signal?.aborted) {
@@ -302,7 +303,7 @@ export class RemoteHarness extends EventEmitter {
             throw died(`harness died mid-run: ${errorMessage(err)}`);
         }
         finally {
-            hlog('client run end', { received, aborted: Boolean(context.signal?.aborted) });
+            log.debug('client run end', { received, aborted: Boolean(context.signal?.aborted) });
             context.signal?.removeEventListener?.('abort', onAbort);
             duplex?.destroy();
             closed = true;
@@ -705,10 +706,10 @@ function abortable(promise, signal) {
     return new Promise((resolve, reject) => {
         if (signal.aborted) {
             promise.then(noop, noop);
-            reject(new Error('embed aborted'));
+            reject(new HarnessError('EMBED_ABORTED'));
             return;
         }
-        const onAbort = () => reject(new Error('embed aborted'));
+        const onAbort = () => reject(new HarnessError('EMBED_ABORTED'));
         signal.addEventListener?.('abort', onAbort, { once: true });
         promise.then(resolve, reject).finally(() => signal.removeEventListener?.('abort', onAbort));
     });
@@ -853,7 +854,7 @@ function answerQuestion(event, { askUser, reply }) {
         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) }));
+        .catch((err) => log.warn('question reply failed', { callId, message: errorMessage(err) }));
 }
 async function bridgeRag(event, context) {
     if (!context.ragSearch) {
@@ -878,15 +879,15 @@ async function* frames(stream) {
     let error = null;
     stream.on('data', (frame) => queue.push(frame));
     stream.on('end', () => {
-        hlog('client stream event', { event: 'end' });
+        log.debug('client stream event', { event: 'end' });
         queue.end();
     });
     stream.on('close', () => {
-        hlog('client stream event', { event: 'close' });
+        log.debug('client stream event', { event: 'close' });
         queue.end();
     });
     stream.on('error', (err) => {
-        hlog('client stream event', { event: 'error', err: err.message });
+        log.warn('client stream event', { event: 'error', err: err.message });
         error = err;
         queue.end();
     });