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.

17.4 KB
Raw Blame
/**
 * The lean bundle a release carries, as the build writes it: what each process of harnessd loads from
 * it. A process parses every file it imports, so the memory each costs is the code it imports, and
 * that is what this holds: the master none of the services' code, a service none of another's, the core
 * none of the CLI's commands, and the master, search and workspaces no zod (`config/env.ts` and `lib/registry.ts` once brought it to every
 * one of them, 8 to 19 MiB each, measured 2026-10-05).
 */
import { execFileSync, spawn, spawnSync } from 'node:child_process'
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { createServer } 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 } from 'vitest'
import { LEAN_CORE_ENTRY, LEAN_ENTRY, readLeanBundle, writeLeanBundle } from './harnessd/leanBundle.js'
import { PROBE_ANSWER } from './harnessd/reexec.js'
import { KNOWN_SERVICES, SERVICE_HOSTS } from './harnessd/services.js'

const CLI_ROOT = fileURLToPath(new URL('..', import.meta.url))
// The updater, beside the services the core knows: the master runs it (harnessd/services.ts `UPDATER_HOST`).
const ROLES = ['master', 'core', ...KNOWN_SERVICES, 'updater']
const RUNNER: Record<string, string> = { master: 'masterProcess', core: 'core-coreProcess' }
for (const name of [...KNOWN_SERVICES, 'updater']) RUNNER[name] = `${name}Process`
RUNNER['engine-claude'] = 'claudeReaderProcess'
RUNNER['engine-codex'] = 'codexReaderProcess'

describe('the lean bundle a release carries', () => {
  let scratch = ''
  let entry = ''
  let files = new Map<string, string>()
  beforeAll(() => {
    scratch = mkdtempSync(join(tmpdir(), 'lean-entry-'))
    execFileSync(process.execPath, ['build-bundle.mjs'], { cwd: CLI_ROOT, env: { ...process.env, BUNDLE_OUT_DIR: join(scratch, 'build') }, stdio: 'pipe' })
    const lean = readLeanBundle(readFileSync(join(scratch, 'build', 'cli.js')))!
    files = new Map([...lean.files].map(([name, code]) => [name, code.toString('utf8')]))
    entry = writeLeanBundle(join(scratch, 'lean'), lean)
  }, 120_000)
  afterAll(() => { rmSync(scratch, { recursive: true, force: true }) })

  /** The files a process loads: the entry, its runner's file, and what they import, but not what they
   *  import only when asked (another role's runner). */
  function loads(role: string): Set<string> {
    const runner = [...files.keys()].find((name) => name.startsWith(`${RUNNER[role]}-`))
    expect(runner, `${role}'s own file`).toBeDefined()
    const roots = role === 'core' ? [LEAN_CORE_ENTRY, runner!]
      : role === 'master' ? [LEAN_ENTRY, runner!]
        : [LEAN_ENTRY, [...files.keys()].find((name) => name.startsWith('serviceProcess-'))!, runner!]
    return reach(roots)
  }
  /** The files [roots] import, and what those import, but not what any imports only when asked (`import("…")`). */
  function reach(roots: string[]): Set<string> {
    const seen = new Set<string>()
    const visit = (name: string): void => {
      if (seen.has(name)) return
      seen.add(name)
      for (const match of files.get(name)!.matchAll(/(?:from|import)\s*"\.\/([^"]+\.mjs)"/g)) visit(match[1])
    }
    for (const root of roots) visit(root)
    return seen
  }
  const runnerOf = (name: string): string | undefined => Object.entries(RUNNER).find(([, runner]) => name.startsWith(`${runner}-`))?.[0]
  const hasZod = (names: Set<string>): boolean => [...names].some((name) => files.get(name)!.includes('$ZodType'))
  /** The binding's loader: the module `lib/sqliteBuiltin.ts` asks Node for, a string only that code holds. */
  const hasSqlite = (names: Set<string>): boolean => [...names].some((name) => files.get(name)!.includes('"node:sqlite"'))

  it('loads the bundled harness assets in the Store alone and shares their bytes across lean builds', () => {
    const asset = 'harness-builtin-assets.mjs'
    expect(files.has(asset)).toBe(true)
    expect(loads('store').has(asset)).toBe(true)
    for (const role of ['master', 'core', 'search', 'workspaces']) expect(loads(role).has(asset), role).toBe(false)
    // The bytes occur once in the combined lean files, even though inline mode can load the Store too.
    const marker = '"builtinFiles")'
    expect(files.get(asset)?.includes(marker)).toBe(true)
    expect([...files].filter(([, code]) => code.includes(marker)).map(([name]) => name)).toEqual([asset])
  })

  it('is files of their own for the master, the core and each service, the code it runs and no other role\'s', () => {
    for (const role of ROLES) {
      const others = [...loads(role)].map(runnerOf).filter((owner) => owner && owner !== role)
      expect(others, `${role} loads another's code`).toEqual([])
    }
  })

  it('builds the core apart: it loads none of the master\'s and the services\' files, and they none of its', () => {
    // Built together, the files they shared held what the core uses too, and the master and every service
    // loaded it (leanCoreEntry.ts).
    const isCores = (name: string): boolean => name === LEAN_CORE_ENTRY || name.startsWith('core-')
    for (const role of ROLES) {
      const loaded = [...loads(role)]
      expect(loaded.filter((name) => isCores(name) !== (role === 'core')), role).toEqual([])
    }
  })

  it.each([
    // Each a string its module alone holds: lib/questionPane.ts's, Amp's thread export's (engines/amp/threadExport.ts), and the name the bundle keeps for Cursor's sub-agents' reader
    // (engines/cursor/subagent.ts), Devin's switch reader (engines/devin/runtimeProfile.ts), the compatibility
    // wrappers for agy's lock lookup and Cursor discovery, and Hermes's optional adoption reader. Core
    // identity and discovery use eager declarations/kit mechanics instead of those optional wrappers.
    ['pane readers', 'Native screen reader must be injected'],
    ['own code: Amp\'s', 'AMP_DISABLE_PLUGINS'],
    ['own code: Cursor\'s', '"loadCursorReplayTaskLinks"'],
    ['runtime profiles: Devin\'s', '"devinModelCommandResult"'],
    ['compatibility lookup: agy\'s', '"agyConversationForPid"'],
    ['compatibility wrapper: Cursor\'s discovery', '"CursorTranscriptDiscovery"'],
    ['adoption: Hermes\'s reader', '"hermesProvider"'],
  ])('leaves the other engines\' %s out of the core until it needs them', (_, marker) => {
    // engines/inProcess.ts imports them (docs/design/2026-10-08-other-engines-out-of-core.md): a file of the
    // core's own, which Node reads only then.
    expect([...files].some(([name, code]) => name.startsWith('core-') && code.includes(marker))).toBe(true)
    expect([...loads('core')].filter((name) => files.get(name)!.includes(marker))).toEqual([])
  })

  // HARNESS_SWARM=off (the review of #1765): the Swarm's code is in files of its own, which a process loads only through
  // a door while the Swarm is on (src/architecture.spec.ts `SWARM_DOORS`). With it off, the core, with every service in
  // it too (`HARNESSD_SERVICES=none`), the master and every other service load none of it.
  it.each([
    ['its side of the core', 'Only a stopped Product Manager of a Swarm project is reopened.'],
    ['its skills', 'A Swarm skill needs a role and session key'],
    ['its GitHub App', 'The Harness GitHub App token is not in the form GitHub gives.'],
    ['its retention', 'Super Tab retention'],
    ['its replacements', 'Invalid agent replacement.'],
    ['its shared APIs', 'This computer could not open a local endpoint for the API.'],
  ])('leaves the Swarm\'s code, %s, out of every process but its own until it is on', (_, marker) => {
    expect([...files.values()].some((code) => code.includes(marker)), 'the marker is in the build').toBe(true)
    const inline = [...files.keys()].find((name) => name.startsWith('core-inline-'))
    expect(inline, 'the core\'s inline services').toBeDefined()
    const processes: Array<[string, Set<string>]> = [...ROLES.filter((role) => role !== 'superTabs').map((role) => [role, loads(role)] as [string, Set<string>]),
      ['core with every service in it', new Set([...loads('core'), ...reach([inline!])])]]
    for (const [role, loaded] of processes) expect([...loaded].filter((name) => files.get(name)!.includes(marker)), role).toEqual([])
  })

  it('loads the Swarm\'s code in its own process, which the master starts only while it is on', () => {
    for (const marker of ['Super Tab retention', 'A Swarm skill needs a role and session key']) {
      expect([...loads('superTabs')].some((name) => files.get(name)!.includes(marker)), marker).toBe(true)
    }
  })

  it('loads native hook declarations eagerly without importing the optional compatibility entry', () => {
    const core = loads('core')
    // This is native source data written into Amp's plugin file, not Amp's optional transcript reader.
    // Readiness and launch must not depend on an import() before the core can install that file.
    const declaration = 'Mirrors this Amp thread to the machine adapter'
    expect([...core].filter(name => files.get(name)!.includes(declaration))).toHaveLength(1)
    expect([...core].some(name => name.startsWith('core-hooks-'))).toBe(false)
    expect([...files.keys()].some(name => name.startsWith('core-hooks-'))).toBe(true)
  })

  it('gives the core its own code and none of the CLI\'s commands, which parsing cli.js cost it', () => {
    const core = loads('core')
    const text = [...core].map((name) => files.get(name)!).join('\n')
    // The core's own (core/main.ts), and not the CLI's: its usage text, written only in cli.ts.
    expect(text).toContain('[fatal-guard] uncaughtException')
    expect(text).not.toContain('sign in with Google in your browser, without asking')
    // Smaller than the whole bundle it used to parse, by the CLI's commands and the other processes' code.
    const whole = [...files.values()].reduce((sum, code) => sum + code.length, 0)
    expect([...core].reduce((sum, name) => sum + files.get(name)!.length, 0)).toBeLessThan(whole)
  })

  it('runs a core only from the core\'s entry, only for the cli.js its master read it from, and says so otherwise', () => {
    const run = (file: string, command: string) => spawnSync(process.execPath, [join(dirname(entry), file), command], {
      env: { PATH: process.env.PATH, HOME: join(scratch, 'home'), ADAPTER_DATA_DIR: join(scratch, 'data') }, encoding: 'utf8', timeout: 30_000,
    })
    const core = run(LEAN_CORE_ENTRY, '__run')
    expect(core.status).toBe(2)
    expect(core.stderr).toContain('the lean bundle runs a core only for the cli.js its master read it from')
    const other = run(LEAN_CORE_ENTRY, '__harnessd')
    expect(other.status).toBe(2)
    expect(other.stderr).toContain('__harnessd is the CLI\'s (cli.js)')
    const nothing = run(LEAN_CORE_ENTRY, '')
    expect(nothing.status).toBe(2)
    // The master's and the services' entry has no core to run.
    const services = run(LEAN_ENTRY, '__run')
    expect(services.status).toBe(2)
    expect(services.stderr).toContain('__run is the CLI\'s (cli.js)')
  })

  it('brings no zod to the master, search, the updater or the edge host', () => {
    expect(hasZod(new Set(files.keys())), 'the bundle still holds zod, for the services whose own code uses it').toBe(true)
    // The edge host's services share one process: zod in any of them would be in all of them.
    for (const role of ['master', 'search', 'updater', 'engine-claude', 'engine-codex', ...SERVICE_HOSTS.edge.services]) expect(hasZod(loads(role)), role).toBe(false)
  })

  it('keeps SQLite read mechanics eager in core and its service consumers', () => {
    // Hook admission must not need a lazy code chunk. Loading the mechanics does not load Node's native
    // binding: builtinSqlite resolves that only at a database read, verified in a real process below.
    expect(hasSqlite(loads('core')), 'core admission can read its store without an import').toBe(true)
    expect(hasSqlite(loads('usage')), 'usage shares the same eager read mechanics').toBe(true)
    expect(hasSqlite(loads('search')), 'search, the native-sqlite host, still has it').toBe(true)
    for (const role of ['master', 'updater']) expect(hasSqlite(loads(role)), role).toBe(false)
  })

  it('starts the edge host without node:sqlite, where search, whose index is SQLite, has it', async () => {
    // Short: the services' socket is `<data>/daemon-<port>.sock`, 96 bytes at most (lib/localSocket.ts).
    const home = mkdtempSync(join(tmpdir(), 'le-'))
    // Each service dials the core once it has started: a socket that counts them, then asks what loaded.
    const loadedOnce = (service: string, names: readonly string[]): Promise<string[]> => new Promise((resolve, reject) => {
      const data = join(home, service)
      mkdirSync(join(data, 'tmux'), { recursive: true })
      let dialled = 0
      const core = createServer((socket) => {
        socket.on('error', () => {})
        if (++dialled === names.length) child.kill('SIGUSR2')
      }).listen(join(data, 'daemon-18999.sock'))
      const report = 'data:text/javascript,process.on("SIGUSR2",()=>{process.stdout.write("LOADED="+JSON.stringify(process.moduleLoadList.filter((m)=>/sqlite/.test(m)))+"\\n");process.exit(0)})'
      // Nothing of this machine's: its own home, data folder and tmux server.
      const child = spawn(process.execPath, ['--import', report, entry, '__service', names.join(',')], {
        env: { PATH: process.env.PATH, HOME: data, ADAPTER_DATA_DIR: data, PORT: '18999', TMUX_TMPDIR: join(data, 'tmux'), HARNESSD_SERVICE: service },
        stdio: ['ignore', 'pipe', 'pipe'],
      })
      let out = ''
      child.stdout.on('data', (chunk: Buffer) => { out += chunk.toString() })
      child.stderr.on('data', (chunk: Buffer) => { out += chunk.toString() })
      const timer = setTimeout(() => child.kill('SIGKILL'), 60_000)
      child.on('close', () => {
        clearTimeout(timer)
        core.close()
        const loaded = /^LOADED=(.*)$/m.exec(out)
        if (loaded) resolve(JSON.parse(loaded[1]) as string[])
        else reject(new Error(`${service} ended before it said what it loaded (${dialled} of ${names.length} dialled):\n${out}`))
      })
    })
    try {
      expect(await loadedOnce('search', ['search']), 'search: what tells a loaded binding apart').toContain('NativeModule sqlite')
      expect(await loadedOnce('edge', SERVICE_HOSTS.edge.services), 'the edge host').toEqual([])
    } finally { rmSync(home, { recursive: true, force: true }) }
  }, 150_000)

  it('passes the release script\'s check, which a lean bundle that breaks a process does not', async () => {
    // @ts-expect-error — plain ESM with no declaration file
    const { leanBlock } = await import('../scripts/lib/leanBlock.mjs') as { leanBlock: (files: Record<string, string>) => string }
    const check = (cli: string) => spawnSync(process.execPath, ['scripts/check-lean-bundle.mjs', cli], { cwd: CLI_ROOT, encoding: 'utf8', timeout: 120_000 })
    const good = check(join(scratch, 'build', 'cli.js'))
    expect(good.status, good.stderr).toBe(0)
    expect(good.stdout).toMatch(/the master answers its probe, and \d+ modules load/)
    const search = [...files.keys()].find((name) => name.startsWith('searchProcess-'))!
    const broken = join(scratch, 'broken.js')
    writeFileSync(broken, `console.log("cli")\n${leanBlock({ ...Object.fromEntries(files), [search]: 'throw new Error("a broken service")' })}`)
    const bad = check(broken)
    expect(bad.status).toBe(1)
    expect(bad.stderr).toContain(`${search} does not load`)
    expect(bad.stderr).toContain('a broken service')
    const core = [...files.keys()].find((name) => name.startsWith('core-coreProcess-'))!
    writeFileSync(broken, `console.log("cli")\n${leanBlock({ ...Object.fromEntries(files), [core]: 'throw new Error("a broken core")' })}`)
    expect(check(broken).stderr).toContain(`${core} does not load`)
    writeFileSync(broken, `console.log("cli")\n${leanBlock({ ...Object.fromEntries(files), [LEAN_CORE_ENTRY]: 'throw new Error("a broken entry")' })}`)
    expect(check(broken).stderr).toContain('its core\'s entry does not load')
    writeFileSync(broken, `console.log("cli")\n${leanBlock({ ...Object.fromEntries(files), [LEAN_CORE_ENTRY]: 'process.exit(0)' })}`)
    expect(check(broken).stderr).toContain('its core\'s entry ran a core no master started')
    const { [core]: _gone, ...coreless } = Object.fromEntries(files)
    writeFileSync(broken, `console.log("cli")\n${leanBlock(coreless)}`)
    expect(check(broken).stderr).toContain('missing the master\'s, the services\' or the core\'s module')
    const { [LEAN_CORE_ENTRY]: _entry, ...entryless } = Object.fromEntries(files)
    writeFileSync(broken, `console.log("cli")\n${leanBlock(entryless)}`)
    expect(check(broken).stderr).toContain('missing the master\'s, the services\' or the core\'s module')
    writeFileSync(broken, `console.log("cli")\n${leanBlock({ ...Object.fromEntries(files), [LEAN_ENTRY]: 'process.exit(5)' })}`)
    expect(check(broken).stderr).toContain('its master does not answer its probe')
    writeFileSync(broken, 'console.log("no lean bundle")\n')
    expect(check(broken).stderr).toContain('carries no lean bundle')
    // Eight checks, most importing every process's module in a Node of its own, the core's among them.
  }, 300_000)

  it('starts as written out: its master answers the probe a re-executing master asks', () => {
    const run = spawnSync(process.execPath, [entry, '__harnessd-probe'], {
      env: { PATH: process.env.PATH, HOME: join(scratch, 'home'), ADAPTER_DATA_DIR: join(scratch, 'data') }, encoding: 'utf8', timeout: 30_000,
    })
    expect(run.status, run.stderr).toBe(0)
    expect(run.stdout).toContain(PROBE_ANSWER)
  })
})