Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
14a943616This file is pinned to the selected release. Download the original to open it in your design tool.
import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest'
import { mkdtemp, mkdir, writeFile, readFile, readdir, rm, stat } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import { createHash } from 'node:crypto'
import { rmSync, writeFileSync } from 'node:fs'
import { spawnSync } from 'node:child_process'
import { compatibleModels, contextLadder, LocalModels, readRunRecords, type GridInventory } from './localModels.js'
import { GridFleetRpc, type GridFleetResult } from './gridFleetRpc.js'
import { encryptDownFrame, encryptRpcResult } from './e2ee/applicationFrames.js'
const card = (id = 'org/Small-GGUF') => ({ repo_id: id, runnable: true, task: 'text-generation', format: 'GGUF',
fit: { version: 'Q4', ctx: 131072, size: 64 },
versions: [{ version: 'Q4', size_bytes: 64, pull_spec: `${id}:Small-Q4.gguf`, urls: ['https://example.test/Small-Q4.gguf'] }] })
const ok = (value: unknown = {}) => ({ ok: true, code: 0, stdout: JSON.stringify(value), stderr: '', error: null })
const response = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } })
let root: string, home: string, stateDir: string, records: string
let calls: string[][], serving: boolean, catalogCards: ReturnType<typeof card>[], service: LocalModels
let request: Mock<(url: string | URL, init?: RequestInit) => Promise<Response>>
let run: Mock<(args: string[], output?: (s: string) => void) => Promise<GridFleetResult>>
let downloadFails: boolean, catalogFails: boolean
/** What `grid info` says of the grid. Down (`stopped`/`asleep`) refuses `engines` and `join`, as
* the real grid does, until `grid start` brings it back. */
let gridState: 'running' | 'stopped' | 'asleep'
/** What `grid ctx FILE` reads from a file's header (null: the command fails), and the window the
* serving engine reports once started (undefined: Grid does not say). */
let trainedWindow: number | null, servedWindow: number | undefined
/** The relay's own test request — as opposed to the probe sent straight to the engine on this
* machine (`127.0.0.1`), which a start now makes first. */
const RELAY_CHAT = 'inference.example.test/v1/chat/completions'
const refused = (message: string) => ({ ok: false, code: 1, stdout: '', stderr: message, error: 'Grid command failed.' })
/** The grid's own answer when a test pins it (null: derived from [gridState], as production derives it). */
let answered: GridInventory['state'] | null
/** What `gridModels.gridInventory` would hand the Model Manager — read without a credential. */
let inventory: Mock<(grid: string, force: boolean) => Promise<GridInventory>>
beforeEach(async () => {
root = await mkdtemp(join(tmpdir(), 'local-models-'))
home = join(root, 'grid'); stateDir = join(root, 'receipts'); records = join(home, 'run', 'engines', 'grid-home')
await mkdir(records, { recursive: true }); await mkdir(join(home, 'models'))
await writeFile(join(home, 'credentials.toml'), 'session_token = "test-only-token"\napi_url = "https://catalog.example.test"\n')
calls = []; serving = false; catalogCards = [card()]; downloadFails = false; catalogFails = false; gridState = 'running'
trainedWindow = null; servedWindow = undefined
run = vi.fn(async (args: string[], output?: (s: string) => void) => {
calls.push(args)
if (args[0] === 'device-info') return ok({ device_class: 'apple-silicon', backend: 'metal', usable_bytes: 54 * 1024 ** 3, memory: { total_gb: 64 } })
if (args.includes('ls')) return ok([{ grid: 'home', id: 'grid-home' }])
if (args.includes('info') && args.includes('--json')) return ok({ grid: 'home', status: gridState })
if (args[1] === 'start') { gridState = 'running'; return ok() }
const down = gridState !== 'running'
if (down && (args.includes('engines') || args.includes('join'))) return refused("Grid home isn't up; run `grid start home` first.")
if (args[0] === 'ctx') return trainedWindow === null ? refused('no header') : ok({ file: args[1], context_length: trainedWindow })
if (args.includes('engines')) return ok(serving ? [{ node_id: 'local-node', online: true, models: ['Small-Q4.gguf'], throughput_tok_s: 17.6,
...(servedWindow === undefined ? {} : { model_capabilities: { 'small-q4': { context_length: servedWindow, vision: false } } }),
vram_used_mb: 99999, answered: { window_seconds: 3600, requests: 4, by_model: [{ model: 'Small-Q4.gguf', requests: 4 }] } }] : [])
if (args[0] === 'pull') {
output?.('42%')
if (downloadFails) return { ...ok(), ok: false, code: 1 }
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
}
if (args[0] === 'engine' && args[1] === 'install') {
await mkdir(join(home, 'bin'), { recursive: true })
await writeFile(join(home, 'bin', 'llama-server'), '#!/bin/sh\nexit 0\n', { mode: 0o755 })
}
if (args.includes('join')) {
serving = true
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: [] }))
await writeFile(join(records, 'remote.heartbeat'), '')
}
if (args.includes('leave')) { serving = false; await rm(join(records, 'remote.json'), { force: true }) }
if (args.includes('info')) return { ...ok(), stdout: "export OPENAI_BASE_URL='https://inference.example.test/v1'\nexport OPENAI_API_KEY='test-inference-token'\n" }
return ok()
})
request = vi.fn(async (url: string | URL, _init?: RequestInit) => {
if (String(url).includes('/catalog')) {
if (catalogFails) throw new Error('private raw error must never escape')
return response({ models: catalogCards, runnable_total: catalogCards.length, pagination: { page: 1, total_pages: 1 } })
}
return response({ choices: [{ message: { content: 'ok' } }] })
})
// The inventory as production reads it (`gridModels.gridInventory`), over this fake's grid: the owner
// status is `gridState`; a sleeping grid answers asleep, a stopped one answers nothing readable (the
// proxy's grid_stopped), and a running one lists what the fake's `engines` lists.
answered = null
inventory = vi.fn(async (grid: string): Promise<GridInventory> => {
const status = gridState
if (answered) return { state: answered, nodes: [], status }
if (status === 'asleep') return { state: 'asleep', nodes: [], status }
if (status !== 'running') return { state: 'unknown', nodes: [], status }
const answer = await run(['--remote', 'engines', grid, '--json'])
if (!answer.ok) return { state: 'unknown', nodes: [], status }
try { return { state: 'awake', nodes: JSON.parse(answer.stdout), status } } catch { return { state: 'unknown', nodes: [], status } }
})
service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory })
})
afterEach(async () => { await service.settled(); vi.useRealTimers(); vi.restoreAllMocks(); vi.unstubAllEnvs(); vi.unstubAllGlobals(); await rm(root, { recursive: true, force: true }) })
describe('local model discovery and lifecycle', () => {
it('inspects silently and offers only confirmed compatible chat models', async () => {
expect(compatibleModels([card()])).toEqual([])
expect(compatibleModels({ models: [card(), { ...card('no'), runnable: false }, { ...card('image'), task: 'image-generation' }] })).toHaveLength(1)
const snapshot = await service.list('home')
expect(snapshot.models).toMatchObject([{ name: 'Small', state: 'available', sizeBytes: 64, canStart: true, canStop: false }])
expect(snapshot.memoryBytes).toBe(64 * 1024 ** 3)
expect(calls.some(args => ['pull', 'join', 'leave', 'install'].some(a => args.includes(a)))).toBe(false)
expect(JSON.stringify(snapshot)).not.toContain('test-only-token')
})
it('paginates all compatible models and does not fetch incompatible trailing pages', async () => {
request.mockImplementation(async (_url, init) => {
const page = JSON.parse(String(init?.body)).page
return response({ models: [card(`org/Model${page}-GGUF`)], runnable_total: 2, pagination: { page, total_pages: 7 } })
})
expect((await service.list('home')).models).toHaveLength(2)
expect(request).toHaveBeenCalledTimes(2)
})
it('rejects catalog pagination that repeats a page', async () => {
request.mockResolvedValue(response({ models: [card()], runnable_total: 100, pagination: { page: 1, total_pages: 7 } }))
// Fresh Response objects (bodies are single-consumption).
request.mockImplementation(async () => response({ models: [card()], runnable_total: 100, pagination: { page: 1, total_pages: 7 } }))
expect((await service.list('home')).notice).toContain('incomplete')
})
it('downloads, loads and verifies without another user step', async () => {
const ack = await service.act('home', 'org/Small-GGUF', 'start')
expect(ack.operation?.phase).toBe('running')
await service.settled()
const snapshot = await service.list('home')
expect(snapshot.models[0]).toMatchObject({ state: 'running', canStop: true,
tokensPerSecond: 17.6, requests: 4, windowSeconds: 3600, operation: { phase: 'done', stage: 'verifying' } })
expect(snapshot.models[0]).not.toHaveProperty('memoryBytes')
expect(calls.find(args => args.includes('join'))).toEqual(['--remote', 'join', 'home', '--serve', 'Small-Q4.gguf', '--max-concurrency', '1', '--ctx-size', '131072', '--endpoint-port', expect.stringMatching(/^\d+$/), '--reasoning-budget', '0'])
expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(true)
expect(await readFile(join(stateDir, (await readdir(stateDir))[0]), 'utf8')).not.toContain('token')
})
// grid-reads-without-waking issue 03: the reply test is an inference THROUGH the grid, so on a sleeping
// grid it starts it — and the platform then keeps it up for hours. A stray Start on a model that is
// already serving has nothing to check.
it('Start on a model already serving at the last read skips the reply test', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home', true)).models[0].state).toBe('running')
request.mockClear(); calls.length = 0
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
// Nothing that reads through the grid with its credential: no reply test, no `info --env` for its
// key, no signed-in `engines` for the served window — and nothing started.
expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(false)
expect(calls.filter(args => args.includes('--env') || args.includes('engines') || args.includes('join'))).toEqual([])
expect((await service.list('home')).models[0]).toMatchObject({ state: 'running', operation: { phase: 'done' } })
})
it('Start on a model this computer holds but that was not serving at the last read runs the reply test, as before', async () => {
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: [] }))
expect((await service.list('home', true)).models[0].state).not.toBe('running')
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(true)
expect(calls.some(args => args.includes('join'))).toBe(false)
})
it('uses an already downloaded complete file, and Stop retains it', async () => {
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
expect((await service.list('home')).models[0].state).toBe('downloaded')
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.some(args => args[0] === 'pull')).toBe(false)
await service.act('home', 'org/Small-GGUF', 'stop'); await service.settled()
expect(calls.find(args => args.includes('leave'))).toEqual(['--remote', 'leave', 'home', '--engine', 'Small-Q4.gguf'])
expect((await stat(join(home, 'models', 'Small-Q4.gguf'))).size).toBe(64)
expect((await service.list('home')).models[0]).toMatchObject({ state: 'downloaded', canStop: false, canStart: true })
})
it('reuses the installed engine on subsequent starts', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
await service.act('home', 'org/Small-GGUF', 'stop'); await service.settled()
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.filter(args => args[0] === 'engine' && args[1] === 'install')).toHaveLength(1)
expect(calls.filter(args => args[0] === 'pull')).toHaveLength(1)
})
it('does not count partial files as downloaded', async () => {
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(12))
await writeFile(join(home, 'models', 'Small-Q4.gguf.part'), Buffer.alloc(64))
expect((await service.list('home')).models[0].state).toBe('available')
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.some(args => args[0] === 'pull')).toBe(true)
})
it('joins repeated clicks, serializes other models, and keeps status independent of its caller', async () => {
let release!: () => void
const barrier = new Promise<void>(resolve => { release = resolve })
const original = request.getMockImplementation()!
request.mockImplementation(async (url, init) => { if (String(url).includes(RELAY_CHAT)) await barrier; return original(url, init) })
const first = await service.act('home', 'org/Small-GGUF', 'start')
const second = await service.act('home', 'org/Small-GGUF', 'start')
expect(second.operation?.id).toBe(first.operation?.id)
expect((await service.act('home', 'other', 'start')).error).toContain('Wait')
await vi.waitFor(() => expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(true))
expect((await service.list('home')).models[0].operation).toMatchObject({ stage: 'verifying', phase: 'running' })
release(); await service.settled()
expect(calls.filter(args => args.includes('join'))).toHaveLength(1)
})
it('reports a failed download and retries it without starting an incomplete model', async () => {
downloadFails = true
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', error: 'The download stopped. Start again to resume.' })
expect(calls.some(args => args.includes('join'))).toBe(false)
downloadFails = false
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.phase).toBe('done')
})
it('keeps a failed Grid registration refresh retryable without starting or downloading', async () => {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('sync') ? { ...ok(), ok: false } : original(args, output))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', stage: 'checking' })
expect(calls.some(args => args.includes('join') || args.includes('pull'))).toBe(false)
run.mockImplementation(original)
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].state).toBe('running')
})
it('never offers Stop for an external endpoint or another machine', async () => {
serving = true
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ endpoint_url: 'http://localhost:1234', models: ['Small-Q4.gguf'] }] }))
await writeFile(join(records, 'remote.heartbeat'), '')
const snapshot = await service.list('home')
expect(snapshot.models[0].canStop).toBe(false)
await service.act('home', 'org/Small-GGUF', 'stop'); await service.settled()
expect(calls.some(args => args.includes('leave'))).toBe(false)
})
it('keeps existing local engines visible when the catalog cannot be reached', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
catalogFails = true
const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch , inventory })
const snapshot = await fresh.list('home')
expect(snapshot.models[0]).toMatchObject({ state: 'running', canStop: true })
expect(snapshot.notice).toContain('unavailable')
expect(JSON.stringify(snapshot)).not.toContain('private raw')
})
it('does not silently evict an existing model to fit the next one', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const next = card('org/Next-GGUF'); next.versions[0].pull_spec = 'org/Next-GGUF:Next.gguf'; next.versions[0].urls = ['https://example.test/Next.gguf']
catalogCards = [card(), next]
await service.list('home', true)
request.mockImplementation(async (_url, init) => response({ models: JSON.parse(String(init?.body)).device.usable_bytes < 54 * 1024 ** 3 ? [] : catalogCards, pagination: { total_pages: 1 } }))
await service.act('home', 'org/Next-GGUF', 'start'); await service.settled()
const snapshot = await service.list('home')
expect(snapshot.models.find(m => m.id === 'org/Next-GGUF')?.operation?.error).toContain('Stop Small-Q4 first')
expect(calls.some(args => args.includes('leave'))).toBe(false)
})
it('rejects arbitrary model ids without passing them to Grid', async () => {
await service.act('home', '--serve /arbitrary', 'start'); await service.settled()
expect(calls.some(args => args.includes('--serve /arbitrary'))).toBe(false)
expect(calls.some(args => args[0] === 'pull')).toBe(false)
})
it('imports an existing local setup, keeps it after Stop, and can start it again', async () => {
catalogCards = []
serving = true
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', meta_name: 'This computer', ctx_size: 8192,
engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: ['Small-Q4.gguf'] }))
await writeFile(join(records, 'remote.heartbeat'), '')
const first = await service.list('home')
expect(first.models[0]).toMatchObject({ id: 'local:Small-Q4.gguf', state: 'running', canStop: true })
await service.act('home', first.models[0].id, 'stop'); await service.settled()
const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch , inventory })
expect((await fresh.list('home')).models[0]).toMatchObject({ state: 'downloaded', canStart: true })
await fresh.act('home', first.models[0].id, 'start'); await fresh.settled()
expect(calls.some(args => args[0] === 'pull')).toBe(false)
expect((await fresh.list('home')).models[0].operation?.phase).toBe('done')
})
it.each(['current', 'legacy', 'malformed'])('preserves imported routing names across restart with %s receipts', async scenario => {
catalogCards = []; serving = true
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node',
engines: [{ models: ['Small-Q4.gguf'] }], advertise_as: ['team/my-model'] }))
await writeFile(join(records, 'remote.heartbeat'), '')
const id = (await service.list('home')).models[0].id
await service.act('home', id, 'stop'); await service.settled()
const path = join(stateDir, (await readdir(stateDir)).find(name => name.endsWith('.known.json'))!)
const saved = JSON.parse(await readFile(path, 'utf8'))
expect(saved[0].aliases).toEqual(['team/my-model'])
// What receipts from before the 64K floor carried: a pinned 16K that must not be replayed.
saved[0].context = 16384
if (scenario === 'legacy') delete saved[0].aliases
if (scenario === 'malformed') saved[0].aliases = [42, '', '--invalid', 'invalid\nname']
await writeFile(path, JSON.stringify(saved))
const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch , inventory })
await fresh.act('home', id, 'start'); await fresh.settled()
const expectedAlias = scenario === 'current' ? 'team/my-model' : scenario === 'legacy' ? 'my-model' : null
const joined = calls.find(args => args.includes('join'))!
expect(joined.slice(joined.indexOf('--reasoning-budget') + 2)).toEqual(expectedAlias ? ['--advertise-as', expectedAlias] : [])
// Not sized by any catalog and its header unread here, so the start begins at 128K — and a
// receipt's saved context, which older ones pinned at 16K, is never replayed.
expect(joined[joined.indexOf('--ctx-size') + 1]).toBe('131072')
const inference = request.mock.calls.find(([url]) => String(url).includes(RELAY_CHAT))!
expect(JSON.parse(String(inference[1]?.body)).model).toBe(expectedAlias ?? 'Small-Q4.gguf')
expect((await fresh.list('home')).models[0].operation?.phase).toBe('done')
})
it('reuses an already downloaded fitting quant of the same model', async () => {
catalogCards[0].versions.push({ version: 'Q3', size_bytes: 48, pull_spec: 'org/Small-GGUF:Small-Q3.gguf', urls: ['https://example.test/Small-Q3.gguf'] })
await writeFile(join(home, 'models', 'Small-Q3.gguf'), Buffer.alloc(48))
const snapshot = await service.list('home')
expect(snapshot.models[0]).toMatchObject({ state: 'downloaded', sizeBytes: 48, quant: 'Q3' })
})
it('matches the current CLI engine shape without attributing another model’s requests', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const record = JSON.parse(await readFile(join(records, 'remote.json'), 'utf8'))
record.meta_name = 'My laptop'
await writeFile(join(records, 'remote.json'), JSON.stringify(record))
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('engines') ? ok([{
name: 'My laptop', online: true, models: ['Small-Q4.gguf'], throughput_tok_s: 12,
answered: { requests: 99, window_seconds: 86400, by_model: [{ model: 'prior-model', requests: 99 }] },
}]) : original(args, output))
const view = await service.list('home')
expect(view.models[0]).toMatchObject({ state: 'running', tokensPerSecond: 12 })
expect(view.models[0].requests).toBeUndefined()
})
it.each(['small-q4', { model: 'small-q4' }])('matches Grid’s canonical model names after start: %j', async alias => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const record = JSON.parse(await readFile(join(records, 'remote.json'), 'utf8'))
record.meta_name = 'My laptop'
await writeFile(join(records, 'remote.json'), JSON.stringify(record))
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('engines') ? ok([{
name: 'My laptop', online: true, models: [alias], throughput_tok_s: 12,
answered: { requests: 99, window_seconds: 86400, by_model: [
{ model: 'small-q8', requests: 95 }, { model: 'small-q4', requests: 4 },
] },
}]) : original(args, output))
expect((await service.list('home')).models[0]).toMatchObject({
state: 'running', canStop: true, tokensPerSecond: 12, requests: 4, windowSeconds: 86400,
})
})
it('assigns an engine only to the downloaded variant when catalog filenames collide', async () => {
const other = card('org/Small-MTP-GGUF')
other.versions[0].size_bytes = 80
catalogCards = [other, card()]
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const snapshot = await service.list('home')
expect(snapshot.models.find(m => m.id === 'org/Small-GGUF')).toMatchObject({
state: 'running', canStop: true, requests: 4,
})
expect(snapshot.models.find(m => m.id === other.repo_id)).toMatchObject({
state: 'available', canStop: false, requests: undefined, tokensPerSecond: undefined,
})
})
it('can still stop a running catalog model after its weights are removed', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
await rm(join(home, 'models', 'Small-Q4.gguf'))
expect((await service.list('home')).models[0]).toMatchObject({ state: 'running', canStop: true })
await service.act('home', 'org/Small-GGUF', 'stop'); await service.settled()
expect((await service.list('home')).models[0]).toMatchObject({ state: 'available', canStop: false })
})
it('encrypts inventory and lifecycle requests and responses', () => {
for (const type of ['grid_fleet_models_list', 'grid_fleet_model_download', 'grid_fleet_model_start', 'grid_fleet_model_stop']) {
expect(encryptDownFrame(type)).toBe(true); expect(encryptRpcResult(`${type}_result`)).toBe(true)
}
})
it('coalesces discovery, caches it briefly, and isolates different accounts', async () => {
const [first, duplicate, other] = await Promise.all([service.list('home'), service.list('home'), service.list('other')])
expect(duplicate).toEqual(first)
expect(other.busy).toBe(false)
expect(calls.filter(args => args[0] === 'device-info')).toHaveLength(1)
const before = calls.length
expect(await service.list('other')).toEqual(other)
expect(calls).toHaveLength(before)
await service.list('home', true)
expect(calls.filter(args => args[0] === 'device-info')).toHaveLength(2)
expect(await service.list(null)).toMatchObject({ models: [], busy: false, notice: expect.stringContaining('Sign in') })
expect((await service.act(null, 'x', 'start')).error).toBeTruthy()
expect((await service.act('home', {}, 'start')).error).toBeTruthy()
})
it.each([
['missing credentials', ''],
['no session token', 'api_url = "https://catalog.example.test"'],
['malformed token', 'session_token = "invalid\\q"'],
])('reports sign-in for %s without sending credentials', async (_name, credentials) => {
await writeFile(join(home, 'credentials.toml'), credentials)
expect((await service.list('home')).notice).toContain('Sign in')
expect(request).not.toHaveBeenCalled()
})
it.each(['http://catalog.example.test', 'file:///tmp/catalog'])('refuses insecure catalog address %s', async base => {
await writeFile(join(home, 'credentials.toml'), `session_token = 'private'\napi_url = '${base}'`)
expect((await service.list('home')).notice).toContain('address')
expect(request).not.toHaveBeenCalled()
})
it.each(['http://localhost:1234', 'http://127.0.0.1:1234', 'http://[::1]:1234'])('permits an explicitly configured local catalog at %s', async base => {
await writeFile(join(home, 'credentials.toml'), `session_token = 'test-only-token'\napi_url = '${base}'`)
expect((await service.list('home')).notice).toBeUndefined()
expect(String(request.mock.calls[0][0])).toBe(`${base}/v1/grid/catalog`)
expect(request.mock.calls[0][1]).toMatchObject({ redirect: 'error' })
})
it.each([undefined, 'https://alternate.example.test'])('uses the configured or default catalog when the credential store omits it', async base => {
await writeFile(join(home, 'credentials.toml'), 'session_token = "test-only-token"\n')
service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home, GRID_CONTROL_PLANE_URL: base }, run, request: request as typeof fetch , inventory })
await service.list('home')
expect(String(request.mock.calls[0][0])).toBe(`${base ?? 'https://api-grid.autonomous.ai'}/v1/grid/catalog`)
})
it.each(['http failure', 'missing rows', 'empty intermediate page', 'unbounded pages'])('handles a catalog %s without inventing compatibility', async scenario => {
request.mockImplementation(async (_url, init) => {
const page = JSON.parse(String(init?.body)).page
return scenario === 'http failure' ? new Response('private detail', { status: 401 })
: response(scenario === 'missing rows' ? { error: 'private detail' }
: { models: scenario === 'empty intermediate page' ? [] : [card()], pagination: { page, total_pages: 101 } })
})
const snapshot = await service.list('home')
expect(snapshot.models).toEqual([])
expect(snapshot.notice).toBeTruthy()
expect(JSON.stringify(snapshot)).not.toContain('private detail')
expect(request.mock.calls.length).toBeLessThanOrEqual(100)
})
it('supports an unpaginated catalog, prefers a useful small download, and skips unfitted versions', async () => {
const large = card('org/Large-GGUF'), small = card('org/Fast-GGUF')
large.versions[0].size_bytes = 20 * 1024 ** 3
small.versions[0].size_bytes = 2 * 1024 ** 3
small.versions.push({ ...small.versions[0], version: 'Q8', size_bytes: 4 * 1024 ** 3 })
small.versions.push({ ...small.versions[0], version: 'unknown', size_bytes: undefined as any })
request.mockImplementation(async () => response({ models: [large, small] }))
expect((await service.list('home')).models.map(m => [m.name, m.recommended])).toEqual([['Fast', true], ['Large', false]])
})
it.each(['failed command', 'invalid json'])('disables actions when inventory returns %s', async scenario => {
await service.list('home')
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('engines')
? { ...ok(), ok: scenario !== 'failed command', stdout: 'not json' } : original(args, output))
const snapshot = await service.list('home', true)
expect(snapshot.notice).toContain('Running models could not be checked')
expect(snapshot.models.every(m => !m.canStart && !m.canStop)).toBe(true)
})
// ── a grid that is down ──────────────────────────────────────────────────────────────────────
//
// ⚠️ REGRESSION. Grid refuses `engines` on a grid that is not up, and that refusal was read as
// "running models unknown": every Start in the list went dark, so the one state in which a person
// most needs to start a model was the one in which none could be. And a Start that did get through
// failed at `join`, which a down grid refuses too.
it.each(['stopped', 'asleep'] as const)('a %s grid runs nothing: every model can start, and nothing is wrong', async state => {
gridState = state
const snapshot = await service.list('home')
expect(snapshot.models).toMatchObject([{ name: 'Small', state: 'available', canStart: true, canStop: false }])
expect(snapshot.notice).toBeUndefined()
// Never `error`: on this protocol that field fails the request and the app keeps no list.
expect(snapshot).not.toHaveProperty('error')
})
it('a refusal from a grid that IS running is still a gap, not an empty list', async () => {
run.mockImplementation(async args => args.includes('engines') ? refused('private detail')
: args.includes('info') ? ok({ status: 'running' }) : ok([{ grid: 'home', id: 'grid-home' }]))
await service.list('home', true)
const snapshot = await service.list('home', true)
expect(snapshot.notice).toContain('Running models could not be checked')
expect(JSON.stringify(snapshot)).not.toContain('private detail')
})
it.each(['stopped', 'asleep'] as const)('Start brings a %s grid up before joining it', async state => {
gridState = state
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const started = calls.findIndex(args => args[0] === '--remote' && args[1] === 'start')
const joined = calls.findIndex(args => args.includes('join'))
expect(calls[started]).toEqual(['--remote', 'start', 'home'])
expect(started).toBeGreaterThanOrEqual(0)
expect(started).toBeLessThan(joined)
expect((await service.list('home', true)).models[0]).toMatchObject({ state: 'running', operation: { phase: 'done' } })
})
it('Start leaves a running grid alone', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.some(args => args[0] === '--remote' && args[1] === 'start')).toBe(false)
expect((await service.list('home', true)).models[0].state).toBe('running')
})
it('an unreadable grid status blocks nothing: the start goes on to the join', async () => {
// A Grid too old to answer `info --json` joined fine before this read existed.
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('info') && args.includes('--json') ? refused('usage') : original(args, output))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.some(args => args[1] === 'start')).toBe(false)
expect((await service.list('home', true)).models[0]).toMatchObject({ state: 'running', operation: { phase: 'done' } })
})
it('a grid that will not come up fails the Start in words, before any join', async () => {
gridState = 'stopped'
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args[1] === 'start' ? refused('private detail') : original(args, output))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.some(args => args.includes('join'))).toBe(false)
expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', error: 'Your grid could not start. Try again.' })
})
it.each(['missing grid', 'invalid grid id', 'missing record directory', 'corrupt record'])('ignores %s without exposing a Stop action', async scenario => {
const original = run.getMockImplementation()!
if (scenario === 'missing grid' || scenario === 'invalid grid id') {
run.mockImplementation(async (args, output) => args.includes('ls') ? ok(scenario === 'missing grid' ? [] : [{ grid: 'home', id: '../escape' }]) : original(args, output))
} else if (scenario === 'missing record directory') await rm(records, { recursive: true })
else await writeFile(join(records, 'broken.json'), 'not-json')
expect((await service.list('home')).models[0].canStop).toBe(false)
expect((await service.list('-invalid', true)).models[0].canStop).toBe(false)
})
it.each([
{}, { engines: [{ models: ['--bad.gguf'] }] }, { engines: [{ models: ['file.bin'] }] },
{ engines: [{ api_kind: 'openai', models: ['Small-Q4.gguf'] }] },
{ engines: [{ models: ['one.gguf', 'two.gguf'] }] },
])('does not treat an unowned or malformed run record as a controllable model: %j', async record => {
await writeFile(join(records, 'remote.json'), JSON.stringify(record))
expect((await service.list('home')).models[0].canStop).toBe(false)
})
it.each(['missing heartbeat', 'offline node', 'ambiguous node', 'missing models', 'missing file'])('does not claim running from %s alone', async scenario => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
if (scenario === 'missing heartbeat') await rm(join(records, 'remote.heartbeat'))
if (scenario === 'missing file') { catalogCards = []; await rm(join(home, 'models', 'Small-Q4.gguf')); serving = false }
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => {
const result = await original(args, output)
if (!args.includes('engines') || scenario === 'missing heartbeat' || scenario === 'missing file') return result
const node = JSON.parse(result.stdout)[0]
return ok(scenario === 'ambiguous node' ? [node, node] : [{ ...node, ...(scenario === 'offline node' ? { online: false } : { models: null }) }])
})
const snapshot = await service.list('home', true)
expect(snapshot.models[0]).toMatchObject({ canStop: true })
expect(snapshot.models[0].state).not.toBe('running')
expect(snapshot.models[0].tokensPerSecond).toBeUndefined()
})
it('keeps a missing-file engine stoppable and requires live inventory to call it running', async () => {
catalogCards = []
serving = true
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ models: ['Small-Q4.gguf'] }] }))
await writeFile(join(records, 'remote.heartbeat'), '')
expect((await service.list('home')).models[0]).toMatchObject({ state: 'running', canStart: false, canStop: true })
await service.act('home', 'local:Small-Q4.gguf', 'stop'); await service.settled()
expect(calls.some(args => args.includes('leave'))).toBe(true)
expect((await service.list('home')).models).toEqual([])
})
it('matches object-shaped aliases and never substitutes engine-total request counts', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('engines') ? ok([{
id: 'local-node', online: true, models: [{ model: 'SMALL-Q4.GGUF' }],
answered: { requests: 200, window_seconds: 3600 },
}]) : original(args, output))
expect((await service.list('home')).models[0]).toMatchObject({ state: 'running', requests: undefined })
})
it('marks an unfinished receipt interrupted after restart without replaying a command', async () => {
await mkdir(stateDir)
const hash = createHash('sha256').update('home').digest('hex').slice(0, 24)
await writeFile(join(stateDir, `${hash}.json`), JSON.stringify({ spec: 1, grid: 'home', operation: {
id: 'interrupted', modelId: 'org/Small-GGUF', action: 'start', stage: 'downloading', phase: 'running', updatedAt: '2026-01-01T00:00:00Z',
} }))
expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', error: expect.stringContaining('interrupted') })
expect(calls.some(args => args[0] === 'pull' || args.includes('join'))).toBe(false)
})
it.each([{ spec: 9, grid: 'home' }, { spec: 1, grid: 'somebody-else' }])('discards an invalid or different-account receipt: %j', async receipt => {
await mkdir(stateDir)
const hash = createHash('sha256').update('home').digest('hex').slice(0, 24)
await writeFile(join(stateDir, `${hash}.json`), JSON.stringify({ ...receipt, operation: { id: 'private', modelId: 'org/Small-GGUF' } }))
expect((await service.list('home')).models[0].operation).toBeUndefined()
})
it('refuses to start if a durable receipt cannot be created', async () => {
await writeFile(stateDir, 'not a directory')
expect((await service.act('home', 'org/Small-GGUF', 'start')).error).toContain('saved')
expect(calls).toEqual([])
await rm(stateDir)
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.phase).toBe('done')
})
it.each(['model no longer fits', 'smaller fit only', 'no machine budget'])('checks changed hardware before downloading: %s', async scenario => {
await service.list('home')
if (scenario === 'no machine budget') {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args[0] === 'device-info' ? ok({}) : original(args, output))
}
request.mockImplementation(async () => response({ models: scenario === 'smaller fit only'
? [{ ...card(), versions: [{ ...card().versions[0], size_bytes: 32 }] }] : [] }))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.error).toContain('make room')
expect(calls.some(args => args[0] === 'pull' || args.includes('join'))).toBe(false)
})
it('does not download when free disk space is insufficient', async () => {
catalogCards[0].versions[0].size_bytes = Number.MAX_SAFE_INTEGER
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.error).toContain('disk space')
expect(calls.some(args => args[0] === 'pull')).toBe(false)
})
it('does not start an incomplete download even after the downloader exits successfully', async () => {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args[0] === 'pull' ? ok() : original(args, output))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.error).toContain('incomplete')
expect(calls.some(args => args.includes('join'))).toBe(false)
})
it.each(['engine', 'join', 'info', 'leave'])('reports a failed %s without inventing success', async step => {
if (step === 'leave') { await service.act('home', 'org/Small-GGUF', 'start'); await service.settled() }
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes(step) ? { ...ok(), ok: false, stderr: 'private-token' } : original(args, output))
await service.act('home', 'org/Small-GGUF', step === 'leave' ? 'stop' : 'start'); await service.settled()
const snapshot = await service.list('home')
expect(snapshot.models[0].operation?.phase).toBe('failed')
expect(JSON.stringify(snapshot)).not.toContain('private-token')
})
it('keeps Stop available while a successful leave has not removed its run record', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('leave') ? ok() : original(args, output))
await service.act('home', 'org/Small-GGUF', 'stop'); await service.settled()
expect((await service.list('home')).models[0]).toMatchObject({ canStop: true, operation: { phase: 'failed', error: expect.stringContaining('still stopping') } })
})
it('protects a shared runtime from simple Stop and Start', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const record = JSON.parse(await readFile(join(records, 'remote.json'), 'utf8'))
record.media = { port: 1234 }
await writeFile(join(records, 'remote.json'), JSON.stringify(record))
await service.act('home', 'org/Small-GGUF', 'stop'); await service.settled()
expect((await service.list('home')).models[0].operation?.error).toContain('share its engine')
expect(calls.some(args => args.includes('leave'))).toBe(false)
})
it('reverifies an already owned instance without downloading or joining again', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.filter(args => args.includes('join'))).toHaveLength(1)
expect(request.mock.calls.filter(([url]) => String(url).includes(RELAY_CHAT))).toHaveLength(2)
})
it.each([false, true])('handles an explicit engine override (available=%s)', async available => {
const binary = join(root, 'custom-llama')
if (available) await writeFile(binary, '#!/bin/sh\nexit 0', { mode: 0o700 })
service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home, LLAMA_SERVER: binary }, run, request: request as typeof fetch , inventory })
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const operation = (await service.list('home')).models[0].operation
expect(operation?.phase).toBe(available ? 'done' : 'failed')
expect(calls.some(args => args[0] === 'engine')).toBe(false)
})
it('keeps a missing endpoint recoverable without sending a test to an unknown address', async () => {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('info') ? ok() : original(args, output))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.phase).toBe('failed')
expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(false)
})
it.each(['reasoning only', 'http error', 'network error'])('requires a real test reply and bounds retries for %s', async scenario => {
const original = request.getMockImplementation()!
let attempted!: () => void
const first = new Promise<void>(resolve => { attempted = resolve })
request.mockImplementation(async (url, init) => {
// The catalog, and the engine on this machine, answer normally: this is about the RELAY check.
if (String(url).includes('/catalog') || String(url).includes('127.0.0.1')) return original(url, init)
attempted()
if (scenario === 'network error') throw new Error('private-token')
return scenario === 'http error' ? new Response('private-token', { status: 503 })
: response({ choices: [{ message: { reasoning_content: 'ok' } }] })
})
vi.useFakeTimers({ toFake: ['setTimeout', 'Date'] })
await service.act('home', 'org/Small-GGUF', 'start')
await first
await vi.advanceTimersByTimeAsync(182_000)
await service.settled()
expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', error: expect.stringContaining('did not answer') })
expect(JSON.stringify(await service.list('home'))).not.toContain('private-token')
vi.useRealTimers()
})
it('rejects unsafe, incomplete and duplicate fit cards while supporting split downloads', () => {
const invalid = [null, {}, { ...card(), runnable: false }, { ...card(), format: 'safetensors' },
{ ...card(), repo_id: '' }, { ...card(), fit: {} },
...['--flag:model.gguf', 'repo-only', 'org/repo:model.bin'].map(pull_spec => ({ ...card(), versions: [{ ...card().versions[0], pull_spec }] })),
{ ...card(), fit: { version: 'Q4', ctx: 0 } },
{ ...card(), versions: [{ ...card().versions[0], size_bytes: -1 }] }]
expect(compatibleModels({ models: invalid })).toEqual([])
expect(compatibleModels({ models: [card(), card()] })).toHaveLength(1)
expect(compatibleModels({ models: [{ ...card(), versions: [{ ...card().versions[0], urls: ['bad-url'] }] }] })[0].files).toEqual(['Small-Q4.gguf'])
expect(compatibleModels({ models: [{ ...card(), versions: [{ ...card().versions[0], urls: null }] }] })[0].files).toEqual(['Small-Q4.gguf'])
expect(compatibleModels({ models: [{ ...card(), task: 'image-text-to-text', versions: [{ ...card().versions[0], urls: ['https://example.test/part-1.gguf', 'https://example.test/part-2.gguf'] }] }] })[0].files).toEqual(['part-1.gguf', 'part-2.gguf'])
})
it('routes production-default dependencies through the bounded Grid subprocess runner', async () => {
vi.stubEnv('GRID_HOME', home)
vi.stubGlobal('fetch', request)
const rpc = vi.spyOn(GridFleetRpc.prototype, 'run').mockImplementation(async (_owner, _id, options, output) => run(options.args, output))
service = new LocalModels({ stateDir, inventory })
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.phase).toBe('done')
expect(rpc).toHaveBeenCalledWith('local-models', expect.any(String), expect.objectContaining({ timeoutMs: 30_000, thinking: false }), undefined, 4 * 1024 * 1024)
expect(rpc.mock.calls.find(call => call[2].args[0] === 'pull')?.[2].timeoutMs).toBe(30 * 60_000)
})
it.each(['memory changed', 'file removed'])('rechecks an imported deployment before restarting when %s', async scenario => {
catalogCards = []
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await run(['--remote', 'join', 'home'])
await service.list('home')
await service.act('home', 'local:Small-Q4.gguf', 'stop'); await service.settled()
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => {
if (args[0] === 'device-info') {
if (scenario === 'file removed') await rm(join(home, 'models', 'Small-Q4.gguf'))
else return ok({ usable_bytes: 0 })
}
return original(args, output)
})
const ack = await service.act('home', 'local:Small-Q4.gguf', 'start'); await service.settled()
expect(ack.operation).toMatchObject({ phase: 'failed', error: expect.stringContaining(scenario === 'memory changed' ? 'make room' : 'no longer available') })
expect(calls.filter(args => args.includes('join'))).toHaveLength(1)
})
it('keeps imported downloads visible, merges catalog matches, and removes deleted files', async () => {
catalogCards = []
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await run(['--remote', 'join', 'home'])
await service.list('home')
await service.act('home', 'local:Small-Q4.gguf', 'stop'); await service.settled()
expect((await service.list('home')).models[0].state).toBe('downloaded')
catalogCards = [card()]
expect((await service.list('home', true)).models).toHaveLength(1)
catalogCards = []
await rm(join(home, 'models', 'Small-Q4.gguf'))
expect((await service.list('home', true)).models).toEqual([])
})
it('does not mistake a directory for downloaded weights or fabricate unavailable device memory', async () => {
await mkdir(join(home, 'models', 'Small-Q4.gguf'))
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args[0] === 'device-info' ? ok({}) : original(args, output))
const view = await service.list('home')
expect(view.models[0].state).toBe('available')
expect(view.memoryBytes).toBeUndefined()
})
it('cannot start a stale catalog choice while compatibility is unavailable', async () => {
await service.list('home')
catalogFails = true
await service.list('home', true)
const ack = await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(ack.operation).toMatchObject({ phase: 'failed', error: expect.stringContaining('could not be checked') })
expect(calls.some(args => args[0] === 'pull')).toBe(false)
})
it('ignores non-progress output and boundedly saves valid download progress', async () => {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => {
if (args[0] === 'pull') { output?.('connecting…'); output?.('150%'); output?.('0%'); output?.('2%') }
return original(args, output)
})
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.phase).toBe('done')
})
it('releases the operation after receipt storage fails during a download', async () => {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => {
if (args[0] === 'pull') {
rmSync(stateDir, { recursive: true, force: true }); writeFileSync(stateDir, 'storage unavailable')
output?.('42%')
await new Promise(resolve => setImmediate(resolve))
throw new Error('private filesystem detail')
}
return original(args, output)
})
const ack = await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(ack.operation).toMatchObject({ phase: 'failed', error: 'The model could not finish. Start again to retry.' })
expect((await service.list('home')).busy).toBe(false)
await rm(stateDir)
run.mockImplementation(original)
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect((await service.list('home')).models[0].operation?.phase).toBe('done')
})
it('recovers malformed aliases and preserves failure status for a model with missing weights', async () => {
catalogCards = []
serving = true
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', advertise_as: [42, ''], engines: [{ models: ['Small-Q4.gguf'] }] }))
await writeFile(join(records, 'remote.heartbeat'), '')
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('leave') ? { ...ok(), ok: false } : original(args, output))
await service.act('home', 'local:Small-Q4.gguf', 'stop'); await service.settled()
expect((await service.list('home')).models[0]).toMatchObject({ name: 'Small-Q4', state: 'running', operation: { phase: 'failed' } })
})
})
/** A pid that existed a moment ago and no longer does. */
function deadPid(): number {
return Number(spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' }).stdout)
}
describe('the Model Manager while its grid sleeps (grid-reads-without-waking issue 02)', () => {
const parkedRecord = (pid: unknown) => JSON.stringify({ node_id: 'local-node', meta_name: 'This computer', pid,
engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: [] })
it('is not an inventory error: Start and Pause stay enabled, and a parked engine reads running', async () => {
gridState = 'asleep'
const next = card('org/Next-GGUF'); next.versions[0].pull_spec = 'org/Next-GGUF:Next.gguf'
catalogCards = [card(), next]
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), parkedRecord(process.pid))
const snapshot = await service.list('home')
expect(snapshot.notice).not.toBe('Running models could not be checked. Try again.')
expect(snapshot.models[0]).toMatchObject({ id: 'org/Small-GGUF', state: 'running', gridAsleep: true, canStop: true })
expect(snapshot.models[1]).toMatchObject({ id: 'org/Next-GGUF', canStart: true })
expect(inventory).toHaveBeenCalledWith('home', false)
})
it('reads a parked engine running on a row the catalog does not know, too', async () => {
gridState = 'asleep'; catalogCards = []
await writeFile(join(records, 'remote.json'), parkedRecord(process.pid))
expect((await service.list('home')).models).toEqual([expect.objectContaining({ id: 'local:Small-Q4.gguf', state: 'running', gridAsleep: true, canStop: true })])
})
it.each([['a process that is gone', () => deadPid()], ['a join mid-spawn (pid 0)', () => 0], ['no pid at all', () => 'x']])(
'does not call %s parked', async (_name, pid) => {
gridState = 'asleep'; catalogCards = []
await writeFile(join(records, 'remote.json'), parkedRecord(pid()))
const [row] = (await service.list('home')).models
expect(row).toMatchObject({ id: 'local:Small-Q4.gguf', state: 'available', canStop: true })
expect(row).not.toHaveProperty('gridAsleep')
})
it('an engine the awake grid lists is running with no asleep flag', async () => {
serving = true
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), parkedRecord(process.pid))
await writeFile(join(records, 'remote.heartbeat'), '')
const [row] = (await service.list('home')).models
expect(row).toMatchObject({ state: 'running' })
expect(row).not.toHaveProperty('gridAsleep')
})
it('a grid that answered nothing readable is still an inventory error', async () => {
answered = 'unknown'
expect((await service.list('home')).notice).toBe('Running models could not be checked. Try again.')
})
it('and so is one whose owner status could not be read either — nothing says it is down', async () => {
inventory.mockResolvedValueOnce({ state: 'unknown', nodes: [], status: null })
expect((await service.list('home')).notice).toBe('Running models could not be checked. Try again.')
})
it.each([['failed', { ...ok(), ok: false, code: 1 }], ['answered with something that is not JSON', { ...ok(), stdout: 'not json' }]])(
'so is a grid list that %s', async (_how, answer) => {
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('ls') ? answer : original(args, output))
expect((await service.list('home')).notice).toBe('Running models could not be checked. Try again.')
})
it('tells its owner when a start or stop has finished, so the lists are read again', async () => {
const onChanged = vi.fn()
service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory, onChanged })
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(onChanged).toHaveBeenCalledOnce()
})
})
describe('readRunRecords — what servedHere knows about this computer', () => {
it('reads the name, the advertised ids (else the models under the display rule) and whether the pid lives', async () => {
await writeFile(join(records, 'a.json'), JSON.stringify({ meta_name: 'mac', pid: process.pid, advertise_as: ['Team/Model', 7, ''], models: ['ignored.gguf'] }))
await writeFile(join(records, 'b.json'), JSON.stringify({ meta_name: 'mac', pid: deadPid(), models: ['Qwen3-8B-Q4_K_M.GGUF', 'plain'] }))
await writeFile(join(records, 'c.json'), JSON.stringify({ pid: 0, models: 'not a list' }))
await writeFile(join(records, 'd.json'), '{ not json')
await writeFile(join(records, 'e.heartbeat'), '')
const found = (await readRunRecords(home, 'grid-home')).sort((x, y) => x.ids.join().localeCompare(y.ids.join()))
expect(found).toEqual([
{ name: '', ids: [], pid: null, alive: false },
{ name: 'mac', ids: ['Qwen3-8B-Q4_K_M', 'plain'], pid: expect.any(Number), alive: false },
{ name: 'mac', ids: ['Team/Model'], pid: process.pid, alive: true },
])
})
it.each(['', '../grid-home', 'missing'])('answers nothing for grid id %j', async (gridId) => {
await writeFile(join(records, 'a.json'), JSON.stringify({ meta_name: 'mac', pid: process.pid, advertise_as: ['X'] }))
expect(await readRunRecords(home, gridId)).toEqual([])
})
})
describe('a context a coding agent can work in', () => {
// ⚠️ REGRESSION. Every model was offered and started at 16K or less — a model that loads, passes
// its one-word check, and then cannot hold a coding agent's first prompt. Codex, Claude Code and
// OpenCode all need 64K at the least; the most this machine can give is what a start now asks for.
it.each([
[32768, false], [65535, false], [65536, true], [262144, true],
])("a catalog fit of %i on this machine is offered: %s", async (ctx, offered) => {
catalogCards[0].fit.ctx = ctx
expect((await service.list('home')).models.length).toBe(offered ? 1 : 0)
})
it('pins the whole fit, capped at the most the model was trained for', async () => {
Object.assign(catalogCards[0].fit, { ctx: 262144, max_ctx: 196608 })
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const joined = calls.find(args => args.includes('join'))!
expect(joined[joined.indexOf('--ctx-size') + 1]).toBe('196608')
})
it('shrinks to what fits at start when memory has since tightened, but never under 64K', async () => {
catalogCards[0].fit.ctx = 262144
await service.list('home')
catalogCards[0].fit.ctx = 98304
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const joined = calls.find(args => args.includes('join'))!
expect(joined[joined.indexOf('--ctx-size') + 1]).toBe('98304')
})
it('refuses to start at all when the fit at start is under 64K', async () => {
await service.list('home')
catalogCards[0].fit.ctx = 32768
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(calls.some(args => args.includes('join'))).toBe(false)
expect((await service.list('home')).models[0].operation).toMatchObject({ phase: 'failed', error: expect.stringContaining('make room') })
})
it('hides a model on disk whose file can never hold 64K, and keeps one it cannot read', async () => {
catalogCards = []; serving = true
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ models: ['Small-Q4.gguf'] }] }))
await writeFile(join(records, 'remote.heartbeat'), '')
const id = (await service.list('home')).models[0].id
await service.act('home', id, 'stop'); await service.settled()
// Unreadable header: unknown is not "too small".
expect((await service.list('home', true)).models.map(m => m.id)).toEqual([id])
trainedWindow = 32768
const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory })
expect((await fresh.list('home')).models).toEqual([])
})
it.each([
[131072, 'done'], [undefined, 'done'], [32768, 'failed'],
] as const)('after a start that served %s tokens, the start is %s', async (window, phase) => {
servedWindow = window
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const operation = (await service.list('home', true)).models[0].operation
expect(operation?.phase).toBe(phase)
if (phase === 'failed') {
// Served too small: taken back down rather than left answering prompts it cannot hold.
expect(calls.find(args => args.includes('leave'))).toEqual(['--remote', 'leave', 'home', '--engine', 'Small-Q4.gguf'])
expect(operation?.error).toBe('Small could only get a 32K context here. Coding agents need at least 64K. Close some apps, or choose a smaller model.')
} else {
expect(calls.some(args => args.includes('leave'))).toBe(false)
}
})
})
describe('stepping down to the context that actually runs', () => {
// ⚠️ REGRESSION, measured on a 64 GB M1 Max. Left to the engine, a 35B model took its whole
// trained 256K, loaded, and then failed its very first request — "Insufficient Memory
// (kIOGPUCommandBufferCallbackErrorOutOfMemory)", then "Compute error." for every request after.
// The relay check waited three minutes and said only "did not answer". The same file ran at 128K.
const joinedAt = () => calls.filter(args => args.includes('join')).map(args => Number(args[args.indexOf('--ctx-size') + 1]))
/** The engine on this machine runs out of memory at any context above [limit]. */
const gpuHolds = (limit: number) => {
const original = request.getMockImplementation()!
request.mockImplementation(async (url, init) => {
if (String(url).includes('127.0.0.1') && String(url).endsWith('/chat/completions') && joinedAt().at(-1)! > limit) {
return new Response(JSON.stringify({ error: { code: 500, message: 'Compute error.', type: 'server_error' } }), { status: 500 })
}
return original(url, init)
})
}
it('halves to the 64K floor and no further', () => {
expect(contextLadder(262144)).toEqual([262144, 131072, 65536])
expect(contextLadder(196608)).toEqual([196608, 98304, 65536])
expect(contextLadder(100000)).toEqual([100000, 65536])
expect(contextLadder(65536)).toEqual([65536])
expect(contextLadder(50000)).toEqual([])
})
it('takes a size the GPU cannot run back down, and settles on the next that does', async () => {
catalogCards[0].fit.ctx = 262144
gpuHolds(131072)
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(joinedAt()).toEqual([262144, 131072])
// Down between the two, and Grid's registration restored before the second join.
const between = calls.slice(calls.findIndex(a => a.includes('join')) + 1, calls.findLastIndex(a => a.includes('join')))
expect(between).toContainEqual(['--remote', 'leave', 'home', '--engine', 'Small-Q4.gguf'])
expect(between).toContainEqual(['--remote', 'sync'])
expect((await service.list('home', true)).models[0]).toMatchObject({ state: 'running', operation: { phase: 'done' } })
})
it('says it is memory, in words, when not even 64K runs — without waiting on the relay', async () => {
catalogCards[0].fit.ctx = 262144
gpuHolds(0)
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(joinedAt()).toEqual([262144, 131072, 65536])
expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(false)
expect((await service.list('home', true)).models[0].operation).toMatchObject({ phase: 'failed',
error: 'This computer does not have the memory to run Small with a 64K context. Close some apps, or choose a smaller model.' })
})
it('steps down from a size whose join fails, since a failed allocation at load looks like that', async () => {
catalogCards[0].fit.ctx = 262144
const original = run.getMockImplementation()!
run.mockImplementation(async (args, output) => args.includes('join') && args.includes('262144') ? refused('engine exited') : original(args, output))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
const joins = run.mock.calls.map(([args]) => args).filter(args => args.includes('join'))
expect(joins.map(a => a[a.indexOf('--ctx-size') + 1])).toEqual(['262144', '131072'])
expect((await service.list('home', true)).models[0].operation?.phase).toBe('done')
})
it.each([
['nothing is listening on this machine', () => { throw new Error('ECONNREFUSED') }],
['the engine fails for another reason', () => new Response('{"error":{"message":"template error"}}', { status: 500 })],
// Not a load in progress (503), so not waited on for ten minutes.
['its health check answers something unexpected', () => new Response('teapot', { status: 418 })],
])('leaves the judgement to the relay check when %s', async (_case, answer) => {
const original = request.getMockImplementation()!
request.mockImplementation(async (url, init) => String(url).includes('127.0.0.1') ? answer() : original(url, init))
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
expect(joinedAt()).toEqual([131072])
expect(request.mock.calls.some(([url]) => String(url).includes(RELAY_CHAT))).toBe(true)
expect((await service.list('home', true)).models[0].operation?.phase).toBe('done')
})
it('starts a file on disk at the most its header says it holds', async () => {
catalogCards = []; serving = true
await writeFile(join(home, 'models', 'Small-Q4.gguf'), Buffer.alloc(64))
await writeFile(join(records, 'remote.json'), JSON.stringify({ node_id: 'local-node', engines: [{ models: ['Small-Q4.gguf'] }] }))
await writeFile(join(records, 'remote.heartbeat'), '')
const id = (await service.list('home')).models[0].id
await service.act('home', id, 'stop'); await service.settled()
trainedWindow = 262144
const fresh = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, inventory })
await fresh.act('home', id, 'start'); await fresh.settled()
expect(joinedAt()).toEqual([262144])
})
})
describe("a model is labelled with the machine's name as Harness shows it", () => {
// ⚠️ REGRESSION. Started from the Models modal, a model joined with no `--name`, so Grid labelled
// it with the host name: `mac.lan` under "On your machines" while Machines called it `M2`.
const joined = () => calls.find(args => args.includes('join'))!
it('joins under the Harness name', async () => {
const named = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, machineName: () => ' M2 ', inventory })
await named.act('home', 'org/Small-GGUF', 'start'); await named.settled()
expect(joined().slice(joined().indexOf('--name'), joined().indexOf('--name') + 2)).toEqual(['--name', 'M2'])
})
it.each([
['is not known yet', () => null],
['would read as a flag', () => '--all'],
['carries a control character', () => 'M2\nevil'],
])('leaves --name off when the name %s, rather than pass it', async (_case, machineName) => {
const named = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch, machineName, inventory })
await named.act('home', 'org/Small-GGUF', 'start'); await named.settled()
expect(joined()).not.toContain('--name')
expect((await named.list('home', true)).models[0].operation?.phase).toBe('done')
})
})
describe('download without starting', () => {
it('stores the weights without waking a grid, installing an engine, or sending a prompt', async () => {
gridState = 'asleep'
const result = await service.act('home', 'org/Small-GGUF', 'download')
await service.settled()
expect(result.operation).toMatchObject({ action: 'download', phase: 'done' })
expect(calls.filter(args => args[0] === 'pull')).toHaveLength(1)
expect(calls.some(args => args.includes('sync') || args.includes('join') || args.includes('start') || args.includes('install'))).toBe(false)
expect(request.mock.calls.some(([url]) => String(url).includes('chat/completions'))).toBe(false)
expect(gridState).toBe('asleep')
expect((await service.list('home')).models[0]).toMatchObject({ state: 'downloaded', canStart: true, canStop: false })
expect((await service.list('home')).supportsDownload).toBe(true)
})
it('a download request for a running model never runs another reply test', async () => {
await service.act('home', 'org/Small-GGUF', 'start'); await service.settled()
calls.length = 0; request.mockClear()
const result = await service.act('home', 'org/Small-GGUF', 'download'); await service.settled()
expect(result.operation?.phase).toBe('done')
expect(serving).toBe(true)
expect(calls.some(args => args.includes('join') || args.includes('pull') || args.includes('sync'))).toBe(false)
expect(request.mock.calls.some(([url]) => String(url).includes('chat/completions'))).toBe(false)
})
it('keeps failed downloads retryable and starts only after a separate Start', async () => {
downloadFails = true
const first = await service.act('home', 'org/Small-GGUF', 'download')
await service.settled()
expect(first.operation?.phase).toBe('failed')
expect(serving).toBe(false)
downloadFails = false
await service.act('home', 'org/Small-GGUF', 'download')
await service.settled()
expect(serving).toBe(false)
const pulls = calls.filter(args => args[0] === 'pull').length
await service.act('home', 'org/Small-GGUF', 'start')
await service.settled()
expect(serving).toBe(true)
expect(calls.filter(args => args[0] === 'pull')).toHaveLength(pulls)
})
})