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
/**
* Which `grid` this daemon runs, and the environment it runs it in: the resolution behind every grid
* call (`gridExec.ts`) and behind every pane the core launches on a grid (`engineLaunch.ts`).
*
* Its own module so the core can launch an agent on a grid without loading the code that runs `grid`
* itself: that is the models service's (services/models.ts), which runs in a process of its own
* (docs/design/2026-10-06-core-boundary-next.md, step 7). It reads files and never spawns.
*/
import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs'
import { join, sep, win32 } from 'node:path'
import { env } from '../config/env.js'
import { binaryOnPath, resolveBinaryOnPath } from './binaryOnPath.js'
/** The command, as it is named on PATH — the last resort of [gridBinaryPath], and the word the
* sign-out's own "nothing to run" sentence uses (`gridLogout.ts`). */
export const GRID_BINARY = 'grid'
/**
* grid's own update check, and the one switch that turns it off.
*
* A `grid` with a terminal on stderr looks for a newer release and, finding one, prints "run
* `grid update`" — and `grid update` replaces the binary IN PLACE, wherever `which grid` found it
* (autonomous-grid `cli/update.py`). Under a managed runtime that file is the pin, and the process
* most likely to read that line and obey it is an agent in a pane. So the check is off for every
* child this daemon spawns ([gridChildEnv]) and in every pane it launches (`engineLaunch.ts`), by
* the variable grid honours for it. The daemon's own spawns pipe stderr and would be spared anyway;
* saying it explicitly is what makes the pane and the daemon one rule.
*/
export const GRID_NO_UPDATE_CHECK_VAR = 'GRID_NO_UPDATE_CHECK'
/** The environment a `grid` child gets: the caller's own, with the update check off. */
export function gridChildEnv(processEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
return { ...processEnv, [GRID_NO_UPDATE_CHECK_VAR]: '1' }
}
/**
* The managed grid — the runtime `current-grid` names — or null when there is none this daemon
* would trust.
*
* Containment-checked exactly like `nodeRuntime.managedNodePath`: a pointer file is only trusted
* when it names something INSIDE the runtime directory we own, so a corrupted or hostile pointer
* cannot turn this into "run any executable on the box". `runtimeInstall.ts` writes the pointer and
* asks this to learn what is already laid down.
*/
export function managedGridPath(): string | null {
try {
const recorded = readFileSync(join(env.ADAPTER_RUNTIME_DIR, 'current-grid'), 'utf-8').trim()
if (recorded && recorded.startsWith(env.ADAPTER_RUNTIME_DIR + sep)) {
accessSync(recorded, constants.X_OK)
return recorded
}
} catch {
// absent, unreadable, or not executable → there is no managed grid
}
return null
}
/**
* The `grid` this daemon should run: the override, the managed runtime, the name on PATH, or —
* last — the directory grid's own public installer uses (`lib/gridInstall.ts`), which a daemon
* started from a launcher with launchd's bare PATH does not have. Named absolutely rather than by
* extending PATH, so the fallback reaches exactly one known file and never whatever else that
* directory holds. The managed runtime outranks it: once the pin is published the installer's
* copy is only ever a fallback for a machine the pin could not reach.
*/
export function gridBinaryPath(processEnv: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): string {
const override = processEnv.HARNESS_GRID_BIN?.trim()
if (override) return override
const managed = managedGridPath()
if (managed) return managed
if (binaryOnPath(GRID_BINARY, processEnv)) return GRID_BINARY
// Keyed on the environment's home rather than `os.homedir()`, so a caller that hands in an
// environment (the tests, a deliberately bare one) gets exactly what that environment can see.
// Windows has no HOME, and grid's installer there (`install.ps1`) writes `grid.exe` — or, where Smart
// App Control blocked that, `grid.cmd` — into `%USERPROFILE%\.local\bin`.
const windows = platform === 'win32'
const home = (windows ? processEnv.USERPROFILE : processEnv.HOME)?.trim()
if (home) {
for (const name of windows ? ['grid.exe', 'grid.cmd'] : [GRID_BINARY]) {
const installed = join(home, '.local', 'bin', name)
try { accessSync(installed, constants.X_OK); return installed } catch { /* not there either */ }
}
}
return GRID_BINARY
}
/**
* What to spawn to run [binary] with [args]. Almost always the binary itself. The exception is the
* `grid.cmd` that grid's Windows installer writes where Smart App Control blocked its unsigned
* `grid.exe`: Node cannot spawn a `.cmd` without a shell, and a shell would have to re-quote every
* argument, so the installer's own line — `"<install>\Scripts\python.exe" -m cli %*` — is read and that
* signed python is run directly. A `.cmd` that is not that shape is returned as it is, and fails as it did.
*
* The same for the `grid.exe` itself, which is a launcher that does nothing but start that python: it is unsigned, so Smart App
* Control refuses it wherever the installer did not see that (593 times in an hour on DESKTOP-0TFH0OJ, 2026-11-05, each a notice
* to the person that Node.js had been blocked). On a Mac nothing stands in its way; here it is stepped past, as `grid.cmd` is.
*/
export function gridCommand(binary: string, args: readonly string[], platform: NodeJS.Platform = process.platform): { file: string; args: string[] } {
if (platform === 'win32') {
const program = binary.includes('\\') || binary.includes('/') ? binary : resolveBinaryOnPath(binary) ?? binary
let python: string | null | undefined
try {
python = /\.(?:cmd|bat)$/i.test(program)
? /"([^"]+\.exe)" -m cli %\*/.exec(readFileSync(program, 'utf8'))?.[1]
: launcherPython(program)
} catch { /* unreadable: spawn reports it */ }
if (python) return { file: python, args: ['-m', 'cli', ...args] }
}
return { file: binary, args: [...args] }
}
/** A launcher is small; anything larger is a program of its own, not read to find out. */
const MAX_LAUNCHER_BYTES = 1024 * 1024
/** The python a pip or uv launcher `.exe` starts, named on a `#!` line near its end, when it is there to run. */
function launcherPython(program: string): string | null {
if (!/\.exe$/i.test(program) || statSync(program).size > MAX_LAUNCHER_BYTES) return null
const bytes = readFileSync(program)
const at = bytes.lastIndexOf('#!')
if (at < 0) return null
const line = bytes.subarray(at + 2, at + 2 + 4096).toString('utf8').split(/[\r\n]/, 1)[0]!.replaceAll('"', '').trim()
return win32.basename(line).toLowerCase() === 'python.exe' && existsSync(line) ? line : null
}
/** Is there a `grid` to run at all? Asked by reading rather than by spawning, so a missing binary is
* a sentence rather than a spawn error every caller has to recognise — and so a present-but-not-
* executable one (EACCES, never ENOENT) is caught too. */
export function gridAvailable(processEnv: NodeJS.ProcessEnv = process.env): boolean {
return binaryOnPath(gridBinaryPath(processEnv), processEnv)
}
/**
* Which `grid` this machine would run, for a desktop that has to say so.
*
* `managed` is the runtime this daemon owns — the pin. `path` is one the user installed themselves,
* or a developer's override: runnable, but not the pin, and not ours to keep current. `missing` is
* nothing to run at all, which the picker and the Local model dialog need to know BEFORE they offer
* to start an agent whose second step is `grid`.
*/
export type GridCliPresence = 'managed' | 'path' | 'missing'
export function gridCliPresence(processEnv: NodeJS.ProcessEnv = process.env): GridCliPresence {
const binary = gridBinaryPath(processEnv)
if (!binaryOnPath(binary, processEnv)) return 'missing'
// An override is the developer's wherever it lives — under the runtime dir included. Only what the
// pointer names is the pin.
if (processEnv.HARNESS_GRID_BIN?.trim()) return 'path'
return binary.startsWith(env.ADAPTER_RUNTIME_DIR + sep) ? 'managed' : 'path'
}