kiku-agent 1.3.1 → 1.3.2

package/server/agent/tests/vramEstimator.test.js

@@ -0,0 +1,520 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  GIB,
+  QUANT_BPW,
+  QUANT_LADDER,
+  ALLOCATION_THRESHOLDS,
+  SWA_ARCH_PROFILES,
+  knownSwaProfile,
+  parseBpw,
+  normalizeQuantName,
+  bytesToGb,
+  estimateWeightsBytes,
+  estimateKvCacheBytes,
+  computeKvBytesPerToken,
+  estimateActivationBytes,
+  estimateVramFootprint,
+  classifyAllocation,
+  recommendAdjustments,
+} from '../../../src/lib/vram/estimator.js';
+import { findRegistryEntry, MODEL_REGISTRY } from '../../../src/lib/vram/modelRegistry.js';
+import { parseGgufMetadata, parseHfConfigJson, extractQuantFromName, listInstalledGgufs } from '../modelConfig.js';
+import { computeVramEstimate, parseEstimateRequest, probeLmStudioRuntime } from '../vramService.js';
+import { computePercentile, TokenTracker } from '../tokenTracker.js';
+import { routeCommand } from '../commands.js';
+
+test('VRAM estimator: quant table matches the calibrated bits-per-weight values', () => {
+  assert.equal(QUANT_BPW.fp16, 16.0);
+  assert.equal(QUANT_BPW.q8_0, 8.0);
+  assert.equal(QUANT_BPW.q6_k, 6.56);
+  assert.equal(QUANT_BPW.q5_k_m, 5.5);
+  assert.equal(QUANT_BPW.q4_k_m, 4.5);
+  assert.equal(QUANT_BPW.q4_0, 4.2);
+  assert.equal(QUANT_BPW.q3_k_m, 3.4);
+  assert.equal(QUANT_BPW.q2_k, 2.6);
+});
+
+test('VRAM estimator: quant names normalize across separators and aliases', () => {
+  assert.equal(normalizeQuantName('Q4_K_M'), 'q4_k_m');
+  assert.equal(normalizeQuantName('q4-k-m'), 'q4_k_m');
+  assert.equal(normalizeQuantName('Q6K'), 'q6_k');
+  assert.equal(parseBpw('Q8_0'), 8.0);
+  assert.equal(parseBpw(5.5), 5.5);
+  assert.equal(parseBpw('nonsense-quant'), null);
+});
+
+test('VRAM estimator: weights use P * bpw / 8 in binary gigabytes', () => {
+  const { bytes } = estimateWeightsBytes({ paramsB: 32.5, quant: 'q4_k_m' });
+  assert.equal(bytes, Math.round(32.5e9 * 4.5 / 8));
+  assert.equal(bytesToGb(bytes).toFixed(2), (Math.round(32.5e9 * 4.5 / 8) / GIB).toFixed(2));
+  assert.equal(estimateWeightsBytes({ quant: 'q4_k_m' }).bytes, null);
+});
+
+test('VRAM estimator: KV cache formula and rapid per-token checkpoint factor', () => {
+  const geo = { layers: 32, kvHeads: 8, headDim: 128 };
+ 
+  assert.equal(computeKvBytesPerToken({ ...geo, cacheBits: 16 }), 4 * 32 * 8 * 128);
+  const ctx = 8192;
+  const { bytes } = estimateKvCacheBytes({ ...geo, contextLength: ctx, cacheBits: 16 });
+  assert.equal(bytes, 4 * 32 * 8 * 128 * ctx);
+ 
+  const q8 = estimateKvCacheBytes({ ...geo, contextLength: ctx, cacheBits: 8 });
+  assert.equal(q8.bytes, bytes / 2);
+  assert.equal(estimateKvCacheBytes({ layers: 32 }).bytes, null);
+});
+
+test('VRAM estimator: SWA hybrid KV keeps full context only on global layers', () => {
+  
+  const geo = { layers: 42, kvHeads: 2, headDim: 512, cacheBits: 16 };
+  const perLayer = 2 * 2 * 512 * 2;
+  const ctx = 16384;
+  const swa = { windowTokens: 512, patternLocal: 5, patternGlobal: 1 };
+
+  const hybrid = estimateKvCacheBytes({ ...geo, contextLength: ctx, swa });
+  assert.equal(hybrid.kvModel, 'swa-hybrid');
+  assert.equal(hybrid.swa.globalLayers, 7);
+  assert.equal(hybrid.swa.localLayers, 35);
+  assert.equal(hybrid.bytes, perLayer * (7 * ctx + 35 * 512));
+
+  const full = estimateKvCacheBytes({ ...geo, contextLength: ctx });
+  assert.equal(full.kvModel, 'full-attention');
+  assert.equal(full.swa, null);
+  assert.equal(full.bytes, perLayer * 42 * ctx);
+  assert.ok(hybrid.bytes * 4 < full.bytes, 'SWA modeling must not be a marginal correction');
+
+ 
+  const tiny = estimateKvCacheBytes({ ...geo, contextLength: 512, swa });
+  assert.equal(tiny.bytes, perLayer * 42 * 512);
+});
+
+test('VRAM estimator: SWA profiles resolve per architecture and validate inputs', () => {
+  assert.deepEqual(knownSwaProfile('gemma4'), { windowTokens: 1024, patternLocal: 5, patternGlobal: 1 });
+  assert.deepEqual(knownSwaProfile('gemma3n-something'), { windowTokens: 512, patternLocal: 5, patternGlobal: 1 });
+  assert.equal(knownSwaProfile('qwen2'), null);
+  assert.equal(knownSwaProfile(null), null);
+  assert.ok(SWA_ARCH_PROFILES.gemma3.windowTokens > 0);
+  assert.equal(estimateKvCacheBytes({
+    layers: 42, kvHeads: 2, headDim: 512, contextLength: 4096, swa: { windowTokens: 0 },
+  }).kvModel, 'full-attention', 'an invalid window falls back to the full-attention formula');
+});
+
+test('VRAM estimator: full footprint carries the SWA-aware KV model through', () => {
+  const base = {
+    paramsB: 7.52, quant: 'q4_k_m', layers: 42, queryHeads: 8, kvHeads: 2,
+    headDim: 512, hiddenSize: 2560, contextLength: 16384,
+  };
+  const worstCase = estimateVramFootprint(base);
+  assert.equal(worstCase.kvModel, 'full-attention');
+  const hybrid = estimateVramFootprint({
+    ...base,
+    swa: { windowTokens: 512, patternLocal: 5, patternGlobal: 1 },
+  });
+  assert.equal(hybrid.kvModel, 'swa-hybrid');
+  assert.equal(hybrid.swa.globalLayers, 7);
+  assert.equal(hybrid.kvCacheBytes, 2 * 2 * 512 * 2 * (7 * 16384 + 35 * 512));
+  assert.ok(hybrid.totalBytes < worstCase.totalBytes);
+  assert.equal(hybrid.warnings.length, 0);
+});
+
+test('VRAM estimator: activation reserves the static workspace and exposes the analytic value', () => {
+  const { analyticBytes, reservedBytes } = estimateActivationBytes({
+    hiddenSize: 4096, queryHeads: 32, kvHeads: 8,
+  });
+  assert.equal(reservedBytes, Math.round(0.25 * GIB));
+  assert.equal(analyticBytes, Math.round(4096 * (34 + 5 * 4) * 2));
+  assert.equal(estimateActivationBytes({}).reservedBytes, Math.round(0.25 * GIB));
+});
+
+test('VRAM estimator: full footprint sums weights + KV + activation + overhead', () => {
+  const estimate = estimateVramFootprint({
+    modelId: 'test-model',
+    paramsB: 8,
+    quant: 'q4_k_m',
+    layers: 32,
+    queryHeads: 32,
+    kvHeads: 8,
+    headDim: 128,
+    hiddenSize: 4096,
+    contextLength: 8192,
+  });
+  const expectedWeights = Math.round(8e9 * 4.5 / 8);
+  const expectedKv = 4 * 32 * 8 * 128 * 8192;
+  assert.equal(estimate.weightsBytes, expectedWeights);
+  assert.equal(estimate.kvCacheBytes, expectedKv);
+  assert.equal(estimate.activationBytes, Math.round(0.25 * GIB));
+  assert.equal(estimate.overheadBytes, Math.round(0.7 * GIB));
+  assert.equal(estimate.totalBytes, expectedWeights + expectedKv + Math.round(0.25 * GIB) + Math.round(0.7 * GIB));
+  assert.deepEqual(estimate.warnings, []);
+});
+
+test('VRAM estimator: VLM correction extends the context with image tokens', () => {
+  const base = {
+    paramsB: 7.25, quant: 'q4_k_m', layers: 32, queryHeads: 32, kvHeads: 8,
+    headDim: 128, hiddenSize: 4096, contextLength: 4096,
+  };
+  const plain = estimateVramFootprint(base);
+  const withVision = estimateVramFootprint({
+    ...base,
+    vision: { images: 4, tokensPerImage: 576, encoderParamsB: 0.42 },
+  });
+  assert.equal(withVision.effectiveContextLength, 4096 + 4 * 576);
+  assert.ok(withVision.kvCacheBytes > plain.kvCacheBytes);
+  assert.ok(withVision.visionEncoderBytes > 0);
+  assert.ok(withVision.totalBytes > plain.totalBytes);
+});
+
+test('VRAM estimator: allocation zones partition at 85% and 100%', () => {
+  const available = 24 * GIB;
+  const green = classifyAllocation({ totalBytes: 0.85 * available, availableBytes: available });
+  const yellow = classifyAllocation({ totalBytes: 0.90 * available, availableBytes: available });
+  const tight = classifyAllocation({ totalBytes: available, availableBytes: available });
+  const over = classifyAllocation({ totalBytes: 25.4 * GIB, availableBytes: available });
+  assert.equal(green.zone, 'GREEN');
+  assert.equal(yellow.zone, 'YELLOW');
+  assert.equal(tight.zone, 'YELLOW', 'an allocation that exactly fills the card still fits');
+  assert.equal(over.zone, 'RED');
+  assert.match(over.message, /Out of memory/);
+  assert.ok(over.headroomBytes < 0);
+  assert.ok(over.requiresForce);
+  assert.ok(!green.requiresForce);
+  assert.equal(classifyAllocation({ totalBytes: 20, availableBytes: null }).zone, 'UNKNOWN');
+});
+
+test('VRAM estimator: remediation suggests context, KV-quant or weight changes into GREEN', () => {
+  const available = 16 * GIB;
+  const estimate = estimateVramFootprint({
+    paramsB: 14.77, quant: 'q4_k_m', layers: 48, queryHeads: 40, kvHeads: 8,
+    headDim: 128, hiddenSize: 5120, contextLength: 32768,
+  });
+  assert.equal(classifyAllocation({ totalBytes: estimate.totalBytes, availableBytes: available }).zone, 'YELLOW');
+  const suggestions = recommendAdjustments(estimate, available);
+  assert.ok(suggestions.length >= 1);
+  for (const suggestion of suggestions) {
+    assert.ok(['context', 'kv-quant', 'quantization'].includes(suggestion.kind));
+    assert.ok(suggestion.projectedBytes <= available * ALLOCATION_THRESHOLDS.green);
+  }
+  assert.ok(suggestions.some(s => s.kind === 'context'), 'exact max-context suggestion expected');
+  assert.ok(suggestions.some(s => s.kind === 'kv-quant'), 'Q8_0 KV cache suggestion expected');
+});
+
+test('VRAM estimator: registry resolves known model families', () => {
+  const gemma = findRegistryEntry('google/gemma-4-e4b');
+  assert.ok(gemma);
+  assert.equal(gemma.paramsB, 8.0);
+  const qwen = findRegistryEntry('Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf');
+  assert.ok(qwen);
+  assert.equal(qwen.layers, 64);
+  assert.equal(findRegistryEntry('totally-unknown-model-xyz'), null);
+  assert.ok(MODEL_REGISTRY.length >= 10);
+});
+
+test('VRAM estimator: registry covers LM Studio tool-calling, vision and reasoning models', () => {
+  for (const entry of MODEL_REGISTRY) {
+    assert.ok(Array.isArray(entry.capabilities) && entry.capabilities.length >= 1, `capabilities missing on ${entry.label}`);
+    assert.ok(entry.capabilities.every(c => ['tools', 'vision', 'reasoning'].includes(c)), `bad capability on ${entry.label}`);
+    assert.ok(entry.paramsB > 0 && entry.layers > 0 && entry.kvHeads > 0 && entry.headDim > 0, `geometry missing on ${entry.label}`);
+    assert.ok(typeof entry.verified === 'string' && entry.verified.length > 0, `verification tag missing on ${entry.label}`);
+  }
+
+  const qwen3 = findRegistryEntry('Qwen/Qwen3-8B');
+  assert.deepEqual([...qwen3.capabilities].sort(), ['reasoning', 'tools']);
+  assert.equal(findRegistryEntry('openai/gpt-oss-20b').isMoE, true);
+  assert.ok(MODEL_REGISTRY.filter(e => e.capabilities.includes('vision')).length >= 6);
+  assert.ok(MODEL_REGISTRY.filter(e => e.capabilities.includes('reasoning')).length >= 5);
+  assert.ok(MODEL_REGISTRY.filter(e => e.capabilities.includes('tools')).length >= 8);
+});
+
+test('VRAM service: GPT-OSS falls back to its native MXFP4 quantization', async () => {
+  const result = await computeVramEstimate({
+    model: 'gpt-oss-20b',
+    includeHardware: false,
+    hardwareOverrideGb: 24,
+  });
+  assert.equal(result.configSource, 'registry');
+  assert.equal(result.input.quant, 'mxfp4');
+  assert.equal(result.estimate.quantBpw, 4.25);
+  assert.equal(result.estimate.layers, 24);
+  assert.equal(result.estimate.paramCount, Math.round(20.91e9));
+  assert.equal(result.classification.zone, 'GREEN');
+});
+
+test('GGUF parser: reads header metadata and sums tensor parameter counts', () => {
+ 
+  const parts = [];
+  const w = (fn) => { const buf = Buffer.alloc(8); fn(buf); parts.push(buf); };
+  const str = (s) => {
+    const bytes = Buffer.from(s, 'utf8');
+    const len = Buffer.alloc(8);
+    len.writeBigUInt64LE(BigInt(bytes.length));
+    parts.push(len, bytes);
+  };
+
+  parts.push(Buffer.from([0x47, 0x47, 0x55, 0x46]));
+  const version = Buffer.alloc(4); version.writeUInt32LE(3); parts.push(version);
+  const tensorCount = Buffer.alloc(8); tensorCount.writeBigUInt64LE(2n); parts.push(tensorCount);
+  const kvCount = Buffer.alloc(8); kvCount.writeBigUInt64LE(8n); parts.push(kvCount);
+
+  str('general.architecture');
+  const strType = Buffer.alloc(4); strType.writeUInt32LE(8); parts.push(strType);
+  str('qwen25');
+  const kv = (key, type, value) => {
+    str(key);
+    const t = Buffer.alloc(4); t.writeUInt32LE(type); parts.push(t);
+    if (type === 8) str(value); else { const v = Buffer.alloc(4); v.writeUInt32LE(value); parts.push(v); }
+  };
+  kv('qwen25.block_count', 4, 28);           
+  kv('qwen25.attention.head_count', 4, 28);
+  kv('qwen25.attention.head_count_kv', 4, 4);
+  kv('qwen25.attention.key_length', 4, 128);
+  kv('qwen25.embedding_length', 4, 3584);
+  kv('qwen25.context_length', 4, 32768);
+  kv('qwen25.attention.swa_size', 4, 1024);
+
+  const tensor = (name, dims) => {
+    str(name);
+    const nDims = Buffer.alloc(4); nDims.writeUInt32LE(dims.length); parts.push(nDims);
+    for (const d of dims) {
+      const dim = Buffer.alloc(8); dim.writeBigUInt64LE(BigInt(d)); parts.push(dim);
+    }
+    const type = Buffer.alloc(4); type.writeUInt32LE(0); parts.push(type);
+    const offset = Buffer.alloc(8); offset.writeBigUInt64LE(0n); parts.push(offset);
+  };
+  tensor('token_embd.weight', [3584, 152064]);
+  tensor('blk.0.attn_q.weight', [3584, 3584]);
+
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kiku-gguf-'));
+  const file = path.join(dir, 'test-model-Q4_K_M.gguf');
+  fs.writeFileSync(file, Buffer.concat(parts));
+
+  const meta = parseGgufMetadata(file);
+  assert.ok(meta && !meta.error, meta && meta.error ? meta.error : 'metadata missing');
+  assert.equal(meta.arch, 'qwen25');
+  assert.equal(meta.layers, 28);
+  assert.equal(meta.queryHeads, 28);
+  assert.equal(meta.kvHeads, 4);
+  assert.equal(meta.headDim, 128);
+  assert.equal(meta.hiddenSize, 3584);
+  assert.equal(meta.contextLength, 32768);
+  assert.deepEqual(meta.swa, { windowTokens: 1024 });
+  assert.equal(meta.quant, 'q4_k_m');
+  assert.equal(meta.paramCount, 3584 * 152064 + 3584 * 3584);
+
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('GGUF parser: rejects non-GGUF payloads and extracts quants from names', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kiku-gguf-'));
+  const file = path.join(dir, 'not-a-model.gguf');
+  fs.writeFileSync(file, Buffer.from('definitely not gguf'));
+  assert.equal(parseGgufMetadata(file), null);
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  assert.equal(extractQuantFromName('model-Q4_K_M.gguf'), 'q4_k_m');
+  assert.equal(extractQuantFromName('gemma-4-e4b-Q8_0'), 'q8_0');
+  assert.equal(extractQuantFromName('no-quant-here'), null);
+});
+
+test('HF config parser: normalizes architecture fields and VLM vision configs', () => {
+  const config = parseHfConfigJson({
+    model_type: 'qwen2',
+    num_hidden_layers: 28,
+    num_attention_heads: 28,
+    num_key_value_heads: 4,
+    hidden_size: 3584,
+    max_position_embeddings: 32768,
+    sliding_window: 1024,
+  }, 'Qwen/Qwen2.5-7B-Instruct');
+  assert.equal(config.layers, 28);
+  assert.equal(config.kvHeads, 4);
+  assert.equal(config.headDim, 128);
+  assert.equal(config.contextLength, 32768);
+  assert.deepEqual(config.swa, { windowTokens: 1024 });
+  assert.equal(config.vision, null);
+
+  const vlm = parseHfConfigJson({
+    model_type: 'llava',
+    num_hidden_layers: 32,
+    num_attention_heads: 32,
+    hidden_size: 4096,
+    vision_config: { hidden_size: 1024, num_hidden_layers: 24, patch_size: 14, image_size: 336 },
+  });
+  assert.ok(vlm.vision);
+  assert.equal(vlm.vision.tokensPerImage, 577);
+  assert.ok(vlm.vision.encoderParamsB > 0.1 && vlm.vision.encoderParamsB < 2);
+});
+
+test('VRAM service: estimate request resolves the built-in registry and classifies with override hardware', async () => {
+  const result = await computeVramEstimate({
+    model: 'Qwen2.5-Coder-32B-Instruct',
+    quant: 'q4_k_m',
+    contextLength: 16384,
+    includeHardware: false,
+    hardwareOverrideGb: 24,
+  });
+  assert.equal(result.configSource, 'registry');
+  assert.equal(result.architecture.layers, 64);
+  assert.equal(result.estimate.contextLength, 16384);
+  assert.equal(result.classification.zone, 'YELLOW');
+  assert.ok(result.estimate.totalBytes > 0);
+ 
+  assert.ok(result.classification.usagePct > 80 && result.classification.usagePct < 95);
+
+  const huge = await computeVramEstimate({
+    model: 'Qwen2.5-Coder-32B-Instruct',
+    quant: 'fp16',
+    contextLength: 32768,
+    includeHardware: false,
+    hardwareOverrideGb: 24,
+  });
+  assert.equal(huge.classification.zone, 'RED');
+  assert.ok(huge.remediation.length >= 1);
+});
+
+test('VRAM service: parseEstimateRequest merges body and query params', () => {
+  const searchParams = new URLSearchParams('ctx=8192&quant=q6_k');
+  const request = parseEstimateRequest({ model: 'llama-3.1-8b' }, searchParams);
+  assert.equal(request.model, 'llama-3.1-8b');
+  assert.equal(request.contextLength, 8192);
+  assert.equal(request.quant, 'q6_k');
+  assert.equal(parseEstimateRequest({ model: 'x', includeHardware: false }).includeHardware, false);
+  assert.equal(parseEstimateRequest({}).includeHardware, true);
+});
+
+test('TokenTracker: computes TTFT, decode throughput, ITL percentiles and context usage', async () => {
+  const tracker = new TokenTracker({ sessionId: 'sess_test', modelId: 'test-model', contextLimit: 32768 });
+  tracker.start();
+  const segment = tracker.beginSegment('iteration-1');
+  tracker.markFirstToken(segment); 
+ 
+  for (let i = 0; i < 10; i++) {
+    segment.tokenTimestamps.push(segment.tFirst + 20 * (i + 1));
+  }
+  tracker.endSegment({ promptTokens: 1420, completionTokens: 384 }, segment);
+  segment.tEnd = segment.tFirst + 200; 
+  await new Promise(r => setTimeout(r, 5));
+  const payload = tracker.finish({ promptTokens: 1420, completionTokens: 384 });
+
+  assert.equal(payload.session_id, 'sess_test');
+  assert.equal(payload.model_id, 'test-model');
+  assert.equal(payload.counts.prompt_tokens, 1420);
+  assert.equal(payload.counts.completion_tokens, 384);
+  assert.equal(payload.counts.total_tokens, 1804);
+  assert.equal(payload.counts.remaining_tokens, 32768 - 1804);
+  assert.ok(payload.timing_ms.ttft >= 0);
+  assert.equal(payload.timing_ms.decode_duration, 200); 
+  assert.ok(Math.abs(payload.rates.decode_tps - 383 / 0.2) < 0.1); 
+  assert.equal(payload.rates.itl_mean_ms, 20);
+  assert.ok(payload.rates.itl_p95_ms <= 20);
+  assert.ok(payload.context_usage_pct > 5 && payload.context_usage_pct < 6);
+  assert.ok(payload.rates.e2e_tps > 0);
+});
+
+test('TokenTracker: aggregates multiple streaming segments and computes p95', () => {
+  const tracker = new TokenTracker({ modelId: 'm', contextLimit: 0 });
+  tracker.start();
+  const seg1 = tracker.beginSegment('a');
+  seg1.tFirst = seg1.tStart + 100;
+  for (let i = 0; i < 4; i++) seg1.tokenTimestamps.push(seg1.tFirst + 10 * (i + 1));
+  tracker.endSegment({ promptTokens: 100, completionTokens: 50 }, seg1);
+  seg1.tEnd = seg1.tFirst + 40;
+
+  const seg2 = tracker.beginSegment('b');
+  seg2.tFirst = seg2.tStart + 200;
+  for (let i = 0; i < 6; i++) seg2.tokenTimestamps.push(seg2.tFirst + 30 * (i + 1));
+  tracker.endSegment({ promptTokens: 200, completionTokens: 70 }, seg2);
+  seg2.tEnd = seg2.tFirst + 180;
+
+  const payload = tracker.finish({ promptTokens: 300, completionTokens: 120 });
+  assert.equal(payload.stream_segments, 2);
+  assert.equal(payload.counts.prompt_tokens, 300);
+  assert.equal(payload.counts.completion_tokens, 120);
+  assert.equal(payload.timing_ms.decode_duration, 40 + 180);
+  assert.equal(payload.counts.context_limit, null);
+  assert.equal(payload.context_usage_pct, null);
+
+  assert.equal(computePercentile([...Array(10).keys()], 0.95), 9);
+});
+
+test('TokenTracker: reported usage falls back to counted stream deltas', () => {
+  const tracker = new TokenTracker({ modelId: 'm' });
+  tracker.start();
+  const segment = tracker.beginSegment();
+  tracker.markToken(segment);
+  tracker.markToken(segment);
+  tracker.markToken(segment);
+  tracker.endSegment({}, segment);
+  const payload = tracker.finish();
+  assert.equal(payload.counts.completion_tokens, 3);
+  assert.ok(payload.timing_ms.ttft >= 0);
+});
+
+test('VRAM estimator: quant ladder is exported in descending bpw order', () => {
+  assert.ok(QUANT_LADDER.length >= 9);
+  for (let i = 1; i < QUANT_LADDER.length; i++) {
+    assert.ok(parseBpw(QUANT_LADDER[i - 1]) >= parseBpw(QUANT_LADDER[i]));
+  }
+});
+
+test('VRAM service: probeLmStudioRuntime degrades gracefully when offline', async () => {
+  const result = await probeLmStudioRuntime('http://127.0.0.1:9');
+  assert.equal(result.reachable, false);
+  assert.equal(result.loadedModel, null);
+  assert.equal(result.loadedContextLength, null);
+});
+
+test('/vram: live, compare, ctx, list, check and default subcommands render correctly', async () => {
+  const agent = { client: { model: 'qwen2.5-7b-instruct', provider: 'lmstudio', baseUrl: 'http://127.0.0.1:9' } };
+  assert.equal(await routeCommand('/vram', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram list', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram live', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram compare --ctx 16384', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram ctx', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram ctx --quant q4_k_m', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram check google/gemma-4-e4b', { agent }), 'HANDLED');
+  assert.equal(await routeCommand('/vram compare', {}), 'HANDLED', 'falls back to registry defaults without an agent');
+  assert.equal(await routeCommand('/resource', { agent }), 'HANDLED');
+});
+
+test('VRAM estimator: missing weights yields null totalBytes and UNKNOWN classification', () => {
+  const estimate = estimateVramFootprint({ modelId: 'cloud-model-gemini', contextLength: 8192 });
+  assert.equal(estimate.weightsBytes, null);
+  assert.equal(estimate.totalBytes, null);
+  assert.equal(estimate.gb.total, null);
+  assert.equal(estimate.gb.weights, null);
+  assert.ok(estimate.warnings.some(w => w.includes('Parameter count unknown')));
+
+  const classification = classifyAllocation({ totalBytes: estimate.totalBytes, availableBytes: 6 * GIB });
+  assert.equal(classification.zone, 'UNKNOWN');
+  assert.equal(classification.usagePct, null);
+  assert.equal(classification.requiresForce, false);
+});
+
+test('VRAM service: auto model resolves to local GGUF or registry entry with realistic footprint', async () => {
+  const result = await computeVramEstimate({ model: 'auto', contextLength: 4096 });
+  assert.equal(result.ok, true);
+  assert.ok(result.estimate.weightsBytes > 0, 'weights should not be null for auto');
+  assert.ok(result.estimate.totalBytes > 0, 'totalBytes should not be null for auto');
+  assert.ok(['GREEN', 'YELLOW', 'RED'].includes(result.classification.zone));
+});
+
+test('VRAM service: unknown cloud model produces UNKNOWN classification without fake numbers', async () => {
+  const result = await computeVramEstimate({ model: 'gemini-3.7-flash', allowNetwork: false });
+  assert.equal(result.estimate.weightsBytes, null);
+  assert.equal(result.estimate.totalBytes, null);
+  assert.equal(result.classification.zone, 'UNKNOWN');
+  assert.equal(result.classification.usagePct, null);
+  assert.equal(result.classification.requiresForce, false);
+});
+
+test('GGUF discovery: listInstalledGgufs returns array of models with valid metadata', () => {
+  const models = listInstalledGgufs();
+  assert.ok(Array.isArray(models));
+  for (const m of models) {
+    assert.ok(m.path && m.fileName);
+    assert.ok(typeof m.sizeGb === 'number' && m.sizeGb > 0);
+  }
+});