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.

11.1 KB
Raw Blame
/**
 * Installing an engine on Windows, as a launch needs one: one hidden installer per engine, whoever asks, with the same
 * answers as `createNativeInstallations` (./nativeInstall.ts), whose evidence walks POSIX paths and runs POSIX shell
 * lines. Here each engine has one record, overwritten by its next install. A launch only ever believes the program it
 * can then find (kit/launchExecutable.ts), so a record says how the install went and never that the engine is there.
 */
import { spawn as nodeSpawn } from 'node:child_process'
import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { dirname, join } from 'node:path'
import { stripVTControlCharacters } from 'node:util'
import { ENGINE_WINDOWS_INSTALL, npmEnginePrefix, type EngineInstallRecipe, type WindowsInstall } from '../../lib/engineInstall.js'
import { managedNodePath } from '../../lib/nodeRuntime.js'
import { powershellPath } from '../../lib/windows/powershell.js'
import { endProcessTree, processTreeKillDeps } from '../../lib/windows/treeKill.js'
import type { AgentEngine } from '../types.js'
import type { NativeInstallation } from './nativeInstall.js'

/** As the Mac's helper: an installer past this is ended, and said to have taken too long. */
export const WINDOWS_INSTALL_LIMIT_MS = 20 * 60_000
/** A running record older than this has nobody behind it, even if another process took its pid. */
const RECORD_SETTLES_MS = WINDOWS_INSTALL_LIMIT_MS + 60_000

interface InstallPlaces { npm: string; prefix: string; comspec: string; powershell: string }
interface SpawnPlaces extends InstallPlaces { node: string; nodeDir: string }
export interface InstallCommand { file: string; args: string[]; verbatim: boolean }

const INSTALL_COMMAND_VARIABLE = 'HARNESS_INSTALL_COMMAND'
/**
 * What the daemon starts, which starts the installer and says how it ended. An installer needs two things Node gives only one of
 * at a time. To outlive the daemon it must be detached, since Node kills its other children with it (libuv's job object). But
 * detached takes the console away, and PowerShell without one exits 0 at once having run nothing: no PowerShell installer ever
 * ran (Hermes on DESKTOP-0TFH0OJ, 2026-11-04). So this small process is the detached one, and its child has a console no one sees.
 * Through `cmd` instead, the hidden console takes the output, and the person is told nothing of why an install failed.
 */
export const INSTALL_RUNNER = [
  "const { spawn } = require('node:child_process')",
  `const { file, args, verbatim } = JSON.parse(process.env.${INSTALL_COMMAND_VARIABLE})`,
  `delete process.env.${INSTALL_COMMAND_VARIABLE}`,
  "const child = spawn(file, args, { windowsHide: true, windowsVerbatimArguments: verbatim, stdio: ['ignore', 1, 2] })",
  "child.once('error', (error) => { console.error(error.message); process.exit(1) })",
  "child.once('exit', (code) => process.exit(code ?? 1))",
].join('\n')

/**
 * The vendor's installer, as `irm <url> | iex` runs it, with its flags. As bytes when the server calls it a download, which
 * `irm` would not read as text (Antigravity's and Claude's are served as application/octet-stream).
 */
export function powershellInstallScript(url: string, args: readonly string[] = []): string {
  return [
    "$ProgressPreference = 'SilentlyContinue'",
    '[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12',
    // A failure is said here and in words: past a failed download, an empty script would run and exit 0, an install that "finished".
    `try { $reply = Invoke-WebRequest -UseBasicParsing -ErrorAction Stop -Uri '${url.replace(/'/g, "''")}' } catch { [Console]::Error.WriteLine('its installer could not be downloaded: ' + $_.Exception.Message); exit 1 }`,
    '$text = if ($reply.Content -is [byte[]]) { [Text.Encoding]::UTF8.GetString($reply.Content) } else { [string]$reply.Content }',
    `try { ${`& ([scriptblock]::Create($text.TrimStart([char]0xFEFF))) ${args.join(' ')}`.trimEnd()} } catch { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }`,
    'if ($LASTEXITCODE) { exit $LASTEXITCODE }',
  ].join('\n')
}

export function windowsInstallCommand(install: WindowsInstall, places: InstallPlaces, arch: string = process.arch): InstallCommand {
  if ('powershell' in install) {
    // -Command and not -EncodedCommand: encoded, PowerShell writes its errors as CLIXML, and the person would be shown XML as the
    // reason. The script holds no double quote for Node to escape (a URL's quote is doubled, in single quotes).
    return { file: places.powershell, args: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', powershellInstallScript(install.powershell, install.args)], verbatim: false }
  }
  const words = [`"${places.npm}" install --global --prefix "${places.prefix}" --no-fund --no-audit --loglevel=error`,
    ...install.args ?? [], ...(arch === 'arm64' ? install.armArgs ?? [] : []), install.npm]
  // cmd's own quoting: /s takes everything between the outer quotes as it stands, spaces in a profile's name included.
  return { file: places.comspec, args: ['/d', '/s', '/c', `"${words.join(' ')}"`], verbatim: true }
}

type InstallRecord =
  | { state: 'running'; pid: number; request: string; startedAt: number }
  | { state: 'done' | 'failed'; request: string; detail?: string }

const running = (): NativeInstallation => ({ complete: false, running: true, detail: 'Installing.' })
const failed = (detail: string): NativeInstallation => ({ complete: false, failed: true, detail })

function processRuns(pid: number): boolean {
  try { process.kill(pid, 0); return true } catch { return false }
}

function lastLine(log: string): string | null {
  try {
    const lines = stripVTControlCharacters(readFileSync(log, 'utf8')).split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
    return lines.at(-1)?.slice(0, 300) ?? null
  } catch { return null }
}

export function createWindowsInstallations({ directory, spawn = nodeSpawn, alive = processRuns, now = Date.now,
  endTree = (pid: number) => endProcessTree(pid, processTreeKillDeps(null)), where }: {
  directory: string
  spawn?: typeof nodeSpawn
  alive?: (pid: number) => boolean
  now?: () => number
  endTree?: (pid: number) => Promise<unknown>
  where?: () => SpawnPlaces
}) {
  const places = where ?? (() => {
    const node = managedNodePath()
    const nodeDir = dirname(node)
    return { node, nodeDir, npm: join(nodeDir, 'npm.cmd'), prefix: npmEnginePrefix(), comspec: process.env.ComSpec ?? 'cmd.exe', powershell: powershellPath() }
  })
  const recordFile = (engine: AgentEngine) => join(directory, `${engine}.json`)
  const read = (engine: AgentEngine): InstallRecord | null => {
    try {
      const record = JSON.parse(readFileSync(recordFile(engine), 'utf8')) as InstallRecord | null
      return record && typeof record.state === 'string' && typeof record.request === 'string' ? record : null
    } catch { return null }
  }
  const write = (engine: AgentEngine, record: InstallRecord) => {
    mkdirSync(directory, { recursive: true })
    const next = `${recordFile(engine)}.${process.pid}.next`
    writeFileSync(next, JSON.stringify(record))
    renameSync(next, recordFile(engine))
  }
  /** A running record with an installer behind it. One whose process is gone (a restart) or too old never holds a launch. */
  const live = (record: InstallRecord | null): boolean =>
    record?.state === 'running' && alive(record.pid) && now() - record.startedAt < RECORD_SETTLES_MS

  const start = (engine: AgentEngine, environment: Record<string, string>, request: string): NativeInstallation => {
    const log = join(directory, `${engine}.log`)
    try {
      mkdirSync(directory, { recursive: true })
      const at = places()
      const install = ENGINE_WINDOWS_INSTALL[engine as keyof typeof ENGINE_WINDOWS_INSTALL]
      if (!install) return failed('Harness has no way to install it on Windows.')
      const command = windowsInstallCommand(install, at)
      const env: NodeJS.ProcessEnv = { ...process.env, ...environment }
      // Windows' names ignore case: one PATH, Harness's Node first, so npm's scripts find it on a computer with none.
      const path = Object.keys(env).filter((key) => key.toLowerCase() === 'path').map((key) => { const value = env[key]; delete env[key]; return value }).find(Boolean)
      env.PATH = path ? `${at.nodeDir};${path}` : at.nodeDir
      rmSync(log, { force: true })
      const output = openSync(log, 'w')
      let child
      try {
        // Detached, so a daemon restarting does not end it, and hidden. See INSTALL_RUNNER for why it does not run the installer itself.
        child = spawn(at.node, ['-e', INSTALL_RUNNER], { env: { ...env, [INSTALL_COMMAND_VARIABLE]: JSON.stringify(command) }, cwd: directory, detached: true, windowsHide: true, stdio: ['ignore', output, output] })
      } finally { closeSync(output) }
      child.unref?.()
      const pid = child.pid ?? 0
      let timedOut = false
      const limit = setTimeout(() => { timedOut = true; void Promise.resolve(endTree(pid)).catch(() => {}) }, WINDOWS_INSTALL_LIMIT_MS)
      limit.unref?.()
      const settle = (record: InstallRecord) => {
        clearTimeout(limit)
        const now = read(engine)
        if (now?.state === 'running' && now.pid === pid) write(engine, record)
      }
      child.once('exit', (code: number | null) => {
        if (code === 0 && !timedOut) return settle({ state: 'done', request })
        const detail = timedOut ? 'it took longer than 20 minutes.' : lastLine(log) ?? `its installer stopped with code ${code}.`
        settle({ state: 'failed', request, detail })
      })
      child.once('error', (error: Error) => settle({ state: 'failed', request, detail: error.message }))
      write(engine, { state: 'running', pid, request, startedAt: now() })
      return running()
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error)
      try { write(engine, { state: 'failed', request, detail }) } catch { /* said below all the same */ }
      return failed(detail)
    }
  }

  const ensure = async (engine: AgentEngine, _recipe: EngineInstallRecipe, environment: Record<string, string>, request: string,
    current: () => boolean): Promise<NativeInstallation> => {
    if (!current()) return { complete: false, detail: 'The saved launch request changed before installation.' }
    const record = read(engine)
    if (live(record)) return running()
    if (record?.request === request && record.state === 'failed') return failed(record.detail ?? 'its installer failed.')
    // Asked again by the launch that installed it, whose look found nothing: another install would find it no better.
    if (record?.request === request && record.state === 'done') return failed('its installer finished, but Harness could not find it. Try again.')
    return start(engine, environment, request)
  }

  const status = async (engine: AgentEngine, request: string, _current: () => boolean): Promise<NativeInstallation | null> => {
    const record = read(engine)
    if (live(record)) return running()
    return record?.request === request && record.state === 'failed' ? failed(record.detail ?? 'its installer failed.') : null
  }

  return { ensure, status }
}