@qvac/harness 0.8.9 → 0.8.11

package/dist-lib/lib/tools/fs/walk.js

@@ -1,7 +1,7 @@
 import { errorMessage } from '../../guards.js';
-import { hlog } from '../../log.js';
+import { log } from '../../log.js';
 import { displayPath } from './scope.js';
-export const WALK_SKIP_DIRS = new Set(['.git', 'node_modules']);
+export const WALK_SKIP_DIRS = new Set(['.git', 'node_modules', '.trash']);
 export const MAX_WALK_ENTRIES = 10_000;
 export const MAX_WALK_MS = 30_000;
 export async function walkFiles(root, folder = '/') {
@@ -29,7 +29,7 @@ export async function walkFiles(root, folder = '/') {
         }
     }
     catch (err) {
-        hlog('warn: walk aborted mid-listing', {
+        log.warn('warn: walk aborted mid-listing', {
             root: displayPath(root, '/'),
             folder,
             visited,

package/dist-lib/lib/tools/generate-image.d.ts

@@ -1,4 +1,5 @@
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { IMAGE_LOAD_STALL_ERROR } from '../errors.ts';
 import type { ToolDefinition } from '../capabilities/completion.ts';
 import type { ModelSrc } from '../models/context.ts';
 import { type ImageClamps } from '../models/model-catalog.ts';
@@ -88,7 +89,7 @@ export interface DiffusionRuntime {
     release(): void;
 }
 export declare function generationPercentTick(onPercent: (percentage: number) => void, encodePhases?: number): (tick: DiffusionTick) => void;
-export declare const IMAGE_LOAD_STALL_ERROR = "image model download stalled";
+export { IMAGE_LOAD_STALL_ERROR };
 export declare function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBeforeLoad, hold, loads, stallMs, ...base }: DiffusionRuntimeOptions): DiffusionRuntime;
 export declare const BUSY_ERROR = "an image generation is already running; try again when it finishes";
 export interface ImageToolError {
@@ -113,4 +114,3 @@ export declare function settingsDimension(value: number | undefined, maxDim?: nu
 export declare function settingsSteps(value: number | undefined, maxSteps?: number): number | undefined;
 export declare function effectiveSteps(parsedSteps: number | undefined, settingsValue: number | undefined, stepsCap: number | undefined): number | undefined;
 export declare function createGenerateImageTool(runtime: DiffusionRuntime, clamps?: ImageClamps): ToolDefinition;
-export {};

package/dist-lib/lib/tools/generate-image.js

@@ -1,4 +1,5 @@
 import ScopeLock from 'scope-lock';
+import { HarnessError, IMAGE_LOAD_STALL_ERROR, isHarnessError } from '../errors.js';
 import { AbortedError, raceAbort } from '../helpers/race-abort.js';
 import { DIFFUSION_CATALOG, imageModelFor } from '../models/model-catalog.js';
 import { createLoadStall } from '../helpers/load-stall.js';
@@ -38,7 +39,7 @@ function diffusionProgressName(set) {
     const entry = DIFFUSION_CATALOG.find((candidate) => candidate.model.src === set.model);
     return entry?.name ?? set.model;
 }
-export const IMAGE_LOAD_STALL_ERROR = 'image model download stalled';
+export { IMAGE_LOAD_STALL_ERROR };
 export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBeforeLoad, hold, loads = createLoadTracker(), stallMs = IMAGE_LOAD_STALL_MS, ...base }) {
     let loading = null;
     let residentFingerprint = null;
@@ -102,7 +103,7 @@ export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBefore
                         config.vaeModelSrc = await resolveModelSrc(sdk, set.vaeModel, 'diffusion');
                     }
                     const modelConfig = Object.keys(config).length ? config : undefined;
-                    const stall = createLoadStall(stallMs, IMAGE_LOAD_STALL_ERROR);
+                    const stall = createLoadStall(stallMs, () => new HarnessError('IMAGE_LOAD_STALLED'));
                     const pending = sdk.loadModel({
                         modelSrc,
                         modelType: 'diffusion',
@@ -118,9 +119,7 @@ export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBefore
                         return { modelId, prediction: set.prediction };
                     }
                     catch (err) {
-                        if (err instanceof Error &&
-                            err.message === IMAGE_LOAD_STALL_ERROR &&
-                            pending.requestId) {
+                        if (isHarnessError(err, 'IMAGE_LOAD_STALLED') && pending.requestId) {
                             void sdk.cancel?.({ requestId: pending.requestId }).catch(noop);
                         }
                         throw err;
@@ -371,7 +370,7 @@ export function createGenerateImageTool(runtime, clamps) {
                 if (err instanceof AbortedError) {
                     return { error: 'image generation canceled' };
                 }
-                if (err instanceof Error && err.message === IMAGE_LOAD_STALL_ERROR) {
+                if (isHarnessError(err, 'IMAGE_LOAD_STALLED')) {
                     return { error: IMAGE_LOAD_STALL_ERROR };
                 }
                 throw err;

package/dist-lib/lib/tools/office.js

@@ -1,4 +1,5 @@
 import b4a from 'b4a';
+import { HarnessError } from '../errors.js';
 import { errorMessage, isRecord } from '../guards.js';
 import { DocsError, docx, pptx, units, xlsx } from '../office/engine/index.js';
 import { stageInputs } from './exec/adapters/python/attachments.js';
@@ -356,7 +357,7 @@ async function attachOutput(job, ctx) {
 function runOp(document, op, input) {
     const method = Reflect.get(document, op.name);
     if (typeof method !== 'function') {
-        throw new Error(`${op.name} is not available on this file`);
+        throw new HarnessError('OFFICE_OP_UNAVAILABLE', [op.name]);
     }
     return Reflect.apply(method, document, opArguments(op.spec, input, units.inches));
 }

package/dist-lib/lib/tools/skill.js

@@ -1,6 +1,7 @@
 import path from 'path';
 import b4a from 'b4a';
 import Localdrive from 'localdrive';
+import { HarnessError } from '../errors.js';
 import { OBSIDIAN_VAULT_MODE_NOTE } from './exec/obsidian/guidance.js';
 import { unquoteArg } from './model-args.js';
 import { credentialRecord } from './skills/auth-resolver.js';
@@ -101,7 +102,7 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
                 return { raw: b4a.toString(buf, 'utf8'), root: root ?? undefined };
             }
         }
-        throw new Error(`ENOENT: ${name}/${file}`);
+        throw new HarnessError('SKILL_FILE_NOT_FOUND', [name, file]);
     }
     return {
         name: 'skill',

package/dist-lib/lib/tools/skills/bundled-dir.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import process from 'process';
+import { HarnessError } from '../../errors.js';
 import { userTmpPath } from '../../tmp-path.js';
 import { hashBundledSkills } from './bundled-hash.js';
 import { SKILLS as BUNDLED_SKILLS } from '@qvac/skills/bundled';
@@ -26,7 +27,7 @@ async function materialize() {
     try {
         await writeTree(staging);
         if (!(await validTree(staging))) {
-            throw new Error(`bundled skills staging dir ${staging} failed validation`);
+            throw new HarnessError('BUNDLED_SKILLS_INVALID', [staging]);
         }
         if (await tryRename(staging, dir)) {
             return dir;
@@ -58,12 +59,11 @@ async function materialize() {
     }
 }
 function tamperError(dir) {
-    return new Error(`bundled skills dir ${dir} failed validation after a rewrite — ` +
-        'another process is tampering with it; remove it and restart');
+    return new HarnessError('BUNDLED_SKILLS_TAMPERED', [dir]);
 }
 function occupiedError(dir, cause) {
     const why = cause instanceof Error ? ` (${cause.message})` : '';
-    return new Error(`bundled skills dir ${dir} could not be read or replaced${why} — remove it and restart`);
+    return new HarnessError('BUNDLED_SKILLS_OCCUPIED', [dir, why]);
 }
 export function randomSuffix() {
     return Math.random().toString(36).slice(2, 10);

package/dist-lib/lib/tools/skills/catalog.js

@@ -10,7 +10,7 @@ import { parseToolGrant } from './tool-grants.js';
 import { deriveSetup } from './setup-routes.js';
 import { resolveSkillsOverlayDir } from './overlay-dir.js';
 import { parseOperationsManifest } from '../operations/manifest.js';
-import { hlog } from '../../log.js';
+import { log } from '../../log.js';
 export function skillSupportsPlatform(entry, platform) {
     return supportsPlatform(entry, platform);
 }
@@ -193,7 +193,7 @@ async function loadOperations(skillDir, name) {
     }
     const operations = parseOperationsManifest(raw);
     if (!operations) {
-        hlog('skill operations manifest rejected', { skill: name });
+        log.warn('skill operations manifest rejected', { skill: name });
         return [];
     }
     return operations;

package/dist-lib/lib/tools/skills/cli-argv.js

@@ -19,7 +19,7 @@ export function walkCommands(argv, schema) {
 }
 export function argvToObject(argv, schema) {
     const { node, pathSegs, index } = walkCommands(argv, schema);
-    const leaf = parseParams(argv.slice(index), node);
+    const leaf = parseParams(argv.slice(index), node, pathSegs.join(' '));
     if (typeof leaf === 'string') {
         return leaf;
     }
@@ -52,7 +52,27 @@ function flagParts(tok) {
     }
     return { key: body.slice(0, ieq), inline: body.slice(ieq + 1) };
 }
-function parseParams(tokens, schema) {
+function accepted(schema, command) {
+    const commands = [];
+    const params = [];
+    for (const [key, prop] of Object.entries(objectProps(schema))) {
+        if (isObjectSchema(prop)) {
+            commands.push(key);
+        }
+        else {
+            params.push(key);
+        }
+    }
+    const parts = [];
+    if (commands.length) {
+        parts.push(`commands: ${commands.join(', ')}`);
+    }
+    if (params.length) {
+        parts.push(`${command || 'it'} takes: ${params.join(', ')}`);
+    }
+    return parts.length ? `; ${parts.join('; ')}` : '';
+}
+function parseParams(tokens, schema, command) {
     const props = objectProps(schema);
     const propSchemas = new Map(Object.entries(props));
     const boolKeys = new Set(Object.entries(props)
@@ -77,7 +97,7 @@ function parseParams(tokens, schema) {
                 continue;
             }
             if (!canAbsorb) {
-                return `unknown parameter "${key}"`;
+                return `unknown parameter "${key}"${accepted(schema, command)}`;
             }
         }
         const flag = tok.startsWith('-') ? flagParts(tok) : null;
@@ -103,7 +123,7 @@ function parseParams(tokens, schema) {
             continue;
         }
         if (flag && !canAbsorb) {
-            return `unknown flag "--${flag.key}"`;
+            return `unknown flag "--${flag.key}"${accepted(schema, command)}`;
         }
         if (boolKeys.has(tok)) {
             out[tok] = true;
@@ -131,7 +151,7 @@ function parseParams(tokens, schema) {
             i++;
             continue;
         }
-        return `unexpected argument "${tok}"`;
+        return `unexpected argument "${tok}"${accepted(schema, command)}`;
     }
     if (restName && restVals.length > 0) {
         out[restName] = restVals;

package/dist-lib/lib/tools/skills/credential-health.js

@@ -1,4 +1,4 @@
-import { hlog } from '../../log.js';
+import { log } from '../../log.js';
 import { scopeKey } from './scope-key.js';
 const rejected = new Set();
 const lastProbedAt = new Map();
@@ -16,12 +16,12 @@ export function markCredentialValid(key, agentId, skill) {
 }
 export function recordCredentialHealth(key, status, agentId) {
     if (status === 401 || status === 403) {
-        hlog('credential rejected by provider', { key, status });
+        log.warn('credential rejected by provider', { key, status });
         markCredentialRejected(key, agentId);
     }
     else if (status < 400) {
         if (isCredentialRejected(key, agentId)) {
-            hlog('credential recovered', { key });
+            log.info('credential recovered', { key });
         }
         markCredentialValid(key, agentId);
     }

package/dist-lib/lib/tools/skills/overlay-crud.js

@@ -1,10 +1,11 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../errors.js';
 import { randomSuffix } from './bundled-dir.js';
 const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 function assertSafeName(name) {
     if (!SAFE_NAME.test(name)) {
-        throw new Error(`invalid skill name: ${name}`);
+        throw new HarnessError('INVALID_SKILL_NAME', [name]);
     }
 }
 async function dirNames(root) {
@@ -66,7 +67,7 @@ export async function copyBaseForEdit(baseDir, overlayDir, name) {
     }
     const src = path.join(baseDir, name);
     if (!(await exists(src))) {
-        throw new Error(`skill not found: ${name}`);
+        throw new HarnessError('SKILL_NOT_FOUND', [name]);
     }
     await copyDir(src, dest);
     return { copied: true };

package/dist-lib/lib/tools/translate.d.ts

@@ -1,4 +1,5 @@
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { TRANSLATION_LOAD_STALL_ERROR } from '../errors.ts';
 import type { ToolDefinition } from '../capabilities/completion.ts';
 import type { ModelSrc } from '../models/context.ts';
 import { type NmtPlan } from '../models/nmt-catalog.ts';
@@ -38,7 +39,7 @@ export type TranslationSdk = ModelRegistrySdk & {
     };
 };
 export declare const TRANSLATION_LOAD_STALL_MS: number;
-export declare const TRANSLATION_LOAD_STALL_ERROR = "translation model download stalled";
+export { TRANSLATION_LOAD_STALL_ERROR };
 export interface TranslationRuntimeOptions {
     loadSdk: () => Promise<TranslationSdk>;
     loads?: LoadTracker;
@@ -76,4 +77,3 @@ export interface TranslateToolOptions {
     slm?: SlmTranslateFn;
 }
 export declare function createTranslateTool(runtime: TranslationRuntime, { slm }?: TranslateToolOptions): ToolDefinition;
-export {};

package/dist-lib/lib/tools/translate.js

@@ -1,5 +1,6 @@
 import ScopeLock from 'scope-lock';
 import { getLangName } from '@qvac/langdetect-text';
+import { HarnessError, isHarnessError, TRANSLATION_LOAD_STALL_ERROR } from '../errors.js';
 import { detectLanguage, UNDETERMINED } from '../capabilities/detect-language.js';
 import { AbortedError, raceAbort } from '../helpers/race-abort.js';
 import { ENGLISH, NMT_FROM_ENGLISH, NMT_TO_ENGLISH, languageLabel, SLM_LANGUAGE_CODES, sameLanguage, translationPlanFor } from '../models/nmt-catalog.js';
@@ -7,7 +8,7 @@ import { createLoadStall } from '../helpers/load-stall.js';
 import { createLoadTracker } from '../models/model-pool.js';
 import { resolveModelSrc } from '../models/model-source.js';
 export const TRANSLATION_LOAD_STALL_MS = 15 * 60_000;
-export const TRANSLATION_LOAD_STALL_ERROR = 'translation model download stalled';
+export { TRANSLATION_LOAD_STALL_ERROR };
 function packName(plan) {
     const pair = plan.model.match(/model\.([a-z]+)\.intgemm/)?.[1];
     if (pair) {
@@ -38,7 +39,7 @@ export function createTranslationRuntime({ loadSdk, loads = createLoadTracker(),
             modelConfig.pivotModel = { modelSrc: await resolveModelSrc(sdk, plan.pivot, 'nmt') };
         }
         const name = packName(plan);
-        const stall = createLoadStall(stallMs, TRANSLATION_LOAD_STALL_ERROR);
+        const stall = createLoadStall(stallMs, () => new HarnessError('TRANSLATION_LOAD_STALLED'));
         onProgress?.(name, {});
         const pending = sdk.loadModel({
             modelSrc,
@@ -54,9 +55,7 @@ export function createTranslationRuntime({ loadSdk, loads = createLoadTracker(),
             return { modelId };
         }
         catch (err) {
-            if (err instanceof Error &&
-                err.message === TRANSLATION_LOAD_STALL_ERROR &&
-                pending.requestId) {
+            if (isHarnessError(err, 'TRANSLATION_LOAD_STALLED') && pending.requestId) {
                 void sdk.cancel?.({ requestId: pending.requestId }).catch(noop);
             }
             throw err;
@@ -216,7 +215,7 @@ export function createTranslateTool(runtime, { slm } = {}) {
                 entered = true;
                 if (plan.route === 'slm') {
                     if (!slm) {
-                        throw new Error('slm translation is unavailable');
+                        throw new HarnessError('SLM_TRANSLATION_UNAVAILABLE');
                     }
                     const text = await slm(plan.model, { text: parsed.text, from: plan.from, to: plan.to }, ctx?.signal);
                     return {

package/dist-lib/lib/tools/weather-lookup/geocode.js

@@ -1,7 +1,8 @@
 import { AbortController } from 'bare-abort-controller';
 import { z } from 'zod';
+import { HarnessError } from '../../errors.js';
 import { errorMessage } from '../../guards.js';
-import { hlog } from '../../log.js';
+import { log } from '../../log.js';
 import { resolveOutboundUrl } from '../url-guard.js';
 import { checkQualifier, describePlace, fold } from './place.js';
 export const GEOCODER_HOST = 'geocoding-api.open-meteo.com';
@@ -33,7 +34,7 @@ export async function geocode(city, lookup) {
         if (lookup.signal.aborted) {
             throw err;
         }
-        hlog('warn: weather geocoder failed, asking wttr.in by name', { err: errorMessage(err) });
+        log.warn('warn: weather geocoder failed, asking wttr.in by name', { err: errorMessage(err) });
         return [];
     }
     finally {
@@ -46,7 +47,7 @@ async function search(city, { fetch, resolveHost }, signal) {
     const url = new URL(`https://${GEOCODER_HOST}/v1/search?${query}`);
     const check = await resolveOutboundUrl(url, resolveHost, signal);
     if (check.blocked) {
-        throw new Error(check.blocked);
+        throw new HarnessError('EGRESS_BLOCKED', [check.blocked]);
     }
     const response = await fetch(url, {
         method: 'GET',
@@ -57,7 +58,7 @@ async function search(city, { fetch, resolveHost }, signal) {
         maxBytes: MAX_BODY_BYTES
     });
     if (response.status !== 200) {
-        throw new Error(`geocoder answered HTTP ${response.status}`);
+        throw new HarnessError('GEOCODER_HTTP_STATUS', [response.status]);
     }
     const { results = [] } = GeocodeSchema.parse(JSON.parse(await response.text()));
     return results.map((result) => ({

package/dist-lib/lib/web-search/engines/bing.js

@@ -1,3 +1,4 @@
+import { HarnessError } from '../../errors.js';
 import { fetchHtml } from '../fetch-html.js';
 import { clean } from '../html-helpers.js';
 import { urlMatchesHost } from '../url-helpers.js';
@@ -101,7 +102,7 @@ export async function searchBing(query, fetcher, signal) {
     const url = `https://www.bing.com/search?q=${encodeURIComponent(query)}`;
     const html = await fetchHtml(fetcher, url, { headers: { 'User-Agent': SAFARI_UA }, signal });
     if (html.includes('captcha') || html.includes('challenge/verify') || html.includes('Turnstile')) {
-        throw new Error('Bing CAPTCHA detected');
+        throw new HarnessError('SEARCH_CAPTCHA', ['Bing']);
     }
     const primary = parseBAlgoBlocks(html);
     if (primary.length > 0) {

package/dist-lib/lib/web-search/engines/google.js

@@ -1,3 +1,4 @@
+import { HarnessError } from '../../errors.js';
 import { fetchHtml } from '../fetch-html.js';
 import { clean } from '../html-helpers.js';
 import { urlMatchesHost } from '../url-helpers.js';
@@ -86,7 +87,7 @@ export async function searchGoogle(query, fetcher, signal) {
         signal
     });
     if (html.includes('detected unusual traffic') || html.includes('g-recaptcha')) {
-        throw new Error('Google CAPTCHA detected');
+        throw new HarnessError('SEARCH_CAPTCHA', ['Google']);
     }
     const primary = parseDataVedAnchors(html);
     if (primary.length > 0) {

package/dist-lib/lib/web-search/fetch-html.d.ts

@@ -1,11 +1,12 @@
 import { type AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { HarnessError } from '../errors.ts';
 import type { Fetcher } from './types.ts';
 export declare const ENGINE_TIMEOUT_MS = 8000;
 export declare const MAX_HTML_CHARS = 2000000;
-export declare class TimeoutError extends Error {
+export declare class TimeoutError extends HarnessError<'FETCH_TIMED_OUT'> {
     constructor(ms: number);
 }
-export declare class AbortError extends Error {
+export declare class AbortError extends HarnessError<'FETCH_CANCELLED'> {
     constructor();
 }
 interface FetchOptions {
@@ -18,9 +19,8 @@ interface FetchOptions {
     readonly signal?: BareAbortSignal;
 }
 export declare function fetchHtml(fetcher: Fetcher, url: string, options?: FetchOptions): Promise<string>;
-export declare class JsonParseError extends Error {
-    readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
+export declare class JsonParseError extends HarnessError<'RESPONSE_NOT_JSON'> {
+    constructor(chars: number, cause: unknown);
 }
 export declare function fetchJson(fetcher: Fetcher, url: string, options?: FetchOptions): Promise<unknown>;
 export {};

package/dist-lib/lib/web-search/fetch-html.js

@@ -1,17 +1,17 @@
 import { AbortController } from 'bare-abort-controller';
+import { errorMessage } from '../guards.js';
+import { HarnessError } from '../errors.js';
 import { BROWSER_UA } from './user-agents.js';
 export const ENGINE_TIMEOUT_MS = 8000;
 export const MAX_HTML_CHARS = 2_000_000;
-export class TimeoutError extends Error {
+export class TimeoutError extends HarnessError {
     constructor(ms) {
-        super(`Request timed out after ${ms}ms`);
-        this.name = 'TimeoutError';
+        super('FETCH_TIMED_OUT', [ms]);
     }
 }
-export class AbortError extends Error {
+export class AbortError extends HarnessError {
     constructor() {
-        super('Request cancelled');
-        this.name = 'AbortError';
+        super('FETCH_CANCELLED');
     }
 }
 function buildInit(options, signal) {
@@ -74,16 +74,13 @@ async function fetchWithTimeout(fetcher, url, options) {
 export async function fetchHtml(fetcher, url, options) {
     const { ok, status, text } = await fetchWithTimeout(fetcher, url, options);
     if (!ok) {
-        throw new Error(`HTTP ${status}`);
+        throw new HarnessError('HTTP_STATUS', [status]);
     }
     return text;
 }
-export class JsonParseError extends Error {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = 'JsonParseError';
+export class JsonParseError extends HarnessError {
+    constructor(chars, cause) {
+        super('RESPONSE_NOT_JSON', [chars, errorMessage(cause)], { cause });
     }
 }
 export async function fetchJson(fetcher, url, options) {
@@ -92,12 +89,12 @@ export async function fetchJson(fetcher, url, options) {
         accept: options?.accept ?? 'application/json'
     });
     if (!ok) {
-        throw new Error(`HTTP ${status}`);
+        throw new HarnessError('HTTP_STATUS', [status]);
     }
     try {
         return JSON.parse(text);
     }
     catch (err) {
-        throw new JsonParseError(`Response was not valid JSON (${text.length} chars): ${(err instanceof Error ? err : new Error(String(err))).message}`, err);
+        throw new JsonParseError(text.length, err);
     }
 }