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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.mdindex 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 — themodel 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 whatis true and what happens next; no "I'd be happy to", no exclamation marks; a thing that is not setup 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 astep 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). Whenthe 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 switchengines silently.@@ -38,10 +42,13 @@ engines silently.active, engines installed, what it can run, ports in use), memory and swap now, engines alreadyanswering 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); otherwisethe one the person named, else `personalGrid` (never a shared grid unasked — below). `"$GRID_FLEET" run -- models GRID --json` — already servedthere? 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 afterthe 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'sengine: ask, then `"$GRID_FLEET" run --machine M -- engine install llama.cpp` before any join (without itthe 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 onthat 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.mjsindex 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 * 1024try {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 = [] }, contextTokeconst 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.mdindex 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.mdindex 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 adiff --git a/store/agents/autonomous-grid/skills/engine-ollama/SKILL.md b/store/agents/autonomous-grid/skills/engine-ollama/SKILL.mdindex 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 theperson'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 proberecords JSON output as unsupported without any error [run]. Grid's own detector finds Ollama only ondiff --git a/store/agents/autonomous-grid/skills/engine-sglang/SKILL.md b/store/agents/autonomous-grid/skills/engine-sglang/SKILL.mdindex 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 hasno 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.mdindex 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.mjsindex 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 entryassert.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', () => {