@qvac/harness 0.1.0 → 0.1.1

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

@@ -0,0 +1,7 @@
+import type { Message } from './capabilities/completion.ts';
+export declare const TOOL_RESULT_TRUNCATION_MARKER = "\n[tool result truncated for context]\n";
+export interface ContextCandidate {
+    history: Message[];
+    droppedTurns: number;
+}
+export declare function contextCandidates(history: Message[]): ContextCandidate[];

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

@@ -0,0 +1,90 @@
+import { TOOL_CONTINUATION_NUDGE } from "./capabilities/tool-turns.js";
+export const TOOL_RESULT_TRUNCATION_MARKER = '\n[tool result truncated for context]\n';
+function isTurnBoundary(message) {
+    return message.role === 'user' && message.content !== TOOL_CONTINUATION_NUDGE;
+}
+export function contextCandidates(history) {
+    const { prefix, turns } = splitTurns(history);
+    if (!turns.length)
+        return [{ history, droppedTurns: 0 }];
+    const maxDropped = Math.max(0, turns.length - 1);
+    const candidates = dropCounts(maxDropped).map((droppedTurns) => ({
+        history: droppedTurns ? [...prefix, ...turns.slice(droppedTurns).flat()] : history,
+        droppedTurns
+    }));
+    appendToolCompactions(candidates);
+    return candidates;
+}
+function splitTurns(history) {
+    const firstUser = history.findIndex(isTurnBoundary);
+    if (firstUser === -1)
+        return { prefix: history, turns: [] };
+    const prefix = history.slice(0, firstUser);
+    const starts = [];
+    for (let i = firstUser; i < history.length; i++) {
+        if (isTurnBoundary(history[i]))
+            starts.push(i);
+    }
+    const turns = starts.map((start, index) => history.slice(start, starts[index + 1]));
+    return { prefix, turns };
+}
+function dropCounts(max) {
+    const counts = [0];
+    for (let step = 1; counts[counts.length - 1] < max; step *= 2) {
+        const next = Math.min(max, step);
+        if (next !== counts[counts.length - 1])
+            counts.push(next);
+    }
+    return counts;
+}
+function appendToolCompactions(candidates) {
+    const last = candidates[candidates.length - 1];
+    if (!last)
+        return;
+    const tools = compactableTools(last.history);
+    let history = last.history;
+    while (true) {
+        const selected = longestTool(tools);
+        if (!selected)
+            return;
+        selected.target = Math.max(TOOL_RESULT_TRUNCATION_MARKER.length, Math.floor(selected.target / 2));
+        history = history.map(compactTool.bind(null, selected));
+        candidates.push({ history, droppedTurns: last.droppedTurns });
+    }
+}
+function compactableTools(history) {
+    let newestUser = -1;
+    for (let index = history.length - 1; index >= 0; index--) {
+        if (!isTurnBoundary(history[index]))
+            continue;
+        newestUser = index;
+        break;
+    }
+    if (newestUser === -1)
+        return [];
+    const tools = [];
+    for (let index = newestUser + 1; index < history.length; index++) {
+        const message = history[index];
+        if (message.role !== 'tool' || message.content.length <= TOOL_RESULT_TRUNCATION_MARKER.length) {
+            continue;
+        }
+        tools.push({ index, original: message.content, target: message.content.length });
+    }
+    return tools;
+}
+function longestTool(tools) {
+    return tools
+        .filter((tool) => tool.target > TOOL_RESULT_TRUNCATION_MARKER.length)
+        .sort((a, b) => b.target - a.target)[0];
+}
+function compactContent(content, target) {
+    const retained = target - TOOL_RESULT_TRUNCATION_MARKER.length;
+    const head = Math.ceil(retained / 2);
+    const tail = Math.floor(retained / 2);
+    return `${content.slice(0, head)}${TOOL_RESULT_TRUNCATION_MARKER}${tail ? content.slice(-tail) : ''}`;
+}
+function compactTool(selected, message, index) {
+    if (index !== selected.index)
+        return message;
+    return { ...message, content: compactContent(selected.original, selected.target) };
+}

package/dist-lib/lib/contract-types.d.ts

@@ -0,0 +1,210 @@
+import type { HarnessCapabilityProfile } from '../spec/hyperschema/types.d.ts';
+import type { ApproveFn, AskUserFn, AttachFn, FetchAttachmentFn, ProgressFn, RagSearchFn, ResourceDescriptor, ResponseFormat } from './capabilities/completion.ts';
+import type { KvCacheDeletionResult } from './capabilities/kv-cache.ts';
+import type { MemoryBudget } from './hardware/memory-budget.ts';
+import type { EmbedDevice } from './models/embed-config.ts';
+import type { LlmGenerationParams } from './models/llm-presets.ts';
+import type { DeleteModelSummary } from './models/model-delete.ts';
+import type { ListModelsOptions, ModelInfo } from './models/model-list.ts';
+import type { ToolCatalogEntry } from './tools/catalog.ts';
+import type { ManagedSkill, SkillFileContent } from './tools/skills/overlay-crud.ts';
+import type { DriveOpFn, GrantedDrive } from './tools/fs/remote.ts';
+import type { ResolvedSkillCatalogEntry } from './tools/skills/catalog.ts';
+import type { InstallStep, SkillSetup } from './tools/skills/manifest.ts';
+export type { InstallStep, ListModelsOptions, ModelInfo, ResolvedSkillCatalogEntry, ResourceDescriptor, SkillSetup, ToolCatalogEntry };
+export type ApprovalCall = Parameters<ApproveFn>[0];
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    attachments?: {
+        path: string;
+    }[] | null;
+}
+export interface AgentKnobs {
+    id?: string;
+    name?: string;
+    bio?: string;
+    reasoning?: 'inherit' | 'enabled' | 'disabled' | null;
+    enabledTools?: string[] | null;
+    enabledSkills?: string[] | null;
+    toolsScope?: 'all' | 'selected' | null;
+    skillsScope?: 'all' | 'selected' | null;
+    ctxSize?: number | null;
+    kvCacheK?: string | null;
+    kvCacheV?: string | null;
+    imageModelChoice?: string | null;
+    imageSteps?: number | null;
+    imageWidth?: number | null;
+    imageHeight?: number | null;
+    approvalMode?: 'ask' | 'skip-all' | null;
+    disabledToolsets?: string[] | null;
+}
+export interface CompletionContext {
+    model: string;
+    agent: AgentKnobs;
+    messages: ChatMessage[];
+    cacheKey?: string;
+    thinkingDefault?: string;
+    toolConfigs?: Record<string, Record<string, unknown>>;
+    generationParams?: LlmGenerationParams;
+    responseFormat?: ResponseFormat;
+    grantedDirs?: string[];
+    grantedDrives?: GrantedDrive[];
+    driveOp?: DriveOpFn;
+    grantedWriteDirs?: string[];
+    approve?: (call: ApprovalCall) => Promise<boolean>;
+    attach?: AttachFn;
+    fetchAttachment?: FetchAttachmentFn;
+    ragSearch?: RagSearchFn;
+    progress?: ProgressFn;
+    askUser?: AskUserFn;
+    signal?: {
+        aborted?: boolean;
+        addEventListener?: (type: 'abort', fn: () => void, opts?: {
+            once?: boolean;
+        }) => void;
+        removeEventListener?: (type: 'abort', fn: () => void) => void;
+    };
+}
+export interface HarnessEvent {
+    type: string;
+    text?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface ModelState {
+    status: string;
+    model?: string;
+    percentage?: number;
+    downloaded?: number;
+    total?: number;
+    message?: string;
+    catalogChanged?: boolean;
+    loaded?: Array<{
+        model: string;
+        refs: number;
+    }>;
+}
+export interface WarmModelContext {
+    model: string;
+    agent?: AgentKnobs;
+    signal?: CompletionContext['signal'];
+}
+export interface DownloadContext {
+    model: string;
+    addon?: string;
+    seed?: boolean;
+    signal?: CompletionContext['signal'];
+}
+export interface EmbedContext {
+    model: string;
+    texts: string[];
+    signal?: CompletionContext['signal'];
+}
+export interface TranscribeContext {
+    model: string;
+    audio: Buffer;
+    signal?: CompletionContext['signal'];
+}
+export interface SpeakContext {
+    model: string;
+    text: string;
+    signal?: CompletionContext['signal'];
+}
+export interface SpeakResult {
+    audio: Buffer;
+    sampleRate: number;
+}
+export interface SpeakStreamContext {
+    model: string;
+    text: AsyncIterable<string>;
+    signal?: CompletionContext['signal'];
+}
+export interface HarnessDiagnostics {
+    models: Array<{
+        model: string;
+        refs: number;
+    }>;
+    suspended: boolean;
+    sdkLoaded: boolean;
+    toolNames: string[];
+    skills: string[];
+    device?: 'cpu' | 'gpu';
+}
+export interface HarnessInfo {
+    toolNames: string[];
+    skills: string[];
+    supportsImages: boolean;
+    supportsKvCacheDeletion?: boolean;
+}
+export interface CapabilityInfo {
+    capabilityProfile: HarnessCapabilityProfile;
+    recommendedModelName: string;
+    memoryBudget?: MemoryBudget;
+}
+export interface HarnessContract {
+    completion(context: CompletionContext): AsyncIterable<HarnessEvent>;
+    download?(context: DownloadContext): AsyncIterable<HarnessEvent>;
+    describe?(): Promise<HarnessInfo | null> | HarnessInfo;
+    embed?(context: EmbedContext): Promise<number[][]>;
+    transcribe?(context: TranscribeContext): Promise<string>;
+    speak?(context: SpeakContext): Promise<SpeakResult>;
+    speakStream?(context: SpeakStreamContext): AsyncIterable<SpeakResult>;
+    getEmbeddingDevice?(): EmbedDevice | Promise<EmbedDevice>;
+    setEmbeddingDevice?(device: EmbedDevice): Promise<void> | void;
+    on?(event: 'model' | 'status', listener: (...args: never[]) => void): unknown;
+    off?(event: 'model' | 'status', listener: (...args: never[]) => void): unknown;
+    presuspend?(): Promise<void> | void;
+    suspend?(): Promise<void> | void;
+    wakeup?(): Promise<void> | void;
+    resume?(): Promise<void> | void;
+    skills?(agentId?: string | null, modelName?: string | null, options?: {
+        readonly refresh?: boolean;
+        readonly skipCredentialProbe?: boolean;
+    }): Promise<ResolvedSkillCatalogEntry[]>;
+    tools?(): Promise<ToolCatalogEntry[]>;
+    setCredentials?(entries: ReadonlyArray<{
+        key: string;
+        token?: string | null;
+        expiresAt?: number | null;
+        agentId?: string | null;
+        skill?: string | null;
+    }>): void | Promise<void>;
+    setSkillSettings?(entries: ReadonlyArray<{
+        skill: string;
+        key: string;
+        value: string;
+        agentId?: string | null;
+    }>): void | Promise<void>;
+    listManagedSkills?(): Promise<ManagedSkill[]>;
+    readSkillFile?(name: string): Promise<SkillFileContent | null>;
+    writeSkillFile?(name: string, content: string): Promise<{
+        readonly ok: boolean;
+    }>;
+    copyBaseForEdit?(name: string): Promise<{
+        readonly copied: boolean;
+    }>;
+    deleteOverlaySkill?(name: string): Promise<{
+        readonly removed: boolean;
+    }>;
+    list?(options?: ListModelsOptions): Promise<ModelInfo[]>;
+    warmModel?(context: WarmModelContext): Promise<void>;
+    deleteModel?(name: string): Promise<DeleteModelSummary>;
+    clearKvCache?(): Promise<KvCacheDeletionResult>;
+    infraModels?(profile: string): Promise<ReadonlyArray<{
+        name: string;
+        addon: string;
+    }>>;
+    setCustomModels?(entries: ReadonlyArray<{
+        name: string;
+        src: string;
+        projectionSrc?: string;
+    }>): void | Promise<void>;
+    capability?(): Promise<CapabilityInfo>;
+    diagnostics?(): HarnessDiagnostics;
+}
+export interface HarnessStatus {
+    state: 'running' | 'died';
+    error?: string;
+    code?: string;
+}

package/dist-lib/lib/contract-types.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/diagram-repair.d.ts

@@ -0,0 +1,21 @@
+export declare const DIAGRAM_REPAIR_PROMPT_PREFIX = "<!-- qvac:diagram-repair:";
+export declare const DIAGRAM_REPAIR_PROMPT_SUFFIX: string;
+export declare function diagramRepairPromptCount(content: string, parentRunId?: string): number | null;
+export declare function isDiagramRepairPrompt(content: string): boolean;
+export declare function completeMermaidDiagramCount(content: string): number;
+export declare function diagramRepairAccepted(text: string): boolean;
+type DiagramRepairRecord = {
+    readonly id: string;
+    readonly seq: number;
+    readonly runId?: string | null;
+    readonly parentId?: string | null;
+};
+export type DiagramRepairLink = {
+    readonly expectedCount: number;
+    readonly parentId: string;
+    readonly promptId: string;
+    readonly promptText: string;
+    readonly runId: string;
+};
+export declare function diagramRepairLinks<T extends DiagramRepairRecord>(records: ReadonlyArray<T>, textOf: (record: T) => string | null): ReadonlyArray<DiagramRepairLink>;
+export {};

package/dist-lib/lib/diagram-repair.js

@@ -0,0 +1,58 @@
+export const DIAGRAM_REPAIR_PROMPT_PREFIX = '<!-- qvac:diagram-repair:';
+export const DIAGRAM_REPAIR_PROMPT_SUFFIX = 'Rewrite the complete previous answer with corrected Mermaid code blocks. Preserve all non-diagram content. Return only the corrected answer. Do not call tools.\n' +
+    'Common fixes: put every label with spaces or punctuation in double quotes like A["Send (HTTP)"]; never use lowercase end as a node label - write "End"; the first line inside the fence must be the diagram type; close the fence before any prose - never leave a sentence inside it; give every node a unique id.';
+export function diagramRepairPromptCount(content, parentRunId) {
+    const match = /^<!-- qvac:diagram-repair:(\d+):([^\s>]+) -->\n(\d+) Mermaid diagram(?:s)? in your previous answer fail(?:s)? to render\.\n/.exec(content);
+    if (!match || !content.endsWith(`\n\n${DIAGRAM_REPAIR_PROMPT_SUFFIX}`))
+        return null;
+    const expected = Number(match[1]);
+    return Number.isSafeInteger(expected) &&
+        expected > 0 &&
+        Number(match[3]) > 0 &&
+        (!parentRunId || match[2] === parentRunId)
+        ? expected
+        : null;
+}
+export function isDiagramRepairPrompt(content) {
+    return diagramRepairPromptCount(content) !== null;
+}
+export function completeMermaidDiagramCount(content) {
+    const fence = /^[ \t]{0,3}(`{3,}|~{3,})[ \t]*mermaid[ \t]*\r?\n([\s\S]*?)^[ \t]{0,3}\1[ \t]*$/gm;
+    return [...content.matchAll(fence)].filter((match) => match[2]?.trim()).length;
+}
+export function diagramRepairAccepted(text) {
+    return completeMermaidDiagramCount(text) > 0;
+}
+export function diagramRepairLinks(records, textOf) {
+    const ordered = [...records].sort((left, right) => left.seq - right.seq);
+    const byId = new Map(ordered.map((record) => [record.id, record]));
+    const used = new Set();
+    return ordered.flatMap((child) => {
+        if (!child.runId || !child.parentId)
+            return [];
+        const parent = byId.get(child.parentId);
+        if (!parent?.runId)
+            return [];
+        const prompt = [...ordered]
+            .reverse()
+            .find((candidate) => candidate.seq > parent.seq &&
+            candidate.seq < child.seq &&
+            !used.has(candidate.id) &&
+            diagramRepairPromptCount(textOf(candidate) ?? '', parent.runId ?? undefined) !== null);
+        const promptText = prompt ? textOf(prompt) : null;
+        const expectedCount = diagramRepairPromptCount(promptText ?? '', parent.runId);
+        if (prompt)
+            used.add(prompt.id);
+        return prompt && promptText && expectedCount
+            ? [
+                {
+                    expectedCount,
+                    parentId: child.parentId,
+                    promptId: prompt.id,
+                    promptText,
+                    runId: child.runId
+                }
+            ]
+            : [];
+    });
+}

package/dist-lib/lib/dns-lookup.d.ts

@@ -0,0 +1 @@
+export declare function lookupHost(hostname: string): Promise<string[]>;

package/dist-lib/lib/dns-lookup.js

@@ -0,0 +1,13 @@
+import * as dns from '#dns';
+export function lookupHost(hostname) {
+    return new Promise((resolve, reject) => {
+        const callback = (err, addresses) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve((addresses ?? []).map((entry) => entry.address));
+        };
+        dns.lookup(hostname, { all: true }, callback);
+    });
+}

package/dist-lib/lib/error-fields.d.ts

@@ -0,0 +1,2 @@
+export declare function errorMessage(err: unknown): string;
+export declare function errorCode(err: unknown): string | undefined;

package/dist-lib/lib/error-fields.js

@@ -0,0 +1,8 @@
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function errorCode(err) {
+    if (!err || typeof err !== 'object' || !('code' in err))
+        return undefined;
+    return typeof err.code === 'string' ? err.code : undefined;
+}

package/dist-lib/lib/fetch-node.d.ts

@@ -0,0 +1 @@
+export default fetch;

package/dist-lib/lib/fetch-node.js

@@ -0,0 +1 @@
+export default fetch;

package/dist-lib/lib/hardware/capability-probe.d.ts

@@ -0,0 +1,9 @@
+import type { CapabilityInfo } from '../contract-types.ts';
+export interface PlatformReads {
+    totalmem(): number;
+    platform(): string;
+    readFile(path: string): Promise<string | null>;
+    run(command: string): Promise<string | null>;
+    readGpuStats(): unknown;
+}
+export declare function probeCapabilityProfile(reads: PlatformReads): Promise<CapabilityInfo>;

package/dist-lib/lib/hardware/capability-probe.js

@@ -0,0 +1,99 @@
+import process from 'process';
+import { capabilityProfileToModelName } from "../models/model-catalog.js";
+import { probeWithAddon } from "./gpu-probe-addon.js";
+import { mobileBudget, parseNvidiaSmiOutput, parseRocmSmiOutput, parseWindowsRegistryOutput, sharedRamBudget } from "./parsers.js";
+const GIB = 1024 * 1024 * 1024;
+const WINDOWS_REGISTRY_QUERY = "(Get-ItemProperty 'HKLM:\\SYSTEM\\ControlSet001\\Control\\Class\\{4d36e968-e325-11ce-bfc1-08002be10318}\\0*' -Name 'HardwareInformation.qwMemorySize' -ErrorAction SilentlyContinue).'HardwareInformation.qwMemorySize' | Sort-Object -Descending | Select-Object -First 1";
+const SYSFS_VRAM_PATHS = [
+    '/sys/class/drm/card0/device/mem_info_vram_total',
+    '/sys/class/drm/card1/device/mem_info_vram_total'
+];
+function pickTier(availableBytes) {
+    if (availableBytes >= 48 * GIB)
+        return 'xhigh';
+    if (availableBytes >= 30 * GIB)
+        return 'high';
+    if (availableBytes >= 8 * GIB)
+        return 'mid';
+    return 'low';
+}
+function tierProfile(budget) {
+    if (budget.source === 'mobile' || budget.source === 'software' || budget.source === 'no-gpu') {
+        return 'low';
+    }
+    return pickTier(budget.availableBytes);
+}
+function recommend(budget) {
+    const profile = tierProfile(budget);
+    return {
+        capabilityProfile: profile,
+        recommendedModelName: capabilityProfileToModelName(profile),
+        memoryBudget: {
+            ...budget,
+            totalBytes: Math.floor(budget.totalBytes),
+            availableBytes: Math.floor(budget.availableBytes)
+        }
+    };
+}
+async function probeSysfs(reads) {
+    for (const path of SYSFS_VRAM_PATHS) {
+        const raw = await reads.readFile(path);
+        if (!raw)
+            continue;
+        const bytes = Number.parseInt(raw.trim(), 10);
+        if (!Number.isNaN(bytes) && bytes > 0) {
+            return { totalBytes: bytes, availableBytes: bytes, source: 'vram' };
+        }
+    }
+    return null;
+}
+async function probeDesktop(reads) {
+    const ram = reads.totalmem();
+    const addon = probeWithAddon(reads.readGpuStats(), ram);
+    if (addon && addon.source === 'vram')
+        return addon;
+    const nvidia = await reads.run('nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits');
+    const nvidiaBudget = nvidia ? parseNvidiaSmiOutput(nvidia) : null;
+    if (nvidiaBudget)
+        return nvidiaBudget;
+    const rocm = await reads.run('rocm-smi --showmeminfo vram');
+    const rocmBudget = rocm ? parseRocmSmiOutput(rocm) : null;
+    if (rocmBudget)
+        return rocmBudget;
+    const sysfs = await probeSysfs(reads);
+    if (sysfs)
+        return sysfs;
+    const registry = await reads.run(`powershell -Command "${WINDOWS_REGISTRY_QUERY}"`);
+    const registryBudget = registry ? parseWindowsRegistryOutput(registry, ram) : null;
+    if (registryBudget)
+        return registryBudget;
+    if (addon)
+        return addon;
+    return { ...sharedRamBudget(ram), source: 'no-gpu' };
+}
+async function isPixel(reads) {
+    const out = await reads.run('getprop ro.product.brand');
+    return out?.trim().toLowerCase() === 'google';
+}
+async function probeMemoryBudget(reads) {
+    const os = reads.platform();
+    if (os === 'android' || os === 'ios')
+        return mobileBudget(reads.totalmem(), await isPixel(reads));
+    if (os === 'darwin')
+        return sharedRamBudget(reads.totalmem());
+    return probeDesktop(reads);
+}
+function forcedProfile() {
+    if (process.env['QVAC_WORKBENCH_E2E'] === '1')
+        return 'mid';
+    if (process.env['QVAC_WORKBENCH_FORCE_TINY_MODEL'] === '1')
+        return 'tiny';
+    return undefined;
+}
+export async function probeCapabilityProfile(reads) {
+    const forced = forcedProfile();
+    if (forced) {
+        return { capabilityProfile: forced, recommendedModelName: capabilityProfileToModelName(forced) };
+    }
+    return recommend(await probeMemoryBudget(reads));
+}

package/dist-lib/lib/hardware/gpu-classify.d.ts

@@ -0,0 +1,2 @@
+export type GpuClassification = 'discrete' | 'integrated' | 'software';
+export declare function classifyGpu(name: string): GpuClassification;

package/dist-lib/lib/hardware/gpu-classify.js

@@ -0,0 +1,32 @@
+const DISCRETE_GPU = [
+    /nvidia/i,
+    /geforce/i,
+    /quadro/i,
+    /tesla/i,
+    /amd radeon rx/i,
+    /radeon rx/i,
+    /radeon pro w/i,
+    /\barc\b.*\b[ab]\d{2,}/i,
+    /adreno/i,
+    /mali-g/i,
+    /apple m\d/i
+];
+const INTEGRATED_GPU = [
+    /intel.*(hd|uhd|iris)/i,
+    /amd radeon(?! rx| pro w)/i,
+    /radeon vega/i,
+    /microsoft basic render/i
+];
+const SOFTWARE_GPU = [/llvmpipe/i, /swrast/i, /mesa/i];
+export function classifyGpu(name) {
+    for (const re of DISCRETE_GPU)
+        if (re.test(name))
+            return 'discrete';
+    for (const re of INTEGRATED_GPU)
+        if (re.test(name))
+            return 'integrated';
+    for (const re of SOFTWARE_GPU)
+        if (re.test(name))
+            return 'software';
+    return 'integrated';
+}

package/dist-lib/lib/hardware/gpu-probe-addon.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryBudget } from './memory-budget.ts';
+export declare function probeWithAddon(rawStats: unknown, systemRamBytes: number): MemoryBudget | null;

package/dist-lib/lib/hardware/gpu-probe-addon.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { classifyGpu } from "./gpu-classify.js";
+import { IGPU_LIE_THRESHOLD, sharedRamBudget } from "./parsers.js";
+const GpuDeviceSchema = z.object({
+    name: z.string(),
+    videoMemoryBytes: z.number()
+});
+const StatsSchema = z.object({
+    memory: z.object({ totalBytes: z.number() }).optional(),
+    gpu: z.object({ devices: z.array(GpuDeviceSchema) }).optional()
+});
+function classifyBestDevice(devices, systemRamBytes) {
+    for (const device of devices) {
+        const cls = classifyGpu(device.name);
+        if (cls === 'software')
+            continue;
+        if (cls === 'discrete') {
+            const vram = device.videoMemoryBytes;
+            if (vram > systemRamBytes * IGPU_LIE_THRESHOLD) {
+                return { ...sharedRamBudget(systemRamBytes), source: 'integrated', gpuClass: 'integrated' };
+            }
+            return { totalBytes: vram, availableBytes: vram, source: 'vram', gpuClass: 'discrete' };
+        }
+    }
+    return null;
+}
+export function probeWithAddon(rawStats, systemRamBytes) {
+    const parsed = StatsSchema.safeParse(rawStats);
+    if (!parsed.success)
+        return null;
+    const devices = parsed.data.gpu?.devices ?? [];
+    if (devices.length === 0)
+        return null;
+    const totalRamBytes = parsed.data.memory?.totalBytes ?? systemRamBytes;
+    const best = classifyBestDevice(devices, totalRamBytes);
+    if (best)
+        return best;
+    if (devices.every((device) => classifyGpu(device.name) === 'software')) {
+        return { ...sharedRamBudget(totalRamBytes), source: 'software' };
+    }
+    return { ...sharedRamBudget(totalRamBytes), source: 'integrated', gpuClass: 'integrated' };
+}

package/dist-lib/lib/hardware/gpu-stats.bare.d.ts

@@ -0,0 +1 @@
+export declare function readSystemStats(): unknown;

package/dist-lib/lib/hardware/gpu-stats.bare.js

@@ -0,0 +1,24 @@
+import os from 'os';
+import GPUInfo from 'bare-gpu-info';
+export function readSystemStats() {
+    try {
+        const info = new GPUInfo();
+        try {
+            const devices = [];
+            for (const gpu of info) {
+                if (typeof gpu.memory !== 'number' || !gpu.name)
+                    continue;
+                devices.push({ name: gpu.name, videoMemoryBytes: gpu.memory });
+            }
+            if (devices.length === 0)
+                return null;
+            return { memory: { totalBytes: os.totalmem() }, gpu: { devices } };
+        }
+        finally {
+            info.destroy();
+        }
+    }
+    catch {
+        return null;
+    }
+}

package/dist-lib/lib/hardware/gpu-stats.stub.d.ts

@@ -0,0 +1 @@
+export declare function readSystemStats(): unknown;

package/dist-lib/lib/hardware/gpu-stats.stub.js

@@ -0,0 +1,3 @@
+export function readSystemStats() {
+    return null;
+}

package/dist-lib/lib/hardware/memory-budget.d.ts

@@ -0,0 +1,8 @@
+export type MemoryBudgetSource = 'vram' | 'shared' | 'mobile' | 'integrated' | 'no-gpu' | 'software';
+export type GpuClass = 'discrete' | 'integrated';
+export interface MemoryBudget {
+    readonly totalBytes: number;
+    readonly availableBytes: number;
+    readonly source: MemoryBudgetSource;
+    readonly gpuClass?: GpuClass;
+}

package/dist-lib/lib/hardware/memory-budget.js

@@ -0,0 +1 @@
+export {};