Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Merge origin/main into feat/grid-scale-phase-a

Kelvin30a7248c6f80
diff --cc cli/src/backendSocket.gridReads.spec.ts
index ef559098e,000000000..ce6f5a0e7
mode 100644,000000..100644
--- a/cli/src/backendSocket.gridReads.spec.ts
+++ b/cli/src/backendSocket.gridReads.spec.ts
@@@ -1,155 -1,0 +1,160 @@@
+/**
+ * The daemon's grid RPCs as a desktop drives them — `grid_models_list`, the Model Manager's
+ * `grid_fleet_models_list` and `agent_retarget` — against a fake relay that records every request it
+ * receives, and a fake `grid` first on PATH (grid-reads-without-waking issue 02).
+ *
+ * The relay is the spy: nothing here recomputes what the daemon sends, it reads what arrived.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer, type IncomingHttpHeaders, type Server } from 'node:http'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { BackendSocket } from './backendSocket.js'
+import { env } from './config/env.js'
+import { fakeGridAnswers, installFakeGrid, type FakeGrid, type FakeGridPlan } from './lib/__fixtures__/fakeGrid.js'
+import { clearGridMcpUrlCache } from './lib/gridMcpUrl.js'
+import { resetGridModels, type GridModelsService } from './lib/gridModels.js'
+
+const OWN = 'mine', OWN_ID = 'net-own'
+const OVERVIEW = '/relay/v1/grid/overview'
+
+let server: Server, base: string, seen: Array<{ path: string; headers: IncomingHttpHeaders }>
+let overview: { status: number; body: unknown }
+let root: string, gridHome: string, previousData: string, grid: FakeGrid, service: GridModelsService, clock: number
+let socket: BackendSocket, frames: Array<{ type: string; payload: Record<string, unknown> }>
+
+function plan(status: string | null = 'running'): FakeGridPlan {
+ return {
+ ls: { stdout: JSON.stringify([{ grid: OWN, id: OWN_ID, type: 'permissioned-public' }]) },
+ [`info ${OWN}`]: { stdout: JSON.stringify({ grid: OWN, status, grid_url: `${base}/g/${OWN_ID}` }) },
+ }
+}
+
+async function ask(type: string, payload: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
+ const requestId = `${type}-${frames.length}`
+ socket.handleLocalFrame('local:grid-reads', { type, payload: { ...payload, requestId } })
+ await vi.waitFor(() => expect(frames.some((f) => f.payload.requestId === requestId)).toBe(true), { timeout: 10_000 })
+ return frames.find((f) => f.payload.requestId === requestId)!.payload
+}
+
+function expectNoCredential(): void {
+ for (const request of seen) {
+ expect(request.headers.authorization).toBeUndefined()
+ expect(request.headers['x-api-key']).toBeUndefined()
+ }
+}
+
+beforeEach(async () => {
+ seen = []
+ overview = { status: 200, body: { nodes: [{ name: 'mac', engine: 'llama.cpp', models: ['small-q4'], online: true }], models: [{ id: 'Small-Q4' }] } }
+ server = createServer((req, res) => {
+ seen.push({ path: req.url ?? '', headers: req.headers })
+ const found = req.url === `/g/${OWN_ID}${OVERVIEW}` ? overview : { status: 404, body: {} }
+ res.writeHead(found.status, { 'content-type': 'application/json' })
+ res.end(JSON.stringify(found.body))
+ })
+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+ base = `http://127.0.0.1:${(server.address() as { port: number }).port}`
+ root = mkdtempSync(join(tmpdir(), 'grid-reads-rpc-'))
+ gridHome = join(root, 'grid-home')
+ mkdirSync(gridHome, { recursive: true })
+ vi.stubEnv('GRID_HOME', gridHome)
+ previousData = env.ADAPTER_DATA_DIR
+ env.ADAPTER_DATA_DIR = join(root, 'data')
+ clock = Date.parse('2026-09-24T10:00:00Z')
+ // Before the socket, which subscribes to the service it finds for its `grid_models_changed` push.
+ service = resetGridModels({ now: () => clock, dataDir: () => join(root, 'data'), gridHome: () => gridHome, email: () => null })
+ grid = installFakeGrid(plan())
+ socket = new BackendSocket('token')
+ socket.setHarnessGridName(OWN)
+ frames = []
+ socket.registerLocalClient('local:grid-reads', { sendFrame: (frame) => { frames.push(frame as typeof frames[number]); return true }, sendBinary: () => true })
+})
+
+afterEach(async () => {
+ await service.settled()
+ await socket.unregisterLocalClient('local:grid-reads')
+ await socket.stop()
+ grid.dispose()
+ clearGridMcpUrlCache()
+ env.ADAPTER_DATA_DIR = previousData
+ vi.unstubAllEnvs()
+ server.closeAllConnections()
+ await new Promise<void>((resolve) => server.close(() => resolve()))
+ rmSync(root, { recursive: true, force: true })
+})
+
+describe('grid_models_list', () => {
+ it('answers in the old shape with the three new fields, and reads the grid with no credential', async () => {
+ const reply = await ask('grid_models_list')
+
+ expect(reply).toMatchObject({ gridName: OWN, models: [{ id: 'Small-Q4', node: 'mac' }] })
+ expect(reply.grids).toEqual([{
+ name: OWN, type: 'permissioned-public', own: true, models: [{ id: 'Small-Q4', node: 'mac' }],
+ state: 'awake', seenAt: new Date(clock).toISOString(), lastKnownAge: 0,
+ }])
+ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}${OVERVIEW}`])
+ expectNoCredential()
+ })
+
+ it('pushes grid_models_changed when a read it did not wait for changes the list', async () => {
+ await ask('grid_models_list')
+ clock += 20_000
+ overview = { status: 200, body: { nodes: [{ name: 'mac', engine: 'llama.cpp', models: ['small-q4', 'big-q8'] }], models: [] } }
+
+ const reply = await ask('grid_models_list')
+ // Answered at once from the picture; the read it started lands behind it and is pushed.
+ expect((reply.models as unknown[]).length).toBe(1)
+ await vi.waitFor(() => expect(frames.some((f) => f.type === 'grid_models_changed')).toBe(true), { timeout: 5_000 })
+
+ const pushed = frames.find((f) => f.type === 'grid_models_changed')!.payload
+ expect(pushed).not.toHaveProperty('requestId')
+ expect(pushed).toMatchObject({ gridName: OWN, models: [{ id: 'Small-Q4', node: 'mac' }, { id: 'big-q8', node: 'mac' }], supportsModelLaunch: true })
+ // Two overview reads, and one of provider discovery: `big-q8` had no spelling from any other source.
+ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}${OVERVIEW}`, `/g/${OWN_ID}${OVERVIEW}`, `/g/${OWN_ID}/nodes/discover`])
+ expectNoCredential()
+ })
+})
+
+describe('grid_fleet_models_list (the Model Manager) on a sleeping own grid', () => {
+ it('is not an inventory error, keeps Start and Pause enabled, and reports a parked engine running', async () => {
+ grid.replan(plan('asleep'))
+ overview = { status: 503, body: { detail: 'resting', code: 'grid_asleep' } }
+ const records = join(gridHome, 'run', 'engines', OWN_ID)
+ mkdirSync(records, { recursive: true })
+ writeFileSync(join(records, 'remote.json'), JSON.stringify({
+ node_id: 'node-1', meta_name: 'mac', pid: process.pid, engines: [{ endpoint_url: null, models: ['Small-Q4.gguf'] }], advertise_as: [],
+ }))
+
+ const reply = await ask('grid_fleet_models_list', { refresh: true })
+
+ expect(reply.error).not.toBe('Running models could not be checked. Try again.')
+ expect(reply.models).toEqual([expect.objectContaining({ id: 'local:Small-Q4.gguf', state: 'running', gridAsleep: true, canStop: true })])
+ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}${OVERVIEW}`])
+ expectNoCredential()
+ // The owner status is asked once and remembered, not asked on every tick.
+ await ask('grid_fleet_models_list', { refresh: true })
+ await ask('grid_fleet_models_list', { refresh: true })
+ expect(grid.calls().filter((argv) => argv.includes('info'))).toHaveLength(1)
+ expect(grid.calls().some((argv) => argv.includes('engines'))).toBe(false)
+ })
+})
+
+describe('agent_retarget', () => {
- it('moves an agent onto a grid model without reading the grid at all', async () => {
++ it('reads nothing on its own: the one request is the model lookup of the move a person made', async () => {
+ const answers = fakeGridAnswers()
- grid.replan(answers.plan)
++ // The relay the grid's `info --env` names is this test's, so nothing here can reach a real host.
++ const relay = `${base}/g/${OWN_ID}/relay/v1`
++ grid.replan({ ...answers.plan, info: { stdout: `export OPENAI_BASE_URL="${relay}"\nexport OPENAI_API_KEY="${answers.token}"\n` } })
+ socket.onRetargetAgent = vi.fn(async () => ({ ok: true as const }))
+
+ const reply = await ask('agent_retarget', { agentId: 'agent-1', gridModel: 'GLM-4.7-Flash', gridName: answers.gridName })
+
+ expect(reply).toMatchObject({ retargeted: true })
- expect(seen).toEqual([])
++ // Moving an agent onto a model is a person's act, which may wake the grid (and is meant to: the
++ // pane is about to use it). What must not happen is any read on the app's own schedule.
++ expect(seen.map((r) => r.path)).toEqual([`/g/${OWN_ID}/relay/v1/models`])
++ expect(seen.some((r) => r.path.endsWith('/grid/overview') || r.path.endsWith('/nodes/discover'))).toBe(false)
+ })
+})
diff --cc cli/src/backendSocket.ts
index ca6b3288a,b8c32b1ee..ecd505207
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@@ -365,42 -365,15 +365,46 @@@ async function enrichSubagentStats(even
}
}
+/** What `grid_models_list` answers and `grid_models_changed` pushes — one shape, so a window parses both
+ * with one reader. `gridName` and `models` keep naming the own grid alone, for an app that predates
+ * `grids`; each section's `state`, `seenAt` and `lastKnownAge` are additive. */
+function gridModelsPayload(gridName: string | null, grids: GridSection[]): Record<string, unknown> {
+ return {
+ gridName,
+ models: grids.find((g) => g.own)?.models ?? [],
+ grids,
+ // Which engines a Local model can be offered to at all. Static per CLI version — it is
+ // the set of launch contracts in `gridLaunch.ts` — and answered here, beside the list,
+ // so the picker can say "Cursor runs only on its own login" instead of offering a row
+ // whose retarget the daemon would refuse. An older app ignores the field; an older
+ // daemon omits it, which the app reads as "offer everything", as before.
+ localModelEngines: gridCapableEngines(),
+ supportsModelLaunch: true,
+ // Whether this MACHINE has a `grid` to run at all — `managed`, `path` or `missing` —
+ // as distinct from `gridName`, which is about the account. The Local model dialog was
+ // gating on the account alone and starting an agent whose second step is `grid`; this
+ // is what lets it, and the picker, say so first. An older app ignores the field.
+ gridCli: gridCliPresence(),
+ }
+}
+
export class BackendSocket {
private readonly gridFleet = new GridFleetRpc()
+ // The Model Manager reads the grid it runs on through the same credential-less reader as every picker
+ // (never `grid engines`, which carries the grid credential and so wakes a sleeping grid on every tick),
+ // and a start or stop it finishes makes every list read again — pushed to the window when it changes.
private readonly localModels = new LocalModels({
stateDir: join(env.ADAPTER_DATA_DIR, 'local-models'),
+ machineName: () => this.machineDisplayName,
+ inventory: gridInventory,
+ onChanged: () => { forgetGridModels(); void this.pushGridModels() },
})
+ /** This machine's name as Harness shows it (Machines), from the backend's `machine_meta`. Null
+ * until the first one arrives. */
+ private machineDisplayName: string | null = null
+ /** A read the window did not ask for changed what a picker would show: tell the window
+ * (`grid_models_changed`), so its one picture stays current without polling. */
+ private readonly stopGridModelsPush = onGridModelsChanged(() => { void this.pushGridModels() })
private readonly apiConnections = new ApiConnections(env.ADAPTER_DATA_DIR)
private ws: WebSocket | null = null
private connecting = false
diff --cc cli/src/lib/gridModels.ts
index c280d289f,8449a852a..3e4b52bab
--- a/cli/src/lib/gridModels.ts
+++ b/cli/src/lib/gridModels.ts
@@@ -1,40 -1,24 +1,41 @@@
/**
- * What the account's private harness grid can answer right now.
+ * What the grids this computer is signed into can answer — read WITHOUT waking any of them.
*
- * One `grid models --json <grid>` away, so this module is a shape and a filter rather than a
- * protocol. It exists because two things have to be decided in one place: which rows are offered to
- * a person, and what an agent is told to ask for.
+ * Every picker, the Models panel and the macOS Models menu ask here, and until issue 02 of
+ * grid-reads-without-waking each ask was a `grid models` spawn plus a SIGNED-IN read of the relay's
+ * model list. On the platform a signed-in read of a sleeping grid wakes it, so an open app kept every
+ * grid of the account awake all day — and the read that woke one usually came back empty. Now:
+ *
+ * - each grid is read through `gridReader.ts`, with no credential: an awake grid answers as before, a
+ * sleeping one says so at once (with the platform's record of what it served) and is not started;
+ * - what was read is kept as a PICTURE per grid (`gridPicture.ts`, persisted), so an answer is given at
+ * once and a sleeping grid shows its last known models instead of vanishing;
+ * - the account's OWN grid, whose status the owner can read, is read at most once per asleep episode.
+ *
+ * The credentialed model-list read is gone from every automatic path. What still wakes a grid is a
+ * person's act, and it does not go through here.
*/
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { env as config } from '../config/env.js'
+import { gridCredentialsPath } from './gridCredentials.js'
+import { signedInGridEmail } from './gridDerive.js'
import { gridExec, gridJson } from './gridExec.js'
+ import { contextWindowHint } from './gridLaunch.js'
import { resolveGridMcpUrl } from './gridMcpUrl.js'
-
-/** A row of `grid models --json`. `node` names the machine serving it — on a private grid, one of
- * the user's own. */
-interface GridModelRow {
- model?: unknown
- engine?: unknown
- node?: unknown
-}
+import {
+ emptyPicture, mergeAwake, idKey, parsePicture, provenStopped, sectionView, servedKey, unspelled, withAsleep,
+ withSpellings, withUnknown, type GridPicture, type LocalRecord, type PictureState, type SectionView, type ServedHere,
+} from './gridPicture.js'
+import {
+ OWNER_ASLEEP_STATUS, readBase, readDiscoveryIds, readGridInfo, readOverview, readViaCli, type GridInfo, type GridRead,
+ type ReadNode,
+} from './gridReader.js'
+import { readRunRecords } from './localModels.js'
export interface GridModel {
- /** The id an engine is pointed at, verbatim from the grid. */
+ /** The id an engine is pointed at, in the exact case the grid serves it. */
id: string
/** Which machine answers it, or empty when the grid does not say. Display only. */
node: string
@@@ -48,409 -92,98 +49,443 @@@ export interface GridSection
type: string
/** True for the account's private grid — the picker labels that one "Local". */
own: boolean
+ /** Its models: live while it is awake, the last known ones while it is not — never blanked. */
models: GridModel[]
+ /** Additive (an older app ignores these three): what the last read said, when the grid was last seen
+ * awake, and how old the list above is. */
+ state?: PictureState
+ seenAt?: string | null
+ lastKnownAge?: number | null
}
-/**
- * Every grid this computer is signed into, each with its live models, own grid first.
- *
- * The picker used to ask only the private grid ("models my machines serve"). A person in a
- * shared grid (a team's, a company's) has models there they can switch an agent to just the
- * same, and had to leave the app to find out. So all of them, in sections, the private one first
- * and marked so the app can call it Local. Listed concurrently: each grid costs a `grid models`
- * spawn and a relay round trip, and three of them one after another was the whole of what a
- * person waited through. A grid that fails to answer is an empty section, not a missing one.
- */
-export async function listAllGridModels(ownGridName: string | null): Promise<GridSection[]> {
- const { value: rows } = await gridJson<Array<{ grid?: unknown; type?: unknown }>>(['--remote', 'ls'])
- if (!Array.isArray(rows)) {
- return ownGridName ? [{ name: ownGridName, type: 'permissioned-public', own: true, models: await listGridModels(ownGridName) }] : []
- }
- const grids = rows
- .filter((row): row is { grid: string; type?: unknown } => typeof row.grid === 'string' && row.grid.trim().length > 0)
- .map((row) => ({ name: row.grid.trim(), type: typeof row.type === 'string' ? row.type : '' }))
- const sections = await Promise.all(grids.map(async (grid) => ({
- name: grid.name,
- type: grid.type,
- own: grid.name === ownGridName,
- models: await listGridModels(grid.name),
- })))
- sections.sort((a, b) => Number(b.own) - Number(a.own))
- return sections
+/** What the Model Manager is told about the grid it runs on (`localModels.ts`'s `GridInventory`). */
+export interface GridInventoryAnswer {
+ state: PictureState
+ nodes: Record<string, unknown>[]
++ /** The owner status as last read (memoised, never asked per tick); null when it could not be read. */
++ status: string | null
+}
+
+/** How long one read's answer stands before the next is made: the list is live while a grid is awake,
+ * and a sleeping grid changes only when something wakes it. A failure is retried sooner than sleep. */
+const AWAKE_MEMO_MS = 15_000
+const ASLEEP_MEMO_MS = 120_000
+const FAILED_MEMO_MS = 30_000
+
+/** `grid info` is a control-plane call: a member's grid address barely moves; the OWNER's status is the
+ * thing that says a grid fell asleep or woke, so it is asked more often, and less often while asleep. */
+const ADDRESS_MEMO_MS = 10 * 60_000
+const OWN_STATUS_AWAKE_MEMO_MS = 15_000
+const OWN_STATUS_ASLEEP_MEMO_MS = 60_000
+
+/** Several changes landing together (three grids refreshed at once) are one push, not three. */
+const CHANGE_COALESCE_MS = 250
+
+/** How long an ask waits for the FIRST read of a grid this daemon has never seen before answering with
+ * what it has. Kept well inside the app's 12s `grid_models_list` timeout, which the grid-name wait
+ * (`GRID_ATTACH_WAIT_MS`, 6s) shares: a read slower than this lands behind the answer and is pushed. */
+const FIRST_READ_WAIT_MS = 4_000
+
+interface GridRow { name: string; type: string; id: string }
+
+/** The key a grid is tracked under when `grid ls` gave it no network id — its name, marked as such, so
+ * it can never collide with an id and never names a run-record directory. */
+const NAME_ONLY_PREFIX = 'name:'
+const nameOnlyRow = (name: string, type = ''): GridRow => ({ name, type, id: `${NAME_ONLY_PREFIX}${name}` })
+
+/** Everything this daemon holds about one grid, keyed by its network id. */
+interface Tracked {
+ id: string
+ /** The name `grid` knows it by — what goes into `grid info <name>` and the fallback's argv. */
+ name: string
+ /** The account's own grid. A property of the GRID, learnt from whoever last knew (the model list,
+ * the Model Manager), so an asker that does not know — a launch check — never changes how it is read. */
+ own: boolean
+ picture: GridPicture
+ loaded: boolean
+ /** Whether a picture existed before this process read anything (on disk, or read since). */
+ known: boolean
+ /** The picture as last written, so a read that changed nothing writes nothing. */
+ saved: string
+ readAt: number | null
+ readTtl: number
+ info: { at: number; value: GridInfo | null } | null
+ /** The own grid's one read of its current asleep episode has been made. */
+ episodeRead: boolean
+ /** What this daemon has watched a live run record serve here since the last awake read. */
+ seen: Set<string>
+ /** Ids discovery has already been asked to spell, so an id no provider spells is asked about once. */
+ spelled: Set<string>
+ /** The last awake overview's own node objects, for the Model Manager. Not persisted. */
+ rawNodes: Record<string, unknown>[]
+ pending: Promise<void> | null
+}
+
+export interface GridModelsDeps {
+ now: () => number
+ /** Where pictures are kept (`<data dir>/grid-pictures`). */
+ dataDir: () => string
+ /** `~/.grid`, whose `run/engines/<grid id>/` holds this computer's run records. */
+ gridHome: () => string
+ /** The signed-in account — a node published under it is the account's own. */
+ email: () => string | null
+ /** [FIRST_READ_WAIT_MS], injectable so a test need not wait it out. */
+ firstReadWaitMs: number
+}
+
+const defaultDeps: GridModelsDeps = {
+ now: () => Date.now(),
+ dataDir: () => config.ADAPTER_DATA_DIR,
+ gridHome: () => dirname(gridCredentialsPath()),
+ email: () => signedInGridEmail(),
+ firstReadWaitMs: FIRST_READ_WAIT_MS,
}
/**
- * The last answer for a grid, for a few seconds.
- *
- * The picker asks on every open, and the answer costs two subprocess spawns and two network round
- * trips — measured at ~1.4s, which is a person watching a header do nothing after a click. Reopening
- * a menu twice in a row should not pay that twice.
+ * The pictures, the reads that keep them current, and the answers built from them.
*
- * Short on purpose. The list is genuinely live — an engine can join or leave between two opens — so
- * this is only the window in which a click is free, not a cache in the sense of holding state. Longer
- * would start offering models nobody is serving, which is the failure the no-caching rule existed to
- * avoid.
+ * Nothing here runs on a timer: a grid is read only when something asks about it and its last answer
+ * has aged past its memo. So an app nobody looks at costs nothing, and an app somebody looks at costs a
+ * credential-less read every 15s at most per grid — and never a wake.
*/
-const TTL_MS = 15_000
-const memo = new Map<string, { at: number; models: GridModel[] }>()
+export class GridModelsService {
+ private readonly deps: GridModelsDeps
+ private readonly tracked = new Map<string, Tracked>()
+ private readonly listeners = new Set<() => void>()
+ private rows: GridRow[] | null = null
+ private changeTimer: NodeJS.Timeout | null = null
+
+ constructor(deps: Partial<GridModelsDeps> = {}) {
+ this.deps = { ...defaultDeps, ...deps }
+ }
+
+ /** Called (coalesced) whenever a read changed what a picker would be told. */
+ onChange(listener: () => void): () => void {
+ this.listeners.add(listener)
+ return () => { this.listeners.delete(listener) }
+ }
+
+ /** Resolves once every read already started has landed — for a test, and for a caller that must see
+ * the answer a read it triggered produced. */
+ async settled(): Promise<void> {
+ await Promise.all([...this.tracked.values()].map((tracked) => tracked.pending?.catch(() => {})))
+ }
+
+ /** Every read is due again — for a caller that has just changed what a grid serves, or which grid is
+ * whose. The pictures stay: they are what is shown until the next read lands. */
+ forget(): void {
+ for (const tracked of this.tracked.values()) {
+ tracked.readAt = null
+ tracked.info = null
+ }
+ this.rows = null
+ }
+
+ /**
+ * Every grid this computer is signed into, own grid first, each with its models.
+ *
+ * Answered from the pictures at once. A grid whose answer has aged is read again in the background —
+ * one read per grid at a time — and a change is announced through [onChange]. Only a grid this daemon
+ * has never seen is waited for, and only for [FIRST_READ_WAIT_MS]: an answer made of nothing is worse
+ * than a short wait, and a timed-out ask is worse than both.
+ */
+ async sections(ownGridName: string | null, opts: { refresh?: boolean } = {}): Promise<GridSection[]> {
+ const rows = await this.gridRows(ownGridName)
+ const sections = await Promise.all(rows.map(async (row) => {
+ const tracked = await this.track(row, row.name === ownGridName)
+ if (opts.refresh !== false && this.due(tracked)) {
+ const refreshing = this.refresh(tracked)
+ if (!tracked.known) await this.within(refreshing, this.deps.firstReadWaitMs)
+ else void refreshing.catch(() => {})
+ }
+ return { name: row.name, type: row.type, own: tracked.own, ...await this.view(tracked) }
+ }))
+ sections.sort((a, b) => Number(b.own) - Number(a.own))
+ return sections
+ }
+
+ /** One grid's models, read now if its answer has aged — for a launch that must not start on a model
+ * nobody serves. Still never a waking read: a sleeping grid answers with what it last served. */
+ async models(gridName: string): Promise<GridModel[]> {
+ const tracked = await this.track(await this.rowFor(gridName))
+ if (this.due(tracked)) await this.refresh(tracked)
+ return (await this.view(tracked)).models
+ }
+
+ /** What the Model Manager needs to tell a running model from a stopped one, on the account's own grid. */
+ async inventory(gridName: string, force: boolean): Promise<GridInventoryAnswer> {
+ const tracked = await this.track(await this.rowFor(gridName), true)
+ if (force) tracked.readAt = null
+ if (this.due(tracked)) await this.refresh(tracked)
- return { state: tracked.picture.state, nodes: tracked.picture.state === 'awake' ? tracked.rawNodes : [] }
++ return {
++ state: tracked.picture.state,
++ nodes: tracked.picture.state === 'awake' ? tracked.rawNodes : [],
++ status: tracked.info?.value?.status ?? null,
++ }
+ }
-function cached(gridName: string): GridModel[] | null {
- const hit = memo.get(gridName)
- return hit && Date.now() - hit.at < TTL_MS ? hit.models : null
+ private async rowFor(gridName: string): Promise<GridRow> {
+ return (await this.gridRows(null)).find((row) => row.name === gridName) ?? nameOnlyRow(gridName)
+ }
+
+ /** `grid ls --json` — a LOCAL registry read, no network. The last good answer stands in for a failed
+ * one; with none, the own grid alone, as before this module knew about shared grids. */
+ private async gridRows(ownGridName: string | null): Promise<GridRow[]> {
+ const { value } = await gridJson<Array<{ grid?: unknown; type?: unknown; id?: unknown }>>(['--remote', 'ls'])
+ if (Array.isArray(value)) {
+ this.rows = value
+ // A name goes into a `grid` argv (`info <grid>`, the fallback's `models <grid>`): one that reads
+ // as a flag, or carries a control character, is not one this daemon will pass along.
+ .filter((row) => typeof row?.grid === 'string' && /^[^-\x00-\x1f\x7f][^\x00-\x1f\x7f]*$/.test(row.grid.trim()))
+ .map((row) => {
+ const name = (row.grid as string).trim()
+ const type = typeof row.type === 'string' ? row.type : ''
+ return typeof row.id === 'string' && row.id.trim() ? { name, type, id: row.id.trim() } : nameOnlyRow(name, type)
+ })
+ }
+ if (this.rows) return this.rows
+ return ownGridName ? [nameOnlyRow(ownGridName, 'permissioned-public')] : []
+ }
+
+ /** The grid behind `row`, loaded from disk the first time. `own`, when the caller knows it, is recorded. */
+ private async track(row: GridRow, own?: boolean): Promise<Tracked> {
+ let tracked = this.tracked.get(row.id)
+ if (!tracked) {
+ tracked = {
+ id: row.id, name: row.name, own: false, picture: emptyPicture(), loaded: false, known: false, saved: '',
+ readAt: null, readTtl: 0, info: null, episodeRead: false, seen: new Set(), spelled: new Set(), rawNodes: [],
+ pending: null,
+ }
+ this.tracked.set(row.id, tracked)
+ }
+ tracked.name = row.name
+ if (own !== undefined) tracked.own = own
+ if (!tracked.loaded) {
+ tracked.loaded = true
+ await this.load(tracked)
+ }
+ return tracked
+ }
+
+ /** `work`, or nothing more than `ms` of it — what it produces meanwhile lands on its own. */
+ private async within(work: Promise<void>, ms: number): Promise<void> {
+ let timer: NodeJS.Timeout | undefined
+ await Promise.race([work.catch(() => {}), new Promise<void>((resolve) => { timer = setTimeout(resolve, ms) })])
+ clearTimeout(timer)
+ }
+
+ private due(tracked: Tracked): boolean {
+ const now = this.deps.now()
+ if (tracked.readAt === null || now - tracked.readAt >= tracked.readTtl) return true
+ // The owner's status is what says the own grid fell asleep or woke; it is checked on its own clock.
+ return tracked.own && (tracked.info === null || now - tracked.info.at >= this.statusTtl(tracked))
+ }
+
+ private statusTtl(tracked: Tracked): number {
+ if (!tracked.own) return ADDRESS_MEMO_MS
+ return tracked.info?.value?.status === OWNER_ASLEEP_STATUS ? OWN_STATUS_ASLEEP_MEMO_MS : OWN_STATUS_AWAKE_MEMO_MS
+ }
+
+ /** One refresh per grid at a time; every asker shares it. */
+ private refresh(tracked: Tracked): Promise<void> {
+ tracked.pending ??= this.read(tracked).finally(() => { tracked.pending = null })
+ return tracked.pending
+ }
+
+ private async read(tracked: Tracked): Promise<void> {
+ const before = JSON.stringify(await this.signature(tracked))
+ const info = await this.info(tracked)
+ const asleepByStatus = tracked.own && info?.status === OWNER_ASLEEP_STATUS
+ // The own grid, while its status says asleep, is read exactly once per asleep episode — to fetch the
+ // platform's record of what it served — and then left alone until the status changes.
+ if (asleepByStatus && tracked.episodeRead) {
+ await this.apply(tracked, { kind: 'asleep', lastKnown: null }, null)
+ } else {
+ tracked.episodeRead = asleepByStatus
+ const base = readBase(info?.gridUrl ?? null)
+ let read: GridRead = base ? await readOverview(base) : { kind: 'unreachable' }
+ // Only when nothing answered at all — never to second-guess an answer the grid gave.
+ if (read.kind === 'unreachable') read = await readViaCli(tracked.name)
+ await this.apply(tracked, read, base)
+ }
+ await this.save(tracked)
+ tracked.known = true
+ if (JSON.stringify(await this.signature(tracked)) !== before) this.changed()
+ }
+
+ private async info(tracked: Tracked): Promise<GridInfo | null> {
+ const now = this.deps.now()
+ if (tracked.info && now - tracked.info.at < this.statusTtl(tracked)) return tracked.info.value
+ // A failed ask keeps the last answer (the address is still the address), and is not re-asked at once.
+ const value = await readGridInfo(tracked.name) ?? tracked.info?.value ?? null
+ tracked.info = { at: now, value }
+ if (value?.status !== OWNER_ASLEEP_STATUS) tracked.episodeRead = false
+ return value
+ }
+
+ private async apply(tracked: Tracked, read: GridRead, base: string | null): Promise<void> {
+ const now = this.deps.now()
+ tracked.readAt = now
+ if (read.kind === 'asleep') {
+ tracked.picture = withAsleep(tracked.picture, read.lastKnown, now)
+ tracked.readTtl = ASLEEP_MEMO_MS
+ return
+ }
+ if (read.kind !== 'awake') {
+ tracked.picture = withUnknown(tracked.picture)
+ tracked.readTtl = FAILED_MEMO_MS
+ return
+ }
+ const here = await this.servedHere(tracked)
+ const email = this.deps.email()?.trim().toLowerCase() ?? ''
+ const isMine = (node: ReadNode): boolean => !!email && node.providerEmail?.trim().toLowerCase() === email
+ const previous = tracked.picture
+ let picture = mergeAwake(previous, read.nodes, now, isMine, (name, key) => provenStopped(previous, here, name, key))
+ picture = { ...picture, caseMap: withSpellings(picture.caseMap, [...read.curatedIds, ...here.records.flatMap((r) => r.ids)]) }
+ const unknownIds = unspelled(picture, read.nodes).filter((key) => !tracked.spelled.has(key))
+ if (unknownIds.length && base) {
+ unknownIds.forEach((key) => tracked.spelled.add(key))
+ picture = { ...picture, caseMap: withSpellings(picture.caseMap, await readDiscoveryIds(base)) }
+ }
+ tracked.picture = picture
+ tracked.rawNodes = read.rawNodes
+ tracked.readTtl = AWAKE_MEMO_MS
+ // What this computer serves is re-learnt from what is live now: the grid has just said what it serves.
+ tracked.seen = new Set(liveKeys(here.records))
+ }
+
+ /**
+ * This computer's own records for the grid, and what they have been seen serving. Deliberately updates
+ * `seen` on EVERY look, answers included: "seen served since the last awake read" is only true if each
+ * look that found a live record counted.
+ */
+ private async servedHere(tracked: Tracked): Promise<ServedHere> {
+ const records: LocalRecord[] = tracked.id.startsWith(NAME_ONLY_PREFIX) ? [] : await readRunRecords(this.deps.gridHome(), tracked.id)
+ for (const key of liveKeys(records)) tracked.seen.add(key)
+ return { records, seen: tracked.seen, own: tracked.own }
+ }
+
+ private async view(tracked: Tracked): Promise<Omit<SectionView, 'models'> & { models: GridModel[] }> {
+ return sectionView(tracked.picture, await this.servedHere(tracked), this.deps.now())
+ }
+
+ /** What a push is about: the rows and the state — not the ages, which move every second. */
+ private async signature(tracked: Tracked): Promise<unknown> {
+ const view = await this.view(tracked)
+ return { models: view.models, state: view.state }
+ }
+
+ private changed(): void {
+ if (this.changeTimer) return
+ this.changeTimer = setTimeout(() => {
+ this.changeTimer = null
+ for (const listener of this.listeners) {
+ try { listener() } catch { /* a listener's failure is its own */ }
+ }
+ }, CHANGE_COALESCE_MS)
+ this.changeTimer.unref?.()
+ }
+
+ private file(tracked: Tracked): string {
+ const name = createHash('sha256').update(tracked.id).digest('hex').slice(0, 24)
+ return join(this.deps.dataDir(), 'grid-pictures', `${name}.json`)
+ }
+
+ private async load(tracked: Tracked): Promise<void> {
+ try {
+ const raw = JSON.parse(await readFile(this.file(tracked), 'utf8')) as { networkId?: unknown; picture?: unknown }
+ const picture = raw.networkId === tracked.id ? parsePicture(raw.picture) : null
+ if (!picture) return
+ tracked.picture = picture
+ tracked.known = true
+ tracked.saved = JSON.stringify(picture)
+ } catch { /* never read on this computer, or not a file this module wrote */ }
+ }
+
+ /** Owner-only, replaced atomically — a crash mid-write leaves the previous picture, never half of one. */
+ private async save(tracked: Tracked): Promise<void> {
+ const text = JSON.stringify(tracked.picture)
+ if (text === tracked.saved) return
+ try {
+ const file = this.file(tracked)
+ await mkdir(dirname(file), { recursive: true, mode: 0o700 })
+ const temp = `${file}.${randomUUID()}.tmp`
+ await writeFile(temp, JSON.stringify({ networkId: tracked.id, picture: tracked.picture }), { mode: 0o600 })
+ await rename(temp, file)
+ tracked.saved = text
+ } catch { /* the picture is still in memory; the next read tries again */ }
+ }
}
-function remember(gridName: string, models: GridModel[]): void {
- memo.set(gridName, { at: Date.now(), models })
+function liveKeys(records: readonly LocalRecord[]): string[] {
+ return records
+ .filter((record) => record.pid !== null && record.alive)
+ .flatMap((record) => record.ids.map((id) => servedKey(record.name, idKey(id))))
}
-/** Drop the memo — for a caller that has just changed what the grid serves. */
+/** The daemon's one service. Module-level like the memo it replaces, so every caller shares one picture. */
+let service = new GridModelsService()
+
+/** Live models on `gridName`, router excluded, as the picture has them after a read if one was due. */
+export async function listGridModels(gridName: string | null): Promise<GridModel[]> {
+ if (!gridName?.trim()) return []
+ return service.models(gridName.trim())
+}
+
+/** Every grid this computer is signed into, each with its models, own grid first. */
+export function listAllGridModels(ownGridName: string | null, opts: { refresh?: boolean } = {}): Promise<GridSection[]> {
+ return service.sections(ownGridName, opts)
+}
+
+/** The Model Manager's inventory of the own grid (`LocalModels`' injected `inventory`). */
+export function gridInventory(gridName: string, force: boolean): Promise<GridInventoryAnswer> {
+ return service.inventory(gridName, force)
+}
+
+/** Make every read due again — for a caller that has just changed what a grid serves. */
export function forgetGridModels(): void {
- memo.clear()
+ service.forget()
}
-/** Model ids exactly as the grid's relay serves them — the names an engine must send. Empty when the
- * relay cannot be asked, which the caller treats as "fall back", never as "no models". */
-async function relayModelIds(gridName: string): Promise<string[]> {
- const info = await gridExec(['--remote', 'info', gridName, '--env'])
- if (info.code !== 'OK') return []
- const env = readEnvExports(info.stdout)
- if (!env.baseUrl || !env.apiKey) return []
- return (await relayModels(env.baseUrl, env.apiKey)).map((m) => m.id)
+/** Be told (coalesced) when a background read changed what a picker would be told. */
+export function onGridModelsChanged(listener: () => void): () => void {
+ return service.onChange(listener)
+}
+
+/** For tests: a fresh service, optionally with its clock and places injected. */
+export function resetGridModels(deps: Partial<GridModelsDeps> = {}): GridModelsService {
+ service = new GridModelsService(deps)
+ return service
}
+ /** A row of the relay's `/models`: the id it routes, and the context window it reports for it. */
+ interface RelayModel { id: string; contextWindow?: number }
+
-/** The relay's own catalogue. Empty when it cannot be asked — callers read that as "fall back". */
++/**
++ * The relay's own catalogue. Empty when it cannot be asked — callers read that as "fall back".
++ *
++ * ⚠️ A SIGNED-IN read, so on a sleeping grid it WAKES it. Asked only by [resolveGridTarget], i.e. when
++ * a person moves an agent onto a model or starts one there — an act that needs the grid anyway. Never
++ * from the model list or any other read made on the app's own schedule (grid-reads-without-waking).
++ */
+ async function relayModels(baseUrl: string, apiKey: string): Promise<RelayModel[]> {
+ try {
+ const response = await fetch(`${baseUrl.replace(/\/$/, '')}/models`, {
+ headers: { authorization: `Bearer ${apiKey}` },
+ signal: AbortSignal.timeout(10_000),
+ })
+ if (!response.ok) return []
+ const body = await response.json() as { data?: Array<{ id?: unknown; context_window?: unknown }> }
+ return (body.data ?? []).flatMap((m) => {
+ if (typeof m.id !== 'string' || !m.id) return []
+ const contextWindow = contextWindowHint(m.context_window)
+ return [{ id: m.id, ...(contextWindow ? { contextWindow } : {}) }]
+ })
+ } catch {
+ return []
+ }
+ }
+
/** `grid info --env` prints shell exports; these are the two that matter. */
const ENV_LINE = /^export\s+(OPENAI_BASE_URL|OPENAI_API_KEY)=(.*)$/gm
diff --cc cli/src/lib/localModels.integration.spec.ts
index 0840f1c68,ac6487224..9d2b88805
--- a/cli/src/lib/localModels.integration.spec.ts
+++ b/cli/src/lib/localModels.integration.spec.ts
@@@ -58,11 -58,7 +59,11 @@@ else if (args.includes('info') && args.
else if (args.includes('info')) console.log("export OPENAI_BASE_URL='${base}/v1'\\nexport OPENAI_API_KEY='inference-fixture'");
else process.exitCode = 2;
`, { mode: 0o700 })
- const options = { stateDir, processEnv: { GRID_HOME: gridHome, HARNESS_GRID_BIN: executable, PATH: root } }
+ // The grid's own answer, as the credential-less reader would give it: the engine is listed while its
+ // run record exists (the fake's `join` writes it, `leave` removes it).
+ const record = join(gridHome, 'run', 'engines', 'fixture-grid', 'remote.json')
- const inventory = async () => ({ state: 'awake' as const, nodes: existsSync(record) ? [{ node_id: 'fixture-node', online: true, models: ['tiny'] }] : [] })
++ const inventory = async () => ({ state: 'awake' as const, status: 'running', nodes: existsSync(record) ? [{ node_id: 'fixture-node', online: true, models: ['tiny'] }] : [] })
+ const options = { stateDir, processEnv: { GRID_HOME: gridHome, HARNESS_GRID_BIN: executable, PATH: root }, inventory }
service = new LocalModels(options)
expect((await service.list('home')).models[0]).toMatchObject({ state: 'available', canStart: true })
expect(replies).toBe(0)
diff --cc cli/src/lib/localModels.spec.ts
index f4fc39091,495f39a78..82536de11
--- a/cli/src/lib/localModels.spec.ts
+++ b/cli/src/lib/localModels.spec.ts
@@@ -4,8 -4,7 +4,8 @@@ import { join } from 'node:path
import { tmpdir } from 'node:os'
import { createHash } from 'node:crypto'
import { rmSync, writeFileSync } from 'node:fs'
-import { compatibleModels, contextLadder, LocalModels } from './localModels.js'
+import { spawnSync } from 'node:child_process'
- import { compatibleModels, LocalModels, readRunRecords, type GridInventory } from './localModels.js'
++import { compatibleModels, contextLadder, LocalModels, readRunRecords, type GridInventory } from './localModels.js'
import { GridFleetRpc, type GridFleetResult } from './gridFleetRpc.js'
import { encryptDownFrame, encryptRpcResult } from './e2ee/applicationFrames.js'
@@@ -19,11 -18,16 +19,20 @@@ let calls: string[][], serving: boolean
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 the grid says it serves. Production reads it without a credential (`gridModels.gridInventory`);
- // here it is the scenario the fake `grid` below answers for `engines`, so each test keeps its meaning,
- // and `gridState` is what the grid's own answer said about it.
- let gridState: GridInventory['state']
+ /** 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')
@@@ -61,13 -72,7 +77,20 @@@
}
return response({ choices: [{ message: { content: 'ok' } }] })
})
- gridState = 'awake'
- inventory = vi.fn(async (grid: string) => {
- service = new LocalModels({ stateDir, processEnv: { GRID_HOME: home }, run, request: request as typeof fetch })
++ // 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) throw new Error('unreadable')
- return { state: gridState, nodes: gridState === 'awake' ? JSON.parse(answer.stdout) : [] }
++ 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 }) })
@@@ -187,10 -192,10 +210,10 @@@ describe('local model discovery and lif
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 })
+ 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.error).toContain('unavailable')
+ expect(snapshot.notice).toContain('unavailable')
expect(JSON.stringify(snapshot)).not.toContain('private raw')
})
@@@ -701,94 -772,178 +790,275 @@@
})
})
+/** 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.error).not.toBe('Running models could not be checked. Try again.')
++ 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 () => {
- gridState = 'unknown'
- expect((await service.list('home')).error).toBe('Running models could not be checked. Try again.')
++ 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')).error).toBe('Running models could not be checked. Try again.')
++ 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 })
++ 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 })
++ 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 ' })
++ 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 })
++ 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')
+ })
+ })
diff --cc cli/src/lib/localModels.ts
index ad56d5ebb,c1f633db9..78f6ffab2
--- a/cli/src/lib/localModels.ts
+++ b/cli/src/lib/localModels.ts
@@@ -39,25 -77,23 +81,35 @@@ export interface LocalModelsSnapshot
observedAt: string; busy: boolean
}
interface Candidate {
- id: string; name: string; pull: string; file: string; files: string[]; size: number; quant: string; context: number
+ id: string; name: string; pull: string; file: string; files: string[]; size: number; quant: string
+ /** The window to pin at start: the catalog's fit for this machine, which is the largest it can
+ * hold. Absent for a model found on disk, which the catalog never sized — the engine then measures
+ * free memory at load and takes the largest window that fits (`grid join` without `--ctx-size`). */
+ context?: number
aliases?: string[]
}
-interface Owned { file: string; selector: string; aliases: string[]; nodeId: string; name: string; live: boolean; siblings: number }
+/** `live`: its heartbeat sidecar is fresh (the grid is hearing from it). `pidAlive`: the process its run
+ * record names exists — the only liveness that holds while the grid sleeps and the sidecar goes stale. */
- interface Owned { file: string; selector: string; aliases: string[]; nodeId: string; name: string; live: boolean; pidAlive: boolean; context: number; siblings: number }
++interface Owned { file: string; selector: string; aliases: string[]; nodeId: string; name: string; live: boolean; pidAlive: boolean; siblings: number }
interface Receipt { spec: 1; grid: string; operation?: ModelOperation }
+/** What the grid says is running on it, read WITHOUT waking it (`gridModels.gridInventory`): the
- * overview's node objects while it is awake, nothing while it sleeps. */
- export interface GridInventory { state: PictureState; nodes: Record<string, unknown>[] }
++ * overview's node objects while it is awake, nothing while it sleeps — and its owner status (`running`,
++ * `stopped`, `asleep`; null for a member or when it could not be read), remembered rather than asked on
++ * every tick. */
++export interface GridInventory { state: PictureState; nodes: Record<string, unknown>[]; status: string | null }
interface Options {
stateDir: string; processEnv?: NodeJS.ProcessEnv
+ /** This machine's name as Harness shows it. Grid labels an engine with its `--name`, and without
+ * one it takes the host name — so a model started here read `mac.lan` under "On your machines"
+ * while Machines called the same computer `M2`. */
+ machineName?: () => string | null | undefined
run?: (args: string[], output?: (chunk: string) => void, timeout?: number) => Promise<GridFleetResult>
request?: typeof fetch
+ /** Injected, never a `grid engines` call: that read carries the grid credential, and a signed-in read
+ * of a sleeping grid WAKES it — once a tick, for as long as the panel is open. */
+ inventory: (grid: string, force: boolean) => Promise<GridInventory>
+ /** Told when a start or stop has finished, so the model lists are read again. */
+ onChanged?: () => void
}
/** One concrete, machine-fitted version per model. Non-chat and unprobed offline
@@@ -213,8 -255,7 +271,8 @@@ export class LocalModels
const advertised = Array.isArray(record.advertise_as) && specs.length === 1
? record.advertise_as.filter((v: unknown) => typeof v === 'string' && v.length > 0) : []
const aliases: string[] = advertised.length ? advertised : [file]
- result.push({ file: basename(file), selector: file, aliases, nodeId: str(record.node_id), name: str(record.meta_name), live, siblings: specs.length + (record.media ? 1 : 0) })
+ const pid = recordPid(record)
- result.push({ file: basename(file), selector: file, aliases, nodeId: str(record.node_id), name: str(record.meta_name), live, pidAlive: pid !== null && processExists(pid), context: Math.min(16384, num(record.ctx_size) || 8192), siblings: specs.length + (record.media ? 1 : 0) })
++ result.push({ file: basename(file), selector: file, aliases, nodeId: str(record.node_id), name: str(record.meta_name), live, pidAlive: pid !== null && processExists(pid), siblings: specs.length + (record.media ? 1 : 0) })
this.blockers.set(grid, `Stop ${cleanName(aliases[0])} first to start another local model.`)
}
}
@@@ -299,15 -405,9 +422,16 @@@
}
private async readList(grid: string, force: boolean): Promise<LocalModelsSnapshot> {
await Promise.all([this.loadCatalog(force), this.readReceipt(grid)])
- let owned: Owned[] = [], nodes: Record<string, any>[] = [], inventoryError: string | undefined
+ let owned: Owned[] = [], nodes: Record<string, any>[] = [], inventoryError: string | undefined, asleep = false
try {
- [owned, nodes] = await Promise.all([this.owned(grid), this.servingNodes(grid)])
+ let inventory: GridInventory
+ [owned, inventory] = await Promise.all([this.owned(grid), this.options.inventory(grid, force)])
- // Asleep is not an inventory error: the grid is resting, what runs here is still known here, and
- // Start and Pause stay enabled. Only a read that failed some other way is.
- if (inventory.state === 'unknown') throw new Error('unanswered')
- asleep = inventory.state !== 'awake'
- nodes = rows(inventory.nodes)
++ // A grid that is down — its owner status says stopped or asleep (DOWN) — runs nothing: an answer,
++ // not a gap, so Start stays enabled (and brings it back up). Asleep says so even to a member, in
++ // the grid's own answer. Only a read that failed some other way is "could not be checked".
++ if (inventory.state === 'unknown' && !DOWN.has(inventory.status ?? '')) throw new Error('unanswered')
++ asleep = inventory.state === 'asleep' || inventory.status === 'asleep'
++ nodes = inventory.state === 'awake' ? rows(inventory.nodes) : []
} catch { inventoryError = 'Running models could not be checked. Try again.' }
const operation = this.active?.grid === grid ? this.active.operation : this.receipt?.grid === grid ? this.receipt.operation : undefined
const choices = [...this.candidates, ...(await this.known(grid, owned)).filter(k => !this.candidates.some(c => c.file === k.file))]
@@@ -345,23 -441,42 +469,28 @@@
tokensPerSecond: single && running ? num(node?.throughput_tok_s) : undefined,
requests: running ? num(perModel?.requests) : undefined,
windowSeconds: running ? num(answered.window_seconds) : undefined,
- operation: operation?.modelId === candidate.id ? operation : undefined }
+ operation: operation?.modelId === candidate.id ? operation : undefined,
+ ...(!node && parked(instance) ? { gridAsleep: true } : {}) }
})
for (const instance of owned.filter(o => !choices.some(c => c.file === o.file))) {
+ const serving = !!servingNode(instance)
models.push({ id: `local:${instance.file}`, name: cleanName(instance.aliases[0]),
- state: servingNode(instance) ? 'running' : 'available', canStart: false, canStop: !inventoryError,
- operation: operation?.modelId === `local:${instance.file}` ? operation : undefined })
+ state: serving || parked(instance) ? 'running' : 'available', canStart: false, canStop: !inventoryError,
+ operation: operation?.modelId === `local:${instance.file}` ? operation : undefined,
+ ...(!serving && parked(instance) ? { gridAsleep: true } : {}) })
}
const value: LocalModelsSnapshot = { models, memoryBytes: num(obj(this.device.memory).total_gb) === undefined ? undefined : this.device.memory.total_gb * GiB,
- hardware: str(obj(this.device.machine).model || obj(this.device.cpu).brand), error: inventoryError || this.catalogError,
+ hardware: str(obj(this.device.machine).model || obj(this.device.cpu).brand), notice: inventoryError || this.catalogError,
observedAt: new Date().toISOString(), busy: !!this.active }
this.cached = { grid, at: Date.now(), value }
return value
}
+ /** What `grid info` says of [grid]: `running`, `stopped`, `asleep`. */
+ private async gridStatus(grid: string): Promise<string> {
+ return str(obj(await this.json(['--remote', 'info', grid, '--json'])).status)
+ }
+
- /** The nodes serving [grid] — none at all when the grid is down.
- *
- * ⚠️ A stopped or asleep grid REFUSES `engines` ("isn't up; run `grid start` first") rather than
- * answering an empty list, and reading that refusal as "unknown" disabled every Start in the
- * list: the one state in which a person most needs to start a model was the one in which none
- * could be. Stopping the last model from this list leaves the grid up, so it was only reached by
- * a grid taken down by hand or gone to sleep — but then there was no way back from here. A grid
- * that is down runs nothing, which is an answer, not a gap. Any other refusal still is one. */
- private async servingNodes(grid: string): Promise<Record<string, any>[]> {
- const result = await this.run(['--remote', 'engines', grid, '--json'])
- if (result.ok) {
- try { return rows(JSON.parse(result.stdout)) } catch { throw new Error('Running models could not be checked. Try again.') }
- }
- if (DOWN.has(await this.gridStatus(grid))) return []
- throw new Error('Running models could not be checked. Try again.')
- }
-
/** A repeated click or lost RPC acknowledgement joins the same operation.
* A different model waits: starts/stops must not race on the machine's budget. */
async act(grid: string | null, modelId: unknown, action: 'start' | 'stop'): Promise<{ operation?: ModelOperation; error?: string }> {
diff --cc desktop/lib/screens/swarm_screen.dart
index 5b1f57307,e70ba7a0e..f4dab3069
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@@ -267,13 -266,20 +266,24 @@@ class _SwarmScreenState extends State<S
app.agentUnread.addListener(_unreadChanged);
// Coming back to the window puts the tab in front of the person again, and
// nothing in the app necessarily changes when that happens — so it is told.
+ //
+ // The daemon is told too, on the way out as well as the way back: it decides
+ // from `app_panes` whether a finished turn is already on screen, and that
+ // roster does not change when the window slips behind a browser. Without
+ // the second half the dial went quiet the first time this window lost focus
+ // and stayed quiet until a pane happened to change.
_lifecycle = AppLifecycleListener(
- onResume: app.seeWatchedAgents,
+ onResume: () {
+ app.seeWatchedAgents();
+ app.announceWindowForeground();
+ },
+ onHide: app.announceWindowForeground,
+ onInactive: app.announceWindowForeground,
+ // Whether the app is in front of anyone decides whether the model surfaces refresh at all
+ // (`AppNotifier.foreground`): a minimised or background window asks no daemon anything.
+ onStateChange: app.appLifecycleChanged,
);
+ app.appLifecycleChanged(WidgetsBinding.instance.lifecycleState);
app.addListener(_syncToolbarNotices);
_toolbarNotices.addListener(_toolbarNoticesChanged);
_onboarding.addListener(_onboardingChanged);
diff --cc desktop/lib/widgets/grid_model_picker.dart
index 2f3b6f008,a5f7f9f0d..a94449d9a
--- a/desktop/lib/widgets/grid_model_picker.dart
+++ b/desktop/lib/widgets/grid_model_picker.dart
@@@ -94,21 -94,18 +94,27 @@@ class GridModelPicker extends StatefulW
class _GridModelPickerState extends State<GridModelPicker> {
bool _loading = false;
- ModelsMenuController? _usage;
+
+ /// The window's shared subscription readings — the same controller the Models panel draws,
+ /// so this row and that menu cannot disagree. Owned by the app, never disposed here.
+ late final ModelsMenuController _usage = widget.notifier.modelsMenu;
GridModels? _last;
+ /// Set when the control was built while the app was in the background: the warm-up it skipped is
+ /// owed, and paid once when the app comes back to the foreground.
+ bool _prefetchOwed = false;
+
@override
void initState() {
super.initState();
+ // The app's one picture of the grids, when some other surface has already read it — or the
+ // daemon has pushed it — is a warm answer for this control's first click.
+ _last = widget.notifier.gridPictures[widget.machineId];
+ widget.notifier.gridPictures.addListener(_pictureChanged);
+ widget.notifier.foreground.addListener(_foregroundChanged);
+ // A reading that lands while the menu is open redraws its Subscription row, rather than
+ // leaving "Checking usage…" there until the next open.
+ _usage.addListener(_redrawOpenMenu);
// Warm the answer as soon as the control exists, so a click lands on a memo rather than on two
// subprocess spawns and two network round trips — measured at ~1.4s, which is a person watching
// a header do nothing. Fire-and-forget: nothing here waits on it, and a failure just means the
@@@ -141,14 -117,9 +147,10 @@@
// Not under `flutter test`: a refresh reads the Keychain and asks the vendors, the same reads the
// usage rail keeps out of tests (kUnderTest) — here every test that drew a pane header left that
// work's timers pending after the tree was gone. Opening the menu still refreshes.
- if (!kUnderTest) unawaited(_usage!.refresh().catchError((_) {}));
+ if (!kUnderTest) unawaited(_usage.refresh().catchError((_) {}));
- final answer = await widget.notifier.gridModels(widget.machineId);
- if (mounted) _last = answer;
+ _prefetchOwed = false;
+ final picture = await widget.notifier.readGridPicture(widget.machineId);
+ if (mounted) _last = picture;
}
/// Closes the menu this control has open, if any. Set while one is showing.
@@@ -301,8 -260,8 +296,8 @@@
// read to draw a list it already has is a menu that feels broken whenever that source is slow.
// This open uses whatever is cached; the refresh lands for the next one. `refresh()` is itself
// capped at once a minute, so opening the menu repeatedly costs nothing.
- unawaited(_usage!.refresh().catchError((_) {}));
+ unawaited(_usage.refresh().catchError((_) {}));
- answer = await widget.notifier.gridModels(widget.machineId);
+ answer = await widget.notifier.readGridPicture(widget.machineId);
} finally {
if (mounted) setState(() => _loading = false);
}
diff --cc desktop/test/grid_picture_test.dart
index f16ddbdc1,000000000..807b39c98
mode 100644,000000..100644
--- a/desktop/test/grid_picture_test.dart
+++ b/desktop/test/grid_picture_test.dart
@@@ -1,508 -1,0 +1,340 @@@
- // The app-level picture of what the account's grids serve, and the three surfaces that refresh it
- // (the Model Manager, the macOS Models menu, the pane picker) keeping quiet while the app is in the
- // background. grid-reads-without-waking issue 02, desktop half.
++// The app-level picture of what the account's grids serve, and the surfaces that refresh it (the Model
++// Manager, the pane picker) keeping quiet while the app is in the background. (The macOS Models menu
++// this also covered was removed on main in #303 — Models opens from the View menu now.)
++// grid-reads-without-waking issue 02, desktop half.
+import 'dart:async';
+
+import 'package:flutter/material.dart';
- import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/models/model_manager_controller.dart';
- import 'package:harness/screens/swarm_screen.dart';
+import 'package:harness/state/app_state.dart';
- import 'package:harness/state/swarm_catalog.dart';
- import 'package:harness/usage/models_menu_controller.dart';
- import 'package:harness/usage/usage_controller.dart';
+import 'package:harness/widgets/grid_model_picker.dart';
+import 'package:harness/ws/ws_conn.dart';
+
+import 'support/model_manager.dart';
+import 'swarm_state_test.dart' show MemoryStore, createApp;
+
+/// A daemon that answers `grid_models_list` from [reply] and counts every time it is asked.
+class _Daemon extends WsConn {
+ _Daemon(this.reply)
+ : super(
+ wsBaseUrl: 'ws://fixture.invalid',
+ autonomousEnv: 'test',
+ machineId: 'm',
+ accessTokenProvider: (_, _) async => '',
+ onAuthFailure: (_) {},
+ onEvent: (_) {},
+ onStatus: (_) {},
+ );
+
+ Map<String, dynamic> reply;
+ int asked = 0;
+
+ /// When set, the next `grid_models_list` waits on it — so a test can land a push while a read is
+ /// still out.
+ Completer<void>? hold;
+
+ @override
+ Future<Map<String, dynamic>> request(
+ String type, {
+ Map<String, dynamic> payload = const {},
+ Duration timeout = const Duration(seconds: 20),
+ }) async {
+ if (type != 'grid_models_list') return {};
+ asked++;
+ final held = hold;
+ if (held != null) {
+ hold = null;
+ final answer = reply;
+ await held.future;
+ return answer;
+ }
+ return reply;
+ }
+}
+
+Map<String, dynamic> _reply({
+ String state = 'awake',
+ String node = 'macbook',
+ List<String> ids = const ['Qwen3.5-4B'],
+ bool withNewFields = true,
+}) => {
+ 'gridName': 'home',
+ 'models': [
+ for (final id in ids) {'id': id, 'node': node},
+ ],
+ 'grids': [
+ {
+ 'name': 'home',
+ 'type': 'permissioned-public',
+ 'own': true,
+ 'models': [
+ for (final id in ids) {'id': id, 'node': node},
+ ],
+ if (withNewFields) ...{
+ 'state': state,
+ 'seenAt': '2026-09-24T08:00:00.000Z',
+ 'lastKnownAge': 42,
+ },
+ },
+ ],
+ 'supportsModelLaunch': true,
+};
+
+void main() {
+ TestWidgetsFlutterBinding.ensureInitialized();
+
+ group('GridModels.fromReply', () {
+ test('reads the three optional fields a newer daemon adds', () {
+ final answer = GridModels.fromReply(_reply(state: 'asleep'));
+ final section = answer.sections.single;
+ expect(section.state, GridSectionState.asleep);
+ expect(section.seenAt, DateTime.utc(2026, 9, 24, 8));
+ expect(section.lastKnownAge, 42);
+ // The sleeping section keeps its last known models — never blanked.
+ expect(section.models.single.id, 'Qwen3.5-4B');
+ });
+
+ test('an older daemon that sends none of them reads exactly as before', () {
+ final answer = GridModels.fromReply(_reply(withNewFields: false));
+ final section = answer.sections.single;
+ expect(section.state, isNull);
+ expect(section.seenAt, isNull);
+ expect(section.lastKnownAge, isNull);
+ expect(section.name, 'home');
+ expect(section.own, isTrue);
+ expect(section.models.single.node, 'macbook');
+ expect(section.models.single.grid, 'home');
+ expect(answer.models.single.id, 'Qwen3.5-4B');
+ expect(answer.reachable, isTrue);
+ expect(answer.supportsModelLaunch, isTrue);
+ });
+
+ test('a state it does not know, a negative age and a bad time are no claim at all', () {
+ final raw = _reply();
+ final grid = (raw['grids'] as List).single as Map<String, dynamic>;
+ grid['state'] = 'hibernating';
+ grid['lastKnownAge'] = -5;
+ grid['seenAt'] = 'yesterday';
+ final section = GridModels.fromReply(raw).sections.single;
+ expect(section.state, isNull);
+ expect(section.lastKnownAge, isNull);
+ expect(section.seenAt, isNull);
+ });
+ });
+
+ group('the app-level picture', () {
+ late _Daemon daemon;
+ late AppNotifier app;
+ setUp(() {
+ daemon = _Daemon(_reply());
+ app = createApp(connectionForTest: (_) => daemon);
+ });
+ tearDown(() => app.dispose());
+
+ test('a grid_models_changed push replaces it with no request', () async {
+ expect(app.gridPictures['m'], isNull);
+ await app.handleEventForTest('m', {
+ 'type': 'grid_models_changed',
+ 'payload': _reply(state: 'asleep', node: 'studio'),
+ });
+ final picture = app.gridPictures['m']!;
+ expect(picture.sections.single.state, GridSectionState.asleep);
+ expect(picture.sections.single.models.single.node, 'studio');
+ expect(daemon.asked, 0);
+ });
+
+ test(
+ 'every read feeds it, and reads that overlap are one request',
+ () async {
+ final first = app.refreshGridModels('m');
+ final second = app.refreshGridModels('m');
+ expect(identical(await first, await second), isTrue);
+ expect(daemon.asked, 1);
+ expect(
+ app.gridPictures['m']!.sections.single.state,
+ GridSectionState.awake,
+ );
+ },
+ );
+
+ test(
+ 'a read that was out when a push landed does not overwrite the push',
+ () async {
+ final hold = daemon.hold = Completer<void>();
+ final read = app.refreshGridModels('m');
+ await app.handleEventForTest('m', {
+ 'type': 'grid_models_changed',
+ 'payload': _reply(state: 'asleep'),
+ });
+ hold.complete();
+ await read;
+ expect(
+ app.gridPictures['m']!.sections.single.state,
+ GridSectionState.asleep,
+ );
+ },
+ );
+
+ test(
+ 'a read that could not reach the machine keeps the last good picture for every surface',
+ () async {
+ await app.refreshGridModels('m');
+ daemon.reply = {'error': 'GRID_MODELS_FAILED'};
+
+ // The caller that must know (the creation check) still hears that the machine did not answer…
+ expect((await app.refreshGridModels('m')).reachable, isFalse);
+ // …while the picture every other surface shows stays the last list it had.
+ final picture = await app.readGridPicture('m');
+ expect(picture.reachable, isTrue);
+ expect(picture.sections.single.models.single.id, 'Qwen3.5-4B');
+ expect(app.gridPictures['m']!.reachable, isTrue);
+ },
+ );
+
+ test('the foreground flag follows the lifecycle, unknown counting as foreground', () {
+ expect(app.inForeground, isTrue);
+ app.appLifecycleChanged(AppLifecycleState.inactive);
+ expect(app.inForeground, isFalse);
+ app.appLifecycleChanged(AppLifecycleState.hidden);
+ expect(app.inForeground, isFalse);
+ app.appLifecycleChanged(AppLifecycleState.resumed);
+ expect(app.inForeground, isTrue);
+ app.appLifecycleChanged(null);
+ expect(app.inForeground, isTrue);
+ });
+ });
+
+ group('the Model Manager timer', () {
+ late ModelManagerTestApp app;
+ setUp(() => app = ModelManagerTestApp(ModelManagerConnection()));
+ tearDown(() => app.dispose());
+
+ // Each test owns its controller and disposes it before the test ends: its 4 s timer is a fake
+ // timer inside `testWidgets`, and one left running fails the test.
+ ModelManagerController manager() =>
+ ModelManagerController(app, storage: MemoryStore())
+ // The visible panel is the tick that reads every 4 s whatever the clock says — the idle
+ // 60 s read compares `DateTime.now()`, which fake time does not move.
+ ..setPanelVisible(true);
+
+ testWidgets(
+ 'a background app runs none of it, and one refresh runs on return',
+ (tester) async {
+ final controller = manager();
+ app.appLifecycleChanged(AppLifecycleState.hidden);
+ controller.start();
+ await tester.pump();
+ for (var i = 0; i < 30; i++) {
+ await tester.pump(const Duration(seconds: 4));
+ }
+ expect(app.localReads, 0);
+ expect(app.gridReads, 0);
+
+ app.appLifecycleChanged(AppLifecycleState.resumed);
+ await tester.pump();
+ expect(app.localReads, 1);
+ expect(app.gridReads, 1);
+ controller.dispose();
+ await tester.pump(const Duration(seconds: 10));
+ },
+ );
+
+ testWidgets('in the foreground it reads as it always did', (tester) async {
+ final controller = manager();
+ controller.start();
+ await tester.pump();
+ final first = app.localReads;
+ expect(first, 1);
+ await tester.pump(const Duration(seconds: 4));
+ expect(app.localReads, 2);
+ controller.dispose();
+ await tester.pump(const Duration(seconds: 10));
+ });
+
+ testWidgets('a push reaches the manager with no read of its own', (
+ tester,
+ ) async {
+ final controller = manager();
+ controller.start();
+ await tester.pump();
+ final reads = app.gridReads;
+ await app.handleEventForTest('m', {
+ 'type': 'grid_models_changed',
+ 'payload': _reply(ids: ['Pushed-Model']),
+ });
+ expect(controller.sections.single.models.single.id, 'Pushed-Model');
+ expect(app.gridReads, reads);
+ controller.dispose();
+ await tester.pump(const Duration(seconds: 10));
+ });
+ });
+
+ group('the pane picker prefetch', () {
+ late _Daemon daemon;
+ late AppNotifier app;
+ setUp(() {
+ daemon = _Daemon(_reply());
+ app = createApp(connectionForTest: (_) => daemon);
+ });
+ tearDown(() => app.dispose());
+
+ Future<void> mount(WidgetTester tester) => tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: Center(
+ child: GridModelPicker(
+ notifier: app,
+ machineId: 'm',
+ engineLabel: 'claude',
+ ),
+ ),
+ ),
+ ),
+ );
+
+ testWidgets('does not run in the background, and runs once on return', (
+ tester,
+ ) async {
+ app.appLifecycleChanged(AppLifecycleState.inactive);
+ await mount(tester);
+ await tester.pump();
+ expect(daemon.asked, 0);
+ app.appLifecycleChanged(AppLifecycleState.resumed);
+ await tester.pump();
+ expect(daemon.asked, 1);
+ app.appLifecycleChanged(AppLifecycleState.inactive);
+ app.appLifecycleChanged(AppLifecycleState.resumed);
+ await tester.pump();
+ // A picker that is already warm owes nothing on a second return.
+ expect(daemon.asked, 1);
+ });
+
+ testWidgets('in the foreground it warms as it always did', (tester) async {
+ await mount(tester);
+ await tester.pump();
+ expect(daemon.asked, 1);
+ });
+
+ testWidgets('a push lands in the open menu with no request', (
+ tester,
+ ) async {
+ tester.view.physicalSize = const Size(1200, 900);
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.reset);
+ await mount(tester);
+ await tester.tap(find.byType(GridModelPicker));
+ await tester.pumpAndSettle();
+ expect(find.text('Qwen3.5-4B'), findsOneWidget);
+ final asked = daemon.asked;
+ await app.handleEventForTest('m', {
+ 'type': 'grid_models_changed',
+ 'payload': _reply(ids: ['Pushed-Model']),
+ });
+ await tester.pumpAndSettle();
+ expect(find.text('Pushed-Model'), findsOneWidget);
+ expect(daemon.asked, asked);
+ });
+ });
-
- group('the macOS Models menu', () {
- const channel = MethodChannel('harness/swarm_tabs');
- late _Daemon daemon;
- late AppNotifier app;
- late List<MethodCall> messages;
- late ModelsMenuController menu;
- late UsageController usage;
- late SwarmProjectStore projects;
-
- setUp(() {
- daemon = _Daemon(_reply());
- app = createApp(connectionForTest: (_) => daemon);
- usage = UsageController(sources: const [], autoStart: false);
- menu = ModelsMenuController(usage: usage);
- projects = SwarmProjectStore();
- });
- tearDown(() {
- menu.dispose();
- usage.dispose();
- app.dispose();
- projects.dispose();
- });
-
- Future<void> mount(WidgetTester tester) async {
- final messenger = tester.binding.defaultBinaryMessenger;
- messages = <MethodCall>[];
- messenger.setMockMethodCallHandler(channel, (call) async {
- messages.add(call);
- return true;
- });
- addTearDown(() => messenger.setMockMethodCallHandler(channel, null));
- await tester.pumpWidget(
- MaterialApp(
- home: SwarmScreen(
- notifier: app,
- nativeTabs: true,
- projectStore: projects,
- modelsMenu: menu,
- ),
- ),
- );
- await tester.pump();
- }
-
- Future<void> native(WidgetTester tester, String method) async {
- final reply = Completer<void>();
- tester.binding.defaultBinaryMessenger.handlePlatformMessage(
- channel.name,
- const StandardMethodCodec().encodeMethodCall(MethodCall(method)),
- (_) => reply.complete(),
- );
- await reply.future;
- await tester.pump();
- }
-
- List<Map<Object?, Object?>> lastSections() =>
- ((messages.lastWhere((c) => c.method == 'modelsState').arguments
- as Map)['sections']
- as List)
- .cast<Map<Object?, Object?>>();
-
- testWidgets(
- 'does not refresh in the background, and refreshes once on return',
- (tester) async {
- tester.binding.handleAppLifecycleStateChanged(
- AppLifecycleState.inactive,
- );
- addTearDown(
- () => tester.binding.handleAppLifecycleStateChanged(
- AppLifecycleState.resumed,
- ),
- );
- await mount(tester);
- // Every app change asks the menu to refresh; in the background none of them may.
- for (var i = 0; i < 5; i++) {
- app.notifyListeners();
- await tester.pump(const Duration(seconds: 15));
- }
- expect(daemon.asked, 0);
- tester.binding.handleAppLifecycleStateChanged(
- AppLifecycleState.resumed,
- );
- await tester.pump();
- expect(daemon.asked, 1);
- await tester.pumpWidget(const SizedBox());
- },
- );
-
- testWidgets('refreshes when it opens, inside the ten-second throttle', (
- tester,
- ) async {
- await mount(tester);
- final before = daemon.asked;
- expect(before, 1);
- await native(tester, 'modelsOpened');
- expect(daemon.asked, before + 1);
- await tester.pumpWidget(const SizedBox());
- });
-
- testWidgets('opening it refreshes even when the window reads as inactive', (
- tester,
- ) async {
- await mount(tester);
- final before = daemon.asked;
- tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive);
- addTearDown(
- () => tester.binding.handleAppLifecycleStateChanged(
- AppLifecycleState.resumed,
- ),
- );
- await tester.pump();
- await native(tester, 'modelsOpened');
- expect(daemon.asked, before + 1);
- await tester.pumpWidget(const SizedBox());
- });
-
- testWidgets('updates when only a node changed', (tester) async {
- await mount(tester);
- expect(lastSections().single['models'], [
- {'id': 'Qwen3.5-4B', 'node': 'macbook'},
- ]);
- daemon.reply = _reply(node: 'studio');
- await native(tester, 'modelsOpened');
- expect(lastSections().single['models'], [
- {'id': 'Qwen3.5-4B', 'node': 'studio'},
- ]);
- await tester.pumpWidget(const SizedBox());
- });
-
- testWidgets('updates when only the state changed', (tester) async {
- await mount(tester);
- expect(lastSections().single['state'], 'awake');
- daemon.reply = _reply(state: 'asleep');
- await native(tester, 'modelsOpened');
- expect(lastSections().single['state'], 'asleep');
- await tester.pumpWidget(const SizedBox());
- });
-
- testWidgets('a push updates it with no request', (tester) async {
- await mount(tester);
- final asked = daemon.asked;
- await app.handleEventForTest('m', {
- 'type': 'grid_models_changed',
- 'payload': _reply(ids: ['Pushed-Model']),
- });
- await tester.pump();
- expect((lastSections().single['models'] as List).single, {
- 'id': 'Pushed-Model',
- 'node': 'macbook',
- });
- expect(daemon.asked, asked);
- await tester.pumpWidget(const SizedBox());
- });
-
- testWidgets('an older daemon sends no state, and the menu says none', (
- tester,
- ) async {
- daemon.reply = _reply(withNewFields: false);
- await mount(tester);
- expect(lastSections().single.containsKey('state'), isFalse);
- await tester.pumpWidget(const SizedBox());
- });
- });
+}