@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/index.js

@@ -0,0 +1,1063 @@
+import fs from 'fs';
+import { platform, totalmem } from 'os';
+import process from 'process';
+import ReadyResource from 'ready-resource';
+import { readSystemStats } from '#hw-gpu-stats';
+import { probeCapabilityProfile } from "./lib/hardware/capability-probe.js";
+import { closePythonWorker } from "./lib/tools/exec/adapters/python/worker/client.js";
+import { completion } from "./lib/capabilities/completion.js";
+import { download } from "./lib/capabilities/download.js";
+import { createEmbedLane } from "./lib/capabilities/embed.js";
+import { deleteAllKvCaches } from "./lib/capabilities/kv-cache.js";
+import { pcmForTranscription } from "./lib/capabilities/audio-resample.js";
+import { buildWavBuffer } from "./lib/wav-encode.js";
+import { createVoiceLane, packSamples, speakOnce, speakStreamOnce, transcribeOnce, transcribeStreaming, SUPERTONIC_SAMPLE_RATE } from "./lib/capabilities/voice.js";
+import { pushQueue } from "./lib/queue.js";
+import { AbortedError, raceAbort } from "./lib/helpers/race-abort.js";
+import { audioGenDownloadMetadata, customProjectionMap, defaultProjectionMap, defaultTtsFor, defaultVoiceModel, diffusionDownloadMetadata, infraModelsFor, modelNameToCapabilityProfile, musicModelSet, setCustomModels } from "./lib/models/model-catalog.js";
+import { createModelStatusCache, invalidateModelStatusCache, listModels } from "./lib/models/model-list.js";
+import { deleteModelFiles, summarizeDelete } from "./lib/models/model-delete.js";
+import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, evictAllWithin, evictIdle, evictModelWithin, isResident, leaseCount, loadedModels, modelKey, releaseModel, resolveLoadOptions, progressState } from "./lib/models/model-pool.js";
+import { resolveMainGpu } from "./lib/models/gpu-selection.js";
+import { openclCacheDir } from "./lib/models/opencl-cache.js";
+import { assertEmbedDevice, createEmbedConfig } from "./lib/models/embed-config.js";
+import { createGpuFaultState, isSdkGpuDeviceLostError, isSdkModelWedgedError } from "./lib/models/sdk-faults.js";
+import { createSdkLoader } from "./lib/sdk-loader.js";
+import { createEditImageTool } from "./lib/tools/edit-image.js";
+import { toolCatalog } from "./lib/tools/catalog.js";
+import { createDiffusionRuntime, createGenerateImageTool } from "./lib/tools/generate-image.js";
+import { createGenerateMusicTool, createMusicRuntime } from "./lib/tools/generate-music.js";
+import { availableSkills, detectPlatform, loadSkillCatalog, resolveSkillStatuses, skillSupportsPlatform, versionProbeSkills } from "./lib/tools/skills/catalog.js";
+import { ensureBundledSkillsDir } from "./lib/tools/skills/bundled-dir.js";
+import { ensureSkillsOverlayDir } from "./lib/tools/skills/overlay-dir.js";
+import { copyBaseForEdit, deleteOverlaySkill, listManagedSkills, readSkillFile, writeSkillFile } from "./lib/tools/skills/overlay-crud.js";
+import { watchSkillsOverlay } from "./lib/tools/skills/overlay-watch.js";
+import { hlog } from "./lib/log.js";
+import { harness } from './spec/index.js';
+import { installResolutionDetector, resolutionDetail } from "./lib/resolution-detector.js";
+import { probeBinVersions } from "./lib/tools/skills/bin-check.js";
+import { bareRuntime } from "./lib/tools/exec.js";
+import { runCommand } from "./lib/tools/exec/runner.js";
+import { createLocalRoots } from "./lib/tools/fs/local.js";
+import { createRemoteRoots } from "./lib/tools/fs/remote.js";
+import { resetCredentialHealth as resetCredentialHealthAfterSnapshot } from "./lib/tools/skills/credential-health.js";
+import { isDeviceSharedCredentialKey, scopeKey } from "./lib/tools/skills/scope-key.js";
+import { settingsScopeKey } from "./lib/tools/skills/skill-settings.js";
+export * from "./lib/capabilities/completion.js";
+export { attachmentTurn, loadedSkillsFrom, skillLoadedTurn } from "./lib/capabilities/tool-turns.js";
+export * from "./lib/capabilities/download.js";
+export * from "./lib/models/model-catalog.js";
+export * from "./lib/models/model-list.js";
+export { harnessChild, spawnHarness } from "./lib/spawn.js";
+export { settingsDimension, settingsSteps } from "./lib/tools/generate-image.js";
+export * from "./lib/tools/skills/catalog.js";
+export { requiredSettings, settingEnvName } from "./lib/tools/skills/skill-settings.js";
+export { TOOLSETS, toolsetEnabled } from "./lib/tools/toolsets.js";
+export { markCredentialRejected, markCredentialValid, recordCredentialHealth, resetAllCredentialHealth, resetCredentialHealth } from "./lib/tools/skills/credential-health.js";
+export { readSetup as normalizeSkillSetup } from "./lib/tools/skills/manifest-parse.js";
+export { isAvailableState, SKILL_STATE } from "./lib/tools/skills/skill-state.js";
+export { connectHarness, HARNESS_DIED, RemoteHarness } from "./lib/connect.js";
+export { serveHarness } from "./lib/serve.js";
+export { hlog, setHarnessLog, setHarnessLogSink } from "./lib/log.js";
+export { harnessHooks } from "./lib/hooks/registry.js";
+export { EgressGuardHook, SkillCatalogGuardHook } from "./lib/hooks/built-in/index.js";
+const HarnessState = harness.getEnum('@harness/state');
+const BIN_VERSION_PROBE_TTL_MS = 45_000;
+const TRANSCRIBE_STREAM_MIN_BYTES = 16_000 * 2 * 60;
+const TRANSCRIPTION_MODEL_LABEL = 'transcription model';
+const DIFFUSION_EVICT_WAIT_MS = 15_000;
+const MUSIC_EVICT_WAIT_MS = 15_000;
+const WEDGED_EVICT_WAIT_MS = 10_000;
+const WEDGED_EVICT_LEASED_MS = 120_000;
+const TTS_MODEL_CONFIG = {
+    ttsEngine: 'supertonic',
+    language: 'en',
+    ttsSpeed: 1.175,
+    ttsNumInferenceSteps: 5
+};
+export class Harness extends ReadyResource {
+    _tools;
+    _sdk;
+    _loads = createLoadTracker();
+    _modelStatus = createModelStatusCache();
+    _models;
+    _embedModels;
+    _retiredEmbedModels;
+    _embedLane = createEmbedLane();
+    _embedFaults;
+    _embedGpuLayers;
+    _embedBatchSize;
+    _embedControl;
+    _ttsModels;
+    _transcriptionModels;
+    _voiceLane = createVoiceLane();
+    _state;
+    _skillsDir;
+    _overlayWatcher = null;
+    _supportedSkills;
+    _projectionModel;
+    _customProjection = {};
+    _llmDevice;
+    _llmGpuLayers;
+    _contextSize;
+    _kvCacheK;
+    _kvCacheV;
+    _transcriptionDevice;
+    _allSkills;
+    _credentialStore;
+    _credentials = new Map();
+    _settings = new Map();
+    _platform;
+    _diffusionSdk;
+    _imageRuntime;
+    _musicSdk;
+    _musicRuntime;
+    _capability = null;
+    _capabilityInflight = null;
+    _modelFaults = new Map();
+    constructor({ tools = [], sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, credentialStore, platform } = {}) {
+        super();
+        this._sdk = sdkLoader ?? createSdkLoader();
+        this._llmDevice = llmDevice;
+        this._llmGpuLayers = llmGpuLayers;
+        this._contextSize = contextSize;
+        this._kvCacheK = kvCacheK;
+        this._kvCacheV = kvCacheV;
+        this._transcriptionDevice = transcriptionDevice;
+        const embedConfig = createEmbedConfig({
+            device: embedDevice,
+            gpuLayers: embedGpuLayers,
+            batchSize: embedBatchSize
+        });
+        this._embedGpuLayers = embedConfig.gpuLayers;
+        this._embedBatchSize = embedConfig.batchSize;
+        this._retiredEmbedModels = new Set();
+        this._embedControl = Promise.resolve();
+        this._embedFaults = createGpuFaultState({
+            device: embedConfig.device,
+            gpuLayers: embedConfig.gpuLayers
+        });
+        const image = typeof imageModel === 'string' ? { model: imageModel } : imageModel;
+        this._imageRuntime = image
+            ? createDiffusionRuntime({
+                ...image,
+                loads: this._loads,
+                loadSdk: () => this._loadDiffusionSdk(),
+                onProgress: (model, progress) => {
+                    const state = progressState(model, progress);
+                    if (state.status === 'loading' && state.percentage === 100) {
+                        invalidateModelStatusCache(this._modelStatus);
+                    }
+                    this.emit('model', state);
+                },
+                onBeforeLoad: async (signal) => {
+                    if (this._models.destroyed)
+                        return;
+                    const evicted = await evictAllWithin(this._models, DIFFUSION_EVICT_WAIT_MS, undefined, signal);
+                    if (signal?.aborted)
+                        throw new AbortedError();
+                    if (!evicted) {
+                        throw new Error('the chat model is busy; try the image again once the current reply finishes');
+                    }
+                }
+            })
+            : null;
+        const music = typeof musicModel === 'string' ? (musicModelSet(musicModel) ?? undefined) : musicModel;
+        this._musicRuntime = music
+            ? createMusicRuntime({
+                ...music,
+                loads: this._loads,
+                loadSdk: () => this._loadMusicSdk(),
+                onProgress: (model, progress) => this.emit('model', progressState(model, progress)),
+                onBeforeLoad: async (signal) => {
+                    if (this._models.destroyed)
+                        return;
+                    const evicted = await evictAllWithin(this._models, MUSIC_EVICT_WAIT_MS, undefined, signal);
+                    if (signal?.aborted)
+                        throw new AbortedError();
+                    if (!evicted) {
+                        throw new Error('the chat model is busy; try the music again once the current reply finishes');
+                    }
+                }
+            })
+            : null;
+        this._tools = [
+            ...tools,
+            ...(this._imageRuntime
+                ? [
+                    createGenerateImageTool(this._imageRuntime, imageClamps),
+                    createEditImageTool(this._imageRuntime, {}, imageClamps)
+                ]
+                : []),
+            ...(this._musicRuntime ? [createGenerateMusicTool(this._musicRuntime, musicClamps)] : [])
+        ];
+        this._projectionModel = projectionModel ?? defaultProjectionMap();
+        this._state = HarnessState.RESUME;
+        this._skillsDir = skillsDir;
+        this._supportedSkills = [];
+        this._allSkills = [];
+        this._credentialStore = credentialStore;
+        this._platform = platform;
+        this._diffusionSdk = null;
+        this._musicSdk = null;
+    }
+    async _open() {
+        installResolutionDetector(import.meta);
+        this._models = this._createPool();
+        this._embedModels = this._createEmbedPool();
+        this._ttsModels = this._createTtsPool();
+        this._transcriptionModels = this._createTranscriptionPool();
+        await this._reloadSkills();
+        await this._startOverlayWatch();
+        hlog('open', { skills: this._supportedSkills.length, tools: this._tools.length });
+    }
+    get suspended() {
+        return this._state === HarnessState.SUSPEND;
+    }
+    get skillNames() {
+        return this._supportedSkills.map((skill) => skill.name);
+    }
+    setCredentials(entries) {
+        const previous = this._credentials;
+        const next = new Map();
+        for (const { key, token, expiresAt, agentId, skill } of entries) {
+            if (!token)
+                continue;
+            const storeKey = scopeKey({ agentId, skill, key });
+            const record = {
+                token,
+                ...(typeof expiresAt === 'number' && expiresAt > 0 ? { expiresAt } : {})
+            };
+            const current = previous.get(storeKey);
+            if (!current || current.token !== record.token || current.expiresAt !== record.expiresAt) {
+                resetCredentialHealthAfterSnapshot(key, agentId, skill);
+            }
+            next.set(storeKey, record);
+        }
+        this._credentials = next;
+    }
+    setSkillSettings(entries) {
+        const next = new Map();
+        for (const { skill, key, value, agentId } of entries) {
+            if (!skill || !key || typeof value !== 'string')
+                continue;
+            const scope = settingsScopeKey(skill, agentId);
+            const bucket = next.get(scope) ?? {};
+            bucket[key] = value;
+            next.set(scope, bucket);
+        }
+        this._settings = next;
+    }
+    skillSettings(skill, agentId) {
+        return {
+            ...this._settings.get(settingsScopeKey(skill, null)),
+            ...(agentId ? this._settings.get(settingsScopeKey(skill, agentId)) : undefined)
+        };
+    }
+    async _baseSkillsDir() {
+        return this._skillsDir ?? (await ensureBundledSkillsDir());
+    }
+    async listManagedSkills() {
+        return listManagedSkills(await this._baseSkillsDir(), await ensureSkillsOverlayDir());
+    }
+    async readSkillFile(name) {
+        return readSkillFile(await this._baseSkillsDir(), await ensureSkillsOverlayDir(), name);
+    }
+    async writeSkillFile(name, content) {
+        const overlay = await ensureSkillsOverlayDir();
+        if (!overlay)
+            throw new Error('no writable skills overlay is configured');
+        await writeSkillFile(overlay, name, content);
+        await this._reloadSkills();
+        return { ok: true };
+    }
+    async copyBaseForEdit(name) {
+        const overlay = await ensureSkillsOverlayDir();
+        if (!overlay)
+            throw new Error('no writable skills overlay is configured');
+        const result = await copyBaseForEdit(await this._baseSkillsDir(), overlay, name);
+        if (result.copied)
+            await this._reloadSkills();
+        return result;
+    }
+    async deleteOverlaySkill(name) {
+        const overlay = await ensureSkillsOverlayDir();
+        if (!overlay)
+            throw new Error('no writable skills overlay is configured');
+        const result = await deleteOverlaySkill(overlay, name);
+        if (result.removed)
+            await this._reloadSkills();
+        return result;
+    }
+    resolveCredential(key, ctx) {
+        if (this._credentialStore)
+            return this._credentialStore(key, ctx);
+        const agentId = ctx?.agentId ?? null;
+        const deviceShared = isDeviceSharedCredentialKey(key);
+        for (const skill of ctx?.skills ?? []) {
+            const owned = this._credentials.get(scopeKey({ agentId, skill, key })) ??
+                (agentId && deviceShared ? this._credentials.get(scopeKey({ skill, key })) : undefined);
+            if (owned)
+                return owned;
+        }
+        if (agentId) {
+            const scoped = this._credentials.get(scopeKey({ agentId, key }));
+            if (scoped)
+                return scoped;
+        }
+        if (!agentId || deviceShared)
+            return this._credentials.get(scopeKey({ key })) ?? null;
+        return null;
+    }
+    async _completionSkills(agentId, model) {
+        const statuses = new Map((await this.skills(agentId, model, { skipCredentialProbe: true, skipBinProbe: true })).map((entry) => [entry.name, entry.status]));
+        return availableSkills(this._supportedSkills, new Set(this._tools.map((tool) => tool.name)), modelNameToCapabilityProfile(model)).map((entry) => ({
+            ...entry,
+            status: statuses.get(entry.name)
+        }));
+    }
+    async skills(agentId, modelName, options) {
+        await this.ready();
+        const platform = this._platform ?? detectPlatform();
+        const refresh = options?.refresh === true;
+        return resolveSkillStatuses(this._allSkills, {
+            installedTools: new Set(this._tools.map((tool) => tool.name)),
+            credentialStore: (key, ctx) => this.resolveCredential(key, ctx),
+            settingsStore: (skill, agentId) => this.skillSettings(skill, agentId),
+            platform,
+            agentId,
+            binVersions: options?.skipBinProbe === true
+                ? (this._binVersionCache?.bySkill ?? new Map())
+                : await this._probeBinVersions(platform, refresh),
+            refresh,
+            skipCredentialProbe: options?.skipCredentialProbe === true,
+            ...(modelName ? { activeProfile: modelNameToCapabilityProfile(modelName) } : {})
+        });
+    }
+    async _reloadSkills() {
+        const skillsDir = this._skillsDir ?? (await ensureBundledSkillsDir());
+        this._allSkills = await loadSkillCatalog(skillsDir, { platform: null });
+        const platform = this._platform ?? detectPlatform();
+        const supported = this._allSkills.filter((skill) => skillSupportsPlatform(skill, platform));
+        this._supportedSkills = availableSkills(supported, new Set(this._tools.map((t) => t.name)));
+    }
+    async _startOverlayWatch() {
+        if (this._overlayWatcher)
+            return;
+        try {
+            const overlay = await ensureSkillsOverlayDir();
+            if (!overlay)
+                return;
+            this._overlayWatcher = watchSkillsOverlay(overlay, () => {
+                this._reloadSkills().catch((err) => hlog('overlay reload failed', { err: err instanceof Error ? err.message : String(err) }));
+            });
+        }
+        catch (err) {
+            hlog('overlay watch unavailable', { err: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    async tools() {
+        return toolCatalog(this._tools);
+    }
+    _binVersionCache = null;
+    _binVersionInflight = null;
+    async _probeBinVersions(platform, refresh = false) {
+        const now = Date.now();
+        if (!refresh && this._binVersionCache && this._binVersionCache.expiresAt > now) {
+            return this._binVersionCache.bySkill;
+        }
+        if (this._binVersionInflight)
+            return this._binVersionInflight;
+        this._binVersionInflight = this._runBinVersionProbes(platform)
+            .then((bySkill) => {
+            this._binVersionCache = {
+                expiresAt: Date.now() + BIN_VERSION_PROBE_TTL_MS,
+                bySkill
+            };
+            return bySkill;
+        })
+            .finally(() => {
+            this._binVersionInflight = null;
+        });
+        return this._binVersionInflight;
+    }
+    async _runBinVersionProbes(platform) {
+        if (process.env.QVAC_NO_SKILL_BIN_PROBE)
+            return new Map();
+        const installed = new Set(this._tools.map((tool) => tool.name));
+        const candidates = versionProbeSkills(this._allSkills, installed, platform);
+        if (candidates.length === 0)
+            return new Map();
+        let runtime;
+        try {
+            runtime = await bareRuntime();
+        }
+        catch {
+            return new Map();
+        }
+        const run = async (command) => {
+            try {
+                const result = await runCommand(command, { ...runtime, timeoutMs: 5_000 });
+                return result.exitCode === 0 ? result.stdout : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const bySkill = new Map();
+        for (const skill of candidates) {
+            const states = await probeBinVersions(skill.requires, { platform, run });
+            if (states.size > 0)
+                bySkill.set(skill.name, states);
+        }
+        return bySkill;
+    }
+    get toolNames() {
+        return this._tools.map((tool) => tool.name);
+    }
+    get supportsImages() {
+        if (!this._projectionModel)
+            return false;
+        if (typeof this._projectionModel === 'string')
+            return true;
+        return Object.keys(this._projectionModel).length > 0;
+    }
+    supportsImagesFor(model) {
+        return Boolean(this._projectionFor(model));
+    }
+    _projectionFor(model) {
+        const custom = this._customProjection[model];
+        if (custom)
+            return custom;
+        const projection = this._projectionModel;
+        if (!projection)
+            return undefined;
+        return typeof projection === 'string' ? projection : projection[model];
+    }
+    setCustomModels(entries) {
+        setCustomModels(entries);
+        this._customProjection = customProjectionMap();
+    }
+    async describe() {
+        if (!this.opened)
+            await this.ready();
+        return {
+            toolNames: this.toolNames,
+            skills: this._supportedSkills.map((skill) => skill.name),
+            supportsImages: this.supportsImages,
+            supportsKvCacheDeletion: true
+        };
+    }
+    diagnostics() {
+        return {
+            models: this.opened ? this._loadedModels() : [],
+            suspended: this.suspended,
+            sdkLoaded: this._sdk.peek() !== null,
+            toolNames: this.toolNames,
+            skills: this._supportedSkills.map((skill) => skill.name),
+            device: this._llmDevice
+        };
+    }
+    _loadedModels() {
+        const pools = [this._embedModels, ...this._retiredEmbedModels];
+        if (this._ttsModels)
+            pools.push(this._ttsModels);
+        if (this._transcriptionModels)
+            pools.push(this._transcriptionModels);
+        return [...loadedModels(this._models), ...pools.flatMap((pool) => loadedModels(pool))];
+    }
+    _loadPluginSdk(current, store, importPlugin) {
+        let pending = current();
+        if (!pending) {
+            pending = (async () => {
+                const sdk = await this._sdk.load();
+                const [plugin, { registerPlugin }] = await Promise.all([
+                    importPlugin(),
+                    import('@qvac/sdk/plugins')
+                ]);
+                try {
+                    registerPlugin(plugin);
+                }
+                catch { }
+                return sdk;
+            })().catch((err) => {
+                store(null);
+                throw err;
+            });
+            store(pending);
+        }
+        return pending;
+    }
+    _loadDiffusionSdk() {
+        return this._loadPluginSdk(() => this._diffusionSdk, (sdk) => {
+            this._diffusionSdk = sdk;
+        }, () => import('@qvac/sdk/sdcpp-generation/plugin').then((m) => m.diffusionPlugin));
+    }
+    _loadMusicSdk() {
+        return this._loadPluginSdk(() => this._musicSdk, (sdk) => {
+            this._musicSdk = sdk;
+        }, () => import('@qvac/sdk/audiogen-ggml/plugin').then((m) => m.audioGenPlugin));
+    }
+    _deviceConfig() {
+        return {
+            device: this._llmDevice,
+            gpuLayers: this._llmGpuLayers,
+            contextSize: this._contextSize,
+            kvCacheK: this._kvCacheK,
+            kvCacheV: this._kvCacheV,
+            mainGpu: resolveMainGpu,
+            openclCacheDir
+        };
+    }
+    _createPool() {
+        const loadSdk = this._sdk.load;
+        return createModelPool(loadSdk, (state) => this._notifyModel(state, true), this._deviceConfig(), this._loads);
+    }
+    _createEmbedPool() {
+        const loadSdk = () => this._sdk.loadEmbed();
+        return createEmbedPool(loadSdk, (state) => this._notifyModel(state, false), this._embedFaults, this._embedBatchSize, openclCacheDir, this._loads);
+    }
+    _createTtsPool() {
+        const loadSdk = () => this._sdk.loadVoice();
+        return createVoicePool(loadSdk, (state) => this._notifyModel(state, false), 'tts-ggml', 'tts', TTS_MODEL_CONFIG, undefined, this._loads);
+    }
+    _createTranscriptionPool() {
+        const loadSdk = () => this._sdk.loadVoice();
+        return createVoicePool(loadSdk, (state) => this._notifyModel({ ...state, model: TRANSCRIPTION_MODEL_LABEL }, false), 'parakeet-transcription', 'parakeet', { useGPU: this._transcriptionDevice !== 'cpu' }, openclCacheDir, this._loads);
+    }
+    _notifyModel(state, languageModel) {
+        const catalogChanged = languageModel && (state.status === 'ready' || state.status === 'unloaded');
+        if (catalogChanged) {
+            invalidateModelStatusCache(this._modelStatus);
+        }
+        this.emit('model', { ...state, catalogChanged, loaded: this._loadedModels() });
+    }
+    async _collectRetiredEmbedPool(pool) {
+        if (!this._retiredEmbedModels.has(pool) || pool.idle !== pool.size)
+            return;
+        this._retiredEmbedModels.delete(pool);
+        await pool.destroy();
+    }
+    async _releaseEmbedResource(pool, key) {
+        releaseModel(pool, key);
+        await this._collectRetiredEmbedPool(pool);
+    }
+    _releaseEmbedResourceAfter(settled, pool, key) {
+        settled
+            .then(() => this._releaseEmbedResource(pool, key), () => this._releaseEmbedResource(pool, key))
+            .catch(noop);
+    }
+    async _destroyEmbedPools() {
+        const pools = [this._embedModels, ...this._retiredEmbedModels];
+        this._retiredEmbedModels.clear();
+        await Promise.all(pools.map((pool) => pool.destroy()));
+    }
+    _enqueueEmbedControl(run) {
+        const next = this._embedControl.then(run, run);
+        this._embedControl = next.catch(noop);
+        return next;
+    }
+    getEmbeddingDevice() {
+        return this._embedFaults.device;
+    }
+    setEmbeddingDevice(device) {
+        assertEmbedDevice(device);
+        return this._enqueueEmbedControl(() => this._setEmbeddingDevice(device));
+    }
+    async _setEmbeddingDevice(device) {
+        await this.ready();
+        if (this.closing)
+            throw new Error('harness is closing');
+        if (this._embedFaults.device === device)
+            return;
+        this._embedFaults = createGpuFaultState({ device, gpuLayers: this._embedGpuLayers });
+        if (this.suspended)
+            return;
+        const retired = this._embedModels;
+        this._retiredEmbedModels.add(retired);
+        this._embedModels = this._createEmbedPool();
+        await this._collectRetiredEmbedPool(retired);
+    }
+    async presuspend() {
+        if (this.closing)
+            return;
+        this._state = HarnessState.PRESUSPEND;
+        hlog('presuspend');
+    }
+    async suspend() {
+        hlog('suspend called');
+        if (this._state === HarnessState.SUSPEND)
+            return;
+        if (this.closing)
+            return;
+        this._state = HarnessState.SUSPEND;
+        hlog('suspending', { models: loadedModels(this._models).map((entry) => entry.model) });
+        const pending = this._sdk.peek();
+        if (pending)
+            this._loads.drain(await pending);
+        await this._releaseRuntimes();
+        await this._sdkLifecycle('suspend');
+        invalidateModelStatusCache(this._modelStatus);
+        hlog('suspended');
+    }
+    async _sdkLifecycle(op) {
+        const sdk = await this._sdk.peek()?.catch(noop);
+        if (!sdk)
+            return;
+        try {
+            await sdk[op]();
+        }
+        catch (err) {
+            hlog(`sdk ${op} failed`, { err: err instanceof Error ? err.message : String(err) });
+            if (op === 'suspend')
+                return;
+            await sdk.resume().catch((retryErr) => {
+                hlog('sdk resume retry failed', {
+                    err: retryErr instanceof Error ? retryErr.message : String(retryErr)
+                });
+            });
+        }
+    }
+    async _releaseRuntimes() {
+        const released = await Promise.allSettled([
+            this._models.destroy(),
+            this._destroyEmbedPools(),
+            this._ttsModels.destroy(),
+            this._transcriptionModels.destroy(),
+            this._imageRuntime?.unload(),
+            this._musicRuntime?.unload()
+        ]);
+        for (const outcome of released) {
+            if (outcome.status !== 'rejected')
+                continue;
+            const err = outcome.reason;
+            hlog('unload failed', { err: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    async resume() {
+        hlog('resume called');
+        if (this._state === HarnessState.RESUME)
+            return;
+        if (this.closing)
+            return;
+        if (this._state === HarnessState.PRESUSPEND) {
+            this._state = HarnessState.RESUME;
+            return;
+        }
+        this._state = HarnessState.RESUME;
+        hlog('resuming', { pools: 'recreated' });
+        this._loads.undrain();
+        this._models = this._createPool();
+        this._embedModels = this._createEmbedPool();
+        this._ttsModels = this._createTtsPool();
+        this._transcriptionModels = this._createTranscriptionPool();
+        await this._sdkLifecycle('resume');
+    }
+    async wakeup() {
+        if (this.closing)
+            return;
+        this._state = HarnessState.WAKEUP;
+        hlog('wakeup');
+        await this.resume();
+    }
+    async _close() {
+        hlog('closing');
+        this._overlayWatcher?.stop();
+        this._overlayWatcher = null;
+        const pending = this._sdk.peek();
+        if (pending)
+            this._loads.drain(await pending);
+        await Promise.all([this._releaseRuntimes(), closePythonWorker()]);
+        const sdk = await this._sdk.peek()?.catch(noop);
+        if (sdk)
+            await sdk.close();
+    }
+    download(args) {
+        const projection = (args.addon ?? 'llm') === 'llm' ? this._projectionFor(args.model) : undefined;
+        const multiFile = diffusionDownloadMetadata(args.model, args.addon) ??
+            audioGenDownloadMetadata(args.model, args.addon);
+        return download(async () => {
+            await this.ready();
+            return this._sdk.load();
+        }, {
+            ...args,
+            projection,
+            companions: multiFile?.companions,
+            assetSizes: multiFile?.assetSizes
+        }, () => invalidateModelStatusCache(this._modelStatus));
+    }
+    async embed({ model, texts, signal }) {
+        await this.ready();
+        if (this.suspended)
+            throw new Error('harness is suspended');
+        if (texts.length === 0)
+            return [];
+        const pool = this._embedModels;
+        const faults = this._embedFaults;
+        const generation = faults.generation;
+        const key = faults.key(model);
+        const handle = pool.open(key, model);
+        let loaded = null;
+        let job = null;
+        let releaseAfter = null;
+        try {
+            loaded = await raceAbort(handle.load(), signal);
+            const sdk = (await this._sdk.loadEmbed());
+            job = this._embedLane(sdk, { modelId: loaded.modelId, texts });
+            const vectors = await raceAbort(job, signal);
+            faults.reset();
+            return vectors;
+        }
+        catch (err) {
+            if (err instanceof AbortedError) {
+                releaseAfter = job ?? (this._retiredEmbedModels.has(pool) ? handle.peek() : null);
+            }
+            if (isSdkGpuDeviceLostError(err)) {
+                faults.recordFault(generation);
+                if (loaded) {
+                    const dead = loaded.modelId;
+                    await this._sdk
+                        .loadEmbed()
+                        .then((sdk) => sdk.unloadModel({ modelId: dead }))
+                        .catch(noop);
+                }
+            }
+            throw err;
+        }
+        finally {
+            if (releaseAfter)
+                this._releaseEmbedResourceAfter(releaseAfter, pool, key);
+            else
+                await this._releaseEmbedResource(pool, key);
+        }
+    }
+    async _defaultVoiceSrc(category) {
+        if (category !== 'tts')
+            return defaultVoiceModel(category);
+        try {
+            const { capabilityProfile } = await this.capability();
+            return defaultTtsFor(capabilityProfile).asset.src;
+        }
+        catch {
+            return defaultVoiceModel('tts');
+        }
+    }
+    async _voiceJob(pool, category, model, signal, run) {
+        await this.ready();
+        if (this.suspended)
+            throw new Error('harness is suspended');
+        const name = model || (await this._defaultVoiceSrc(category));
+        const handle = pool.open(name, name);
+        let job = null;
+        let releaseAfter = null;
+        let sdk = null;
+        let modelId = null;
+        try {
+            modelId = (await raceAbort(handle.load(), signal)).modelId;
+            sdk = (await this._sdk.loadVoice());
+            const boundSdk = sdk;
+            const boundId = modelId;
+            job = this._voiceLane(() => run(boundSdk, boundId));
+            return await raceAbort(job, signal);
+        }
+        catch (err) {
+            if (err instanceof AbortedError) {
+                if (sdk && modelId)
+                    void sdk.cancel({ modelId, operation: 'inference' }).catch(noop);
+                releaseAfter = job;
+            }
+            throw err;
+        }
+        finally {
+            const release = () => {
+                releaseModel(pool, name);
+            };
+            if (releaseAfter)
+                void releaseAfter.then(release, release);
+            else
+                release();
+        }
+    }
+    async transcribe({ model, audio, signal }) {
+        return this._voiceJob(this._transcriptionModels, 'transcription', model, signal, async (sdk, id) => {
+            const pcm = await pcmForTranscription(audio);
+            if (signal?.aborted)
+                throw new AbortedError();
+            if (pcm && pcm.length >= TRANSCRIBE_STREAM_MIN_BYTES) {
+                return transcribeStreaming(sdk, id, pcm, signal);
+            }
+            return transcribeOnce(sdk, id, pcm ? buildWavBuffer(pcm) : audio);
+        });
+    }
+    async speak({ model, text, signal }) {
+        const samples = await this._voiceJob(this._ttsModels, 'tts', model, signal, (sdk, id) => speakOnce(sdk, id, text));
+        return { audio: packSamples(samples), sampleRate: SUPERTONIC_SAMPLE_RATE };
+    }
+    async *speakStream({ model, text, signal }) {
+        await this.ready();
+        if (this.suspended)
+            throw new Error('harness is suspended');
+        const name = model || (await this._defaultVoiceSrc('tts'));
+        const pool = this._ttsModels;
+        const handle = pool.open(name, name);
+        const chunks = pushQueue();
+        let sdk = null;
+        let modelId = null;
+        const cancel = () => {
+            if (sdk && modelId)
+                void sdk.cancel({ modelId, operation: 'inference' }).catch(() => { });
+        };
+        signal?.addEventListener('abort', cancel, { once: true });
+        const job = this._voiceLane(async () => {
+            try {
+                modelId = (await handle.load()).modelId;
+                sdk = (await this._sdk.loadVoice());
+                if (signal?.aborted)
+                    return;
+                for await (const chunk of speakStreamOnce(sdk, modelId, text))
+                    chunks.push(chunk);
+            }
+            finally {
+                chunks.end();
+            }
+        });
+        let settled = false;
+        try {
+            yield* chunks;
+            await job;
+            settled = true;
+        }
+        finally {
+            signal?.removeEventListener('abort', cancel);
+            if (!settled)
+                cancel();
+            void job.catch(noop).finally(() => {
+                releaseModel(pool, name);
+            });
+        }
+    }
+    async list(options = {}) {
+        await this.ready();
+        const sdk = (await this._sdk.load());
+        return listModels(sdk, options, this._modelStatus, (name) => this._projectionFor(name));
+    }
+    async deleteModel(name) {
+        await this.ready();
+        const sdk = (await this._sdk.load());
+        const result = await deleteModelFiles(sdk, name);
+        invalidateModelStatusCache(this._modelStatus);
+        return summarizeDelete(result);
+    }
+    async clearKvCache() {
+        await this.ready();
+        return deleteAllKvCaches(() => this._sdk.load());
+    }
+    async infraModels(profile) {
+        return infraModelsFor(profile);
+    }
+    async capability() {
+        if (this._capability)
+            return this._capability;
+        if (this._capabilityInflight)
+            return this._capabilityInflight;
+        const reads = {
+            totalmem,
+            platform,
+            readFile: async (path) => {
+                try {
+                    return String(await fs.promises.readFile(path, 'utf8'));
+                }
+                catch {
+                    return null;
+                }
+            },
+            run: async (command) => {
+                try {
+                    const runtime = await bareRuntime();
+                    const result = await runCommand(command, { ...runtime, timeoutMs: 5_000 });
+                    return result.exitCode === 0 ? result.stdout : null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            readGpuStats: () => readSystemStats()
+        };
+        this._capabilityInflight = probeCapabilityProfile(reads)
+            .then((capability) => {
+            this._capability = capability;
+            return capability;
+        })
+            .finally(() => {
+            this._capabilityInflight = null;
+        });
+        return this._capabilityInflight;
+    }
+    async warmModel({ model, agent, signal }) {
+        await this.ready();
+        if (this.suspended)
+            return;
+        const projectionModel = this._projectionFor(model);
+        const loadOpts = resolveLoadOptions({
+            ctxSize: agent?.ctxSize ?? undefined,
+            kvCacheK: agent?.kvCacheK ?? undefined,
+            kvCacheV: agent?.kvCacheV ?? undefined,
+            projectionModel
+        }, this._deviceConfig());
+        const key = modelKey(model, loadOpts);
+        const pool = this._models;
+        hlog('warm model', { model, resident: isResident(pool, key) });
+        if (!isResident(pool, key)) {
+            await evictIdle(pool);
+            await this._imageRuntime?.unloadIdle().catch(noop);
+        }
+        try {
+            await raceAbort(pool.open(key, model, loadOpts).load(), signal);
+        }
+        finally {
+            releaseModel(pool, key);
+        }
+    }
+    async *completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }) {
+        await this.ready();
+        if (this.suspended)
+            throw new Error('harness is suspended');
+        const projectionModel = this._projectionFor(model);
+        const loadOpts = resolveLoadOptions({
+            ctxSize: agent?.ctxSize ?? undefined,
+            kvCacheK: agent?.kvCacheK ?? undefined,
+            kvCacheV: agent?.kvCacheV ?? undefined,
+            projectionModel
+        }, this._deviceConfig());
+        const key = modelKey(model, loadOpts);
+        const pool = this._models;
+        const resident = isResident(pool, key);
+        hlog('completion start', { model, resident, projection: Boolean(projectionModel) });
+        if (!resident) {
+            await evictIdle(pool);
+            await this._imageRuntime?.unloadIdle().catch(noop);
+            await this._musicRuntime?.unloadIdle().catch(noop);
+        }
+        const acquireRound = async () => {
+            if (!isResident(pool, key)) {
+                await evictIdle(pool);
+                await this._imageRuntime?.unloadIdle().catch(noop);
+                await this._musicRuntime?.unloadIdle().catch(noop);
+            }
+            try {
+                const { modelId } = await raceAbort(pool.open(key, model, loadOpts).load(), signal);
+                return {
+                    modelId,
+                    release: () => {
+                        releaseModel(pool, key);
+                    }
+                };
+            }
+            catch (err) {
+                releaseModel(pool, key);
+                throw err;
+            }
+        };
+        const handle = pool.open(key, model, loadOpts);
+        let held = true;
+        const releaseHeld = () => {
+            if (!held)
+                return;
+            held = false;
+            releaseModel(pool, key);
+        };
+        try {
+            const { modelId, ctxSize } = await raceAbort(handle.load(), signal);
+            hlog('model ready', { model });
+            const sdk = await this._sdk.load();
+            const turns = projectionModel ? messages : messages.map(({ attachments, ...turn }) => turn);
+            const remoteRoots = driveOp && grantedDrives?.length ? createRemoteRoots(grantedDrives, driveOp) : [];
+            const fsRoots = [
+                ...(grantedDirs?.length ? await createLocalRoots(grantedDirs) : []),
+                ...remoteRoots
+            ];
+            const fsWriteRoots = [
+                ...(grantedWriteDirs?.length ? await createLocalRoots(grantedWriteDirs) : []),
+                ...remoteRoots.filter((root) => root.writable)
+            ];
+            releaseHeld();
+            yield* completion(sdk, {
+                modelId,
+                acquireRound,
+                model,
+                agent,
+                ctxSize,
+                cacheKey,
+                thinkingDefault,
+                generationParams,
+                responseFormat,
+                messages: turns,
+                tools: this._tools,
+                skillCatalog: await this._completionSkills(agent?.id ?? null, model),
+                toolConfigs,
+                fsRoots,
+                fsWriteRoots,
+                approve,
+                attach,
+                fetchAttachment,
+                ragSearch,
+                progress,
+                askUser,
+                signal
+            });
+            this._modelFaults.delete(model);
+        }
+        catch (err) {
+            if (err instanceof AbortedError || this.suspended) {
+                hlog('completion aborted', { model, suspended: this.suspended });
+                yield { type: 'aborted' };
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                hlog('completion failed', { model, ...resolutionDetail(err), err: message });
+                if (isSdkModelWedgedError(err)) {
+                    const wedged = await this._evictWedgedModel(model, key);
+                    yield { type: 'error', message: wedged.message };
+                    if (wedged.fatal)
+                        process.exit(1);
+                }
+                else {
+                    yield { type: 'error', message };
+                }
+            }
+        }
+        finally {
+            hlog('completion end', { model });
+            releaseHeld();
+            void this._imageRuntime?.unloadIdle().catch(noop);
+            void this._musicRuntime?.unloadIdle().catch(noop);
+        }
+    }
+    async _evictWedgedModel(model, key) {
+        const faults = (this._modelFaults.get(model) ?? 0) + 1;
+        this._modelFaults.set(model, faults);
+        const leased = leaseCount(this._models, key) > 0;
+        const evicted = leased ? false : await evictModelWithin(this._models, key, WEDGED_EVICT_WAIT_MS);
+        hlog('wedged model evicted', { model, faults, evicted, leased });
+        if (leased)
+            this._evictAfterLeases(model, key);
+        if (!evicted && !leased) {
+            return {
+                message: `${model} is stuck in device memory — restarting the model runtime`,
+                fatal: true
+            };
+        }
+        return {
+            message: faults > 1
+                ? `${model} keeps failing during inference on this device — it may need more memory than is available`
+                : `${model} failed during inference and was unloaded — try again`,
+            fatal: false
+        };
+    }
+    _evictAfterLeases(model, key) {
+        void evictModelWithin(this._models, key, WEDGED_EVICT_LEASED_MS)
+            .then((evicted) => hlog('wedged model evicted after leases', { model, evicted }))
+            .catch(noop);
+    }
+}
+function noop() { }