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
/**
 * Hand this computer's Harness access token to the `grid` CLI, so signing in to a grid needs no
 * second browser.
 *
 * **Every kind of sign-in goes to `grid`, and `grid` alone says no.** A browser sign-in holds an
 * Autonomous token; a computer signed in by QR holds a Harness-issued sign-in, whose token starts
 * `hna_`. This module used to refuse the second before `grid` was asked, because the control plane
 * could only read Autonomous tokens and a QR-signed computer was told to sign in again with Google or
 * Apple. The control plane now asks the Harness backend who holds either kind (autonomous-grid ADR
 * 0046), and a sign-in it cannot take — one that has lapsed, or an account whose Google identity
 * Harness has not yet learned — comes back as `grid`'s own refusal, which names its own way forward.
 * A check here would only be a second copy of that rule to fall out of step with it.
 *
 * The seam is a child process and nothing else: `grid login --harness` reads the token off its own
 * standard input, exchanges it at the control plane, and owns everything after that. This module's
 * whole job is to run that child honestly — put the credential somewhere a process listing cannot
 * reach, let its output and its exit code through, and turn the one exit code that means something
 * specific into a sentence.
 *
 * **Standard input, never argv and never the environment.** An argument would put a live account
 * credential into `ps` output for every user on the machine, for the life of the call; an environment
 * variable would put it in `/proc/<pid>/environ` and in anything the child later spawns.
 */
import { spawn } from 'node:child_process'
import { binaryOnPath } from './binaryOnPath.js'
import { gridEnvelopes } from './gridEnvelope.js'
import { gridCallStarted } from './gridCalls.js'
import { gridBinaryPath, gridChildEnv, gridCommand } from './gridExec.js'

/** The flag on `grid login` that means "read the token off stdin" (autonomous-grid's `cli/parser.py`).
 *  WHICH `grid` is not decided here: `gridBinaryPath()` (lib/gridExec.ts) answers that for every grid
 *  call alike — the developer override, then the managed runtime, then PATH — because this call
 *  carries the token, and a sign-in on one binary with models on another would be two versions
 *  writing one `~/.grid`. */
export const GRID_HANDOFF_FLAG = '--harness'

/**
 * argparse exits 2 on an unknown flag — BEFORE the handler, the network, or anything else in `grid`
 * runs. So a `grid` predating `--harness` fails here loudly and at once, which is what makes the
 * three-repo rollout order a deployment convenience rather than a correctness requirement.
 */
const ARGPARSE_USAGE_EXIT = 2

export type GridHandoffCode = 'OK' | 'GRID_CLI_MISSING' | 'GRID_CLI_OUTDATED' | 'GRID_LOGIN_FAILED'

export interface GridHandoffResult {
  code: GridHandoffCode
  /** The child's own exit code, propagated; 1 when there was no child, or it died on a signal. */
  exitCode: number
  /** What to show a person: `grid`'s own refusal under `json` ({@link refusalMessage}), else this
   *  module's classification. Empty on success. Never contains the token (`grid` redacts it). */
  message: string
  /** The child's stdout, captured only when `json` was asked for; otherwise it went straight out. */
  stdout: string
  /** The child's stderr — where `grid` writes every refusal — captured only when `json` was asked
   *  for, and passed through to this process's stderr either way. */
  stderr: string
}

/** A bound on what a child can put into one JSON line. `grid` answers a small document and refuses
 *  in a sentence or two, so this is not a tuning knob; it is a bound on a process whose output this
 *  one does not control, and it is applied to the CAPTURE only — the passthrough is untouched. */
const MAX_CAPTURED_CHARS = 64 * 1024

function capped(sofar: string, chunk: Buffer): string {
  return sofar.length >= MAX_CAPTURED_CHARS ? sofar : (sofar + chunk.toString()).slice(0, MAX_CAPTURED_CHARS)
}

const MISSING_MESSAGE =
  'No `grid` on PATH and no managed grid runtime, so there is nothing to hand this sign-in to. Install '
  + 'the grid CLI, then run `harness grid login` again.'

const OUTDATED_MESSAGE =
  `Your \`grid\` CLI is too old: it does not understand \`grid login ${GRID_HANDOFF_FLAG}\`. Update `
  + 'it, then run `harness grid login` again.'

/**
 * How long the child may take before it is killed and reported as a failure.
 *
 * ⚠️ Without this the spawn had no watchdog at all, unlike every other `grid` call
 * (`gridExec`'s `DEFAULT_TIMEOUT_MS`): a control plane that accepts the connection and then answers
 * nothing left this promise pending forever — a `harness login` that never returned, and, once the
 * daemon began reconciling on its own (`lib/gridAttach.ts`), an attempt that never settled.
 *
 * Longer than `gridExec`'s 30s on purpose. This child makes TWO control-plane round trips (the
 * token exchange, then the per-grid token fetch) where the others make one, and it is the call a
 * person is most likely to be watching — cutting a slow but working sign-in off would be worse than
 * waiting. It is a bound on a hang, not a performance budget.
 */
const HANDOFF_TIMEOUT_MS = 60_000

function timedOutMessage(timeoutMs: number): string {
  return `\`grid login ${GRID_HANDOFF_FLAG}\` did not answer within ${Math.round(timeoutMs / 1000)}s.`
}

function failedMessage(status: number | null, signal: NodeJS.Signals | null): string {
  const how = status === null ? `was killed by ${signal ?? 'a signal'}` : `exited ${status}`
  // No "see the output above": under --json there IS no above for whatever is reading the stream.
  // What `grid` said travels with the failure instead, on `stderr`.
  return `\`grid login ${GRID_HANDOFF_FLAG}\` ${how}.`
}

/** `grid`'s sentence off its `--json` envelope, or null: none written, or stderr never captured (no
 *  `json`). ⚠️ Found in ticket 03's review: Set up shows `message` alone, so a refusal naming its own
 *  remedy reached the person as "`grid login --harness` exited 1." It is `grid`'s to word (ADR 0046). */
function refusalMessage(stderr: string): string | null {
  return gridEnvelopes(stderr).find((envelope) => envelope.message !== null)?.message ?? null
}

/**
 * Run `grid login --harness`, writing `token` to its standard input and closing it.
 *
 * With `json`, the child is asked for JSON too and BOTH its streams are captured, so THIS process's
 * stdout stays a clean NDJSON stream for whatever is driving it. stderr is captured **and** written
 * straight back out, because it is needed twice: `grid` refuses on stderr, so that text is the only
 * actionable thing a failure has — and a client reading NDJSON off stdout would never see it, while
 * a person watching the terminal expects it where it has always been. Without `json` both streams
 * are inherited and the child talks to the terminal directly.
 */
export async function handOffToGrid(
  token: string,
  opts: { json?: boolean; timeoutMs?: number } = {},
): Promise<GridHandoffResult> {
  // Asking by reading rather than by spawning to find out: a missing `grid` is a sentence about
  // installing one, not a spawn error the caller has to recognise — and a present-but-unrunnable
  // one (EACCES, never ENOENT) is caught too. Resolved off this process's own environment, which is
  // the one place the override and the runtime dir are read from.
  const binary = gridBinaryPath()
  if (!binaryOnPath(binary)) {
    return { code: 'GRID_CLI_MISSING', exitCode: 1, message: MISSING_MESSAGE, stdout: '', stderr: '' }
  }
  const timeoutMs = opts.timeoutMs ?? HANDOFF_TIMEOUT_MS
  const args = ['login', GRID_HANDOFF_FLAG, ...(opts.json ? ['--json'] : [])]
  // Not while grid's installer replaces the install, and counted so an install waits for this (gridCalls.ts).
  const ended = await gridCallStarted()
  return await new Promise<GridHandoffResult>((resolve) => {
    const command = gridCommand(binary, args)
    let child: ReturnType<typeof spawn>
    try {
      child = spawn(command.file, command.args, {
        stdio: ['pipe', opts.json ? 'pipe' : 'inherit', opts.json ? 'pipe' : 'inherit'],
        // The human path inherits stderr, which is a terminal — exactly where grid would offer
        // `grid update` for a binary the harness pins. See GRID_NO_UPDATE_CHECK_VAR in gridExec.ts.
        env: gridChildEnv(),
      })
    } catch (error) {
      // Windows' application control refuses an unsigned program synchronously (UNKNOWN). The
      // hand-off reports every failure through its result, and an install waits on this counter.
      ended()
      resolve({
        code: 'GRID_LOGIN_FAILED',
        exitCode: 1,
        message: `Could not run \`${binary}\`: ${error instanceof Error ? error.message : String(error)}`,
        stdout: '',
        stderr: '',
      })
      return
    }
    let stdout = ''
    let stderr = ''
    child.stdout?.on('data', (chunk: Buffer) => { stdout = capped(stdout, chunk) })
    child.stderr?.on('data', (chunk: Buffer) => {
      stderr = capped(stderr, chunk)
      process.stderr.write(chunk) // the passthrough, unbounded — only the capture is bounded
    })

    let settled = false
    let timer: ReturnType<typeof setTimeout> | undefined
    const settle = (result: GridHandoffResult): void => {
      if (settled) return
      settled = true
      if (timer) clearTimeout(timer)
      ended()
      resolve(result)
    }

    // The watchdog, armed before anything can block. `SIGKILL` with no `SIGTERM` first, exactly as
    // `gridExec` does: what is being bounded is a child that has stopped responding, and a graceful
    // signal it may never handle is one more thing to wait for. The `close` this provokes finds
    // `settled` already true, so the kill reports the timeout rather than a signal death.
    timer = setTimeout(() => {
      try { child.kill('SIGKILL') } catch { /* already gone */ }
      settle({ code: 'GRID_LOGIN_FAILED', exitCode: 1, message: timedOutMessage(timeoutMs), stdout, stderr })
    }, timeoutMs)

    // stdio[0] is a pipe, so this is never null. Refusing loudly anyway rather than optional-chaining
    // past it: with no pipe the token is never delivered, and a `grid` left waiting for one on a
    // stdin nobody will close would hang with nothing on screen from either process.
    const { stdin } = child
    if (!stdin) {
      child.kill()
      settle({ code: 'GRID_LOGIN_FAILED', exitCode: 1, message: `Could not open a pipe to \`${binary}\`.`, stdout, stderr })
      return
    }

    // Between the PATH check and the spawn the binary can still be gone; and a child that exits
    // before reading breaks the pipe. Both are the child's story to tell, never a crash here.
    child.once('error', (err: NodeJS.ErrnoException) => settle(err.code === 'ENOENT'
      ? { code: 'GRID_CLI_MISSING', exitCode: 1, message: MISSING_MESSAGE, stdout, stderr }
      : { code: 'GRID_LOGIN_FAILED', exitCode: 1, message: `Could not run \`${binary}\`: ${err.message}`, stdout, stderr }))
    stdin.on('error', () => { /* EPIPE — see above */ })

    // A trailing newline as well as the close: `grid` reads one bounded LINE, so the hand-off does
    // not depend on which of the two it notices first.
    stdin.end(`${token}\n`)

    // `close`, not `exit`: the captured stdout must be complete before it is reported.
    child.once('close', (status, signal) => {
      if (status === 0) { settle({ code: 'OK', exitCode: 0, message: '', stdout, stderr }); return }
      if (status === ARGPARSE_USAGE_EXIT) { settle({ code: 'GRID_CLI_OUTDATED', exitCode: status, message: OUTDATED_MESSAGE, stdout, stderr }); return }
      settle({ code: 'GRID_LOGIN_FAILED', exitCode: status ?? 1, message: refusalMessage(stderr) ?? failedMessage(status, signal), stdout, stderr })
    })
  })
}