@qvac/harness 0.3.3 → 0.5.0

package/dist-lib/lib/hooks/built-in/arg-repair.js

@@ -1,4 +1,5 @@
 import { jsonrepair } from 'jsonrepair';
+import { isRecord } from '../../guards.js';
 import { hlog } from '../../log.js';
 const STRUCTURED_TYPES = new Set(['object', 'array']);
 export class ArgRepairHook {
@@ -9,11 +10,13 @@ export class ArgRepairHook {
         let args = ctx.args;
         for (const [key, schema] of Object.entries(ctx.parameters.properties)) {
             const value = args[key];
-            if (typeof value !== 'string')
+            if (typeof value !== 'string') {
                 continue;
+            }
             const types = structuredTypes(schema);
-            if (types.size === 0)
+            if (types.size === 0) {
                 continue;
+            }
             const parsed = parseStructured(value, types);
             if (parsed === null) {
                 hlog('arg repair declined', { tool: ctx.toolName, param: key, length: value.length });
@@ -21,8 +24,9 @@ export class ArgRepairHook {
             }
             args = { ...args, [key]: parsed };
         }
-        if (args !== ctx.args)
+        if (args !== ctx.args) {
             return { args };
+        }
     }
 }
 function parseStructured(value, types) {
@@ -36,16 +40,18 @@ function parseStructured(value, types) {
         return null;
     }
     const accepted = accept(parsed, types);
-    if (accepted !== null)
+    if (accepted !== null) {
         return accepted;
+    }
     if (Array.isArray(parsed) &&
         types.has('object') &&
-        isRecord(parsed[0]) &&
+        isPlainObject(parsed[0]) &&
         typeof parsed.at(-1) === 'string') {
         return parsed[0];
     }
-    if (text[0] === '"' && types.has('object'))
+    if (text[0] === '"' && types.has('object')) {
         return accept(read(`{${text}}`), types);
+    }
     return null;
 }
 function read(text) {
@@ -57,7 +63,7 @@ function read(text) {
     }
 }
 function accept(value, types) {
-    if (isRecord(value) && types.has('object'))
+    if (isPlainObject(value) && types.has('object'))
         return value;
     if (Array.isArray(value) && types.has('array'))
         return value;
@@ -65,24 +71,28 @@ function accept(value, types) {
 }
 function structuredTypes(schema) {
     const found = new Set();
-    if (!isRecord(schema))
+    if (!isPlainObject(schema)) {
         return found;
+    }
     const declared = Array.isArray(schema.type) ? schema.type : [schema.type];
     for (const type of declared) {
-        if (typeof type === 'string' && STRUCTURED_TYPES.has(type))
+        if (typeof type === 'string' && STRUCTURED_TYPES.has(type)) {
             found.add(type);
+        }
     }
     for (const key of ['oneOf', 'anyOf']) {
         const branches = schema[key];
-        if (!Array.isArray(branches))
+        if (!Array.isArray(branches)) {
             continue;
+        }
         for (const branch of branches) {
-            for (const type of structuredTypes(branch))
+            for (const type of structuredTypes(branch)) {
                 found.add(type);
+            }
         }
     }
     return found;
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+function isPlainObject(value) {
+    return isRecord(value) && !Array.isArray(value);
 }

package/dist-lib/lib/hooks/built-in/egress.js

@@ -23,7 +23,8 @@ export class EgressGuardHook {
             return;
         }
         const blocked = checkOutboundHost(url);
-        if (blocked)
+        if (blocked) {
             return { error: blocked, guidance: true };
+        }
     }
 }

package/dist-lib/lib/hooks/built-in/skill-catalog.js

@@ -11,8 +11,9 @@ export class SkillCatalogGuardHook {
         const known = new Set(entries.map((entry) => (typeof entry === 'string' ? entry : entry.name)));
         const raw = ctx.args.name ?? ctx.args.skill_name ?? ctx.args.skill;
         const name = typeof raw === 'string' ? raw : '';
-        if (known.has(name))
+        if (known.has(name)) {
             return;
+        }
         const listed = [...known].join(', ');
         const rest = listed
             ? `The only skills are: ${listed}. Nothing else needs a skill load — answer or act with the tools you already have.`

package/dist-lib/lib/hooks/pipeline.d.ts

@@ -7,14 +7,15 @@ export type PreToolFold = {
     ok: false;
     rejection: HookRejection;
 };
+export interface PostToolFold {
+    result: unknown;
+    outcome?: ToolExecutionOutcome;
+}
 export declare class HookPipeline {
     private readonly _behaviorHooks;
     constructor(hooks?: readonly HarnessHook[]);
     onRunStart(payload: Omit<RunStartPayload, 'phase'>): Promise<void>;
     onRunEnd(payload: Omit<RunEndPayload, 'phase'>): Promise<void>;
     runPreToolFold(payload: Omit<PreToolCallPayload, 'phase'>): Promise<PreToolFold>;
-    runPostToolFold(payload: Omit<PostToolCallPayload, 'phase'>): Promise<{
-        result: unknown;
-        outcome?: ToolExecutionOutcome;
-    }>;
+    runPostToolFold(payload: Omit<PostToolCallPayload, 'phase'>): Promise<PostToolFold>;
 }

package/dist-lib/lib/hooks/pipeline.js

@@ -9,13 +9,15 @@ export class HookPipeline {
     }
     async onRunStart(payload) {
         const folded = await runHooks(this._behaviorHooks, { phase: 'runStart', ...payload });
-        if ('guidance' in folded)
+        if ('guidance' in folded) {
             hlog('run hook failed', { stage: 'runStart', error: folded.error });
+        }
     }
     async onRunEnd(payload) {
         const folded = await runHooks(this._behaviorHooks, { phase: 'runEnd', ...payload });
-        if ('guidance' in folded)
+        if ('guidance' in folded) {
             hlog('run hook failed', { stage: 'runEnd', error: folded.error });
+        }
     }
     async runPreToolFold(payload) {
         const folded = await runHooks(this._behaviorHooks, { phase: 'preToolCall', ...payload });
@@ -42,8 +44,9 @@ export class HookPipeline {
                 result = folded.result;
             }
         }
-        if (outcome !== undefined)
+        if (outcome !== undefined) {
             outcome = normalizeToolExecutionOutcome(result, outcome);
+        }
         return { result, outcome };
     }
 }

package/dist-lib/lib/hooks/run.js

@@ -1,3 +1,4 @@
+import { errorMessage, isRecord } from '../guards.js';
 import { hlog } from '../log.js';
 function cloneJson(value) {
     try {
@@ -8,19 +9,20 @@ function cloneJson(value) {
         return value;
     }
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+function isPlainObject(value) {
+    return isRecord(value) && !Array.isArray(value);
 }
 function cloneArgs(args) {
     const cloned = cloneJson(args);
-    return isRecord(cloned) ? cloned : args;
+    return isPlainObject(cloned) ? cloned : args;
 }
 function isMessage(value) {
-    return isRecord(value) && typeof value.role === 'string' && typeof value.content === 'string';
+    return isPlainObject(value) && typeof value.role === 'string' && typeof value.content === 'string';
 }
 function freshContext(ctx) {
-    if (ctx.phase === 'preToolCall')
+    if (ctx.phase === 'preToolCall') {
         return { ...ctx, args: cloneArgs(ctx.args) };
+    }
     if (ctx.phase === 'postToolCall') {
         return { ...ctx, args: cloneArgs(ctx.args), result: cloneJson(ctx.result) };
     }
@@ -52,7 +54,7 @@ function merge(current, returned) {
     return current;
 }
 function rejectionOf(current, err) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = errorMessage(err);
     hlog('hook failed', { stage: current.phase, error: message });
     if (current.phase === 'postToolCall') {
         return {
@@ -69,10 +71,12 @@ export async function runHooks(hooks, ctx) {
             continue;
         try {
             const returned = await hook.run(freshContext(current));
-            if (!returned || typeof returned !== 'object')
+            if (!returned || typeof returned !== 'object') {
                 continue;
-            if (isRejection(returned))
+            }
+            if (isRejection(returned)) {
                 return rejection(returned);
+            }
             current = merge(current, returned);
         }
         catch (err) {

package/dist-lib/lib/model-download-progress.js

@@ -1,20 +1,24 @@
+import { isRecord } from './guards.js';
 const EMA_WEIGHT = 0.25;
 const STALL_MS = 2_000;
 const NO_BYTES = { downloaded: 0, total: 0, aggregate: false };
 export function transferProgress(event) {
     const aggregate = aggregateTransfer(event.fileSetInfo) ?? aggregateTransfer(event.shardInfo);
-    if (aggregate)
+    if (aggregate) {
         return aggregate;
+    }
     const bytes = { downloaded: uint(event.downloaded), total: uint(event.total), aggregate: false };
     const reported = reportedPercentage(event.percentage);
-    if (reported === null && bytes.downloaded === 0 && bytes.total === 0)
+    if (reported === null && bytes.downloaded === 0 && bytes.total === 0) {
         return null;
+    }
     return { ...bytes, percentage: resolvePercentage(reported, bytes) };
 }
 export function progressBytes(event) {
     const transfer = transferProgress(event);
-    if (!transfer)
+    if (!transfer) {
         return NO_BYTES;
+    }
     return {
         downloaded: transfer.downloaded,
         total: transfer.total,
@@ -34,8 +38,9 @@ export class DownloadSpeedSampler {
             return 0;
         }
         const elapsedMs = at - this._at;
-        if (elapsedMs <= 0)
+        if (elapsedMs <= 0) {
             return Math.round(this._bytesPerSecond);
+        }
         const delta = bytes.downloaded - this._downloaded;
         if (delta === 0) {
             if (elapsedMs >= STALL_MS) {
@@ -62,7 +67,7 @@ export class DownloadSpeedSampler {
     }
 }
 function aggregateTransfer(value) {
-    if (!record(value))
+    if (!isRecord(value))
         return null;
     const bytes = {
         downloaded: uint(value.overallDownloaded),
@@ -84,9 +89,6 @@ function reportedPercentage(value) {
 function bytesPercentage(bytes) {
     return bytes.total > 0 ? percentage((bytes.downloaded / bytes.total) * 100) : 0;
 }
-function record(value) {
-    return typeof value === 'object' && value !== null;
-}
 function uint(value) {
     return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
 }

package/dist-lib/lib/models/context.d.ts

@@ -2,4 +2,4 @@ import type { ModelRegistryEntry } from '@qvac/sdk';
 export type ModelSrc = string | (ModelRegistryEntry & {
     src: string;
 });
-export declare function defaultContextSize(modelSrc: ModelSrc): number;
+export declare function defaultContextSize(modelSrc: ModelSrc, trainedContext?: number): number;

package/dist-lib/lib/models/context.js

@@ -1,7 +1,11 @@
 const TINY_MODEL_PARAMS_BILLIONS = 0.8;
 const TINY_MODEL_CONTEXT_SIZE = 8_192;
 const DESKTOP_DEFAULT_CONTEXT_SIZE = 51_200;
-export function defaultContextSize(modelSrc) {
+export function defaultContextSize(modelSrc, trainedContext) {
+    const size = tieredContextSize(modelSrc);
+    return trainedContext ? Math.min(size, trainedContext) : size;
+}
+function tieredContextSize(modelSrc) {
     if (typeof modelSrc === 'string')
         return DESKTOP_DEFAULT_CONTEXT_SIZE;
     const params = Number.parseFloat(modelSrc.params);

package/dist-lib/lib/models/custom-model-cache.d.ts

@@ -0,0 +1,13 @@
+import type { CustomModelEntry } from './model-catalog.ts';
+export interface CustomDownloads {
+    readonly files: ReadonlyArray<string>;
+    readonly dirs: ReadonlyArray<string>;
+}
+export declare function customFileCachePath(src: string, modelsDir: string | undefined): string | null;
+export interface CustomShardCache {
+    readonly dir: string;
+    readonly files: ReadonlyArray<string>;
+}
+export declare function customShardCache(src: string, modelsDir: string | undefined): CustomShardCache | null;
+export declare function customDownloads(entry: CustomModelEntry, modelsDir: string | undefined): Promise<CustomDownloads>;
+export declare function isCustomModelCached(entry: CustomModelEntry, modelsDir: string | undefined): Promise<boolean>;

package/dist-lib/lib/models/custom-model-cache.js

@@ -0,0 +1,70 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { isRemoteSource, localSourcePath } from './gguf-header.js';
+import { shardSet } from './shards.js';
+const ARCHIVE = /\.(tar|tgz|zip)(\.\w+)?$/i;
+export function customFileCachePath(src, modelsDir) {
+    if (!isRemoteSource(src)) {
+        return localSourcePath(src);
+    }
+    const filename = filenameOf(src);
+    if (!modelsDir || shardSet(src) || ARCHIVE.test(filename)) {
+        return null;
+    }
+    return path.join(modelsDir, `${shortHash(src)}_${filename}`);
+}
+export function customShardCache(src, modelsDir) {
+    const set = shardSet(src);
+    if (!modelsDir || !isRemoteSource(src) || !set) {
+        return null;
+    }
+    const dir = path.join(modelsDir, 'sharded', shortHash(`${set.baseUrl}/${set.base}`));
+    return { dir, files: set.shards.map((shard) => path.join(dir, shard.filename)) };
+}
+export async function customDownloads(entry, modelsDir) {
+    const remote = sourcesOf(entry).filter(isRemoteSource);
+    const shardDirs = remote.flatMap((src) => customShardCache(src, modelsDir)?.dir ?? []);
+    const inShardDirs = await Promise.all(shardDirs.map(listFiles));
+    const singles = remote.flatMap((src) => customFileCachePath(src, modelsDir) ?? []);
+    return { files: [...singles, ...inShardDirs.flat()], dirs: shardDirs };
+}
+export async function isCustomModelCached(entry, modelsDir) {
+    const expected = sourcesOf(entry).flatMap((src) => customShardCache(src, modelsDir)?.files ?? [customFileCachePath(src, modelsDir)]);
+    const sizes = await Promise.all(expected.map(onDiskSize));
+    const present = sizes.filter((size) => size !== null);
+    if (present.length < sizes.length) {
+        return false;
+    }
+    const total = present.reduce((sum, size) => sum + size, 0);
+    return entry.expectedSize ? total === entry.expectedSize : true;
+}
+function sourcesOf(entry) {
+    return entry.projectionSrc ? [entry.src, entry.projectionSrc] : [entry.src];
+}
+function filenameOf(src) {
+    return src.split('/').pop()?.split('?')[0] || 'model.gguf';
+}
+function shortHash(input) {
+    return crypto.createHash('sha256').update(input, 'utf8').digest('hex').slice(0, 16);
+}
+async function listFiles(dir) {
+    try {
+        const names = await fs.promises.readdir(dir);
+        return names.map((name) => path.join(dir, String(name)));
+    }
+    catch {
+        return [];
+    }
+}
+async function onDiskSize(file) {
+    if (file === null)
+        return null;
+    try {
+        const stat = await fs.promises.stat(file);
+        return stat.isFile() ? stat.size : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist-lib/lib/models/gguf-header.d.ts

@@ -0,0 +1,31 @@
+import { type AbortSignal } from 'bare-abort-controller';
+export interface GgufHeader {
+    readonly architecture?: string;
+    readonly name?: string;
+    readonly type?: string;
+    readonly license?: string;
+    readonly contextLength?: number;
+    readonly sizeLabel?: string;
+    readonly tags?: ReadonlyArray<string>;
+}
+export type GgufRangeFetch = (url: string, init: {
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+export declare const GGUF_HEADER_BYTES = 1048576;
+export declare const GGUF_HEADER_TIMEOUT_MS = 30000;
+export declare function isRemoteSource(src: string): boolean;
+export declare function localSourcePath(src: string): string | null;
+export interface ReadGgufHeaderOptions {
+    fetch?: GgufRangeFetch;
+    maxBytes?: number;
+}
+export declare function readGgufHeaderBytes(src: string, opts?: ReadGgufHeaderOptions): Promise<Uint8Array | null>;
+export declare function parseGgufHeader(bytes: Uint8Array): GgufHeader | null;

package/dist-lib/lib/models/gguf-header.js

@@ -0,0 +1,230 @@
+import b4a from 'b4a';
+import { AbortController } from 'bare-abort-controller';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import defaultFetch from '#fetch';
+const rangeFetch = defaultFetch;
+export const GGUF_HEADER_BYTES = 1_048_576;
+export const GGUF_HEADER_TIMEOUT_MS = 30_000;
+const UINT8 = 0;
+const INT8 = 1;
+const UINT16 = 2;
+const INT16 = 3;
+const UINT32 = 4;
+const INT32 = 5;
+const FLOAT32 = 6;
+const BOOL = 7;
+const STRING = 8;
+const ARRAY = 9;
+const UINT64 = 10;
+const INT64 = 11;
+const FLOAT64 = 12;
+export function isRemoteSource(src) {
+    return /^https?:\/\//i.test(src);
+}
+export function localSourcePath(src) {
+    if (/^file:/i.test(src)) {
+        return filePath(src);
+    }
+    if (/^[a-z][a-z0-9+.-]+:/i.test(src))
+        return null;
+    if (src === '~') {
+        return os.homedir();
+    }
+    if (src.startsWith('~/')) {
+        return path.join(os.homedir(), src.slice(2));
+    }
+    return src;
+}
+function filePath(src) {
+    try {
+        return fileURLToPath(src);
+    }
+    catch {
+        return null;
+    }
+}
+export function readGgufHeaderBytes(src, opts = {}) {
+    const maxBytes = opts.maxBytes ?? GGUF_HEADER_BYTES;
+    return isRemoteSource(src)
+        ? fetchHead(src, maxBytes, opts.fetch ?? rangeFetch)
+        : readLocalHead(src, maxBytes);
+}
+async function fetchHead(src, maxBytes, fetch) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(undefined), GGUF_HEADER_TIMEOUT_MS);
+    try {
+        const response = await fetch(src, {
+            headers: { Range: `bytes=0-${maxBytes - 1}` },
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const length = response.headers.get('content-length');
+        if (length === null || !(Number(length) <= maxBytes)) {
+            return null;
+        }
+        return new Uint8Array(await response.arrayBuffer()).subarray(0, maxBytes);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readLocalHead(src, maxBytes) {
+    const file = localSourcePath(src);
+    if (file === null) {
+        return null;
+    }
+    let handle;
+    try {
+        handle = await fs.promises.open(file, 'r');
+        const buffer = b4a.allocUnsafe(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export function parseGgufHeader(bytes) {
+    if (bytes.byteLength < 24)
+        return null;
+    if (b4a.toString(bytes.subarray(0, 4), 'latin1') !== 'GGUF')
+        return null;
+    const c = {
+        view: new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        bytes,
+        offset: 16
+    };
+    if (c.view.getUint32(4, true) < 2) {
+        return null;
+    }
+    const count = readU64(c);
+    const header = {};
+    const contextLengths = new Map();
+    for (let i = 0; i < count; i += 1) {
+        const key = readString(c);
+        if (key === null || !has(c, 4)) {
+            break;
+        }
+        const value = readValue(c, readU32(c), key === 'general.tags');
+        if (!value.ok) {
+            break;
+        }
+        if (key === 'general.architecture') {
+            header.architecture = value.str;
+        }
+        else if (key === 'general.name') {
+            header.name = value.str;
+        }
+        else if (key === 'general.type') {
+            header.type = value.str;
+        }
+        else if (key === 'general.license') {
+            header.license = value.str;
+        }
+        else if (key === 'general.size_label') {
+            header.sizeLabel = value.str;
+        }
+        else if (key === 'general.tags') {
+            header.tags = value.strs;
+        }
+        else if (key.endsWith('.context_length')) {
+            contextLengths.set(key, value.num);
+        }
+    }
+    header.contextLength =
+        contextLengths.get(`${header.architecture}.context_length`) ??
+            contextLengths.values().next().value;
+    return header;
+}
+function readValue(c, type, collect = false) {
+    switch (type) {
+        case UINT8:
+        case BOOL:
+            return fixed(c, 1, () => c.view.getUint8(c.offset));
+        case INT8:
+            return fixed(c, 1, () => c.view.getInt8(c.offset));
+        case UINT16:
+            return fixed(c, 2, () => c.view.getUint16(c.offset, true));
+        case INT16:
+            return fixed(c, 2, () => c.view.getInt16(c.offset, true));
+        case UINT32:
+            return fixed(c, 4, () => c.view.getUint32(c.offset, true));
+        case INT32:
+            return fixed(c, 4, () => c.view.getInt32(c.offset, true));
+        case FLOAT32:
+            return fixed(c, 4, () => c.view.getFloat32(c.offset, true));
+        case FLOAT64:
+            return fixed(c, 8, () => c.view.getFloat64(c.offset, true));
+        case UINT64:
+        case INT64:
+            return has(c, 8) ? { ok: true, num: readU64(c) } : { ok: false };
+        case STRING: {
+            const str = readString(c);
+            return str === null ? { ok: false } : { ok: true, str };
+        }
+        case ARRAY: {
+            if (!has(c, 12)) {
+                return { ok: false };
+            }
+            const elementType = readU32(c);
+            const length = readU64(c);
+            const strs = new Array();
+            for (let i = 0; i < length; i += 1) {
+                const element = readValue(c, elementType);
+                if (!element.ok) {
+                    return { ok: false };
+                }
+                if (collect && element.str !== undefined) {
+                    strs.push(element.str);
+                }
+            }
+            return collect ? { ok: true, strs } : { ok: true };
+        }
+        default:
+            return { ok: false };
+    }
+}
+function fixed(c, width, read) {
+    if (!has(c, width)) {
+        return { ok: false };
+    }
+    const num = read();
+    c.offset += width;
+    return { ok: true, num };
+}
+function has(c, n) {
+    return n >= 0 && c.offset + n <= c.bytes.byteLength;
+}
+function readU32(c) {
+    const value = c.view.getUint32(c.offset, true);
+    c.offset += 4;
+    return value;
+}
+function readU64(c) {
+    const lo = c.view.getUint32(c.offset, true);
+    const hi = c.view.getUint32(c.offset + 4, true);
+    c.offset += 8;
+    return hi * 2 ** 32 + lo;
+}
+function readString(c) {
+    if (!has(c, 8))
+        return null;
+    const length = readU64(c);
+    if (!has(c, length)) {
+        return null;
+    }
+    const str = b4a.toString(c.bytes.subarray(c.offset, c.offset + length), 'utf8');
+    c.offset += length;
+    return str;
+}

package/dist-lib/lib/models/idle-unload.d.ts

@@ -0,0 +1,14 @@
+export interface IdleReaperOptions {
+    sweep: () => Promise<void>;
+    waitMs: number;
+    onError: (err: unknown) => void;
+    now?: () => number;
+    tickMs?: number;
+}
+export interface IdleReaper {
+    configure(timeoutMs: number): void;
+    enter(): Promise<void>;
+    exit(): void;
+    close(): void;
+}
+export declare function createIdleReaper({ sweep, waitMs, onError, now, tickMs }: IdleReaperOptions): IdleReaper;