@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/lib/queue.js

@@ -0,0 +1,48 @@
+export function pushQueue({ highWaterMark = 0 } = {}) {
+    const items = [];
+    let wake = null;
+    let drain = null;
+    let ended = false;
+    const wakeConsumer = () => {
+        wake?.resolve();
+        wake = null;
+    };
+    const wakeProducer = () => {
+        drain?.resolve();
+        drain = null;
+    };
+    return {
+        get size() {
+            return items.length;
+        },
+        push(item) {
+            if (ended)
+                return Promise.resolve();
+            items.push(item);
+            wakeConsumer();
+            if (highWaterMark <= 0 || items.length < highWaterMark)
+                return Promise.resolve();
+            drain ??= Promise.withResolvers();
+            return drain.promise;
+        },
+        end() {
+            ended = true;
+            wakeConsumer();
+            wakeProducer();
+        },
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                while (items.length) {
+                    const item = items.shift();
+                    if (highWaterMark > 0 && items.length < highWaterMark)
+                        wakeProducer();
+                    yield item;
+                }
+                if (ended)
+                    return;
+                wake = Promise.withResolvers();
+                await wake.promise;
+            }
+        }
+    };
+}

package/dist-lib/lib/resolution-detector.d.ts

@@ -0,0 +1,5 @@
+export declare function resolutionDetail(err: unknown): Record<string, unknown>;
+export declare function isReferrerLost(referrer: unknown, parent: string, cache: object | null): boolean;
+export declare function resolutionFailure(specifier: string, parent: string, err: unknown): Record<string, unknown>;
+export declare function installResolutionDetector(meta: ImportMeta): () => void;
+export declare function uninstallResolutionDetector(): void;

package/dist-lib/lib/resolution-detector.js

@@ -0,0 +1,100 @@
+import { hlog } from "./log.js";
+function readValue(value, key) {
+    if (value === null)
+        return undefined;
+    if (typeof value !== 'object' && typeof value !== 'function')
+        return undefined;
+    return Reflect.get(value, key);
+}
+function readString(value, key) {
+    const found = readValue(value, key);
+    return typeof found === 'string' ? found : null;
+}
+function readCandidates(err) {
+    const found = readValue(err, 'candidates');
+    if (!Array.isArray(found))
+        return undefined;
+    return found.map((candidate) => readString(candidate, 'href') ?? String(candidate));
+}
+export function resolutionDetail(err) {
+    const detail = {};
+    const code = readString(err, 'code');
+    if (code !== null)
+        detail.code = code;
+    const specifier = readString(err, 'specifier');
+    if (specifier !== null)
+        detail.specifier = specifier;
+    const referrer = readString(readValue(err, 'referrer'), 'href');
+    if (referrer !== null)
+        detail.referrer = referrer;
+    const candidates = readCandidates(err);
+    if (candidates !== undefined)
+        detail.candidates = candidates;
+    return detail;
+}
+function readCache(meta) {
+    const cache = readValue(meta, 'cache');
+    return typeof cache === 'object' && cache !== null ? cache : null;
+}
+export function isReferrerLost(referrer, parent, cache) {
+    if (referrer !== null && referrer !== undefined)
+        return false;
+    if (cache === null)
+        return false;
+    return Reflect.get(cache, parent) !== undefined;
+}
+export function resolutionFailure(specifier, parent, err) {
+    return {
+        specifier,
+        parent,
+        ...resolutionDetail(err),
+        err: err instanceof Error ? err.message : String(err)
+    };
+}
+let uninstall = null;
+export function installResolutionDetector(meta) {
+    const cacheRecord = readCache(meta);
+    if (cacheRecord === null)
+        return noop;
+    if (uninstall !== null)
+        return noop;
+    const self = Reflect.get(cacheRecord, meta.url);
+    const Module = readValue(self, 'constructor');
+    if (typeof Module !== 'function')
+        return noop;
+    const resolve = readValue(Module, 'resolve');
+    if (typeof resolve !== 'function')
+        return noop;
+    const startedAt = Date.now();
+    const original = resolve.bind(Module);
+    const wrapped = (specifier, parentURL, opts = {}) => {
+        const parent = String(parentURL);
+        if (isReferrerLost(opts.referrer, parent, cacheRecord)) {
+            hlog('diag referrer LOST', {
+                specifier,
+                parent,
+                modules: Object.keys(cacheRecord).length,
+                aliveSec: Math.round((Date.now() - startedAt) / 1000)
+            });
+        }
+        try {
+            return original(specifier, parentURL, opts);
+        }
+        catch (err) {
+            if (isReferrerLost(opts.referrer, parent, cacheRecord)) {
+                hlog('diag resolve FAILED after a lost referrer', resolutionFailure(specifier, parent, err));
+            }
+            throw err;
+        }
+    };
+    Reflect.set(Module, 'resolve', wrapped);
+    uninstall = () => {
+        Reflect.set(Module, 'resolve', resolve);
+        uninstall = null;
+    };
+    return uninstall;
+}
+export function uninstallResolutionDetector() {
+    uninstall?.();
+}
+function noop() { }

package/dist-lib/lib/rpc-session.d.ts

@@ -0,0 +1,8 @@
+export interface Stream {
+    destroyed?: boolean;
+    destroy(): void;
+    on(event: 'close', listener: () => void): unknown;
+    on(event: 'error', listener: (err: unknown) => void): unknown;
+}
+export type Transport = () => Stream | Promise<Stream>;
+export declare function settleOnClose<T>(hrpc: T): T;

package/dist-lib/lib/rpc-session.js

@@ -0,0 +1,20 @@
+export function settleOnClose(hrpc) {
+    const session = hrpc;
+    let reason = null;
+    const dead = (err) => {
+        reason ??= err ?? new Error('rpc stream destroyed');
+    };
+    const call = session._call.bind(session);
+    const callSync = session._callSync.bind(session);
+    session._call = (name, args) => (reason ? Promise.reject(reason) : call(name, args));
+    session._callSync = (name, args) => {
+        if (reason)
+            throw reason;
+        return callSync(name, args);
+    };
+    session._stream.on('error', (err) => dead(err));
+    session._stream.on('close', () => dead(null));
+    if (session._stream.destroyed)
+        dead(null);
+    return hrpc;
+}

package/dist-lib/lib/sdk-config-loader.node.d.ts

@@ -0,0 +1 @@
+export function installSdkConfigLoader(): void;

package/dist-lib/lib/sdk-config-loader.node.js

@@ -0,0 +1 @@
+export function installSdkConfigLoader() { }

package/dist-lib/lib/sdk-loader.d.ts

@@ -0,0 +1,30 @@
+type Sdk = typeof import('@qvac/sdk');
+export type SdkPlugin = Parameters<(typeof import('@qvac/sdk/plugins'))['registerPlugin']>[0];
+type Plugin = SdkPlugin;
+interface PluginRegistry {
+    registerPlugin(plugin: Plugin): void;
+}
+export interface SdkImports {
+    sdk(): Promise<Sdk>;
+    plugins(): Promise<PluginRegistry>;
+    llm(): Promise<{
+        llmPlugin: Plugin;
+    }>;
+    embeddings(): Promise<{
+        embeddingsPlugin: Plugin;
+    }>;
+    tts(): Promise<{
+        ttsPlugin: Plugin;
+    }>;
+    parakeet(): Promise<{
+        parakeetPlugin: Plugin;
+    }>;
+}
+export interface SdkLoader {
+    load(): Promise<Sdk>;
+    loadEmbed(): Promise<Sdk>;
+    loadVoice(): Promise<Sdk>;
+    peek(): Promise<Sdk> | null;
+}
+export declare function createSdkLoader(imports?: SdkImports): SdkLoader;
+export {};

package/dist-lib/lib/sdk-loader.js

@@ -0,0 +1,53 @@
+import { retryMemo } from "./helpers/retry-memo.js";
+import { hlog } from "./log.js";
+const defaultImports = {
+    sdk: () => import('@qvac/sdk'),
+    plugins: () => import('@qvac/sdk/plugins'),
+    llm: () => import('@qvac/sdk/llamacpp-completion/plugin'),
+    embeddings: () => import('@qvac/sdk/llamacpp-embedding/plugin'),
+    tts: () => import('@qvac/sdk/onnx-tts/plugin'),
+    parakeet: () => import('@qvac/sdk/parakeet-transcription/plugin')
+};
+function register(registry, name, plugin) {
+    try {
+        registry.registerPlugin(plugin);
+    }
+    catch (err) {
+        hlog('plugin registration skipped', {
+            plugin: name,
+            err: err instanceof Error ? err.message : String(err)
+        });
+    }
+}
+export function createSdkLoader(imports = defaultImports) {
+    const load = retryMemo(async () => {
+        const [sdk, { llmPlugin }, registry] = await Promise.all([
+            imports.sdk(),
+            imports.llm(),
+            imports.plugins()
+        ]);
+        register(registry, 'llm', llmPlugin);
+        return sdk;
+    });
+    const loadEmbed = retryMemo(async () => {
+        const [sdk, { embeddingsPlugin }, registry] = await Promise.all([
+            load(),
+            imports.embeddings(),
+            imports.plugins()
+        ]);
+        register(registry, 'embeddings', embeddingsPlugin);
+        return sdk;
+    });
+    const loadVoice = retryMemo(async () => {
+        const [sdk, { ttsPlugin }, { parakeetPlugin }, registry] = await Promise.all([
+            load(),
+            imports.tts(),
+            imports.parakeet(),
+            imports.plugins()
+        ]);
+        register(registry, 'tts', ttsPlugin);
+        register(registry, 'parakeet', parakeetPlugin);
+        return sdk;
+    });
+    return { load, loadEmbed, loadVoice, peek: () => load.peek() };
+}

package/dist-lib/lib/sdk-storage.d.ts

@@ -0,0 +1,8 @@
+import { type SdkStorage } from './storage.ts';
+export declare const SDK_CONFIG_PATH_ENV = "QVAC_CONFIG_PATH";
+export declare const OPENCL_CACHE_DIR_ENV = "QVAC_OPENCL_CACHE_DIR";
+export interface SdkStorageChannels {
+    readonly env?: Record<string, string | undefined>;
+    readonly argv?: Array<string> | null;
+}
+export declare function configureSdkStorage(storage: SdkStorage, channels?: SdkStorageChannels): string;

package/dist-lib/lib/sdk-storage.js

@@ -0,0 +1,24 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import process from 'process';
+import { isBareKit } from 'which-runtime';
+import { installSdkConfigLoader } from '#sdk-config-loader';
+import { SDK_HOME_ENV } from "./storage.js";
+export const SDK_CONFIG_PATH_ENV = 'QVAC_CONFIG_PATH';
+export const OPENCL_CACHE_DIR_ENV = 'QVAC_OPENCL_CACHE_DIR';
+export function configureSdkStorage(storage, channels = {}) {
+    const { env = process.env, argv = isBareKit ? Bare.argv : null } = channels;
+    installSdkConfigLoader();
+    mkdirSync(storage.home, { recursive: true });
+    const configPath = join(storage.home, 'qvac.config.json');
+    writeFileSync(configPath, `${JSON.stringify({ cacheDirectory: storage.models }, null, 2)}\n`);
+    const openclCacheDir = join(storage.home, 'opencl-cache');
+    mkdirSync(openclCacheDir, { recursive: true });
+    if (argv)
+        argv[0] = storage.home;
+    else
+        env[SDK_HOME_ENV] = storage.home;
+    env[SDK_CONFIG_PATH_ENV] = configPath;
+    env[OPENCL_CACHE_DIR_ENV] = openclCacheDir;
+    return configPath;
+}

package/dist-lib/lib/serve.d.ts

@@ -0,0 +1,3 @@
+import { type Stream } from './rpc-session.ts';
+import type { HarnessContract } from './contract-types.ts';
+export declare function serveHarness(stream: Stream, harness: HarnessContract): void;