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.

14.5 KB
Raw Blame
/**
 * Which `grid` the sign-in hand-off runs.
 *
 * The hand-off carries the account token, so it has to run the SAME binary every other grid call
 * resolves to (`gridExec.ts`): the developer override, then the managed runtime, then PATH. A
 * hand-off that asked PATH on its own would sign in with one `grid` while models ran on another —
 * two versions writing one `~/.grid`. The token seam itself (stdin, never argv) is covered end to end
 * in `gridCommand.spec.ts`; this file is about WHICH child gets it, and that every kind of sign-in
 * reaches it.
 */
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'

let root = ''
let runtimeDir = ''
const saved = { PATH: process.env.PATH, HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, HARNESS_GRID_BIN: process.env.HARNESS_GRID_BIN, ADAPTER_RUNTIME_DIR: process.env.ADAPTER_RUNTIME_DIR }

/** `gridExec.ts` reads `env.ADAPTER_RUNTIME_DIR` at import time, so the module is loaded fresh per case. */
async function load() {
  vi.resetModules()
  process.env.ADAPTER_RUNTIME_DIR = runtimeDir
  return import('./gridHandoff.js')
}

/** A `grid` that records its argv and (on `login`) its standard input, under `label`. A shell script
 *  rather than a Node one, with `/bin/cat` by absolute path: several cases below run with an EMPTY
 *  PATH, where `#!/usr/bin/env node` — or a bare `cat` — would fail for a reason that has nothing to
 *  do with the resolution under test. */
function fakeGrid(dir: string, label: string): string {
  mkdirSync(dir, { recursive: true })
  const bin = join(dir, 'grid')
  writeFileSync(bin, [
    '#!/bin/sh',
    `printf '%s\\n' "$@" > "${join(root, `${label}.args`)}"`,
    `printf '%s' "\${GRID_NO_UPDATE_CHECK-unset}" > "${join(root, `${label}.update-check`)}"`,
    `[ "$1" = login ] && /bin/cat > "${join(root, `${label}.stdin`)}"`,
    'exit 0',
    '',
  ].join('\n'), { mode: 0o755 })
  return bin
}

function ran(label: string): boolean { return existsSync(join(root, `${label}.args`)) }
function argsOf(label: string): string[] { return readFileSync(join(root, `${label}.args`), 'utf8').trim().split('\n') }
function updateCheckSeenBy(label: string): string { return readFileSync(join(root, `${label}.update-check`), 'utf8') }

beforeEach(() => {
  root = mkdtempSync(join(tmpdir(), 'grid-handoff-'))
  runtimeDir = join(root, 'runtime')
  mkdirSync(runtimeDir)
  // Nothing on PATH unless a case puts something there — never this machine's own `grid`.
  mkdirSync(join(root, 'empty-bin'))
  process.env.PATH = join(root, 'empty-bin')
  // The resolver's last fallback is `$HOME/.local/bin/grid` (grid's own installer's path), so a
  // developer machine that has one must not leak into "nothing to run" (`USERPROFILE` is Windows' HOME).
  process.env.HOME = root
  process.env.USERPROFILE = root
  delete process.env.HARNESS_GRID_BIN
})

afterEach(() => {
  for (const [key, value] of Object.entries(saved)) {
    if (value === undefined) delete process.env[key]
    else process.env[key] = value
  }
  rmSync(root, { recursive: true, force: true })
})

describe('handOffToGrid — which grid it runs', () => {
  it('runs the grid HARNESS_GRID_BIN names, with nothing on PATH', async () => {
    const override = fakeGrid(join(root, 'elsewhere'), 'override')
    process.env.HARNESS_GRID_BIN = override
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_1', { json: true })

    expect(result.code).toBe('OK')
    expect(argsOf('override')).toEqual(['login', '--harness', '--json'])
    expect(readFileSync(join(root, 'override.stdin'), 'utf8')).toBe('tok_1\n')
    // grid's own "a newer version is out — run `grid update`" must never reach a binary the
    // harness pins: `update` would overwrite it in place. Off for every child this daemon spawns.
    expect(updateCheckSeenBy('override')).toBe('1')
  })

  it('waits while an install holds grid calls back (gridCalls.ts)', async () => {
    process.env.HARNESS_GRID_BIN = fakeGrid(join(root, 'elsewhere'), 'override')
    const { handOffToGrid } = await load()
    const { withGridCallsPaused } = await import('./gridCalls.js')
    let finish: () => void = () => {}
    const install = withGridCallsPaused(() => new Promise<void>((resolve) => { finish = resolve }))
    const call = handOffToGrid('tok_1', { json: true })
    // Spawning takes up to half a second on a busy Mac: give it well over that.
    await new Promise((resolve) => setTimeout(resolve, 2_000))
    expect(ran('override')).toBe(false)
    finish()
    await install
    expect((await call).code).toBe('OK')
  })

  it('prefers the managed runtime over a grid on PATH', async () => {
    fakeGrid(join(root, 'path-bin'), 'path')
    process.env.PATH = join(root, 'path-bin')
    const managed = fakeGrid(join(runtimeDir, 'grid-0.3.47-darwin-arm64'), 'managed')
    writeFileSync(join(runtimeDir, 'current-grid'), `${managed}\n`)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_2', { json: true })

    expect(result.code).toBe('OK')
    expect(argsOf('managed')).toEqual(['login', '--harness', '--json'])
    expect(ran('path')).toBe(false)
  })

  it('reports GRID_CLI_MISSING when neither the managed runtime nor PATH has one', async () => {
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_3', { json: true })

    expect(result).toMatchObject({ code: 'GRID_CLI_MISSING', exitCode: 1 })
    expect(result.message).toContain('grid')
  })
})

/**
 * A computer signed in by QR holds a Harness-issued sign-in. The hand-off used to refuse one before
 * `grid` was ever asked, because the control plane could only read Autonomous tokens. It now asks the
 * Harness backend who holds one (autonomous-grid ADR 0046), so accepting or refusing it is `grid`'s
 * answer to give, and this module passes the token on like any other.
 */
describe('handOffToGrid — a Harness-issued sign-in', () => {
  /** The shape the Harness backend issues (`backend/src/lib/harnessTokenFormat.ts`): `hna_` and 43
   *  base64url characters. The removed refusal matched on the prefix alone. */
  const HARNESS_ISSUED = `hna_${'Q'.repeat(43)}`

  it('hands it to grid on standard input, exactly as it does an Autonomous token', async () => {
    fakeGrid(join(root, 'path-bin'), 'path')
    process.env.PATH = join(root, 'path-bin')
    const { handOffToGrid } = await load()

    const result = await handOffToGrid(HARNESS_ISSUED, { json: true })

    expect(result).toMatchObject({ code: 'OK', exitCode: 0, message: '' })
    expect(argsOf('path')).toEqual(['login', '--harness', '--json'])
    expect(readFileSync(join(root, 'path.stdin'), 'utf8')).toBe(`${HARNESS_ISSUED}\n`)
  })
})

/**
 * What a refusal says. `grid` refuses on stderr, and under `--json` it writes one JSON line there —
 * `{"error": {"code", "message", "status"}}` (autonomous-grid `cli/json_error.py`) — before the
 * interpreter prints the same sentence in plain text. The daemon's Set up shows this module's
 * `message` and nothing else, so a refusal that names its own way forward has to arrive there, not
 * only on `stderr`.
 */
describe('handOffToGrid — grid\'s own refusal', () => {
  /** What the control plane says while Harness has not yet learned the account's Google identity
   *  (ADR 0046), rendered the way `grid` renders every control-plane refusal (`control_plane._raise`). */
  const SENTENCE = 'POST https://cp.example.test/v1/grid/auth/harness failed (409): {"detail":"Harness hasn\'t '
    + 'confirmed this account\'s Google identity yet, so nothing was changed. Sign in to Harness once with '
    + 'Google, Apple or your email on any device, then try again."}'
  const ENVELOPE = JSON.stringify({ error: { code: null, message: SENTENCE, status: 409 } })

  /** A `grid` that reads the token, writes `stderr` and exits `status`. The text goes through a file
   *  so no shell quoting stands between the test and the bytes `grid` would write. */
  function refusingGrid(dir: string, stderr: string, status: number): string {
    mkdirSync(dir, { recursive: true })
    const said = join(dir, 'stderr.txt')
    writeFileSync(said, stderr)
    const bin = join(dir, 'grid')
    writeFileSync(bin, ['#!/bin/sh', '/bin/cat > /dev/null', `/bin/cat "${said}" >&2`, `exit ${status}`, ''].join('\n'), { mode: 0o755 })
    return bin
  }

  it('carries the envelope\'s sentence as the message, and leaves stderr as grid wrote it', async () => {
    // The order the real `grid` writes them in: the envelope from `main()`'s handler, then the
    // interpreter's own print of the same `SystemExit` on its way out.
    const stderr = `${ENVELOPE}\n${SENTENCE}\n`
    process.env.HARNESS_GRID_BIN = refusingGrid(join(root, 'refuses'), stderr, 1)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_refused', { json: true })

    expect(result).toMatchObject({ code: 'GRID_LOGIN_FAILED', exitCode: 1, message: SENTENCE, stderr })
  })

  it('falls back to the exit code when grid wrote no envelope', async () => {
    process.env.HARNESS_GRID_BIN = refusingGrid(join(root, 'plain'), `${SENTENCE}\n`, 1)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_plain', { json: true })

    expect(result).toMatchObject({ code: 'GRID_LOGIN_FAILED', exitCode: 1, message: '`grid login --harness` exited 1.' })
  })

  it('falls back to the exit code when no envelope carries a sentence', async () => {
    const blank = JSON.stringify({ error: { code: 'some_code', message: ' \n ', status: 400 } })
    const none = JSON.stringify({ error: { code: null, message: null, status: null } })
    process.env.HARNESS_GRID_BIN = refusingGrid(join(root, 'blank'), `{not json\n${blank}\n${none}\n`, 1)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_blank', { json: true })

    expect(result.message).toBe('`grid login --harness` exited 1.')
  })

  it('reads no envelope without json: grid\'s stderr went to the terminal, uncaptured', async () => {
    process.env.HARNESS_GRID_BIN = refusingGrid(join(root, 'human'), `${ENVELOPE}\n${SENTENCE}\n`, 1)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_human')

    expect(result).toMatchObject({ code: 'GRID_LOGIN_FAILED', message: '`grid login --harness` exited 1.', stderr: '' })
  })

  it('still calls exit 2 an outdated grid, though argparse\'s refusal comes with an envelope too', async () => {
    // What a `grid` predating `--harness` writes under `--json`: argparse's `SystemExit(2)` carries no
    // sentence, so the envelope's is json_error's generic one — and "too old" is the only useful reading.
    const argparse = JSON.stringify({ error: { code: null, message: 'the command failed with exit status 2', status: null } })
    process.env.HARNESS_GRID_BIN = refusingGrid(join(root, 'old'), `${argparse}\nusage: grid login [-h]\n`, 2)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_old', { json: true })

    expect(result).toMatchObject({ code: 'GRID_CLI_OUTDATED', exitCode: 2 })
    expect(result.message).toContain('too old')
  })

  it('shows the sentence as one bounded line, whatever bytes the child put in it', async () => {
    // Astral characters past the bound: a cut by UTF-16 unit would leave half a surrogate pair.
    const noisy = `first line\nsecond\tline \u001b[31mred\u001b[0m \u009b2J \u202eagain\u2066\u200b. ${'\u{1F600}'.repeat(700)}`
    const envelope = JSON.stringify({ error: { code: null, message: noisy, status: 500 } })
    process.env.HARNESS_GRID_BIN = refusingGrid(join(root, 'noisy'), `${envelope}\n`, 1)
    const { handOffToGrid } = await load()

    const result = await handOffToGrid('tok_noisy', { json: true })

    expect(result.message.startsWith('first line second line [31mred [0m 2J again . \u{1F600}')).toBe(true)
    expect(result.message).not.toMatch(/[\p{Cc}\p{Cf}]/u)
    expect(result.message).not.toMatch(/\p{Surrogate}/u)
    expect(Array.from(result.message)).toHaveLength(600)
    expect(result.message.endsWith('\u{1F600}…')).toBe(true)
  })
})

/**
 * The watchdog. `grid login --harness` makes two control-plane round trips, and a connection that is
 * accepted and then answered by nobody used to leave this promise pending for good — a `harness
 * login` that never returned, and a daemon reconcile that never settled.
 */
describe('handOffToGrid — a child that never answers', () => {
  /** A `grid` that reads the token and then hangs, the shape of a black-holed control plane.
   *
   *  It IGNORES SIGTERM on purpose: that is the case the watchdog's `SIGKILL` exists for, and a fake
   *  that died politely would let a child which cannot be asked to stop pass as one that can. (The
   *  signal itself is not observable through this module's result — the kill and the settle happen
   *  together — so what this pins is that a TERM-immune child still ends the call.) */
  function hangingGrid(dir: string): string {
    mkdirSync(dir, { recursive: true })
    const bin = join(dir, 'grid')
    // Absolute paths, since PATH is empty here: Linux's sh exits 127 on a bare `sleep` before the watchdog fires.
    writeFileSync(bin, ['#!/bin/sh', "trap '' TERM", '/bin/cat > /dev/null', '/bin/sleep 60', ''].join('\n'), { mode: 0o755 })
    return bin
  }

  it('kills it and reports a timeout rather than awaiting forever', async () => {
    process.env.HARNESS_GRID_BIN = hangingGrid(join(root, 'hangs'))
    const { handOffToGrid } = await load()

    const started = Date.now()
    const result = await handOffToGrid('tok_hang', { json: true, timeoutMs: 300 })

    // It returned at all — the property the whole watchdog exists for.
    expect(Date.now() - started).toBeLessThan(10_000)
    // Classified as the ordinary failure rather than a new code, so every caller's existing
    // handling applies unchanged (the same choice `gridExec` makes for its own timeout).
    expect(result).toMatchObject({ code: 'GRID_LOGIN_FAILED', exitCode: 1 })
    expect(result.message).toContain('did not answer')
  }, 20_000)

  it('does not arm the timeout against a child that answers promptly', async () => {
    fakeGrid(join(root, 'prompt-bin'), 'prompt')
    process.env.HARNESS_GRID_BIN = join(root, 'prompt-bin', 'grid')
    const { handOffToGrid } = await load()

    // A timeout far shorter than the case would take if the timer were not cleared on success.
    const result = await handOffToGrid('tok_fast', { json: true, timeoutMs: 5_000 })

    expect(result.code).toBe('OK')
    expect(argsOf('prompt')).toEqual(['login', '--harness', '--json'])
  })
})