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.

21.4 KB
Raw Blame
/**
 * Every launch shape that carries a grid model or a saved API, answer for answer: recorded from the code as it stood
 * before the models service built those launches for the core (docs/design/2026-10-08-launch-port.md, (L1)). For
 * each engine, it records what a create, a relaunch (restart, resume, restore), a fork and a retarget start the pane
 * with: the argv, the environment, the variables cleared, the row's launch record. It also records the config files
 * written for an engine that reads its provider from a file, the saved-API instructions an agent's folder gets, the
 * log lines and every refusal. It covers what the socket asks of a saved API, the variables a pane leaving a grid
 * has cleared, and the engines a picker may offer a grid model to.
 *
 * Each case runs with `process.platform` pinned to darwin and to linux, and linux's are stored where they differ.
 * Local time is pinned. The home folder, the data folder and the saved API's address are the spec's own, and no
 * size depends on their paths.
 *
 * `RECORD_LAUNCH_SHAPES_GOLDEN=1` writes the fixture. Record it again only for a change meant to alter a launch,
 * and say so in that change.
 */
import { createHash } from 'node:crypto'
import { createServer, type Server } from 'node:http'
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
import type { AddressInfo } from 'node:net'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
import { ENGINES, type AgentEngine } from './types.js'
import { baseNode } from '../harnessd/baseNode.js'
import { resolveBinaryOnPath } from '../lib/binaryOnPath.js'
import type { RegisteredSession } from '../lib/registry.js'
import type { GridLaunchOverride } from '../lib/gridLaunch.js'

process.env.TZ = 'America/New_York'

// The pane itself, and the probes of this machine's binaries: the launch is what is recorded, never a spawn.
const pane = vi.hoisted(() => ({ calls: [] as Array<Record<string, unknown>>, tmux: true }))
vi.mock('../lib/createAgentPane.js', () => ({
  createAndRegisterPane: vi.fn(async (input: Record<string, unknown>) => {
    pane.calls.push(input)
    return { ok: false, error: 'RECORDED', detail: 'the pane is not opened by this spec' }
  }),
}))
vi.mock('../engines/launchControl.js', async (real) => ({ ...await real<object>(), opencodeMajorVersion: vi.fn(() => 2) }))
vi.mock('../lib/engineBin.js', async (real) => ({ ...await real<object>(), enginePathOverride: vi.fn(() => null) }))

const GOLDEN = fileURLToPath(new URL('./__fixtures__/launch-shapes.golden.json', import.meta.url))
const RECORD = process.env.RECORD_LAUNCH_SHAPES_GOLDEN === '1'

let root = ''
let server: Server
let apiBase = ''
let port = ''
const saved: Record<string, string | undefined> = {}
/** The variables a launch reads of the daemon's own environment, each pinned (or cleared) for the record. */
const VARS = ['ADAPTER_DATA_DIR', 'HOME', 'USERPROFILE', 'ZDOTDIR', 'SHELL', 'CODEX_HOME', 'CODEX_PATH', 'HARNESS_OS', 'HARNESS_GRID_BIN', 'CLAUDE_PATH', 'CURSOR_PATH',
  'OPENCODE_PATH', 'PI_PATH', 'HERMES_PATH', 'COMMANDCODE_PATH', 'DEVIN_PATH', 'MUSE_PATH', 'AMP_PATH', 'KILO_PATH', 'GROK_PATH', 'AGY_PATH', 'COPILOT_PATH'] as const
/** The launch scripts the cases name, by digest: most shapes share theirs with others. */
const scripts: Record<string, string> = {}
type Shapes = ReturnType<typeof import('../testing/launchShapes.js')['launchShapes']>
let shapes: (machine: { hermesSystemManaged: boolean; opencodeMajor?: number | null }) => Shapes

const GRID: GridLaunchOverride = {
  networkId: 'net-home', networkName: 'Home', baseUrl: 'https://grid.example/g/home/relay/v1', apiKey: 'grid-key-1', model: 'qwen3-coder',
  mcpUrl: 'https://control.example/v1/grid/web-mcp/', contextWindow: 131072,
}
const BARE: GridLaunchOverride = { networkId: 'net-home', networkName: 'Home', baseUrl: 'https://grid.example/g/home/relay/v1', apiKey: 'grid-key-2' }
const api = (connection: string, model = 'vendor/model-a'): GridLaunchOverride => ({
  networkId: `api:${connection}`, networkName: 'Router', baseUrl: apiBase, apiKey: 'stale-key', model, contextWindow: 200000,
})
const M1 = { hermesSystemManaged: false, opencodeMajor: 2 }
const M2 = { hermesSystemManaged: true, opencodeMajor: 1 }

/** The machine's own parts of a text, as placeholders: the spec's folders, the API's port, this node, its tmux. */
const placeheld = (text: string, label?: string): string => {
  const node = baseNode(process.execPath)
  // The daemon's tmux, as a launch finds it on PATH: /opt/homebrew/bin/tmux on a Mac, /usr/bin/tmux on CI's Linux.
  const tmux = resolveBinaryOnPath('tmux')
  // Quoted, as every script quotes them: a Node in /usr/bin must not turn `/usr/bin/env` into a placeholder.
  let out = text.split(`'${node}'`).join("'<daemon-node>'").split(`'${dirname(node)}'`).join("'<daemon-node-dir>'")
  if (tmux) out = out.split(`'${tmux}'`).join("'<tmux>'")
    .split(root).join('<root>').split(`127.0.0.1:${port}`).join('127.0.0.1:<port>')
    .replace(/\/launch\/[0-9a-f-]{36}\.sh/g, '/launch/<script>.sh')
  if (label) out = out.split(label).join('<label>')
  return out
}
const norm = (value: unknown, label?: string): unknown => value === undefined ? '<undefined>' : JSON.parse(placeheld(JSON.stringify(value), label))
/** The script a launch's argv sources, kept once by its digest. */
function scriptOf(argv: unknown, label?: string): string | null {
  const sourced = Array.isArray(argv) ? argv.map(String).map((arg) => /^\. '(.+\/launch\/[0-9a-f-]{36}\.sh)'$/.exec(arg)?.[1]).find(Boolean) : undefined
  if (!sourced || !existsSync(sourced)) return null
  const text = placeheld(readFileSync(sourced, 'utf8'), label)
  const digest = createHash('sha256').update(text).digest('hex').slice(0, 16)
  scripts[digest] = text
  return digest
}
async function attempt<T>(run: () => T | Promise<T>): Promise<unknown> {
  try { return norm(await run()) } catch (error) { return { threw: norm(error instanceof Error ? error.message : String(error)) } }
}

/** A folder's files: names, bytes and modes, and where each link points. */
function tree(dir: string): Record<string, unknown> | null {
  if (!existsSync(dir)) return null
  const out: Record<string, unknown> = {}
  for (const name of readdirSync(dir).sort()) {
    const path = join(dir, name)
    const info = lstatSync(path)
    out[name] = info.isSymbolicLink() ? { link: readlinkSync(path) }
      : info.isDirectory() ? { dir: tree(path) }
        : { mode: (statSync(path).mode & 0o777).toString(8), text: readFileSync(path, 'utf8') }
  }
  return out
}
const configRoot = () => join(root, 'data', 'grid-engine-config')
let folders = 0
const work = (): string => { const dir = join(root, 'work', `w${++folders}`); mkdirSync(dir, { recursive: true }); return dir }

beforeAll(async () => {
  root = realpathSync(mkdtempSync(join(tmpdir(), 'launch-shapes-golden-')))
  for (const name of VARS) saved[name] = process.env[name]
  for (const name of VARS) delete process.env[name]
  process.env.ADAPTER_DATA_DIR = join(root, 'data')
  process.env.HOME = join(root, 'home')
  process.env.USERPROFILE = join(root, 'home')
  process.env.SHELL = '/bin/zsh'
  process.env.CODEX_HOME = join(root, 'home', '.codex')
  // A zsh user with a startup file of their own: the plain launch.
  process.env.ZDOTDIR = join(root, 'zdotdir')
  for (const dir of ['data', 'zdotdir', 'home/.grok/sessions', 'home/.pi/agent/skills', 'home/.codex']) mkdirSync(join(root, dir), { recursive: true })
  writeFileSync(join(root, 'zdotdir', '.zshrc'), '')
  // A saved API's model list, as an OpenAI-compatible API answers it, only for the key saved now.
  server = createServer((request, response) => {
    if (request.url !== '/v1/models') { response.statusCode = 404; response.end(); return }
    if (request.headers.authorization !== 'Bearer fresh-key') { response.statusCode = 401; response.end(); return }
    response.setHeader('content-type', 'application/json')
    response.end(JSON.stringify({ data: [
      { id: 'vendor/model-a', name: 'Vendor: Model A', context_length: 200000, supported_parameters: ['tools'] },
      { id: 'vendor/model-b' },
      { id: 'tiny', context_length: 1000 },
      { id: 'no-tools', supported_parameters: ['temperature'] },
    ] }))
  })
  await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
  port = String((server.address() as AddressInfo).port)
  apiBase = `http://127.0.0.1:${port}/v1`
  vi.resetModules()
  const { ApiConnections } = await import('../lib/apiConnections.js')
  const store = new ApiConnections(join(root, 'data'))
  store.save({ provider: 'custom', name: 'Router', baseUrl: apiBase, apiKey: 'fresh-key' })
  store.save({ provider: 'custom', name: 'Keyed', baseUrl: apiBase, apiKey: 'other-key', authHeader: 'x-api-key', authPrefix: '' })
  const { launchShapes } = await import('../testing/launchShapes.js')
  shapes = (machine) => launchShapes({
    dataDir: join(root, 'data'), machine: () => ({ ...machine }), capabilities: async () => ({ sessionEnv: pane.tmux }),
    readCodexConfig: () => null, setGridLaunch: () => {},
  })
})

afterAll(async () => {
  for (const name of VARS) {
    if (saved[name] === undefined) delete process.env[name]
    else process.env[name] = saved[name]
  }
  await new Promise<void>((done) => server.close(() => done()))
  rmSync(root, { recursive: true, force: true })
  vi.resetModules()
})

/** What was logged while `run` ran, of the lines a launch writes. */
async function logged<T>(run: () => Promise<T>): Promise<{ value: T; lines: string[] }> {
  const lines: string[] = []
  const keep = (...args: unknown[]) => { lines.push(args.map(String).join(' ')) }
  const log = vi.spyOn(console, 'log').mockImplementation(keep)
  const warn = vi.spyOn(console, 'warn').mockImplementation(keep)
  try { return { value: await run(), lines } } finally { log.mockRestore(); warn.mockRestore() }
}

// ------------------------------------------------------------------------------------------------ create

const pending = { agentId: 'created', sessionId: '', engine: 'claude' } as RegisteredSession
const rest = () => ({
  createBackend: { capabilities: async () => ({ sessionEnv: pane.tmux }) } as never, registry: { setLaunch: () => pending } as never,
  adoptableSession: async () => ({ ok: false, error: 'UNUSED' }) as never, heldBy: async () => 'none' as const, takeOverWhenIdle: async () => {},
  watchNewPane: (async () => {}) as never, announceSession: () => {}, attachDsh: () => {}, hookPort: 4242, hooksDisabled: true,
  installOpencodePlugin: async () => true, terminalHintMachineName: () => 'this-mac', blocksFolder: () => false, gridSetup: () => null,
  privateGridName: async () => null,
})

async function createCase(engine: AgentEngine, grid: GridLaunchOverride | null, machine = M1, over: Record<string, unknown> = {}): Promise<unknown> {
  pane.calls.length = 0
  rmSync(configRoot(), { recursive: true, force: true })
  const cwd = work()
  const { value, lines } = await logged(() => shapes(machine).create(rest() as never)({
    engine, cwd, bypassPermission: false, permissionMode: null, grid, codexHome: null, dsh: null, prompt: null, name: null, agent: null,
    resumeSessionId: null, takeOver: null, ...over,
  } as never))
  const call = pane.calls[0]
  const label = typeof call?.sessionLabel === 'string' ? call.sessionLabel : undefined
  return norm({
    result: value,
    pane: call ? {
      argv: call.argv, script: scriptOf(call.argv, label), env: call.env, grid: call.grid, gridLaunchRecord: call.gridLaunchRecord,
      ...(call.startedBy ? { startedBy: call.startedBy } : {}),
    } : null,
    config: tree(configRoot()),
    folder: tree(cwd),
    logged: lines.filter((line) => /grid|refused|\[apis\]/i.test(line)),
  }, label)
}

async function createCases(): Promise<Record<string, unknown>> {
  const cases: Record<string, unknown> = {}
  for (const engine of ENGINES) cases[`${engine} · grid`] = await createCase(engine, GRID)
  for (const engine of ['claude', 'codex', 'opencode', 'pi', 'hermes', 'grok', 'copilot'] as const) {
    cases[`${engine} · grid without a model, web tools or window`] = await createCase(engine, BARE)
    cases[`${engine} · grid · another machine`] = await createCase(engine, GRID, M2)
    cases[`${engine} · saved API`] = await createCase(engine, api('router'))
  }
  pane.tmux = false
  cases['claude · grid · an old tmux'] = await createCase('claude', GRID)
  pane.tmux = true
  cases['claude · own login'] = await createCase('claude', null)
  cases['codex · own login'] = await createCase('codex', null)
  // Started by another agent: the pull request line last (lib/agentAttribution.ts), none for an engine with no way to say it.
  for (const engine of ['claude', 'codex', 'opencode'] as const) {
    cases[`${engine} · own login · started by an agent`] = await createCase(engine, null, M1, { startedBy: 'agent' })
  }
  cases['claude · grid · started by an agent'] = await createCase('claude', GRID, M1, { startedBy: 'agent' })
  return cases
}

// ---------------------------------------------------------------------------------------------- relaunch

const session = (engine: AgentEngine, over: Partial<RegisteredSession> = {}): RegisteredSession => ({
  agentId: `agent-${engine}`, sessionId: 's', engine, cwd: work(), gridLaunch: null, codexHome: null, dsh: null, dshRuntime: null, agent: null,
  scmLaunch: null, ...over,
}) as unknown as RegisteredSession

async function relaunchCase(engine: AgentEngine, s: RegisteredSession, source?: Parameters<Shapes['relaunch']>[1], machine = M1): Promise<unknown> {
  rmSync(configRoot(), { recursive: true, force: true })
  const { value, lines } = await logged(() => shapes(machine).relaunch(s, source))
  return norm({
    result: value,
    retargetLine: value.ok ? shapes(machine).retargetLine(engine, value.overrides) : null,
    config: tree(configRoot()),
    folder: tree(s.cwd!),
    logged: lines.filter((line) => /grid|refused|\[apis\]/i.test(line)),
  })
}

async function relaunchCases(): Promise<Record<string, unknown>> {
  const cases: Record<string, unknown> = {}
  for (const engine of ENGINES) {
    cases[`${engine} · restart on a grid`] = await relaunchCase(engine, session(engine, { gridLaunch: GRID }))
  }
  for (const engine of ['claude', 'codex', 'opencode', 'pi', 'hermes', 'grok', 'copilot'] as const) {
    cases[`${engine} · restart on a grid without a model`] = await relaunchCase(engine, session(engine, { gridLaunch: BARE }))
    cases[`${engine} · restart on a grid · another machine`] = await relaunchCase(engine, session(engine, { gridLaunch: GRID }), undefined, M2)
    cases[`${engine} · restart on a saved API, its key as saved now`] = await relaunchCase(engine, session(engine, { gridLaunch: api('router') }))
    // Retarget hands the override it just resolved; fork drops the harness and the named agent.
    cases[`${engine} · retarget onto a grid`] = await relaunchCase(engine, session(engine), { gridLaunch: GRID })
    cases[`${engine} · retarget back to the own login`] = await relaunchCase(engine, session(engine, { gridLaunch: GRID }), { gridLaunch: null, subscriptionModel: 'own-model' })
    cases[`${engine} · fork on a grid`] = await relaunchCase(engine, session(engine, { gridLaunch: GRID, agent: 'reviewer' }), { gridLaunch: GRID, dsh: null, agent: null })
  }
  cases['claude · restart on a removed API'] = await relaunchCase('claude', session('claude', { gridLaunch: api('gone') }))
  cases['codex · restart on an API with no Bearer key'] = await relaunchCase('codex', session('codex', { gridLaunch: api('keyed') }))
  pane.tmux = false
  cases['codex · restart on a grid · an old tmux'] = await relaunchCase('codex', session('codex', { gridLaunch: GRID }))
  pane.tmux = true
  cases['opencode · restart as a named agent on a grid'] = await relaunchCase('opencode', session('opencode', { gridLaunch: GRID, agent: 'reviewer' }))
  // Started by another agent: every relaunch keeps the line; a fork of it is the forker's and has none.
  for (const engine of ['claude', 'codex'] as const) {
    cases[`${engine} · restart, started by an agent`] = await relaunchCase(engine, session(engine, { startedBy: 'agent' }))
    cases[`${engine} · retarget onto a grid, started by an agent`] = await relaunchCase(engine, session(engine, { startedBy: 'agent' }), { gridLaunch: GRID })
    cases[`${engine} · fork of one an agent started`] = await relaunchCase(engine, session(engine, { startedBy: 'agent' }), { dsh: null, agent: null, startedBy: null })
  }
  return cases
}

// ------------------------------------------------------------------------- retarget, the socket, the pickers

async function otherCases(): Promise<Record<string, unknown>> {
  const cases: Record<string, unknown> = {}
  for (const engine of ENGINES) {
    cases[`validate · ${engine} · grid`] = await attempt(() => shapes(M1).validate(engine, { gridLaunch: GRID }))
    cases[`validate · ${engine} · own login`] = await attempt(() => shapes(M1).validate(engine, { gridLaunch: null }))
    cases[`leaving a grid · ${engine}`] = norm(shapes(M1).leavingGrid(engine))
  }
  pane.tmux = false
  cases['validate · claude · grid · an old tmux'] = await attempt(() => shapes(M1).validate('claude', { gridLaunch: GRID }))
  pane.tmux = true
  cases['validate · opencode · grid · another machine'] = await attempt(() => shapes(M2).validate('opencode', { gridLaunch: GRID }))
  cases['grid-capable engines'] = norm(shapes(M1).gridCapable())
  for (const [name, connection, model] of [
    ['a listed model', 'router', 'vendor/model-a'], ['a model without details', 'router', 'vendor/model-b'], ['a window too small', 'router', 'tiny'],
    ['a model without tools', 'router', 'no-tools'], ['an unlisted model', 'router', 'missing'], ['no model', 'router', ''],
    ['an API with no Bearer key', 'keyed', 'vendor/model-a'], ['a removed API', 'gone', 'vendor/model-a'],
  ] as const) {
    cases[`API target · ${name}`] = await attempt(() => shapes(M1).apiTarget(connection, model))
  }
  for (const engine of ['claude', 'codex', 'opencode', 'gemini', 'terminal'] as const) {
    const cwd = work()
    shapes(M1).apiTools(cwd, engine)
    cases[`API tools · ${engine}`] = norm(tree(cwd))
  }
  const kept = work()
  writeFileSync(join(kept, 'AGENTS.md'), '# Ours\n')
  shapes(M1).apiTools(kept, 'codex')
  shapes(M1).apiTools(kept, 'codex')
  cases['API tools · an existing file, twice'] = norm(tree(kept))
  shapes(M1).apiTools(null, 'codex')
  return cases
}

type Sections = Record<string, Record<string, unknown>>
const PLATFORMS = ['darwin', 'linux'] as const

async function sectionsOn(platform: (typeof PLATFORMS)[number]): Promise<Sections> {
  const real = Object.getOwnPropertyDescriptor(process, 'platform')!
  Object.defineProperty(process, 'platform', { ...real, value: platform })
  rmSync(join(root, 'work'), { recursive: true, force: true })
  folders = 0
  try {
    return { create: await createCases(), relaunch: await relaunchCases(), other: await otherCases() }
  } finally { Object.defineProperty(process, 'platform', real) }
}

describe('every launch on a grid model or a saved API starts as it did before the models service built it', () => {
  it('create, relaunch, fork, retarget, the API target and the pickers match the record, on darwin and linux', async () => {
    const darwin = await sectionsOn('darwin')
    const linux = await sectionsOn('linux')
    const linuxDiffers = Object.fromEntries(Object.entries(linux).map(([section, cases]) => [section,
      Object.fromEntries(Object.entries(cases).filter(([key, value]) => JSON.stringify(value) !== JSON.stringify(darwin[section]![key])))]))
    // Both platforms' scripts, by digest: a case names its own, and its digest is its text.
    const used = Object.fromEntries(Object.entries(scripts).sort(([a], [b]) => a.localeCompare(b)))
    if (RECORD) {
      const block = (cases: Record<string, unknown>): string => Object.entries(cases).map(([key, value]) => ` ${JSON.stringify(key)}: ${JSON.stringify(value)}`).join(',\n')
      const sections = (all: Sections): string => Object.entries(all).map(([section, cases]) => `${JSON.stringify(section)}: {\n${block(cases)}\n}`).join(',\n')
      writeFileSync(GOLDEN, `{\n${sections(darwin)},\n"linux": {\n${sections(linuxDiffers)}\n},\n"scripts": {\n${block(used)}\n}\n}\n`)
      return
    }
    const { linux: linuxGolden, scripts: scriptsGolden, ...darwinGolden } = JSON.parse(readFileSync(GOLDEN, 'utf8')) as Sections & { linux: Sections; scripts: Record<string, string> }
    expect(Object.keys(used)).toEqual(Object.keys(scriptsGolden))
    for (const [digest, text] of Object.entries(scriptsGolden)) expect(used[digest], `script ${digest}`).toEqual(text)
    for (const [platform, actual, golden] of [
      ['darwin', darwin, darwinGolden],
      ['linux', linux, Object.fromEntries(Object.entries(darwinGolden).map(([section, cases]) => [section, { ...cases, ...linuxGolden[section] }]))],
    ] as const) {
      expect(Object.keys(actual), platform).toEqual(Object.keys(golden))
      for (const [section, cases] of Object.entries(golden)) {
        expect(Object.keys(actual[section]!).sort(), `${platform} · ${section}`).toEqual(Object.keys(cases).sort())
        for (const [key, value] of Object.entries(cases)) expect(actual[section]![key], `${platform} · ${section} · ${key}`).toEqual(value)
      }
    }
  }, 240_000)

  it('records no machine-specific path', () => {
    const text = readFileSync(GOLDEN, 'utf8')
    expect(text).not.toContain('launch-shapes-golden-')
    expect(text).not.toContain(root)
    expect(text).not.toMatch(/\/Users\/|\/home\/runner/)
  })
})