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.

7.3 KB
Raw Blame
/**
 * Installing a guest's engine on Windows (docs/superpowers/specs/2026-11-05-windows-guests-design.md): the Windows twin
 * of the macOS helper's `install` (lib/guestAccounts.ts `installGuestEngine`), which runs the engine's installer as the
 * guest so the engine lands in that account's own profile.
 *
 * Only the guest's own host can run a process as the guest, so this asks it to run two short panes: one that asks
 * whether the engine is on that account's PATH (`where claude`), and, when it is not, the package manager itself from
 * the Node runtime the setup task staged for guests. Both are plain argv — no shell text, no prompt, no flag of the
 * person's. The engine then starts in its own pane exactly as an owner's does, with the guest's PATH carrying
 * `%USERPROFILE%\.local` (the setup task writes that into the host's wrapper).
 */
import { ENGINE_WINDOWS_INSTALL } from '../engineInstall.js'
import type { TerminalBackend } from '../terminalBackend.js'
import type { TerminalRuntimeRef } from '../terminalTypes.js'
import { WINDOWS_GUEST_ROOT } from './guestRequests.js'

/** The Node runtime the setup task copies for guests, beside the signed pty (`guestScript.ts`). */
export function guestNodeDir(setupVersion: number): string {
  return `${WINDOWS_GUEST_ROOT}\\bin\\node-${setupVersion}`
}
export function guestNodeExe(setupVersion: number): string {
  return `${guestNodeDir(setupVersion)}\\node.exe`
}
/** npm ships inside Node's Windows distribution, beside `node.exe`. */
export function guestNpmCli(setupVersion: number): string {
  return `${guestNodeDir(setupVersion)}\\node_modules\\npm\\bin\\npm-cli.js`
}

/** The engines a guest's harness may be: the two the subscription relay can spend (lib/guestPaneCommand.ts). */
export const GUEST_INSTALLABLE_ENGINES = ['claude', 'codex'] as const
export type GuestInstallableEngine = (typeof GUEST_INSTALLABLE_ENGINES)[number]

/** Whether [engine] is one this machine may install for a guest. */
export function guestEngineInstallable(engine: string): engine is GuestInstallableEngine {
  return (GUEST_INSTALLABLE_ENGINES as readonly string[]).includes(engine)
}

/** `where <engine>`: the account's PATH answers with where it would run it. */
export function guestEngineProbeArgv(engine: GuestInstallableEngine): string[] {
  return ['cmd.exe', '/d', '/s', '/c', `where ${engine}`]
}

/**
 * The engine's own installer as the guest: npm from the staged Node, into [prefix] — the guest host's own `engines`
 * folder, which the guest may write and the owner may read (so the daemon resolves the shim it wrote, exactly as it
 * resolves one of its own: lib/windows/launch.ts `windowsEngineArgv`).
 */
export function guestEngineInstallArgv(engine: GuestInstallableEngine, prefix: string, setupVersion: number): string[] {
  const install = ENGINE_WINDOWS_INSTALL[engine]
  if (!('npm' in install)) throw new Error(`${engine} has no npm install on Windows`)
  return [guestNodeExe(setupVersion), guestNpmCli(setupVersion), 'install', '--global', '--prefix', prefix,
    '--no-fund', '--no-audit', '--loglevel=error', install.npm]
}

/** What this helper needs of a terminal backend: make a pane, ask what it runs, read it, close it. */
export type GuestEngineBackend = Pick<TerminalBackend, 'create' | 'kill' | 'paneState' | 'capture'>

export interface GuestEngineOptions {
  user: string
  engine: string
  /** The guest's workspace: where both short panes run. */
  cwd: string
  /** The guest host's `engines` folder: where npm installs as the guest, and where the daemon later resolves the engine. */
  prefix: string
  setupVersion: number
  /** The person's language is not needed here: both panes only install and record their status. */
  checkTimeoutMs?: number
  installTimeoutMs?: number
  pollMs?: number
  sleep?: (ms: number) => Promise<void>
  now?: () => number
  log?: (line: string) => void
}

export type GuestEngineResult = { ok: true } | { ok: false; error: 'GUEST_ENGINE_UNSUPPORTED' | 'GUEST_ENGINE_CHECK_FAILED' | 'GUEST_ENGINE_INSTALL_FAILED'; detail: string }

/** The last lines a failed pane said, for the person to read as the reason. */
function tail(text: string, limit = 8): string {
  return text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-limit).join(' ').slice(0, 600)
}

async function waitForExit(backend: GuestEngineBackend, runtime: TerminalRuntimeRef,
  options: { timeoutMs: number; pollMs: number; sleep: (ms: number) => Promise<void>; now: () => number }): Promise<number | null> {
  const deadline = options.now() + options.timeoutMs
  for (;;) {
    const state = await backend.paneState(runtime)
    // A pane that is gone has no exit status to report; unknown is asked again until the deadline.
    if (state === 'gone') return null
    if (state !== 'unknown' && state.dead) return state.exitStatus
    if (options.now() >= deadline) return null
    await options.sleep(options.pollMs)
  }
}

/**
 * Makes sure [engine] is installed for [user], installing it in a pane on the guest's own host when it is not. Answers
 * a failure with the pane's own last words, so the person is told what npm said rather than "it did not work".
 */
export async function ensureGuestEngine(backend: GuestEngineBackend, options: GuestEngineOptions): Promise<GuestEngineResult> {
  if (!guestEngineInstallable(options.engine)) {
    return { ok: false, error: 'GUEST_ENGINE_UNSUPPORTED', detail: 'You can start Claude Code or Codex on this computer.' }
  }
  const engine = options.engine
  const log = options.log ?? (() => {})
  const pollMs = options.pollMs ?? 500
  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
  const now = options.now ?? Date.now
  const wait = { pollMs, sleep, now }

  const asked = await backend.create({ cwd: options.cwd, label: 'guest-engine-check', command: guestEngineProbeArgv(engine) })
  if (asked.state !== 'succeeded') {
    return { ok: false, error: 'GUEST_ENGINE_CHECK_FAILED', detail: asked.reason || 'The guest\'s host could not check for the engine.' }
  }
  const present = await waitForExit(backend, asked.runtime, { ...wait, timeoutMs: options.checkTimeoutMs ?? 30_000 })
  await backend.kill(asked.runtime)
  if (present === 0) return { ok: true }

  log(`install · ${engine} · ${options.user}${present === null ? ' · the check did not answer' : ''}`)
  const installing = await backend.create({ cwd: options.cwd, label: `guest-engine-install-${engine}`,
    command: guestEngineInstallArgv(engine, options.prefix, options.setupVersion) })
  if (installing.state !== 'succeeded') {
    return { ok: false, error: 'GUEST_ENGINE_INSTALL_FAILED', detail: installing.reason || 'The guest\'s host could not start the install.' }
  }
  const status = await waitForExit(backend, installing.runtime, { ...wait, timeoutMs: options.installTimeoutMs ?? 20 * 60_000 })
  const said = await backend.capture(installing.runtime, { historyLines: 60, ansi: false })
  await backend.kill(installing.runtime)
  if (status === 0) {
    log(`install · ${engine} · ${options.user} · done`)
    return { ok: true }
  }
  const words = said.state === 'succeeded' ? tail(said.value) : ''
  return { ok: false, error: 'GUEST_ENGINE_INSTALL_FAILED',
    detail: words || (status === null ? `Installing ${engine} did not finish in time. Try again from this computer.`
      : `Installing ${engine} failed on this computer (${status}).`) }
}