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.

19.0 KB
Raw Blame
import { spawn } from 'node:child_process'
import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { dirname, join, sep, win32 } from 'node:path'

import { env } from '../config/env.js'
import { gridAvailable, gridChildEnv, gridCommand, gridVersion, managedGridPath, meetsVersionFloor } from './gridExec.js'
import { installGrid } from './gridInstall.js'
import { followWindowsGridPin } from './gridWindowsPin.js'
import { managedNodePath } from './nodeRuntime.js'
import { RUNTIME_DOWNLOAD_LIMITS, downloadVerified } from './selfUpdate.js'

/**
 * Provisioning the Node the CLI runs on, from inside the CLI.
 *
 * Until now only the shell installers ever wrote a runtime or a launcher, and nothing re-ran them —
 * so a computer installed before the product owned its Node keeps a launcher that execs a bare `node`
 * (or an absolute path to a system Node that may since have been removed), and stays broken until
 * somebody re-runs an installer by hand. Doing it here means `harness start` and the post-update
 * restart repair the machine themselves.
 *
 * Everything in this file is best-effort and returns rather than throws: a daemon must not fail to
 * start because a download failed. It keeps running on the interpreter it already has, and tries
 * again next start.
 */

/** `darwin-*` | `linux-*` | `win32-*` for arm64 and x64: the keys every runtime manifest uses. Null elsewhere. */
export function platformKey(platform: NodeJS.Platform = process.platform, arch: string = process.arch): string | null {
  const os = platform === 'darwin' || platform === 'linux' || platform === 'win32' ? platform : null
  const cpu = arch === 'arm64' ? 'arm64' : arch === 'x64' ? 'x64' : null
  return os && cpu ? `${os}-${cpu}` : null
}

/**
 * How a runtime's archive is unpacked. On Unix it is nodejs.org's `.tar.gz` with /usr/bin/tar. On Windows it is
 * the `.zip`, unpacked by the bsdtar that Windows has shipped in System32 since 1803, which reads zip. It is never
 * a `tar` found on PATH: Git for Windows puts GNU tar there, which cannot read a zip.
 */
export function unpackCommand(
  archive: string,
  into: string,
  platform: NodeJS.Platform = process.platform,
  systemRoot: string | undefined = process.env.SystemRoot,
): { file: string; args: string[] } {
  if (platform === 'win32') return { file: win32.join(systemRoot || 'C:\\Windows', 'System32', 'tar.exe'), args: ['-xf', archive, '-C', into] }
  return { file: '/usr/bin/tar', args: ['-xzf', archive, '-C', into] }
}

/**
 * What differs on Windows: nodejs.org's archive is a zip with `node.exe` at its root folder, not `bin/node`. The
 * pointer line ends in CRLF there, as install.ps1 writes it (installLayout.ts writePointer).
 */
export function runtimeLayout(platform: NodeJS.Platform = process.platform): { archiveSuffix: '.zip' | '.tar.gz'; nodeBinary: string; eol: string } {
  return platform === 'win32'
    ? { archiveSuffix: '.zip', nodeBinary: 'node.exe', eol: '\r\n' }
    : { archiveSuffix: '.tar.gz', nodeBinary: join('bin', 'node'), eol: '\n' }
}

interface RuntimeArtifact {
  version: string
  url: string
  sha256: string
  size?: number
  archiveRoot: string
}

/** The `<name>` → `<platform>` → entry document every managed runtime publishes, read for one runtime. */
function artifactFor(document: unknown, name: string, key: string): RuntimeArtifact | null {
  const runtime = (document as Record<string, Record<string, unknown> | undefined> | null)?.[name]
  const raw = runtime?.[key] as Partial<RuntimeArtifact> | undefined
  if (!raw || typeof raw.version !== 'string' || typeof raw.url !== 'string') return null
  if (typeof raw.sha256 !== 'string' || typeof raw.archiveRoot !== 'string') return null
  // Refuse a plaintext URL: this archive becomes something the daemon executes.
  if (!raw.url.startsWith('https://')) return null
  return { version: raw.version, url: raw.url, sha256: raw.sha256, size: raw.size, archiveRoot: raw.archiveRoot }
}

/** How long a child that outlived its deadline has between SIGTERM and SIGKILL. */
const KILL_GRACE_MS = 2_000

/**
 * Runs [file] to its end and says whether it exited 0 within [timeoutMs] — WITHOUT holding up the
 * event loop while it runs.
 *
 * This module runs inside the core: on every start, and every ten minutes while it runs
 * ([startGridPinRecheck]). A synchronous exec here froze the core for as long as the child took — up
 * to two minutes for an unpack and one for a onefile grid's first `--version` — and a core that does
 * not turn its event loop answers no client, beats no heartbeat, and is restarted by its master. A
 * child that outlives its deadline is sent SIGTERM, as the synchronous exec did, and SIGKILL if it
 * is still there [KILL_GRACE_MS] later; the answer waits for it to be gone, so a staging directory is
 * never removed under a tar that is still writing into it.
 */
export function finishesCleanly(file: string, args: string[], timeoutMs: number, childEnv?: NodeJS.ProcessEnv): Promise<boolean> {
  return new Promise((resolve) => {
    let child: ReturnType<typeof spawn>
    try {
      child = spawn(file, args, { stdio: 'ignore', ...(childEnv ? { env: childEnv } : {}) })
    } catch {
      resolve(false)
      return
    }
    let timedOut = false
    let grace: NodeJS.Timeout | undefined
    const deadline = setTimeout(() => {
      timedOut = true
      child.kill('SIGTERM')
      grace = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS)
    }, timeoutMs)
    let settled = false
    const settle = (ok: boolean) => {
      if (settled) return
      settled = true
      clearTimeout(deadline)
      clearTimeout(grace)
      resolve(ok)
    }
    child.once('error', () => settle(false))
    child.once('close', (code) => settle(!timedOut && code === 0))
  })
}

/** Does `binary --version` answer? `env` and `timeout` for a runtime whose first run is slow — a
 *  onefile grid unpacks itself the first time, and must not be told to update itself while it does. */
function runs(binary: string, timeout: number = 15_000, childEnv?: NodeJS.ProcessEnv): Promise<boolean> {
  return finishesCleanly(binary, ['--version'], timeout, childEnv)
}

/**
 * One managed runtime, as this module lays it down. Node and grid differ in four things and share
 * everything else: the archive shape (`<name>-<version>-<key>/bin/<name>`), the staging, the rename
 * race, the pointer file — the convention nodejs.org's tarballs set and tmux and grid copy.
 */
interface ManagedArchive {
  /** The manifest's top-level key and the runtime's name in every path. */
  name: 'node' | 'grid'
  /** How the runtime is named to a person. */
  label: string
  manifestUrl: string
  /** The executable, relative to the archive root. */
  binary: string
  /** What this daemon already resolved to under the runtime dir, or null when nothing is there. */
  installed: () => string | null
  /**
   * Whether an installed runtime that is not the manifest's version is replaced. Node stops at "one
   * is installed" — which version is the installer's business, and a daemon must not swap the
   * interpreter it is running on. The grid follows the PIN: the manifest names the version this build
   * of the CLI drives, and a pin that moved must reach a machine that already has an older one.
   */
  followsPin: boolean
  /** A version the manifest may not go below — this daemon's floor, which a manifest cannot lower. */
  acceptsVersion?: (version: string) => boolean
  /** Does the laid-down binary run on this computer? Asked before the pointer is written. */
  runs: (binary: string) => Promise<boolean>
  /**
   * Lay the binary and its directory down read-only. For a runtime whose own updater would replace
   * the file in place — `grid update` is an os.replace INTO the directory — a directory it cannot
   * write to is what makes that fail loudly instead of overwriting the pin.
   */
  readOnly?: boolean
  log: (message: string) => void
}

/**
 * Install [spec]'s runtime from its manifest, or move to the version the manifest pins, or leave it
 * be. Returns the binary this daemon should use — which is whatever it already had whenever the
 * manifest, the download or the unpacked binary cannot be trusted — or null when there is nothing.
 *
 * Everything here is best-effort and returns rather than throws: a daemon must not fail to start
 * because a download failed.
 */
/**
 * The staging folders of processes that are gone: a core that exited in the middle of an unpack (an
 * update's handoff, a master's restart) left its `.<name>-staging-<pid>-<time>`, the archive and a
 * partial tree in it, and nothing else ever removes one. Another process's, still running, is its own.
 */
function sweepStaging(name: string): void {
  const prefix = `.${name}-staging-`
  let entries: string[]
  try { entries = readdirSync(env.ADAPTER_RUNTIME_DIR) } catch { return }
  for (const entry of entries) {
    if (!entry.startsWith(prefix)) continue
    const pid = Number(entry.slice(prefix.length).split('-')[0])
    if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid)) continue
    try { rmSync(join(env.ADAPTER_RUNTIME_DIR, entry), { recursive: true, force: true }) } catch { /* the next start tries again */ }
  }
}

function processAlive(pid: number): boolean {
  try { process.kill(pid, 0); return true } catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM' }
}

async function ensureManagedArchive(spec: ManagedArchive): Promise<string | null> {
  sweepStaging(spec.name)
  const installed = spec.installed()
  if (installed && !spec.followsPin) return installed
  const key = platformKey()
  if (!key) return installed
  const layout = runtimeLayout()

  try {
    const response = await fetch(spec.manifestUrl)
    if (!response.ok) return installed
    const artifact = artifactFor(await response.json(), spec.name, key)
    if (!artifact) return installed
    if (spec.acceptsVersion && !spec.acceptsVersion(artifact.version)) return installed

    const target = join(env.ADAPTER_RUNTIME_DIR, `${spec.name}-${artifact.version}-${key}`)
    const binary = join(target, spec.binary)
    // The pin is what is installed: nothing to fetch, nothing to write.
    if (installed === binary) return installed
    if (!existsSync(binary)) {
      spec.log(`▸ installing the Harness ${spec.label} runtime (${artifact.version}, ${key})…`)
      // downloadVerified checks the sha256 but not the length, so check it here: a truncated body
      // that somehow collided would be caught by the hash anyway, but a mismatch here is the cheaper
      // and clearer failure.
      const bytes = await downloadVerified(artifact, RUNTIME_DOWNLOAD_LIMITS)
      if (artifact.size !== undefined && bytes.length !== artifact.size) return installed

      mkdirSync(env.ADAPTER_RUNTIME_DIR, { recursive: true, mode: 0o700 })
      const staging = join(env.ADAPTER_RUNTIME_DIR, `.${spec.name}-staging-${process.pid}-${Date.now()}`)
      try {
        mkdirSync(staging, { recursive: true, mode: 0o700 })
        const archive = join(staging, `${spec.name}${layout.archiveSuffix}`)
        writeFileSync(archive, bytes)
        const unpack = unpackCommand(archive, staging)
        if (!await finishesCleanly(unpack.file, unpack.args, 120_000)) return installed
        const unpacked = join(staging, artifact.archiveRoot)
        if (!existsSync(join(unpacked, spec.binary))) return installed
        // Another start may have won the race; theirs is as good as ours.
        if (!existsSync(target)) renameSync(unpacked, target)
      } finally {
        rmSync(staging, { recursive: true, force: true })
      }
    }
    // After the rename, never in staging: a read-only directory cannot be emptied, and staging must
    // always be.
    // Never on Windows: a read-only folder there cannot be removed by retireSuperseded, and nothing updates grid in place there (it is not installed).
    if (spec.readOnly && process.platform !== 'win32') {
      chmodSync(binary, 0o555)
      chmodSync(dirname(binary), 0o555)
    }

    // A pin this computer could not run is tried ONCE and remembered. A runtime that follows its pin
    // is asked on every daemon start, and without this a wrong-arch or broken build would cost a
    // hung exec each time until the manifest moved. A new pin is a new directory, and starts clean.
    const unrunnable = join(target, '.unrunnable')
    if (spec.followsPin && existsSync(unrunnable)) return installed
    if (!await spec.runs(binary)) {
      if (spec.followsPin) {
        try { writeFileSync(unrunnable, `${new Date().toISOString()}\n`, { mode: 0o600 }) } catch { /* the retry is the cost */ }
      }
      return installed
    }
    // Written last, and only once the binary has answered: Desktop Harness and the hook installer
    // both read this file to decide what to execute, so it must never name something that cannot run.
    writeFileSync(join(env.ADAPTER_RUNTIME_DIR, `current-${spec.name}`), `${binary}${layout.eol}`, { mode: 0o600 })
    spec.log(`  ✓ ${spec.label} runtime ready → ${target}`)
    if (spec.followsPin) retireSuperseded(spec.name, key, target, installed)
    return binary
  } catch {
    return installed
  }
}

/**
 * Every `<name>-*-<key>` under the runtime dir except the one just installed and the one it
 * replaced.
 *
 * One version back stays on purpose. A pane launched before the pin moved has the OLD directory on
 * its PATH for as long as it lives (`gridPanePrelude` in engineLaunch.ts), and deleting it would
 * take `grid` away from an agent mid-conversation. Two versions of a 20 MB runtime is the price;
 * the third is not paid.
 */
function retireSuperseded(name: string, key: string, target: string, previous: string | null): void {
  const keep = new Set([target, previous ? dirname(dirname(previous)) : ''])
  try {
    for (const entry of readdirSync(env.ADAPTER_RUNTIME_DIR)) {
      if (!entry.startsWith(`${name}-`) || !entry.endsWith(`-${key}`)) continue
      const dir = join(env.ADAPTER_RUNTIME_DIR, entry)
      if (keep.has(dir)) continue
      // A read-only `bin/` cannot be emptied as it is; give it back before the sweep.
      try { chmodSync(join(dir, 'bin'), 0o755) } catch { /* not laid down read-only */ }
      rmSync(dir, { recursive: true, force: true })
    }
  } catch {
    // Disk housekeeping only; the runtime that matters is already in place and recorded.
  }
}

/**
 * The managed Node, installing it when this computer has not got one. Returns its path, or null when
 * no runtime could be provisioned — callers keep whatever interpreter they already have.
 *
 * Idempotent and cheap once installed: [managedNodePath] returning a path under the runtime directory
 * means the work is already done, and nothing is fetched.
 */
export async function ensureManagedRuntime(log: (message: string) => void = () => {}): Promise<string | null> {
  return ensureManagedArchive({
    name: 'node',
    label: 'Node',
    manifestUrl: env.ADAPTER_RUNTIME_METADATA_URL,
    binary: runtimeLayout().nodeBinary,
    installed: () => {
      const existing = managedNodePath()
      return existing.startsWith(env.ADAPTER_RUNTIME_DIR + sep) ? existing : null
    },
    followsPin: false,
    runs: (node) => runs(node),
    log,
  })
}

/**
 * The managed grid at the version the harness manifest PINS — installing it, moving to it, or
 * leaving it be. Returns its path, or null when there is none: callers fall back to whatever `grid`
 * PATH has (`gridBinaryPath`), and an agent's pane is told when it has none (`gridCliPresence`).
 *
 * Best-effort like the Node runtime: a daemon must not fail to start because a download failed. Asked
 * on every daemon start rather than on `--repair` only, because the pin is expected to MOVE and a
 * machine installed last month has to notice. Never below [GRID_VERSION_FLOOR]: the floor is this
 * daemon's, and a manifest cannot lower it. A developer's HARNESS_GRID_BIN is left alone entirely —
 * it outranks the pin at resolution, so a pin laid down under it would be work nobody asked for.
 */
export async function ensureManagedGrid(log: (message: string) => void = () => {}): Promise<string | null> {
  if (process.env.HARNESS_GRID_BIN?.trim()) return null
  // No managed grid build on Windows: grid's own installer lays the pinned release down there, and there is no
  // managed binary to return (gridWindowsPin.ts).
  if (process.platform === 'win32') {
    await followWindowsGridPin({
      key: platformKey(),
      manifest: async () => {
        const response = await fetch(env.ADAPTER_GRID_RUNTIME_METADATA_URL)
        if (!response.ok) throw new Error(`manifest answered ${response.status}`)
        return response.json()
      },
      installedVersion: () => gridAvailable() ? gridVersion() : Promise.resolve(null),
      install: (version) => installGrid(version),
      log,
    })
    return null
  }
  return ensureManagedArchive({
    name: 'grid',
    label: 'grid',
    manifestUrl: env.ADAPTER_GRID_RUNTIME_METADATA_URL,
    binary: join('bin', 'grid'),
    installed: managedGridPath,
    followsPin: true,
    acceptsVersion: (version) => meetsVersionFloor(version),
    // A minute, not fifteen seconds: a onefile grid unpacks itself the first time it runs.
    // `gridCommand` steps past an unsigned launcher and runs the signed python it names, so this
    // probe never asks Smart App Control to start the very file it would refuse (windows-rules.md §2).
    runs: (grid) => {
      const command = gridCommand(grid, ['--version'])
      return finishesCleanly(command.file, command.args, 60_000, gridChildEnv())
    },
    readOnly: true,
    log,
  })
}

/** How often a running daemon re-reads the managed `grid` pin. */
export const GRID_PIN_RECHECK_MS = 10 * 60_000

/**
 * Follow the pin while the daemon RUNS, not only when it starts.
 *
 * A daemon updates itself within about a minute of a release, but it can then run for days, and a pin
 * moved in between would wait for the next restart. That matters here because the pin and the daemon's
 * code are released in an ORDER (grid-reads-without-waking: CLI tag → harness tag → pin, never 0.3.48
 * alone): the pin has to reach the daemons already running the new code, the same day.
 *
 * Idempotent by construction — [ensureManagedGrid] fetches only the manifest and writes nothing while the
 * installed grid IS the pin — and one check at a time. Every `grid` call resolves the binary afresh
 * (`gridBinaryPath` reads `current-grid`), so a moved pin takes effect on the next call. Returns a stop.
 */
export function startGridPinRecheck(options: { ensure?: () => Promise<unknown>; intervalMs?: number } = {}): () => void {
  const ensure = options.ensure ?? (() => ensureManagedGrid((m) => console.log(`[grid-runtime] ${m}`)))
  let checking = false
  const timer = setInterval(() => {
    if (checking) return
    checking = true
    void ensure().catch(() => {}).finally(() => { checking = false })
  }, options.intervalMs ?? GRID_PIN_RECHECK_MS)
  timer.unref?.()
  return () => clearInterval(timer)
}

// The launchers are launchers.ts's: the hn updater, which the core runs, repairs them without loading the
// managed runtimes' code, which grid's half of is the models service's (docs/design/2026-10-06-core-boundary-next.md, step 7).
export { ensureHnLauncher, ensureLauncher } from './launchers.js'