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
/**
* `ensureHarnessGrid` against a fake `grid` first on PATH — the same seam `gridCommand.spec.ts`
* uses, for the same reason: the real binary talks to a control plane, and the questions worth
* asking here are all about which argv this module sends and what it believes about the answer.
*/
import { afterEach, describe, expect, it } from 'vitest'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { installFakeGrid, type FakeGrid, type FakeGridPlan, type FakeGridTurn as Turn } from './__fixtures__/fakeGrid.js'
let fake: FakeGrid | null = null
afterEach(() => {
fake?.dispose()
fake = null
// One test below points HARNESS_GRID_BIN at nothing by hand, with no fake to dispose of.
delete process.env.HARNESS_GRID_BIN
})
/** The fake `grid` from `__fixtures__/fakeGrid.ts`, remembered so `afterEach` can dispose of it. */
function fakeGrid(plan: FakeGridPlan): FakeGrid {
fake = installFakeGrid(plan)
return fake
}
const VERSION_OK: Turn = { stdout: 'grid 0.3.46\n' }
const rows = (...names: string[]): string =>
JSON.stringify(names.map((n) => ({ grid: n, type: 'permissioned-public', id: `grid-${n}` })))
/** Every wait a retry asked for, in order — the retries never really sleep in a test. */
let slept: number[] = []
async function ensure(name = 'someone-7f3a91c4') {
const { ensureHarnessGrid } = await import('./gridEnsure.js')
slept = []
return ensureHarnessGrid(name, { sleep: async (ms) => { slept.push(ms) } })
}
/** What the public CLI prints for a control-plane refusal — `remote/control_plane._raise`, whose format
* is a contract there (`cli/auth._SESSION_EXPIRED_RE` anchors on it) — around grid-apis' 402 body. */
const QUOTA_MESSAGE = 'Free plan allows one network, and a network deleted in the last 30 days still counts. ' +
'You can create a new one from 2026-10-31 14:13 UTC, or upgrade to create one now'
const QUOTA_REFUSAL = 'POST https://api-grid.autonomous.ai/v1/grid/managed-networks failed (402): ' +
JSON.stringify({ detail: { error_code: 'free_network_limit', message: QUOTA_MESSAGE } }) + '\n'
describe('ensureHarnessGrid', () => {
it('creates the grid when the account has none, as a private permissioned-public one', async () => {
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: { stdout: rows('something-else') },
start: {},
})
expect(await ensure()).toEqual({ status: 'created', message: '' })
const start = fake.calls().find((c) => c.includes('start'))
// The type is the whole safety property: `permissioned-providers` would open the grid to
// strangers and switch billing on.
expect(start).toEqual(['--remote', 'start', 'someone-7f3a91c4', '--type', 'permissioned-public'])
})
it('syncs AGAIN after creating, so the new grid has its access token', async () => {
// A just-created grid has no per-grid token locally; `grid info --env` and `grid join` both
// refuse until a refresh. Measured against the real control plane.
const fake = fakeGrid({ version: VERSION_OK, sync: {}, ls: { stdout: rows() }, start: {} })
expect((await ensure()).status).toBe('created')
const verbs = fake.calls().map((c) => c.find((a) => a !== '--remote'))
expect(verbs.filter((v) => v === 'sync').length).toBe(2)
expect(verbs.lastIndexOf('sync')).toBeGreaterThan(verbs.indexOf('start'))
})
it('does nothing when the grid is already there', async () => {
const fake = fakeGrid({ version: VERSION_OK, sync: {}, ls: { stdout: rows('someone-7f3a91c4') } })
expect(await ensure()).toEqual({ status: 'existed', message: '' })
expect(fake.calls().some((c) => c.includes('start'))).toBe(false)
})
it('syncs BEFORE looking, so a grid another machine made is seen', async () => {
const fake = fakeGrid({ version: VERSION_OK, sync: {}, ls: { stdout: rows('someone-7f3a91c4') } })
await ensure()
const order = fake.calls().map((c) => c.find((a) => a !== '--remote'))
expect(order.indexOf('sync')).toBeLessThan(order.indexOf('ls'))
})
it('adopts rather than duplicating when another machine won the create race', async () => {
// The control plane rejects a duplicate name, and the refusal is prose — so this is resolved by
// looking again, not by reading the error.
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: [{ stdout: rows() }, { stdout: rows('someone-7f3a91c4') }],
start: { exit: 1, stderr: 'POST …/managed-networks failed (409): name already taken\n' },
})
expect(await ensure()).toEqual({ status: 'adopted', message: '' })
expect(fake.calls().filter((c) => c.includes('sync')).length).toBe(2)
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
})
it('reports grid’s own words when the create really failed', async () => {
fakeGrid({
version: VERSION_OK,
sync: {},
ls: { stdout: rows() },
start: { exit: 1, stderr: 'the control plane is unreachable\n' },
})
const result = await ensure()
expect(result.status).toBe('failed')
expect(result.message).toContain('control plane is unreachable')
})
it('looks once more after the last refusal, and uses a grid that is there', async () => {
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
// Before the create, then before each retry; there at the look after the third refusal.
ls: [{ stdout: rows() }, { stdout: rows() }, { stdout: rows() }, { stdout: rows('someone-7f3a91c4') }],
start: { exit: 1, stderr: 'POST …/managed-networks failed (503): {"detail":"The server is low on memory right now"}\n' },
})
expect(await ensure()).toEqual({ status: 'adopted', message: '' })
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(3)
})
it('retries a failed create with backoff before saying it failed', async () => {
// A create the control plane refused for a reason that can pass (the server low on memory, a restart)
// is asked again, waiting longer each time — no longer reported failed at the first refusal.
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: { stdout: rows() },
start: { exit: 1, stderr: 'POST …/managed-networks failed (503): {"detail":"The server is low on memory right now"}\n' },
})
const result = await ensure()
expect(result.status).toBe('failed')
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(3)
expect(slept).toEqual([2_000, 5_000])
})
it('creates the grid when a retry succeeds', async () => {
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: { stdout: rows() },
start: [{ exit: 1, stderr: 'POST …/managed-networks failed (503): {"detail":"The server is low on memory right now"}\n' }, {}],
})
expect(await ensure()).toEqual({ status: 'created', message: '' })
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(2)
expect(slept).toEqual([2_000])
})
it('shows the Free plan’s refusal instead of retrying it', async () => {
// A 402 `free_network_limit` is the owner's plan, not a bad minute: asking again cannot succeed, so
// it is never retried, and the person reads the control plane's own sentence — which says when a new
// grid becomes possible — rather than the CLI's raw request line around it.
const fake = fakeGrid({ version: VERSION_OK, sync: {}, ls: { stdout: rows() }, start: { exit: 1, stderr: QUOTA_REFUSAL } })
expect(await ensure()).toEqual({ status: 'refused', message: QUOTA_MESSAGE })
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
expect(slept).toEqual([])
// …and only after looking again: the account had no such grid, so the quota was not spent on it.
expect(fake.calls().filter((c) => c.includes('ls')).length).toBe(2)
})
it('uses the grid, not the Free plan’s refusal, when the grid turns out to be there', async () => {
// A 402 while the account holds a grid of this name means the quota counted that very grid: made by
// another machine, or by a create that finished on the server after its client gave up.
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: [{ stdout: rows() }, { stdout: rows('someone-7f3a91c4') }],
start: { exit: 1, stderr: QUOTA_REFUSAL },
})
expect(await ensure()).toEqual({ status: 'adopted', message: '' })
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
expect(slept).toEqual([])
})
it('looks again right before asking again, and uses a grid that appeared in the wait', async () => {
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: [{ stdout: rows() }, { stdout: rows('someone-7f3a91c4') }],
start: { exit: 1, stderr: 'POST …/managed-networks failed (503): {"detail":"The server is low on memory right now"}\n' },
})
expect(await ensure()).toEqual({ status: 'adopted', message: '' })
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
expect(slept).toEqual([2_000])
})
// A create can outlast `grid start`'s own bound and still succeed: the control plane keeps going after
// its client gives up, and registers the grid only at the END of the create, once the grid's server is
// up. What the CLI prints then is no answer at all — no `failed (<status>)`.
const NO_ANSWER = 'Cannot reach the control plane (POST https://api-grid.autonomous.ai/v1/grid/managed-networks): timed out\n'
it('uses the grid a slow create made after grid gave up on it, and never creates it twice', async () => {
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
// Not there before the create, nor at the first look after it; there once the server has finished.
ls: [{ stdout: rows() }, { stdout: rows() }, { stdout: rows('someone-7f3a91c4') }],
start: { exit: 1, stderr: NO_ANSWER },
})
expect(await ensure()).toEqual({ status: 'adopted', message: '' })
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
expect(slept).toEqual([2_000])
})
it('never asks again after a create that got no answer, even when no grid appears', async () => {
// It may still be running on the server, and a second create would make a second grid of the same
// name: the control plane does not serialize two creates. Looking is all that is safe.
const fake = fakeGrid({ version: VERSION_OK, sync: {}, ls: { stdout: rows() }, start: { exit: 1, stderr: NO_ANSWER } })
const result = await ensure()
expect(result.status).toBe('failed')
expect(result.message).toContain('timed out')
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
// Before the create, then once at once and once after each wait.
expect(fake.calls().filter((c) => c.includes('ls')).length).toBe(4)
expect(slept).toEqual([2_000, 5_000])
})
it('takes a gateway timeout for no answer: a proxy stopped waiting, the create may still be running', async () => {
const fake = fakeGrid({
version: VERSION_OK,
sync: {},
ls: { stdout: rows() },
start: { exit: 1, stderr: 'POST …/managed-networks failed (504): <html>504 Gateway Time-out</html>\n' },
})
expect((await ensure()).status).toBe('failed')
expect(fake.calls().filter((c) => c.includes('start')).length).toBe(1)
})
it('skips, without touching the grid, when the binary is older than the floor', async () => {
const fake = fakeGrid({ version: { stdout: 'grid 0.3.34\n' } })
const result = await ensure()
expect(result.status).toBe('skipped')
expect(result.message).toContain('0.3.36')
expect(fake.calls().some((c) => c.includes('start'))).toBe(false)
})
it('skips when there is no grid at all, and never throws', async () => {
process.env.HARNESS_GRID_BIN = join(tmpdir(), 'definitely-not-a-grid-binary')
const result = await ensure()
expect(result.status).toBe('skipped')
})
it('refuses an empty name rather than creating a grid called nothing', async () => {
fakeGrid({ version: VERSION_OK })
expect((await ensure(' ')).status).toBe('skipped')
})
})
describe('quotaRefusal', () => {
it('reads the control plane’s sentence out of the CLI’s refusal line', async () => {
const { quotaRefusal } = await import('./gridEnsure.js')
expect(quotaRefusal(QUOTA_REFUSAL)).toBe(QUOTA_MESSAGE)
expect(quotaRefusal(`some warning first\n${QUOTA_REFUSAL}`)).toBe(QUOTA_MESSAGE)
})
it('reads the sentence for an owner whose live grids fill the plan', async () => {
// grid-apis `_free_limit_message(None)`: no deleted grid is counting, so the sentence names no date.
const { quotaRefusal } = await import('./gridEnsure.js')
const live = 'Free plan allows one network; upgrade to create more'
const line = 'POST https://api-grid.autonomous.ai/v1/grid/managed-networks failed (402): ' +
JSON.stringify({ detail: { error_code: 'free_network_limit', message: live } })
expect(quotaRefusal(line)).toBe(live)
})
it('is not fooled by another refusal', async () => {
const { quotaRefusal } = await import('./gridEnsure.js')
expect(quotaRefusal('POST …/managed-networks failed (402): {"detail":"Insufficient balance"}')).toBeNull()
expect(quotaRefusal('POST …/managed-networks failed (409): {"detail":"You already have a network with this name"}')).toBeNull()
expect(quotaRefusal('POST …/managed-networks failed (503): {"detail":{"error_code":"free_network_limit"}}')).toBeNull()
expect(quotaRefusal('the control plane is unreachable')).toBeNull()
})
it('still knows the refusal when the CLI cut the body short', async () => {
// The CLI keeps the first 400 characters of a body, so a long sentence can arrive as broken JSON.
// The code is near the front and still decides; the person then gets a sentence of our own.
const { quotaRefusal } = await import('./gridEnsure.js')
const cut = QUOTA_REFUSAL.slice(0, QUOTA_REFUSAL.indexOf('You can'))
expect(quotaRefusal(cut)).toMatch(/Free plan/)
})
})