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.

13.7 KB
Raw Blame
/**
 * Bring this machine's grid sign-in into line with its harness sign-in — when a grid feature needs it.
 *
 * Grid is an add-on to Harness, not part of signing in: a person who never touches local or shared
 * models never gets a `grid` binary, a grid sign-in or a grid of their own. The first time something
 * does need grid — "Set up" on the models picker's local and shared models, a local model's Get or
 * Use, an agent moved onto a grid model, the Model Manager — the daemon calls [GridAccess.ensure],
 * which installs `grid` if it is missing, hands this machine's harness token to `grid login --harness`
 * over stdin (no second browser, `gridHandoff.ts`), and — only for what needs one — makes sure the
 * account's private grid exists. It used to run on every daemon start and every backend reconnect,
 * and signing in to Harness did it too; neither does now.
 *
 * **Silent account switch.** When this machine is signed in to grid as a *different* account, the
 * hand-off overwrites it without asking, matching `grid login`'s own rule (a swap is a line, never a
 * refusal): Harness's grid features run as the Harness account or not at all. `grid login --harness`
 * never touches a running `grid join --serve` child; it only warns about one whose grid has gone.
 *
 * **Cheap when there is nothing to do.** The gate is almost entirely offline (a file read and one
 * `grid ls` that makes no network call) plus one idempotent `POST /api/grid/name`, and a success is
 * remembered for the daemon's life ([createGridAccess]), so the acts that ask again pay nothing.
 */

import { gridJson } from './gridExec.js'
import type { GridHandoffResult } from './gridHandoff.js'
import type { EnsureResult, EnsureStatus } from './gridEnsure.js'

export type GridAttachStatus =
  /** No `grid` on this machine — there is nothing to attach a sign-in to. */
  | 'no-cli'
  /** The backend issued no grid name (an older backend, or the control plane was unreachable). */
  | 'no-name'
  /** This machine's `grid` already knows the account's grid — signed in as the right account, grid
   *  present. Nothing was changed. */
  | 'converged'
  /** The token was handed over (a fresh sign-in, a re-sign-in, or an account swap) — then, when it
   *  was asked for, the account's grid ensured ([GridAttachResult.ownGrid]). */
  | 'signed-in'
  /** The hand-off was needed and did not succeed. The harness sign-in is untouched. */
  | 'handoff-failed'

export interface GridAttachResult {
  status: GridAttachStatus
  /** The account's private grid name, once known; null when the backend issued none. */
  name: string | null
  /** One sentence for a caller that wants to log the outcome. Never contains a credential. */
  detail: string
  /** What making sure the account's own grid exists came to, when it was asked for; absent when only
   *  a sign-in was needed. `converged` means the grid is there already. */
  ownGrid?: EnsureStatus
}

/**
 * The seams this reconcile runs through. The grid-facing ones default to the real modules
 * ({@link defaultGridAttachDeps}); the network and daemon-facing ones are supplied by `cli.ts`,
 * which alone holds the HTTP helpers and the live `BackendSocket`.
 */
export interface GridAttachDeps {
  /** Awaited first: puts `grid` on a machine that has none (the pinned managed runtime, else grid's
   *  own installer), so the hand-off runs on the binary that will serve. A rejection is ignored — a
   *  failed download is the binary check's story to tell, not this await's. */
  installCli: () => Promise<unknown>
  /** Is there a `grid` to run at all? */
  gridAvailable: () => boolean
  /** `POST /api/grid/name` — the account's private grid name, minted if this is its first ask. Null
   *  when the backend predates the route. Throws when the control plane cannot be reached. */
  mintName: () => Promise<string | null>
  /** A live harness access token, for the hand-off. Throws when the SSO session is gone. */
  accessToken: () => Promise<string>
  /** The email `grid` recorded for this machine's sign-in, or null when signed out of grid. */
  signedInEmail: () => string | null
  /** The grid names this machine's `grid` knows locally (`grid --remote ls`, no network call). */
  gridNames: () => Promise<string[]>
  /** Run `grid login --harness` with this token. */
  handoff: (token: string) => Promise<GridHandoffResult>
  /** Make sure the account's private grid exists. */
  ensure: (name: string) => Promise<EnsureResult>
  /** Publish the confirmed name into the daemon and drop the grid memos, so the next `grid_models_list`
   *  / retarget answers with this account's grid rather than a stale or absent one. */
  onName: (name: string) => void
  /** One sentence, prefixed by the caller. */
  log: (line: string) => void
}

function msg(err: unknown): string {
  return err instanceof Error ? err.message : String(err)
}

/**
 * Reconcile this machine's grid sign-in with its harness account. See the module comment for the
 * shape of the decision; the branches below are exactly its four answers.
 */
export async function reconcileGridAttach(
  deps: GridAttachDeps,
  opts: { ownGrid?: boolean; signedInThisRun?: boolean } = {},
): Promise<GridAttachResult> {
  const ownGrid = opts.ownGrid ?? true
  try { await deps.installCli() } catch { /* the binary check answers a failed download */ }

  if (!deps.gridAvailable()) {
    deps.log('no grid CLI on this machine yet — nothing to attach a sign-in to')
    return { status: 'no-cli', name: null, detail: '' }
  }

  let name: string | null
  try {
    name = await deps.mintName()
  } catch (err) {
    deps.log(`could not read this account's grid name (${msg(err)}) — will try again on the next start`)
    return { status: 'no-name', name: null, detail: msg(err) }
  }
  if (!name) {
    deps.log('this account has no grid name yet (older backend) — skipping grid setup')
    return { status: 'no-name', name: null, detail: '' }
  }

  // The exact, unambiguous signal that this machine is already set up: the account's grid name is
  // GLOBALLY UNIQUE (its suffix is a hash of the account id), so this machine's `grid` knowing that
  // name locally can only mean it is signed in as this account AND the grid exists. A weaker check —
  // "is the signed-in email's private-grid pattern a match" — would false-positive across two
  // accounts sharing an email local-part (`kelvin@personal` vs `kelvin@company`), skip the overwrite
  // decision (1) calls for, and then `ensure` under the wrong account. `grid ls` is a local read
  // (no network), so this stays cheap on the common, already-set-up path.
  const email = deps.signedInEmail()
  let names: string[] = []
  if (email) {
    try {
      names = await deps.gridNames()
    } catch (err) {
      // Could not read the local registry. That cannot PROVE the machine is set up, so it falls
      // through to the hand-off below — which rewrites that registry, so the next start reads it.
      deps.log(`could not read this machine's grid list (${msg(err)}) — signing in again to rebuild it`)
    }
  }
  if (email && names.includes(name)) {
    deps.onName(name)
    deps.log(`already signed in with grid '${name}' — nothing to do`)
    return { status: 'converged', name, detail: '', ...(ownGrid ? { ownGrid: 'existed' as const } : {}) }
  }
  // Signed in as this account earlier in this daemon's life, and nothing here needs the account's own
  // grid: the sign-in is all there is to have. (A grid of its own is not proof this machine is signed
  // in — the gate above — only for an account that has one.)
  if (!ownGrid && email && opts.signedInThisRun) {
    deps.onName(name)
    return { status: 'converged', name, detail: '' }
  }

  // Everything else — signed out, signed in as a DIFFERENT account, or the grid not yet created /
  // synced on this machine — is resolved by (re)signing in as this account and making sure the grid
  // exists. When the machine was signed in as a different account, this overwrites it, by design
  // (decision 1, and the module comment). When it was already the right account but the grid was
  // merely missing locally, this re-fetches the account's grids before ensuring — a small redundancy
  // that only recurs until the grid is created and synced, after which the converged path skips it.
  // Signed in as this account already this run: only the grid is missing, so no second hand-off —
  // each one rotates the account's grid token.
  if (!(email && opts.signedInThisRun)) {
    let token: string
    try {
      token = await deps.accessToken()
    } catch (err) {
      deps.log(`no harness token to hand to grid (${msg(err)})`)
      return { status: 'handoff-failed', name, detail: msg(err) }
    }
    const handoff = await deps.handoff(token)
    if (handoff.code !== 'OK') {
      deps.log(`grid sign-in did not happen: ${handoff.message}`)
      return { status: 'handoff-failed', name, detail: handoff.message }
    }
  }
  if (!ownGrid) {
    deps.onName(name)
    deps.log(`signed grid in as this account ('${name}' not needed yet)`)
    return { status: 'signed-in', name, detail: '' }
  }
  const ensured = await deps.ensure(name)
  deps.onName(name)
  deps.log(`signed grid in and ensured '${name}': ${ensured.status}${ensured.message ? ` — ${ensured.message}` : ''}`)
  return { status: 'signed-in', name, detail: ensured.message, ownGrid: ensured.status }
}

/** A grid of the account's own is there: made, found, or won by another machine's create. */
const OWN_GRID_THERE: ReadonlySet<string> = new Set(['created', 'existed', 'adopted'])

export interface GridAccessOptions {
  /** Runs one reconcile ([reconcileGridAttach]). Injected so the coordination is testable alone. */
  attempt: (request: { ownGrid: boolean; signedInThisRun: boolean }) => Promise<GridAttachResult>
  /** Whether `grid` still holds a sign-in on this machine (a file read) — a `grid logout` run by hand
   *  since forgets what this daemon remembered. */
  signedIn: () => boolean
  log: (line: string) => void
  /** Injected for the tests. */
  now?: () => number
}

/** How long a failure is answered as it is before grid is asked again: a minute, doubled for each failure in a row. */
const FAILURE_HOLD_MS = 60_000
const MAX_FAILURE_HOLD_MS = 10 * 60_000

export interface GridAccess {
  /** Have grid ready for what the caller is about to do: signed in as this account, and — `ownGrid` —
   *  the account's grid there too. Resolves with what happened; never rejects. */
  ensure: (request?: { ownGrid?: boolean }) => Promise<GridAttachResult>
}

/**
 * When to reconcile, as opposed to {@link reconcileGridAttach}, which decides what to do: on demand,
 * one at a time, and never twice for what is already done.
 *
 * - **One at a time.** Calls queue behind the one in flight and each then reads what it left behind,
 *   so a picker's Set up and a Get pressed a moment later make one sign-in, not two token rotations.
 * - **Remembered.** A sign-in as this account, and the account's grid once it is there, hold for the
 *   daemon's life — until `grid` no longer holds a sign-in at all, which a hand-run `grid logout`
 *   leaves behind.
 * - **A failure is held.** Not every ask is a person acting: a held Swarm start asks every 2 seconds
 *   (core/agents/pendingLaunches.ts) and each owner's Swarm every minute (superTabs/swarmGrids.ts), and each ask that
 *   failed ran grid's installer again. A failure answers as it is for a minute, twice as long after each failure in a
 *   row up to ten; a success clears it.
 */
export function createGridAccess(opts: GridAccessOptions): GridAccess {
  const now = opts.now ?? Date.now
  let signedIn = false
  let ownGridThere = false
  let last: GridAttachResult | null = null
  let failure: { result: GridAttachResult; until: number; hold: number } | null = null
  let queue: Promise<unknown> = Promise.resolve()

  const failed = (result: GridAttachResult): GridAttachResult => {
    const hold = failure ? Math.min(failure.hold * 2, MAX_FAILURE_HOLD_MS) : FAILURE_HOLD_MS
    failure = { result, until: now() + hold, hold }
    return result
  }

  const once = async (ownGrid: boolean): Promise<GridAttachResult> => {
    if (!opts.signedIn()) signedIn = ownGridThere = false
    if (last && signedIn && (!ownGrid || ownGridThere)) return last
    if (failure && now() < failure.until) return failure.result
    let result: GridAttachResult
    try {
      result = await opts.attempt({ ownGrid, signedInThisRun: signedIn })
    } catch (err) {
      const detail = err instanceof Error ? err.message : String(err)
      opts.log(`attempt failed: ${detail}`)
      return failed({ status: 'handoff-failed', name: null, detail })
    }
    if (result.status !== 'converged' && result.status !== 'signed-in') return failed(result)
    failure = null
    signedIn = true
    if (result.ownGrid && OWN_GRID_THERE.has(result.ownGrid)) ownGridThere = true
    last = result
    return result
  }

  return {
    ensure: (request = {}) => {
      const next = queue.then(() => once(request.ownGrid ?? false))
      queue = next.catch(() => {})
      return next
    },
  }
}

export async function gridNamesLocal(): Promise<string[]> {
  const { value, result } = await gridJson<Array<{ grid?: unknown }>>(['--remote', 'ls'])
  // ⚠️ A FAILED read is NOT an empty list, and conflating the two is how "this machine has no grids"
  // stops being a fact and becomes a guess — one that would make the gate below answer "not set up"
  // forever on a machine whose registry is unreadable. Thrown rather than returned as `[]` so the
  // caller says which of the two happened in its log.
  if (result.code !== 'OK') {
    throw new Error(result.stderr.trim() || result.message || `\`grid ls\` exited ${result.exitCode}`)
  }
  if (!Array.isArray(value)) throw new Error('`grid ls --json` did not answer a list')
  return value.map((row) => (typeof row.grid === 'string' ? row.grid : '')).filter(Boolean)
}