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.6 KB
Raw Blame
/**
 * How an engine starts in a Windows pane. Windows has no POSIX shell to run Harness's launch script in
 * (lib/engineLaunch.ts `buildEngineLaunchArgv`), so the pane's command is the engine itself (lib/windows/launch.ts),
 * and what that script does on Unix is done here, by the daemon, or by the pty host:
 *
 * - The screen's variables and a native launch's marker: the pane's env (`engineLaunchEnv`).
 * - `cd` into the workspace after the rc files: there are no rc files, so the pane starts in it (`windowsPaneLaunch`).
 * - Codex's owned-process probe (`--no-daemon`): the daemon reads the engine's help as it inspects the launch
 *   (engines/nativeLaunch.ts `startupArgs`), and the flag goes first in the argv (`windowsStartupArgs`). A launch with
 *   no such answer is refused, as the script ends one whose probe could not answer.
 * - Codex's startup retry reads the pane through tmux, and a Windows pane has none: off, as it is on Unix's pty host.
 * - The native guard (the prepared executable and settings are still the ones confirmed): checked as the argv is built
 *   (`nativeLaunchConfirmed`). A launch whose evidence changed opens a held pane instead (`windowsHeldPaneArgv`), which
 *   a respawn under its token replaces once the launch is prepared again, as on the pty host elsewhere.
 * - `harness_after`, the engine's exit turning the pane into the person's shell with its status recorded where the
 *   daemon reads it: the pty host does it, given `afterExit` (pty/src/panes.rs `hand_off`), with
 *   `defaultWindowsShell()`. PowerShell says what happened, as the script does; cmd.exe says nothing.
 * - The variables a grid launch clears (`unset`): the pty host leaves them out of what the engine inherits from the
 *   host's own environment (`clearInherited`, `windowsPaneLaunch`).
 * - Not done: an install before the engine and a take-over's wait (no script to run them in), Harness's Node at the
 *   end of PATH, the open-files raise and the stop handling, which Windows has no counterpart of.
 *
 * Every value the shells are given travels in their environment, never in their command text.
 */
import { win32 } from 'node:path'
import type { NativeLaunch } from '../../engines/nativeLaunch.js'
import { startupOwnedFlag } from '../../engines/kit/launchStartup.js'
import { launchContract } from '../../engines/launches.js'
import { isTerminalEngine, type AgentEngine } from '../../engines/types.js'
import { baseNode } from '../../harnessd/baseNode.js'
import { engineBin } from '../engineBin.js'
import { GRID_NO_UPDATE_CHECK_VAR, gridBinaryPath } from '../gridBinary.js'
import { managedNodePath } from '../nodeRuntime.js'
import type { TerminalAfterExit } from '../terminalTypes.js'
import { WindowsLaunchRefused } from './launch.js'
import { defaultWindowsShell } from './shell.js'

/** A launch whose engine declares a startup probe (Codex's owned-process flag) that nobody answered for it. */
export class WindowsStartupUnverified extends WindowsLaunchRefused {
  constructor(readonly engine: string, unverified: string) {
    super(`${unverified.charAt(0).toUpperCase()}${unverified.slice(1)}`)
    this.name = 'WindowsStartupUnverified'
  }
}

/**
 * The arguments [engine]'s declared startup puts first on Windows: its owned-process flag when the engine's help lists
 * it, as the launch script's probe decides elsewhere (engines/kit/launchStartup.ts). The answer is the native launch's,
 * read from the help of the very executable it holds; without one the launch is refused rather than started on the
 * shared server the flag keeps it off.
 */
export function windowsStartupArgs(engine: AgentEngine, native: Pick<NativeLaunch, 'startupArgs'> | undefined): string[] {
  const owned = startupOwnedFlag(launchContract(engine))
  if (!owned) return []
  if (!native?.startupArgs) throw new WindowsStartupUnverified(engine, owned.unverified)
  return [...native.startupArgs]
}

/**
 * Whether a native launch may still run its prepared executable: what the launch script's guard checks after the rc
 * files (engines/kit/nativeLaunchGuard.ts), asked of the launch itself as the argv is built. Nothing runs between this
 * and the engine on Windows but the pane's creation.
 */
export function nativeLaunchConfirmed(native: Pick<NativeLaunch, 'executable' | 'ready' | 'proofs'>): boolean {
  if (!native.executable) return true
  return native.ready?.() !== false && native.executable.current() && native.proofs.every((proof) => proof.current())
}

/**
 * A held pane on Windows: it says why, waits, and survives Ctrl-C and Ctrl-Break, as the `/bin/sh` loop does elsewhere
 * (core/agents/heldLaunches.ts `heldPaneArgv`). Run by the daemon's own Node, the detail and the token as arguments:
 * the start command must carry `harness-held` and the token, which is how the daemon and the host know a held pane
 * (lib/nativePaneHold.ts `isHeldStartCommand`, pty/src/panes.rs `held_by`).
 */
export function windowsHeldPaneArgv(detail: string, token?: string, node: string = baseNode(process.execPath)): string[] {
  const script = 'for(const s of ["SIGINT","SIGBREAK","SIGHUP"])process.on(s,()=>{});'
    + 'process.stdout.write(process.argv[2]+"\\r\\n");setInterval(()=>{},3600000)'
  const argv = [node, '-e', script, 'harness-held', detail, ...(token ? [token] : [])]
  HELD_PANES.add(argv)
  return argv
}

/** The argv `windowsHeldPaneArgv` made, by identity: never what an argv says, which a person's prompt can say too. */
const HELD_PANES = new WeakSet<readonly string[]>()

/** Whether [argv] is a held pane's, as `windowsHeldPaneArgv` made it (`buildEngineLaunchArgv` returns it as it is). */
export function isWindowsHeldPane(argv: readonly string[]): boolean {
  return HELD_PANES.has(argv)
}

/**
 * What PowerShell runs before its prompt in a pane an engine has left, read from the environment the host gives it
 * (`HARNESS_ENGINE_EXIT`, the engine's status; `HARNESS_ENGINE_COMMAND`, its name): the line a Unix pane prints in
 * `harness_after`. Both are then taken out, so the person's shell does not keep them.
 */
export const ENGINE_EXIT_NOTICE_PS = "Write-Host ''; Write-Host ('harness: ' + $env:HARNESS_ENGINE_COMMAND + ' exited ('"
  + " + $env:HARNESS_ENGINE_EXIT + '). This pane is a shell now - run ' + $env:HARNESS_ENGINE_COMMAND + ' again, or stop"
  + " the pane.'); Remove-Item Env:HARNESS_ENGINE_COMMAND, Env:HARNESS_ENGINE_EXIT -ErrorAction SilentlyContinue"

/** What cmd.exe, the shell where there is no PowerShell, runs first: both variables taken out again, fixed text. */
export const ENGINE_EXIT_CLEAR_CMD = 'set HARNESS_ENGINE_COMMAND=& set HARNESS_ENGINE_EXIT='

/** The shell a Windows engine's pane becomes when the engine exits (`afterExit`), named by [command] in its notice. */
export function windowsAfterExit(command: string, shell: string[] = defaultWindowsShell()): TerminalAfterExit {
  const powershell = /^(?:pwsh|powershell)(?:\.exe)?$/i.test(shell[0]!.split(/[\\/]/).pop()!)
  return {
    command: powershell ? [...shell, '-NoExit', '-Command', ENGINE_EXIT_NOTICE_PS] : [...shell, '/k', ENGINE_EXIT_CLEAR_CMD],
    env: { HARNESS_ENGINE_COMMAND: command },
  }
}

/** What a pane request takes beside its argv on Windows (`windowsPaneLaunch`). */
export interface WindowsPaneLaunch {
  /** The folder the engine starts in: the workspace, which a Unix launch enters after the rc files. */
  cwd?: string
  afterExit?: TerminalAfterExit
  /**
   * Names this launch's engine, and the shell it hands the pane to, must not get from the host's own environment: the
   * launch's `clearEnv` (a grid launch's provider keys, lib/gridLaunch.ts) and the native launch's `clearEnvironment`,
   * which the script unsets elsewhere. The host inherited the daemon's environment, so without this a grid launch saw
   * the person's ANTHROPIC_API_KEY. Per launch, as the script's unset is: an agent moved home gets them back.
   */
  clearInherited?: string[]
  /**
   * What the Unix launch script adds to an engine's pane and Windows had no counterpart of: grid's folder at the
   * front of PATH and Harness's Node at the end, so an agent's own tool calls find both, and grid's update check off
   * (GRID_NO_UPDATE_CHECK_VAR) so an agent never replaces the grid this daemon pinned.
   */
  env?: Record<string, string>
}

/** The launch facts `windowsPaneLaunch` reads: its options (lib/engineLaunch.ts `LaunchCommandOptions`). */
export interface WindowsPaneLaunchOptions {
  cwd?: string | null
  clearEnv?: readonly string[]
  native?: Pick<NativeLaunch, 'clearEnvironment'>
  /** The argv is a held pane's (`isWindowsHeldPane`), which hands off to nothing. */
  held?: boolean
  /** The environment the pane's PATH is built from. `process.env` unless a test hands in one. */
  environment?: NodeJS.ProcessEnv
  /** The grid and Node the pane's PATH names. Resolved here unless a test hands them in. */
  gridBinary?: string
  nodeRuntime?: string
}

/**
 * The cwd, cleared names and hand-off of a Windows pane for [engine], to spread into its create or respawn request;
 * nothing elsewhere, where the launch script enters the workspace, unsets the names and hands the pane on itself. A
 * terminal or a held pane hands off to nothing: its process ending is the pane's end. The notice names the engine by
 * the command a person would type (`cursor-agent`, `command-code`), as `harness_after`'s does.
 */
export function windowsPaneLaunch(engine: AgentEngine, launch: WindowsPaneLaunchOptions,
  platform: NodeJS.Platform = process.platform): WindowsPaneLaunch {
  if (platform !== 'win32') return {}
  const clearInherited = [...new Set([...(launch.clearEnv ?? []), ...(launch.native?.clearEnvironment ?? [])])]
  const enginePane = !isTerminalEngine(engine) && !launch.held
  return {
    ...(launch.cwd ? { cwd: launch.cwd } : {}),
    ...(clearInherited.length ? { clearInherited } : {}),
    ...(enginePane ? { env: windowsPaneEnv(launch) } : {}),
    ...(enginePane ? { afterExit: windowsAfterExit(engineBin(engine, platform).split(/[\\/]/).pop() || engine) } : {}),
  }
}

/** The first and last PATH entries an engine's Windows pane needs, and grid's update check off. */
function windowsPaneEnv(launch: WindowsPaneLaunchOptions): Record<string, string> {
  // A test that fakes the platform has no Windows environment to read; it passes one, or gets only
  // the update switch. On Windows itself the daemon's own environment is the pane's base.
  const real = process.platform === 'win32'
  const environment = launch.environment ?? (real ? process.env : {})
  const grid = launch.gridBinary ?? (real ? gridBinaryPath(environment) : '')
  const node = launch.nodeRuntime ?? (real ? managedNodePath() : '')
  // Windows names it `Path` as often as `PATH`, and a second spelling would be a duplicate the OS
  // may resolve to the inherited one: measured on DESKTOP-0TFH0OJ, 2026-11-05, the new `PATH` was
  // ignored and the agent's shell did not see Harness's Node.
  const pathName = Object.keys(environment).find((key) => key.toLowerCase() === 'path') ?? 'PATH'
  const parts = (environment[pathName] ?? '').split(';').filter((part) => part.length > 0)
  // grid's own folder first, so a managed grid a shell's PATH cannot see is the one the agent runs;
  // Harness's Node last, because a `node` the person installed still comes first, as on Unix.
  if (/[\\/]/.test(grid)) prependOnce(parts, win32.dirname(grid))
  if (node) appendOnce(parts, win32.dirname(node))
  return {
    ...(parts.length ? { [pathName]: parts.join(';') } : {}),
    [GRID_NO_UPDATE_CHECK_VAR]: '1',
  }
}

function prependOnce(parts: string[], dir: string): void {
  if (!parts.some((part) => part.toLowerCase() === dir.toLowerCase())) parts.unshift(dir)
}

function appendOnce(parts: string[], dir: string): void {
  if (!parts.some((part) => part.toLowerCase() === dir.toLowerCase())) parts.push(dir)
}