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.

8.1 KB
Raw Blame
/**
 * 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'
}