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.

Grid harness: close the gaps a plain-language test run found

Tim96b1f8419936
diff --git a/store/agents/autonomous-grid/AGENTS.md b/store/agents/autonomous-grid/AGENTS.md
index ba92c40b3..dfa0286db 100644
--- a/store/agents/autonomous-grid/AGENTS.md
+++ b/store/agents/autonomous-grid/AGENTS.md
@@ -22,14 +22,18 @@ different says so, and that one thing changes.
**Ask through a tool, not prose.** Every "ask" means the question tool with real options — the
model shortlist when they ask for other options, every go-ahead before a slow step. A question mark in a
-paragraph is not a stop. **Talk the way Harness talks:** short, declarative, second person; say what
+paragraph is not a stop. When no question tool is offered (some modes have none [run]), a download, a
+copy, a replacement or a restart of what is serving is asked in one short message with numbered
+options, and the turn **ends there** until the person answers.
+**Talk the way Harness talks:** short, declarative, second person; say what
is true and what happens next; no "I'd be happy to", no exclamation marks; a thing that is not set
up is said plainly and stopped at, the way a failed build is reported.
**Starting a model on this computer — the whole flow.** Do it in this order; open a skill only when a
step names one. The commands below are verified: run them as written, without reading `--help` first —
each extra step costs a minute. Technical choices (file, engine, context, port, flags) are yours, from
-measurements; the person is asked only what the model is for, and about trade-offs they can feel. When
+measurements, and so is what the model is for — a coding agent unless the person says otherwise; they
+are asked only about trade-offs they can feel (a download, a copy, replacing what runs). When
the person names an engine, that engine is the plan: if it has no suitable model, ask one question —
*Use <file on disk> with Grid's engine now · Get a model for <engine> (N GB download)* — never switch
engines silently.
@@ -38,10 +42,13 @@ engines silently.
active, engines installed, what it can run, ports in use), memory and swap now, engines already
answering with their `--at` URL, grids this computer is joined to (`joined`), and one row per model file on disk of every format (size, context,
cache at 64K, tool calls, vision, which engines read it). Read the table; do not filter it yourself.
- Drop `--summary` for the full JSON only when a field you need is not in the table. A request that
- does not say what the model is for ("I have some models, can we run one?") gets the purpose question
- right after this table — question tool, before reading any skill: a person waited 6 minutes for
- one [run]. Everything this flow needs is on this page; open a skill only where a step names it.
+ Drop `--summary` for the full JSON only when a field you need is not in the table. The table is
+ checked: a model folder without "download unfinished" has every weight file on disk, sizes are the
+ real files' — never re-check with `du`, `find` or `ls` [run: a hand check read the cache's links and
+ dropped a complete model]. A request that does not say what the model is for ("I have some models,
+ can we run one?") goes straight on from this table — pick, start, and say what you picked; a person
+ waited 6 minutes while an agent read skills first [run]. Everything this flow needs is on this page;
+ open a skill only where a step names it.
2. Which grid: "on this computer only", "not online", "just here" → a **local grid** (below); otherwise
the one the person named, else `personalGrid` (never a shared grid unasked — below). `"$GRID_FLEET" run -- models GRID --json` — already served
there? Then no start. This computer already joined to it = the `joined` line of step 1, never the
@@ -58,9 +65,11 @@ engines silently.
engines already answering that belong to a `joined` grid are not free to reuse; MLX folder → `skills/engine-mlx-lm`; safetensors on an NVIDIA/AMD box →
`skills/engine-vllm` or `engine-sglang`; Ollama or LM Studio → their `skills/engine-*`.
5. GGUF start: `"$GRID_FLEET" link FILE NAME.gguf` (Grid serves only from `~/.grid/models`; a link, no copy), then
- `"$GRID_FLEET" run --thinking off -- join GRID --serve NAME.gguf --advertise-as ALIAS --name MACHINE-ALIAS
+ `"$GRID_FLEET" run --thinking off -- join GRID --serve NAME.gguf --advertise-as ALIAS
--ctx-size CTX --endpoint-port PORT --reasoning-budget 0` plus `--max-concurrency 1` on a remote grid or
`--parallel 1` on a local one (`--max-concurrency` is remote-only), PORT not in `listeningPorts`.
+ Never pass `--name`: the runner sets it on every join to the machine's name as Harness shows it
+ [run: an agent's own `--name` once listed a Mac as a model].
6. `"$GRID_FLEET" verify --at http://127.0.0.1:PORT/v1 --model ALIAS --kind llama.cpp --grid GRID --alias ALIAS`
— `--alias` is the `--advertise-as` name; `--model` is what the engine itself lists. Run it right after
the start, without `| tail` or `| head` — it waits by itself and narrates; pass its progress on. Every
@@ -75,7 +84,7 @@ engines silently.
`"$GRID_FLEET" link --machine M FILE NAME.gguf` — it prints `NOT READY` when that machine lacks Grid's
engine: ask, then `"$GRID_FLEET" run --machine M -- engine install llama.cpp` before any join (without it
the join still says "starting" and the engine dies at once) —, then
-`"$GRID_FLEET" run --machine M --thinking off -- join GRID --serve NAME.gguf --advertise-as ALIAS --name M
+`"$GRID_FLEET" run --machine M --thinking off -- join GRID --serve NAME.gguf --advertise-as ALIAS
--ctx-size CTX --max-concurrency 1 --reasoning-budget 0`, where ALIAS is a name no other machine serves on
that grid (`run -- models GRID --json`) — a shared name cannot show which machine answered — and then
`"$GRID_FLEET" verify --grid GRID --alias ALIAS` (through the relay only).
diff --git a/store/agents/autonomous-grid/lib/inventory.mjs b/store/agents/autonomous-grid/lib/inventory.mjs
index e984909df..a2475af0d 100644
--- a/store/agents/autonomous-grid/lib/inventory.mjs
+++ b/store/agents/autonomous-grid/lib/inventory.mjs
@@ -155,7 +155,9 @@ async function walk(dir, depth, visit, budget) {
if (depth < 0 || budget.dirs-- <= 0) return;
let entries;
try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
- if (entries.some(e => e.name === 'config.json') && entries.some(e => e.name.endsWith('.safetensors'))) await visit('folder', dir);
+ // A weight index with no weights yet is a download that started, which the table must show.
+ if (entries.some(e => e.name === 'config.json')
+ && entries.some(e => e.name.endsWith('.safetensors') || e.name === 'model.safetensors.index.json')) await visit('folder', dir);
for (const entry of entries) {
const path = join(dir, entry.name);
if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name) && entry.name !== 'blobs') await walk(path, depth - 1, visit, budget); }
@@ -198,14 +200,27 @@ function hubName(path) {
async function describeFolder(dir) {
const config = JSON.parse(await readFile(join(dir, 'config.json'), 'utf8'));
- let bytes = 0;
- for (const name of await readdir(dir)) if (name.endsWith('.safetensors')) bytes += (await stat(join(dir, name))).size;
+ // Complete = every weight file the folder names is really there. `stat` follows the Hugging Face
+ // cache's links to the real blobs, so a link whose blob never arrived counts as missing. Said here so
+ // an agent never re-checks by hand — one did, measured the links instead of the blobs, and wrongly
+ // decided a complete model was not on disk [run].
+ const present = new Map();
+ for (const name of await readdir(dir)) {
+ if (!name.endsWith('.safetensors')) continue;
+ const size = (await stat(join(dir, name)).catch(() => null))?.size;
+ if (size) present.set(name, size);
+ }
+ const index = await readFile(join(dir, 'model.safetensors.index.json'), 'utf8').then(JSON.parse).catch(() => null);
+ const expected = index?.weight_map ? [...new Set(Object.values(index.weight_map))] : [...present.keys()];
+ const missingFiles = expected.filter(name => !present.has(name)).length;
+ const bytes = [...present.values()].reduce((sum, size) => sum + size, 0);
const mlx = Boolean(config.quantization?.bits) || /mlx/i.test(dir);
const template = await readFile(join(dir, 'chat_template.jinja'), 'utf8')
.catch(async () => JSON.parse(await readFile(join(dir, 'tokenizer_config.json'), 'utf8')).chat_template ?? '')
.catch(() => '');
return {
format: mlx ? 'mlx' : 'safetensors', bytes,
+ complete: expected.length > 0 && missingFiles === 0, missingFiles, weightFiles: expected.length,
config: {
architecture: config.architectures?.[0] ?? config.model_type ?? null,
contextLength: config.max_position_embeddings ?? config.text_config?.max_position_embeddings ?? null,
@@ -229,7 +244,7 @@ export async function scanModels({ roots = defaultRoots(), minBytes = 50 * 1024
try {
if (found.kind === 'folder') {
Object.assign(entry, await describeFolder(realPath));
- if (entry.bytes < minBytes) return;
+ if (entry.bytes < minBytes && !entry.missingFiles) return; // a small folder is noise; a started download is news
} else {
if (info.size < minBytes) return;
const header = await readGguf(realPath);
@@ -553,7 +568,9 @@ export function summarize({ machine, engines, models, joined = [] }, contextToke
const note = [runnable ? '' : `no engine this machine can run reads ${m.format}${m.format === 'mlx' ? ' (Apple silicon only)' : ''}`,
mlxCopy ? `an MLX copy is on disk (${mlxCopy}): serve that one on this Mac unless vision is needed` : '',
m.gguf?.unsupportedTensorTypes?.length ? `llama.cpp cannot load (tensor type ${m.gguf.unsupportedTensorTypes.join(', ')})` : '',
- facts.contextLength && facts.contextLength < contextTokens ? `context ${facts.contextLength} < ${contextTokens}` : '', m.error ?? ''].filter(Boolean).join('; ');
+ facts.contextLength && facts.contextLength < contextTokens ? `context ${facts.contextLength} < ${contextTokens}` : '',
+ m.missingFiles ? `download unfinished: ${m.missingFiles} of ${m.weightFiles} weight files missing` : '',
+ m.error ?? ''].filter(Boolean).join('; ');
lines.push([
m.format.padEnd(11), gb(m.bytes).padStart(8), String(facts.contextLength ?? '—').padStart(8),
(kv ? gb(kv * contextTokens) : '—').padStart(10), String(facts.toolCalls ?? '?').padEnd(5), (m.projector ? 'yes' : 'no').padEnd(6),
diff --git a/store/agents/autonomous-grid/skills/engine-lm-studio/SKILL.md b/store/agents/autonomous-grid/skills/engine-lm-studio/SKILL.md
index 66581a59e..1573d098c 100644
--- a/store/agents/autonomous-grid/skills/engine-lm-studio/SKILL.md
+++ b/store/agents/autonomous-grid/skills/engine-lm-studio/SKILL.md
@@ -70,7 +70,7 @@ serve the file with Grid's engine instead.
## Join Harness Compute
- "$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <id> --advertise-as ALIAS --name NAME
+ "$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <id> --advertise-as ALIAS
`/v1` is required: with the bare root, Grid's capability probe records structured output as unsupported [run].
Grid's own detector finds LM Studio only on 1234 [run].
@@ -103,3 +103,5 @@ Grid's own detector finds LM Studio only on 1234 [run].
| `lms get … -y` shows a spinner forever | it downloads in the background [run]; never start a download without the go-ahead |
| a foreign GGUF must appear in LM Studio | `lms import -l -y --user-repo <user>/<repo> FILE.gguf`: **without `-l` it moves the file** [doc]; the file name must end in `.gguf` and the link must point at the real file, not a temp copy [run] |
| 401 from `/v1/models` | authentication is on in the person's settings [doc]; do not turn it off |
+| a model already on disk is not in `lms ls` | no download: an **MLX folder** is symlinked as `~/.lmstudio/models/<publisher>/<name>` → the folder, then `lms ls` lists it [run]; a **GGUF** goes in with `lms import -l` (row above). Neither copies |
+| answers come back as reasoning only; no request switch turns thinking off | some models keep thinking under LM Studio whatever the request says [run]. That is not a failure: `fleet verify` asks once more with room to think and passes, noting it. Never hand-test switches with `curl` (it cost minutes [run]); tell the person replies will be slower, and offer a model that can switch it off if they want that |
diff --git a/store/agents/autonomous-grid/skills/engine-mlx-lm/SKILL.md b/store/agents/autonomous-grid/skills/engine-mlx-lm/SKILL.md
index b497a721e..2937ed536 100644
--- a/store/agents/autonomous-grid/skills/engine-mlx-lm/SKILL.md
+++ b/store/agents/autonomous-grid/skills/engine-mlx-lm/SKILL.md
@@ -79,7 +79,7 @@ Run `"$GRID_FLEET" verify --at http://127.0.0.1:P/v1 --model <path or id> --kind
## Join Harness Compute
- "$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <path or id you started with> --advertise-as ALIAS --name NAME
+ "$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <path or id you started with> --advertise-as ALIAS
`/v1` is required: `/models` without it answers 404 (only chat accepts both) [doc][run]. Without
`--advertise-as` the picker shows the whole snapshot path, and `verify --alias` waits five minutes for a
diff --git a/store/agents/autonomous-grid/skills/engine-ollama/SKILL.md b/store/agents/autonomous-grid/skills/engine-ollama/SKILL.md
index 32a7fbfcb..8768209c8 100644
--- a/store/agents/autonomous-grid/skills/engine-ollama/SKILL.md
+++ b/store/agents/autonomous-grid/skills/engine-ollama/SKILL.md
@@ -18,13 +18,18 @@ Tags: `[doc]` official page above, `[run]` seen on the tested machine, `[?]` unv
- **Ollama is already answering** (`fleet models` lists `kind: ollama`): adopt it as it is; it is the
person's app, so never restart or reconfigure it without asking.
-- **Ollama is installed but stopped, or its settings do not fit the job**: do not start it. Its models
- are GGUF files that Grid's engine serves in place — link the blob into `~/.grid/models` and
- `join --serve` [run]. That also gives the context you choose instead of Ollama's default.
-- Start Ollama yourself only when Grid's engine refuses a blob Ollama runs (Ollama ships its own engine
- for some new architectures [?]); then use the start below.
-- Never `ollama create` to reuse a file from another app: it copies the whole file into Ollama's blobs
- (+624 MB for a 640 MB GGUF) [run]. Never `ollama pull` without the person's go-ahead: it downloads.
+- **The person asked for Ollama and it is not running**: start it yourself (below) — it is theirs to
+ want, and an engine that is off is the normal case, not a reason to switch [run].
+- **Ollama is stopped and nobody asked for it**: leave it off. Its models are GGUF files that Grid's
+ engine serves in place — link the blob into `~/.grid/models` and `join --serve` [run], with the
+ context you choose instead of Ollama's default.
+- Start Ollama unasked only when Grid's engine refuses a blob Ollama runs (Ollama ships its own engine
+ for some new architectures [?]).
+- A GGUF from another app enters Ollama only by `ollama create` (a `Modelfile` with `FROM <file>`), and
+ that **copies the whole file** into Ollama's store (+624 MB for a 640 MB GGUF) [run]. So never do it
+ unasked; when the person wants Ollama and it has nothing suitable, offer it with the size it adds on
+ disk, beside the no-copy choice (the same file on Grid's engine). Never `ollama pull` without the
+ go-ahead: it downloads.
## MLX inside Ollama (Apple silicon)
@@ -86,7 +91,7 @@ Then `GET /api/ps` must show the model with `context_length` ≥ 65536 [doc]; le
## Join Harness Compute
- "$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <model>:<tag> --advertise-as ALIAS --name NAME
+ "$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <model>:<tag> --advertise-as ALIAS
`/v1` is required: without it `/models` and `/chat/completions` answer 404, and Grid's capability probe
records JSON output as unsupported without any error [run]. Grid's own detector finds Ollama only on
diff --git a/store/agents/autonomous-grid/skills/engine-sglang/SKILL.md b/store/agents/autonomous-grid/skills/engine-sglang/SKILL.md
index e8f42ff19..311fc9821 100644
--- a/store/agents/autonomous-grid/skills/engine-sglang/SKILL.md
+++ b/store/agents/autonomous-grid/skills/engine-sglang/SKILL.md
@@ -77,7 +77,7 @@ returns (log `run/sglang-P.log`).
- Verify: `"$GRID_FLEET" verify --at http://127.0.0.1:P/v1 --model <id> --kind sglang` (bounded, narrated).
- Ready: the log says `The server is fired up and ready to roll!` [doc]; `GET /health` → 200;
`GET /health_generate` generates one token [doc]; `GET /v1/models` lists `<id>`; one bounded answer; one tool call.
-- Join: `"$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <id> --advertise-as ALIAS --name NAME`. Grid's detector has
+- Join: `"$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <id> --advertise-as ALIAS`. Grid's detector has
no SGLang probe and would mislabel it on 8000 or 8080 [run], so always `--at`, always with `/v1`.
- Thinking off per request: `"chat_template_kwargs": {"enable_thinking": false}` where the cookbook page shows it [doc].
diff --git a/store/agents/autonomous-grid/skills/engine-vllm/SKILL.md b/store/agents/autonomous-grid/skills/engine-vllm/SKILL.md
index 7968bdb49..df8a1150d 100644
--- a/store/agents/autonomous-grid/skills/engine-vllm/SKILL.md
+++ b/store/agents/autonomous-grid/skills/engine-vllm/SKILL.md
@@ -88,7 +88,7 @@ returns; log `run/vllm-P.log`.)
- Verify: `"$GRID_FLEET" verify --at http://127.0.0.1:P/v1 --model <id> --kind vllm` (bounded, narrated).
- Ready: PID alive; log shows `Application startup complete.` [run] (minutes for a big model); `GET /health`
→ 200 and `GET /v1/models` lists `<id>` [run]; one bounded answer; one tool call.
-- Join: `"$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <id> --advertise-as ALIAS --name NAME`. `/v1` is required —
+- Join: `"$GRID_FLEET" run -- join GRID --at http://127.0.0.1:P/v1 -m <id> --advertise-as ALIAS`. `/v1` is required —
without it `/models` and `/chat/completions` answer 404 [run]. `--api-key` guards only `/v1` routes [doc].
- Thinking off for everyday use: the recipe's guide names the flag when there is one
(`--default-chat-template-kwargs '{"enable_thinking": false}'` in the recipes that document it [doc]).
diff --git a/store/agents/autonomous-grid/test/inventory.test.mjs b/store/agents/autonomous-grid/test/inventory.test.mjs
index 457d018f8..d1a02973c 100644
--- a/store/agents/autonomous-grid/test/inventory.test.mjs
+++ b/store/agents/autonomous-grid/test/inventory.test.mjs
@@ -88,6 +88,30 @@ test('scan finds models other apps downloaded, names them, and reports one entry
assert.equal(byName.plain.format, 'safetensors');
assert.ok(byName.plain.readableBy.includes('vllm'));
assert.ok(byName['qwen2.5-0.5b'].readableBy.includes('llama.cpp'));
+ assert.equal(byName['mlx-community/Tiny-4bit'].complete, true);
+});
+
+test('a model folder says whether every weight file is really there, following the cache links to the blobs', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'home-'));
+ const hub = join(home, '.cache', 'huggingface', 'hub');
+ const done = join(hub, 'models--org--Done-4bit', 'snapshots', 'a');
+ await put(join(hub, 'models--org--Done-4bit', 'blobs', 'b1'), 'weights-1');
+ await put(join(done, 'config.json'), JSON.stringify({ quantization: { bits: 4 } }));
+ await put(join(done, 'model.safetensors.index.json'), JSON.stringify({ weight_map: { a: 'model-1.safetensors' } }));
+ await symlink(join(hub, 'models--org--Done-4bit', 'blobs', 'b1'), join(done, 'model-1.safetensors'));
+ const half = join(hub, 'models--org--Half-4bit', 'snapshots', 'a');
+ await put(join(half, 'config.json'), JSON.stringify({ quantization: { bits: 4 } }));
+ await put(join(half, 'model.safetensors.index.json'), JSON.stringify({ weight_map: { a: 'model-1.safetensors', b: 'model-2.safetensors' } }));
+ await put(join(half, 'model-1.safetensors'), 'weights-1');
+ await symlink(join(hub, 'models--org--Half-4bit', 'blobs', 'never-arrived'), join(half, 'model-2.safetensors'));
+
+ const { models } = await scanModels({ roots: [{ source: 'huggingface', path: hub }], minBytes: 1024 });
+ const byName = Object.fromEntries(models.map(model => [model.name, model]));
+ assert.equal(byName['org/Done-4bit'], undefined, 'a complete folder below the size floor is still noise');
+ assert.equal(byName['org/Half-4bit'].complete, false);
+ assert.equal(byName['org/Half-4bit'].missingFiles, 1, 'a link whose blob never arrived is missing');
+ const text = summarize({ machine: { platform: 'darwin', arch: 'arm64', accelerators: [], engines: [], canRun: ['mlx-lm'], listeningPorts: [] }, engines: [], models });
+ assert.match(text, /org\/Half-4bit .*download unfinished: 1 of 2 weight files missing/);
});
test('the summary table lists every model of every format, with the reasons one cannot be used', () => {