@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/lib/models/model-handle.js

@@ -0,0 +1,33 @@
+import { retryMemo } from "../helpers/retry-memo.js";
+export class ModelHandle {
+    _load;
+    _peek;
+    _tracked = null;
+    _loading = false;
+    constructor({ load }) {
+        const memo = retryMemo(load);
+        this._load = memo;
+        this._peek = memo.peek;
+        this.load().catch(noop);
+    }
+    load() {
+        const attempt = this._load();
+        if (attempt !== this._tracked) {
+            this._tracked = attempt;
+            this._loading = true;
+            const settled = () => {
+                if (this._tracked === attempt)
+                    this._loading = false;
+            };
+            attempt.then(settled, settled);
+        }
+        return attempt;
+    }
+    get loading() {
+        return this._loading;
+    }
+    peek() {
+        return this._peek();
+    }
+}
+function noop() { }

package/dist-lib/lib/models/model-list.d.ts

@@ -0,0 +1,42 @@
+import type * as QvacSdk from '@qvac/sdk';
+import type { ModelAddon, ModelRegistrySdk } from './model-source.ts';
+export type ModelType = ModelAddon;
+export interface StaticCatalogEntry {
+    readonly name: string;
+    readonly registryPath: string;
+}
+export type ModelListSdk = ModelRegistrySdk & Pick<typeof QvacSdk, 'getModelInfo'> & {
+    readonly models: ReadonlyArray<StaticCatalogEntry>;
+};
+export interface ModelInfo {
+    name: string;
+    type: ModelType;
+    registryPath: string;
+    registrySource: string;
+    isCached: boolean;
+    isLoaded: boolean;
+    supportsImages: boolean;
+    expectedSize: number;
+    actualSize?: number;
+}
+export interface ListModelsOptions {
+    type?: ModelType;
+    cachedOnly?: boolean;
+    fullRegistry?: boolean;
+}
+interface ModelStatus {
+    at: number;
+    isCached: boolean;
+    isLoaded: boolean;
+    expectedSize?: number;
+    actualSize?: number;
+}
+export type ModelStatusCache = {
+    readonly entries: Map<string, ModelStatus>;
+    epoch: number;
+};
+export declare const MODEL_STATUS_TTL_MS = 30000;
+export declare function createModelStatusCache(): ModelStatusCache;
+export declare function invalidateModelStatusCache(cache: ModelStatusCache): void;
+export declare function listModels(sdk: ModelListSdk, { type, cachedOnly, fullRegistry }?: ListModelsOptions, cache?: ModelStatusCache, projectionFor?: (name: string) => string | undefined): Promise<ModelInfo[]>;
+export {};

package/dist-lib/lib/models/model-list.js

@@ -0,0 +1,123 @@
+import { companionRegistryPaths, curatedListables, musicListables } from "./model-catalog.js";
+export const MODEL_STATUS_TTL_MS = 30_000;
+export function createModelStatusCache() {
+    return { entries: new Map(), epoch: 0 };
+}
+export function invalidateModelStatusCache(cache) {
+    cache.entries.clear();
+    cache.epoch += 1;
+}
+const STATUS_CONCURRENCY = 8;
+async function mapPool(items, limit, fn) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const worker = async () => {
+        while (true) {
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+const COMPANIONS_BY_WEIGHT = companionRegistryPaths();
+async function musicRows(hydrate) {
+    const rows = [];
+    for (const listable of musicListables()) {
+        const status = await hydrate(listable.asset.registryPath, listable.asset.name);
+        let companionsCached = true;
+        for (const companion of listable.companions) {
+            companionsCached =
+                (await hydrate(companion.registryPath, companion.name)).isCached && companionsCached;
+        }
+        rows.push({
+            name: listable.name,
+            type: 'audiogen',
+            registryPath: listable.asset.registryPath,
+            registrySource: listable.asset.registrySource,
+            isCached: status.isCached && companionsCached,
+            isLoaded: status.isLoaded,
+            supportsImages: false,
+            expectedSize: listable.expectedSize
+        });
+    }
+    return rows;
+}
+export async function listModels(sdk, { type, cachedOnly, fullRegistry } = {}, cache, projectionFor) {
+    const now = Date.now();
+    const seesImages = (name, addon) => addon === 'llm' && Boolean(projectionFor?.(name));
+    const hydrate = async (registryPath, catalogName) => {
+        const hit = cache?.entries.get(registryPath);
+        if (hit && now - hit.at < MODEL_STATUS_TTL_MS)
+            return hit;
+        const epoch = cache?.epoch;
+        const info = catalogName
+            ? await sdk.getModelInfo({ name: catalogName }).catch(() => null)
+            : null;
+        const status = {
+            at: now,
+            isCached: info?.isCached ?? false,
+            isLoaded: info?.isLoaded ?? false,
+            expectedSize: info?.expectedSize,
+            actualSize: info?.actualSize
+        };
+        if (cache && cache.epoch === epoch)
+            cache.entries.set(registryPath, status);
+        return status;
+    };
+    if (!fullRegistry) {
+        const listables = curatedListables().filter((listable) => !type || listable.asset.addon === type);
+        const rows = await mapPool(listables, STATUS_CONCURRENCY, async (listable) => {
+            const status = await hydrate(listable.asset.registryPath, listable.asset.name);
+            let companionsCached = true;
+            for (const companion of listable.companions) {
+                companionsCached =
+                    (await hydrate(companion.registryPath, companion.name)).isCached && companionsCached;
+            }
+            if (listable.projection && projectionFor?.(listable.name) === listable.projection.src) {
+                const projection = await hydrate(listable.projection.registryPath, listable.projection.name);
+                companionsCached = projection.isCached && companionsCached;
+            }
+            return {
+                name: listable.name,
+                type: listable.asset.addon,
+                registryPath: listable.asset.registryPath,
+                registrySource: listable.asset.registrySource,
+                isCached: status.isCached && companionsCached,
+                isLoaded: status.isLoaded,
+                supportsImages: seesImages(listable.name, listable.asset.addon),
+                expectedSize: status.expectedSize ?? listable.asset.expectedSize,
+                actualSize: status.actualSize
+            };
+        });
+        const music = !type || type === 'audiogen' ? await musicRows(hydrate) : [];
+        const all = [...rows, ...music];
+        return cachedOnly ? all.filter((row) => row.isCached) : all;
+    }
+    const entries = await sdk.modelRegistrySearch(type ? { addon: type } : {});
+    const catalog = new Map();
+    for (const c of sdk.models)
+        catalog.set(c.registryPath, c.name);
+    const rows = await mapPool(entries, STATUS_CONCURRENCY, async (entry) => {
+        const status = await hydrate(entry.registryPath, catalog.get(entry.registryPath));
+        const companions = COMPANIONS_BY_WEIGHT.get(entry.registryPath) ?? [];
+        let companionsCached = true;
+        for (const path of companions) {
+            companionsCached = (await hydrate(path, catalog.get(path))).isCached && companionsCached;
+        }
+        return {
+            name: entry.name,
+            type: entry.addon,
+            registryPath: entry.registryPath,
+            registrySource: entry.registrySource,
+            isCached: status.isCached && companionsCached,
+            isLoaded: status.isLoaded,
+            supportsImages: seesImages(entry.name, entry.addon),
+            expectedSize: status.expectedSize ?? entry.expectedSize,
+            actualSize: status.actualSize
+        };
+    });
+    return cachedOnly ? rows.filter((row) => row.isCached) : rows;
+}

package/dist-lib/lib/models/model-pool.d.ts

@@ -0,0 +1,116 @@
+import ResourcePuddle from 'resource-puddle';
+import { ModelHandle } from './model-handle.ts';
+import { type ModelSrc } from './context.ts';
+import { type ModelAddon } from './model-source.ts';
+import type { GpuFaultState } from './sdk-faults.ts';
+type SdkModule = typeof import('@qvac/sdk');
+export interface ModelState {
+    status: 'loading' | 'downloading' | 'ready' | 'unloading' | 'unloaded';
+    model: string;
+    [key: string]: unknown;
+}
+export type NotifyFn = (state: ModelState) => void;
+export interface LlmDeviceConfig {
+    device?: 'cpu' | 'gpu';
+    gpuLayers?: number;
+    contextSize?: number;
+    kvCacheK?: string;
+    kvCacheV?: string;
+    mainGpu?: () => Promise<string | undefined>;
+    openclCacheDir?: () => string | undefined;
+}
+export type TrackedLoad = Promise<string> & {
+    requestId?: string;
+};
+export interface CancelSdk {
+    cancel(params: {
+        requestId: string;
+    }): Promise<unknown>;
+}
+export interface LoadTracker {
+    readonly draining: boolean;
+    track(pending: TrackedLoad): TrackedLoad;
+    drain(sdk: CancelSdk): void;
+    undrain(): void;
+}
+export declare function createLoadTracker(): LoadTracker;
+export type ModelLifecycleSdk = Pick<SdkModule, 'unloadModel' | 'modelRegistrySearch'> & Partial<CancelSdk> & {
+    loadModel(params: {
+        modelSrc: ModelSrc;
+        modelType: 'llamacpp-completion';
+        modelConfig?: {
+            verbosity?: 0 | 1 | 2 | 3;
+            tools?: boolean;
+            stop_sequences?: readonly string[];
+            ctx_size?: number;
+            'cache-type-k'?: string;
+            'cache-type-v'?: string;
+            projectionModelSrc?: ModelSrc;
+            device?: 'cpu' | 'gpu';
+            gpu_layers?: number;
+            'main-gpu'?: string;
+            openclCacheDir?: string;
+        };
+        onProgress?: (progress: Record<string, unknown>) => void;
+    }): TrackedLoad;
+};
+export interface ModelLoadOptions {
+    ctxSize?: number;
+    kvCacheK?: string;
+    kvCacheV?: string;
+    projectionModel?: string;
+}
+export declare function resolveLoadOptions(opts?: ModelLoadOptions, deviceConfig?: LlmDeviceConfig): ModelLoadOptions;
+export declare function modelKey(model: string, opts?: ModelLoadOptions): string;
+export interface LoadedModel {
+    model: string;
+    refs: number;
+}
+type PoolLike = ReturnType<typeof createModelPool>;
+export declare function releaseModel(pool: PoolLike, key: string): void;
+export declare function loadedModels(pool: PoolLike): LoadedModel[];
+export declare function isResident(pool: PoolLike, key: string): boolean;
+export declare function leaseCount(pool: PoolLike, key: string): number;
+export declare function evictIdle(pool: PoolLike): Promise<void>;
+export declare function evictAllWithin(pool: PoolLike, deadlineMs: number, tickMs?: number, signal?: {
+    aborted?: boolean;
+}): Promise<boolean>;
+export declare function evictModelWithin(pool: PoolLike, key: string, deadlineMs: number, tickMs?: number): Promise<boolean>;
+export type LoadSdk = () => Promise<ModelLifecycleSdk>;
+export type EmbedLifecycleSdk = Pick<SdkModule, 'unloadModel' | 'modelRegistrySearch'> & Partial<CancelSdk> & {
+    loadModel(params: {
+        modelSrc: ModelSrc;
+        modelType: 'llamacpp-embedding';
+        modelConfig?: {
+            batchSize?: number;
+            gpuLayers?: number;
+            device?: string;
+            openclCacheDir?: string;
+        };
+        onProgress?: (progress: Record<string, unknown>) => void;
+    }): TrackedLoad;
+};
+export type LoadEmbedSdk = () => Promise<EmbedLifecycleSdk>;
+export declare function progressState(model: string, progress: Record<string, unknown>): ModelState;
+interface LoadClockGuardOptions {
+    now?: () => number;
+    monoMs?: () => number;
+    sampleMs?: number;
+    jumpMs?: number;
+}
+export declare function loadClockGuard(model: string, sdk: Partial<CancelSdk>, { now, monoMs, sampleMs, jumpMs }?: LoadClockGuardOptions): {
+    race: (pending: TrackedLoad) => Promise<string>;
+};
+export declare function createModelPool(loadSdk: LoadSdk, notify: NotifyFn, deviceConfig?: LlmDeviceConfig, loads?: LoadTracker): ResourcePuddle<string, ModelHandle>;
+export declare function createEmbedPool(loadSdk: LoadEmbedSdk, notify: NotifyFn, faults: GpuFaultState, batchSize?: number, openclCacheDir?: () => string | undefined, loads?: LoadTracker): ResourcePuddle<string, ModelHandle>;
+export type VoiceLifecycleSdk = Pick<SdkModule, 'unloadModel' | 'modelRegistrySearch'> & Partial<CancelSdk> & {
+    loadModel(params: {
+        modelSrc: ModelSrc;
+        modelType: string;
+        modelConfig?: Record<string, unknown>;
+        onProgress?: (progress: Record<string, unknown>) => void;
+    }): TrackedLoad;
+};
+export type LoadVoiceSdk = () => Promise<VoiceLifecycleSdk>;
+export declare function createVoicePool(loadSdk: LoadVoiceSdk, notify: NotifyFn, modelType: string, addon: ModelAddon, modelConfig?: Record<string, unknown>, openclCacheDir?: () => string | undefined, loads?: LoadTracker): ResourcePuddle<string, ModelHandle>;
+export {};

package/dist-lib/lib/models/model-pool.js

@@ -0,0 +1,356 @@
+import process from 'process';
+import { transferProgress } from "../model-download-progress.js";
+import ResourcePuddle from 'resource-puddle';
+import { ModelHandle } from "./model-handle.js";
+import { defaultContextSize } from "./context.js";
+import { adrenoSafeKvCache } from "./kv-cache.js";
+import { DEFAULT_EMBED_BATCH_SIZE } from "./embed-config.js";
+import { hlog } from "../log.js";
+import { RUNAWAY_STOP_SEQUENCES } from "../helpers/control-tokens.js";
+import { resolveModelSrc } from "./model-source.js";
+export function createLoadTracker() {
+    const inflight = new Set();
+    let draining = null;
+    const cancel = (sdk, requestId) => {
+        void sdk.cancel({ requestId }).catch(() => { });
+    };
+    return {
+        get draining() {
+            return draining !== null;
+        },
+        track(pending) {
+            const { requestId } = pending;
+            if (!requestId)
+                return pending;
+            if (draining) {
+                cancel(draining, requestId);
+                return pending;
+            }
+            inflight.add(requestId);
+            const untrack = () => inflight.delete(requestId);
+            pending.then(untrack, untrack);
+            return pending;
+        },
+        drain(sdk) {
+            draining = sdk;
+            for (const requestId of inflight)
+                cancel(sdk, requestId);
+            inflight.clear();
+        },
+        undrain() {
+            draining = null;
+        }
+    };
+}
+const NO_IDLE_GC = { gcInterval: 0, gcIdleTicks: 1 };
+export function resolveLoadOptions(opts = {}, deviceConfig = {}) {
+    return {
+        ctxSize: opts.ctxSize || deviceConfig.contextSize,
+        kvCacheK: opts.kvCacheK ?? deviceConfig.kvCacheK,
+        kvCacheV: opts.kvCacheV ?? deviceConfig.kvCacheV,
+        projectionModel: opts.projectionModel
+    };
+}
+export function modelKey(model, opts = {}) {
+    return [
+        model,
+        opts.ctxSize ?? '',
+        opts.kvCacheK ?? '',
+        opts.kvCacheV ?? '',
+        opts.projectionModel ?? ''
+    ].join('\0');
+}
+function entryOf(pool, key) {
+    return pool.resources.get(key);
+}
+export function releaseModel(pool, key) {
+    if (pool.destroyed)
+        return;
+    const handle = entryOf(pool, key)?.value;
+    if (handle === undefined || !handle.loading) {
+        pool.release(key);
+        return;
+    }
+    const pending = handle.peek();
+    if (pending === null) {
+        pool.release(key);
+        return;
+    }
+    void pending.then(() => releaseSettled(pool, key), () => releaseSettled(pool, key));
+}
+function releaseSettled(pool, key) {
+    if (!pool.destroyed)
+        pool.release(key);
+}
+export function loadedModels(pool) {
+    const out = [];
+    for (const entry of pool.resources.values()) {
+        if (entry.value.peek() === null)
+            continue;
+        out.push({ model: entry.id.split('\0')[0], refs: entry.refs });
+    }
+    return out;
+}
+export function isResident(pool, key) {
+    const handle = entryOf(pool, key)?.value;
+    return handle !== undefined && handle.peek() !== null;
+}
+export function leaseCount(pool, key) {
+    return entryOf(pool, key)?.refs ?? 0;
+}
+export async function evictIdle(pool) {
+    for (let tick = 0; pool.idle > 0 && tick <= pool.gcIdleTicks; tick++) {
+        await pool.gc();
+    }
+}
+export async function evictAllWithin(pool, deadlineMs, tickMs = 250, signal) {
+    let done = false;
+    let timer = null;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            done = true;
+            resolve(false);
+        }, deadlineMs);
+    });
+    const evicting = (async () => {
+        await evictIdle(pool);
+        while (loadedModels(pool).length > 0) {
+            if (done || signal?.aborted)
+                return false;
+            await new Promise((resolve) => setTimeout(resolve, tickMs));
+            if (done || signal?.aborted)
+                return false;
+            await evictIdle(pool);
+        }
+        return true;
+    })();
+    try {
+        return await Promise.race([evicting, expired]);
+    }
+    finally {
+        done = true;
+        if (timer !== null)
+            clearTimeout(timer);
+    }
+}
+export async function evictModelWithin(pool, key, deadlineMs, tickMs = 250) {
+    let timer = null;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), deadlineMs);
+    });
+    const evicting = (async () => {
+        while (isResident(pool, key)) {
+            await evictIdle(pool);
+            if (!isResident(pool, key))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, tickMs));
+        }
+        return true;
+    })();
+    try {
+        return await Promise.race([evicting, expired]);
+    }
+    finally {
+        if (timer !== null)
+            clearTimeout(timer);
+    }
+}
+function llmVerbosity() {
+    const raw = Number(process.env.QVAC_LLM_VERBOSITY ?? 0);
+    return raw === 1 || raw === 2 || raw === 3 ? raw : 0;
+}
+export function progressState(model, progress) {
+    const transfer = transferProgress(progress);
+    if (!transfer)
+        return { status: 'loading', model };
+    const { percentage, downloaded, total } = transfer;
+    return percentage < 100
+        ? { ...progress, status: 'downloading', model, percentage, downloaded, total }
+        : { status: 'loading', model, percentage, downloaded, total };
+}
+const CLOCK_JUMP_MS = 250;
+const CLOCK_SAMPLE_MS = 2_000;
+function monotonicMs() {
+    return Number(process.hrtime.bigint() / 1000000n);
+}
+export function loadClockGuard(model, sdk, { now = () => Date.now(), monoMs = monotonicMs, sampleMs = CLOCK_SAMPLE_MS, jumpMs = CLOCK_JUMP_MS } = {}) {
+    let timer = null;
+    let fail;
+    let done = false;
+    let abandoned = false;
+    let lastWall = now();
+    let lastMono = monoMs();
+    const jumped = new Promise((_resolve, reject) => {
+        fail = reject;
+    });
+    const arm = () => {
+        timer = setTimeout(sample, sampleMs);
+        timer.unref?.();
+    };
+    const sample = () => {
+        if (done)
+            return;
+        const wall = now();
+        const mono = monoMs();
+        if (wall - lastWall < mono - lastMono - jumpMs) {
+            abandoned = true;
+            fail(new Error(`model load abandoned: system clock moved backward mid-load: ${model}`));
+            return;
+        }
+        lastWall = wall;
+        lastMono = mono;
+        arm();
+    };
+    arm();
+    const race = async (pending) => {
+        try {
+            return await Promise.race([pending, jumped]);
+        }
+        catch (err) {
+            if (abandoned && pending.requestId) {
+                void sdk.cancel?.({ requestId: pending.requestId }).catch(() => { });
+            }
+            throw err;
+        }
+        finally {
+            done = true;
+            if (timer !== null)
+                clearTimeout(timer);
+        }
+    };
+    return { race };
+}
+export function createModelPool(loadSdk, notify, deviceConfig = {}, loads = createLoadTracker()) {
+    const load = async (model, opts) => {
+        const sdk = await loadSdk();
+        notify({ status: 'loading', model });
+        const modelSrc = await resolveModelSrc(sdk, model);
+        const resolved = resolveLoadOptions(opts, deviceConfig);
+        const ctxSize = resolved.ctxSize || defaultContextSize(modelSrc);
+        const projectionModelSrc = resolved.projectionModel
+            ? await resolveModelSrc(sdk, resolved.projectionModel)
+            : undefined;
+        const mainGpu = deviceConfig.device !== 'cpu' && deviceConfig.mainGpu
+            ? await deviceConfig.mainGpu()
+            : undefined;
+        const kvCache = adrenoSafeKvCache(deviceConfig.device, resolved.kvCacheK, resolved.kvCacheV);
+        const openclCache = deviceConfig.device !== 'cpu' && deviceConfig.openclCacheDir
+            ? deviceConfig.openclCacheDir()
+            : undefined;
+        const modelConfig = {
+            verbosity: llmVerbosity(),
+            tools: true,
+            stop_sequences: RUNAWAY_STOP_SEQUENCES,
+            ctx_size: ctxSize,
+            'cache-type-k': kvCache.k,
+            'cache-type-v': kvCache.v,
+            projectionModelSrc,
+            ...(deviceConfig.device ? { device: deviceConfig.device } : {}),
+            ...(deviceConfig.gpuLayers === undefined ? {} : { gpu_layers: deviceConfig.gpuLayers }),
+            ...(mainGpu === undefined ? {} : { 'main-gpu': mainGpu }),
+            ...(openclCache ? { openclCacheDir: openclCache } : {})
+        };
+        const { projectionModelSrc: projection, ...loggedConfig } = modelConfig;
+        hlog('llm load config', { model, projection: Boolean(projection), ...loggedConfig });
+        const loadStarted = Date.now();
+        const modelId = await loadClockGuard(model, sdk).race(loads.track(sdk.loadModel({
+            modelSrc,
+            modelType: 'llamacpp-completion',
+            modelConfig,
+            onProgress: (progress) => notify(progressState(model, progress))
+        })));
+        hlog('llm loaded', { model, loadMs: Date.now() - loadStarted });
+        notify({ status: 'ready', model });
+        return { model, modelId, ctxSize };
+    };
+    return new ResourcePuddle({
+        open: (key, model = key, opts = {}) => new ModelHandle({ load: () => load(model, opts) }),
+        gc: unloadOnGc(loadSdk, notify),
+        ...NO_IDLE_GC
+    });
+}
+export function createEmbedPool(loadSdk, notify, faults, batchSize = DEFAULT_EMBED_BATCH_SIZE, openclCacheDir, loads = createLoadTracker()) {
+    const load = async (model) => {
+        const sdk = await loadSdk();
+        notify({ status: 'loading', model });
+        const modelSrc = await resolveModelSrc(sdk, model, 'embeddings');
+        const openclCache = faults.device !== 'cpu' && openclCacheDir ? openclCacheDir() : undefined;
+        const modelId = await loadClockGuard(model, sdk).race(loads.track(sdk.loadModel({
+            modelSrc,
+            modelType: 'llamacpp-embedding',
+            modelConfig: {
+                batchSize,
+                gpuLayers: faults.gpuLayers(),
+                device: faults.device,
+                ...(openclCache ? { openclCacheDir: openclCache } : {})
+            },
+            onProgress: (progress) => notify(progressState(model, progress))
+        })));
+        notify({ status: 'ready', model });
+        return { model, modelId };
+    };
+    return new ResourcePuddle({
+        open: (key, model = key) => new ModelHandle({ load: () => load(model) }),
+        gc: unloadOnGc(loadSdk, notify),
+        ...NO_IDLE_GC
+    });
+}
+export function createVoicePool(loadSdk, notify, modelType, addon, modelConfig, openclCacheDir, loads = createLoadTracker()) {
+    const wantsGpu = modelConfig?.['useGPU'] === true;
+    let gpuRefused = false;
+    const load = async (model) => {
+        const sdk = await loadSdk();
+        notify({ status: 'loading', model });
+        const modelSrc = await resolveModelSrc(sdk, model, addon);
+        const attempt = () => {
+            const config = gpuRefused ? { ...modelConfig, useGPU: false } : modelConfig;
+            const openclCache = gpuRefused ? undefined : openclCacheDir?.();
+            return loads.track(sdk.loadModel({
+                modelSrc,
+                modelType,
+                modelConfig: openclCache ? { openclCacheDir: openclCache, ...config } : config,
+                onProgress: (progress) => notify(progressState(model, progress))
+            }));
+        };
+        const modelId = await loadClockGuard(model, sdk).race(attempt().catch((err) => {
+            if (!wantsGpu || gpuRefused || loads.draining)
+                throw err;
+            hlog('voice gpu load refused, retrying on cpu', { model, modelType, error: String(err) });
+            gpuRefused = true;
+            return attempt();
+        }));
+        notify({ status: 'ready', model });
+        return { model, modelId };
+    };
+    return new ResourcePuddle({
+        open: (key, model = key) => new ModelHandle({ load: () => load(model) }),
+        gc: unloadOnGc(loadSdk, notify),
+        ...NO_IDLE_GC
+    });
+}
+function unloadOnGc(loadSdk, notify) {
+    return async (handles) => {
+        const sdk = await loadSdk();
+        for (const handle of handles) {
+            const pending = handle.peek();
+            if (pending === null)
+                continue;
+            let loaded;
+            try {
+                loaded = await pending;
+            }
+            catch {
+                continue;
+            }
+            const { model, modelId } = loaded;
+            notify({ status: 'unloading', model });
+            try {
+                await sdk.unloadModel({ modelId });
+            }
+            catch {
+                continue;
+            }
+            notify({ status: 'unloaded', model });
+        }
+    };
+}

package/dist-lib/lib/models/model-source.d.ts

@@ -0,0 +1,6 @@
+import type * as QvacSdk from '@qvac/sdk';
+import type { ModelRegistryEntryAddon } from '@qvac/sdk';
+import type { ModelSrc } from './context.ts';
+export type ModelRegistrySdk = Pick<typeof QvacSdk, 'modelRegistrySearch'>;
+export type ModelAddon = ModelRegistryEntryAddon;
+export declare function resolveModelSrc(sdk: ModelRegistrySdk, model: string, addon?: ModelAddon): Promise<ModelSrc>;