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.

16.2 KB
Raw Blame
// Claude Code, Codex and OpenCode created through the daemon's own create path (core/agents/create.ts, its native
// inspection, launch argv and pane request) on the real Harness PTY host, with no POSIX shell anywhere. Windows only,
// on a machine where the engines are installed (and Claude Code and Codex signed in). Build the host first:
//   cd pty && cargo build
//   cd cli && set HARNESS_PTY_BIN=C:\...\pty\target\debug\harness-pty.exe && npx vitest run src/lib/windows/engineStart.real.spec.ts
// Engine hooks are not installed (DISABLE_HOOK_INSTALL's path): their POSIX ownership checks are another task's.
import { copyFileSync, existsSync, mkdirSync, mkdtempSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
import { createAgentCreator, type CreateAgentDeps } from '../../core/agents/create.js'
import { heldPaneArgv } from '../../core/agents/heldLaunches.js'
import { captureLaunchExecutable } from '../../engines/kit/launchExecutable.js'
import { inspectNativeLaunch } from '../../engines/nativeLaunch.js'
import type { AgentEngine } from '../../engines/types.js'
import { PtyHostBackend } from '../ptyHostBackend.js'
import { listDiscoveries } from '../ptyHost/launch.js'
import { PTY_PROTOCOL } from '../ptyHost/protocol.js'
import { processRows } from '../processTable.js'
import { registry, type RegisteredSession } from '../registry.js'
import { removeTree } from '../terminalBackend.contract.js'
import type { PtyRuntimeRef } from '../terminalTypes.js'
import { windowsAfterExit } from './engineStart.js'

const enabled = process.platform === 'win32' && !!process.env.HARNESS_PTY_BIN
const CASE_TIMEOUT_MS = 120_000
const POSIX_ONLY = /^(?:\/bin\/(?:sh|dash|bash|zsh)|\/usr\/bin\/env)$/

async function until<T>(read: () => T | Promise<T>, ok: (value: T) => boolean, ms = 30_000): Promise<T> {
  const end = Date.now() + ms
  for (;;) {
    const value = await read()
    if (ok(value) || Date.now() > end) return value
    await new Promise((resolve) => setTimeout(resolve, 250))
  }
}

async function withBackend(run: (backend: PtyHostBackend) => Promise<void>): Promise<void> {
  const home = mkdtempSync(join(tmpdir(), 'pty-engines-'))
  const backend = new PtyHostBackend({ home })
  try {
    const prepared = await backend.prepare({ ownedPanes: new Map() })
    if (prepared.state !== 'ready') throw new Error(`the pty host is unavailable: ${prepared.reason}`)
    await run(backend)
  } finally {
    const discovery = listDiscoveries(home).findLast((found) => found.protocol === PTY_PROTOCOL)
    backend.dispose()
    if (discovery) try { process.kill(discovery.pid) } catch { /* gone */ }
    removeTree(home)
  }
}

/** The core's creator with the real native inspection, registry and pty host; every service it would ask is absent. */
function creator(backend: PtyHostBackend) {
  const unused = async () => { throw new Error('not used here') }
  const deps: CreateAgentDeps = {
    native: (engine, source) => inspectNativeLaunch(engine, source),
    createBackend: backend,
    noBackendCode: 'PTY_HOST_UNAVAILABLE',
    registry,
    externalResume: unused,
    watchNewPane: (async () => {}) as unknown as CreateAgentDeps['watchNewPane'],
    announceSession: () => {},
    attachDsh: () => {},
    prepareApiTools: () => {},
    hookPort: 0,
    hooksDisabled: true,
    installOpencodePlugin: async () => true,
    gridLaunchMachine: unused as unknown as CreateAgentDeps['gridLaunchMachine'],
    buildGridLaunch: unused,
    terminalHintMachineName: () => 'windows-vm',
    blocksFolder: () => false,
    gridSetup: () => null,
    privateGridName: async () => null,
    dshLaunch: { materialize: unused, launch: unused } as unknown as CreateAgentDeps['dshLaunch'],
  }
  return createAgentCreator(deps)
}

const request = (engine: AgentEngine, cwd: string) => ({
  engine, cwd, bypassPermission: false, permissionMode: null, grid: null, codexHome: null, dsh: null, prompt: null,
  name: null, agent: null, scmLaunchRecord: null, startedBy: null, parentAgentId: null,
}) as unknown as Parameters<ReturnType<typeof createAgentCreator>>[0]

/** Create [engine] through the core and wait for its process in the pane's Job; the evidence, for the report. */
async function created(backend: PtyHostBackend, engine: AgentEngine) {
  const cwd = mkdtempSync(join(tmpdir(), `ws-${engine}-`))
  const answer = await creator(backend)(request(engine, cwd))
  if (!answer.ok) throw new Error(`create ${engine}: ${JSON.stringify(answer)}`)
  const session = (answer as { session: RegisteredSession }).session
  const runtime = session.runtimes[0] as PtyRuntimeRef
  const host = (backend as unknown as { client: { call(op: object): Promise<{ state: string; value?: Record<string, unknown> }> } }).client
  const state = await host.call({ op: 'paneState', pane: runtime.paneId })
  const command = ((state.value?.state as { command?: string[] })?.command) ?? []
  console.log(`[${engine}] pane ${runtime.paneId} command ${JSON.stringify(command)}`)
  expect(command.filter((arg) => POSIX_ONLY.test(arg))).toEqual([])
  const validation = await until(() => backend.validate(runtime, { engine }), (v) => v.state === 'alive', 45_000)
  return { cwd, runtime, host, command, validation }
}

;(enabled ? describe : describe.skip)('engines created on the real pty host', () => {
  registry.load()

  // A grid launch's provider keys: the host inherited them from the daemon, and a pane told to clear them must not see
  // them, in any case of the name, while the rest of what it inherits stays (security; lib/windows/engineStart.ts).
  it('keeps the names a launch clears from what the host inherited, in any case, for that launch and its hand-off', async () => {
    const saved = { key: process.env.ANTHROPIC_API_KEY, kept: process.env.HN_KEPT_VARIABLE }
    process.env.ANTHROPIC_API_KEY = 'sk-person-secret'
    process.env.HN_KEPT_VARIABLE = 'kept'
    try {
      await withBackend(async (backend) => {
        const show = ['cmd.exe', '/d', '/k', 'echo [%ANTHROPIC_API_KEY%][%HN_KEPT_VARIABLE%][%GRID_KEY%]']
        for (const clearEnv of [['ANTHROPIC_API_KEY'], ['anthropic_api_key']]) {
          const created = await backend.create({ command: show, env: { GRID_KEY: 'grid' }, clearInherited: clearEnv })
          if (created.state !== 'succeeded') throw new Error(`create failed: ${JSON.stringify(created)}`)
          const seen = await until(() => backend.capture(created.runtime, { mode: 'visible', ansi: false }),
            (s) => s.state === 'succeeded' && s.value.includes('][kept][grid]'))
          expect(seen.state === 'succeeded' && seen.value).toContain('[%ANTHROPIC_API_KEY%][kept][grid]')
          expect(seen.state === 'succeeded' && seen.value).not.toContain('sk-person-secret')
          await backend.kill(created.runtime)
        }
        // Without the name cleared the child does see it: the host really has it.
        const plain = await backend.create({ command: show })
        if (plain.state !== 'succeeded') throw new Error('create failed')
        const leaked = await until(() => backend.capture(plain.runtime, { mode: 'visible', ansi: false }),
          (s) => s.state === 'succeeded' && s.value.includes('[sk-person-secret]'))
        expect(leaked.state === 'succeeded' && leaked.value).toContain('[sk-person-secret][kept]')
        await backend.kill(plain.runtime)
        // The engine's respawn and the shell it hands the pane to stay without it.
        const engine = await backend.create({ command: ['cmd.exe', '/c', 'exit 4'], clearInherited: ['ANTHROPIC_API_KEY'],
          afterExit: { command: show } })
        if (engine.state !== 'succeeded') throw new Error('create failed')
        const handed = await until(() => backend.capture(engine.runtime, { mode: 'visible', ansi: false }),
          (s) => s.state === 'succeeded' && s.value.includes('][kept]'))
        expect(handed.state === 'succeeded' && handed.value).toContain('[%ANTHROPIC_API_KEY%][kept]')
        // Per launch: a respawn with its own list clears that list alone; the last launch's names are back.
        await backend.respawn(engine.runtime, { command: show, clearInherited: ['HN_KEPT_VARIABLE'] })
        const respawned = await until(() => backend.capture(engine.runtime, { mode: 'visible', ansi: false }),
          (s) => s.state === 'succeeded' && s.value.includes('[%HN_KEPT_VARIABLE%]'))
        expect(respawned.state === 'succeeded' && respawned.value).toContain('[sk-person-secret][%HN_KEPT_VARIABLE%]')
        // And one that sends none (an agent moved off its grid) clears nothing the host inherited.
        await backend.respawn(engine.runtime, { command: show })
        const home = await until(() => backend.capture(engine.runtime, { mode: 'visible', ansi: false }),
          (s) => s.state === 'succeeded' && s.value.includes('[sk-person-secret][kept]'))
        expect(home.state === 'succeeded' && home.value).toContain('[sk-person-secret][kept]')
        await backend.kill(engine.runtime)
      })
    } finally {
      if (saved.key === undefined) delete process.env.ANTHROPIC_API_KEY; else process.env.ANTHROPIC_API_KEY = saved.key
      if (saved.kept === undefined) delete process.env.HN_KEPT_VARIABLE; else process.env.HN_KEPT_VARIABLE = saved.kept
    }
  }, CASE_TIMEOUT_MS)

  it('hands a pane to cmd.exe, where there is no PowerShell, without leaving the engine\'s variables in it', async () => {
    await withBackend(async (backend) => {
      const created = await backend.create({ command: ['cmd.exe', '/c', 'exit 5'], afterExit: windowsAfterExit('codex', [process.env.ComSpec ?? 'cmd.exe']) })
      if (created.state !== 'succeeded') throw new Error('create failed')
      await until(() => backend.paneState(created.runtime), (p) => typeof p !== 'string' && p.engineExit === 5)
      await new Promise((resolve) => setTimeout(resolve, 1_000))
      await backend.typeLiteral(created.runtime, 'echo [%HARNESS_ENGINE_COMMAND%][%HARNESS_ENGINE_EXIT%][%HARNESS_PANE:~0,1%]\n')
      const seen = await until(() => backend.capture(created.runtime, { mode: 'visible', ansi: false }),
        (s) => s.state === 'succeeded' && /^\[%HARNESS_ENGINE_COMMAND%\]/m.test(s.value))
      expect(seen.state === 'succeeded' && seen.value).toMatch(/^\[%HARNESS_ENGINE_COMMAND%\]\[%HARNESS_ENGINE_EXIT%\]\[p\]/m)
      expect(await backend.paneState(created.runtime)).toMatchObject({ dead: false, engineExit: 5 })
      await backend.kill(created.runtime)
    })
  }, CASE_TIMEOUT_MS)

  it('holds a pane in the daemon\'s Node, which says why and outlasts Ctrl-C', async () => {
    await withBackend(async (backend) => {
      const token = '0f0e0d0c-0b0a-4908-8706-050403020100'
      const created = await backend.create({ command: heldPaneArgv('Waiting for the Store.', token) })
      if (created.state !== 'succeeded') throw new Error(`create failed: ${JSON.stringify(created)}`)
      const shown = await until(() => backend.capture(created.runtime, { mode: 'visible', ansi: false }),
        (s) => s.state === 'succeeded' && s.value.includes('Waiting for the Store.'))
      expect(shown.state === 'succeeded' && shown.value).toContain('Waiting for the Store.')
      expect(await backend.isHeld(created.runtime, token)).toBe(true)
      const host = (backend as unknown as { client: { call(op: object): Promise<unknown> } }).client
      await host.call({ op: 'key', pane: created.runtime.paneId, key: 'C-c' })
      await host.call({ op: 'write', pane: created.runtime.paneId, data: Buffer.from('\u0003').toString('base64') })
      await new Promise((resolve) => setTimeout(resolve, 1_500))
      expect(await backend.paneState(created.runtime)).toMatchObject({ dead: false })
      expect(await backend.rootProcess(created.runtime)).toEqual(expect.any(Number))
      await backend.kill(created.runtime)
    })
  }, CASE_TIMEOUT_MS)

  for (const engine of ['claude', 'codex', 'opencode'] as const) {
    it(`starts ${engine} with no POSIX shell, its process in the pane's Job, and the pane a shell after it`, async (context) => {
      // Found as the launch finds it (engines/kit/launchExecutable.ts). Only an engine that is not installed (CI's
      // runners, where the launch would install it first) skips, saying so; any other hold is a failure to read.
      const found = await captureLaunchExecutable(engine)
      if (found.state === 'install') context.skip(`${engine} is not installed here`)
      if (found.state === 'held') throw new Error(`${engine}'s launch could not resolve its executable: ${found.detail}`)
      await withBackend(async (backend) => {
        const home = process.env.HOME
        if (engine === 'codex') {
          // Codex's own login, in a home of the test's: the pane starts it with CODEX_HOME there. One that lasts from
          // run to run: Codex 0.162.1 migrating a new state_5.sqlite raced itself one start in four ("index
          // idx_threads_project_recency already exists", then exit 1), and it puts no helpers under a temporary folder.
          process.env.HOME = join(process.env.LOCALAPPDATA ?? tmpdir(), 'harness-engine-start-test')
          const auth = join(process.env.USERPROFILE ?? '', '.codex', 'auth.json')
          mkdirSync(join(process.env.HOME, '.codex'), { recursive: true })
          if (existsSync(auth)) copyFileSync(auth, join(process.env.HOME, '.codex', 'auth.json'))
        }
        try {
        const { cwd, runtime, host, command, validation } = await created(backend, engine)
        const job = await host.call({ op: 'jobPids', pane: runtime.paneId })
        const pids = (job.value?.pids as number[] | undefined) ?? []
        const rows = (await processRows()) ?? []
        const inJob = rows.filter((row) => pids.includes(row.pid)).map((row) => `${row.pid} <- ${row.parentPid} ${row.args.slice(0, 160)}`)
        console.log(`[${engine}] validate ${JSON.stringify(validation)}\n[${engine}] job:\n  ${inJob.join('\n  ')}`)
        if (engine === 'codex') expect(command).toContain('--no-daemon')
        // A few seconds on, the engine still runs in its own folder: its interactive start, not a quick exit.
        await new Promise((resolve) => setTimeout(resolve, 6_000))
        const screen = await backend.capture(runtime, { historyLines: 60, ansi: false })
        const pane = await backend.paneState(runtime)
        console.log(`[${engine}] after 6 s: ${JSON.stringify(pane)}\n[${engine}] screen:\n${screen.state === 'succeeded' ? screen.value.split('\n').filter((l) => l.trim()).slice(-30).join('\n') : screen.reason}`)
        const info = await backend.paneInfo(runtime)
        console.log(`[${engine}] pane info ${JSON.stringify(info)} (workspace ${cwd})`)
        expect(validation.state).toBe('alive')
        const history = screen.state === 'succeeded' ? screen.value : ''
        // OpenCode's terminal UI cannot load on Windows on Arm: its build has no bun:ffi (measured, OpenCode 1.19.0 on
        // the arm64 VM, 2026-10-15). It starts in the pane's Job, then exits of its own accord, and the pane hands on.
        const unsupported = engine === 'opencode' && process.arch === 'arm64' && /bun:ffi dlopen\(\) is not available/.test(history)
        if (!unsupported) {
          expect(pane).toMatchObject({ dead: false, engineExit: null })
          expect(info?.path.toLowerCase()).toBe(cwd.toLowerCase())
          // The engine ends: the pane is the person's shell, and the daemon reads why.
          backend.signalProcess(info!.pid!, 'SIGTERM')
        }
        const after = await until(() => backend.paneState(runtime), (p) => typeof p !== 'string' && p.engineExit !== null, 30_000)
        const shell = await until(() => backend.capture(runtime, { mode: 'visible', ansi: false }),
          (s) => s.state === 'succeeded' && /exited \(-?\d+\)\. This pane is a shell now/.test(s.value), 20_000)
        console.log(`[${engine}] after the engine: ${JSON.stringify(after)}\n${shell.state === 'succeeded' ? shell.value.split('\n').filter((l) => l.trim()).slice(-4).join('\n') : ''}`)
        expect(after).toMatchObject({ dead: false })
        expect(typeof after !== 'string' && after.engineExit).not.toBeNull()
        expect(typeof after !== 'string' && after.command).toMatch(/^(?:pwsh|powershell|cmd)\.exe$/i)
        expect(shell.state === 'succeeded' && shell.value).toMatch(new RegExp(`harness: ${engine} exited \\(-?\\d+\\)\\. This pane is a shell now`))
        await backend.kill(runtime)
        } finally { process.env.HOME = home }
      })
    }, CASE_TIMEOUT_MS)
  }
})