Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
11.3 KB
Raw Blame
#!/usr/bin/env node
/**
 * guard-engine-registry — an engine is either wired up everywhere, or nowhere.
 *
 * Making a BYOA engine runnable means adding its id to about ten hand-kept
 * lists across the server, the renderer and the tooling. Miss one and nothing
 * shouts: the worst of them, `BYOA_SOURCES`, is read through
 * `normalizeByoaSource()`, which falls back to `'byoa-claude'` for anything it
 * does not recognise — so an engine missing from that list does not error, it
 * quietly bills every one of its runs to Claude in the ledger.
 *
 * That failure mode is not hypothetical. #102 was one of two identical blocks
 * getting a fix while the other did not, and `cli-version.ts` spent a while
 * telling the next person to sync a list that had been deleted. This script
 * makes the sync mechanical instead of remembered.
 *
 * The check is anchored on `ENGINE_IDS` in agents/computer/engine.ts — the
 * engines the daemon actually probes and wakes. For each id it asserts:
 *
 *   1. an ADAPTERS entry                        engine.ts
 *   2. the EngineId union carries it            engine.ts, computer/registry.ts, src/types.ts
 *   3. a label and a PATH binary                src/lib/engines.ts
 *   4. RUNNABLE_ENGINE_IDS carries it           src/lib/engines.ts
 *   5. a version spec                           computer/cli-version.ts
 *   6. `byoa-<id>` in the shared source list    runtime/byoa-source.ts
 *   7. `byoa-<id>` in every ledger union        llm-ledger, observability, admin/api, api/client
 *   8. the engine's binary is spawn-guarded     scripts/guard-big-brain.mjs
 *
 * A guard that quietly stops checking is worse than no guard, so every anchor
 * below is REQUIRED: if a refactor moves or renames one, this fails with
 * "anchor not found" rather than passing vacuously.
 *
 * Run:  node scripts/guard-engine-registry.mjs
 */
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'

const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..')

const read = (rel) => readFileSync(join(ROOT, rel), 'utf8')

/** Pull one declaration's text out of a file, or explain why we could not.
 *  `anchor` is matched as a RegExp with one capture group holding the body. */
export function extract(source, anchor) {
  const m = source.match(anchor)
  return m ? m[1] : null
}

/** The engines the daemon probes and wakes — everything else is derived. */
export function engineIds(engineTs) {
  const body = extract(engineTs, /export const ENGINE_IDS: EngineId\[\] = \[([^\]]*)\]/)
  if (body == null) return null
  return body.split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
}

/** Every check, as data: where to look, what must be in it, and how to say so.
 *  `body` returns the slice of the file the id must appear in — narrowing to
 *  the declaration means an unrelated mention elsewhere cannot satisfy it. */
const CHECKS = [
  {
    file: 'server/src/agents/computer/engine.ts',
    what: 'the ADAPTERS registry',
    body: (s) => extract(s, /const ADAPTERS: Record<EngineId, EngineAdapter> = \{([\s\S]*?)\n\}/),
    needle: (id) => `${id}: new `,
    fix: 'add `<id>: new <Name>Adapter(),` to ADAPTERS',
  },
  {
    file: 'server/src/agents/computer/engine.ts',
    what: 'the EngineId union',
    body: (s) => extract(s, /export type EngineId = ([^\n]*)/),
    needle: (id) => `'${id}'`,
    fix: "widen `export type EngineId`",
  },
  {
    file: 'server/src/agents/computer/registry.ts',
    what: 'the EngineId union',
    body: (s) => extract(s, /export type EngineId = ([^\n]*)/),
    needle: (id) => `'${id}'`,
    fix: "widen `export type EngineId`",
  },
  {
    file: 'src/types.ts',
    what: 'the renderer EngineId union',
    body: (s) => extract(s, /export type EngineId = ([^\n]*)/),
    needle: (id) => `'${id}'`,
    fix: "widen `export type EngineId`",
  },
  {
    file: 'src/lib/engines.ts',
    what: 'ENGINE_LABEL',
    body: (s) => extract(s, /export const ENGINE_LABEL: Record<string, string> = \{([\s\S]*?)\n\}/),
    needle: (id) => `${id}:`,
    fix: 'add a display name to ENGINE_LABEL',
  },
  {
    file: 'src/lib/engines.ts',
    what: 'ENGINE_BIN',
    body: (s) => extract(s, /export const ENGINE_BIN: Record<string, string> = \{([\s\S]*?)\n\}/),
    needle: (id) => `${id}:`,
    fix: 'add the PATH binary name to ENGINE_BIN',
  },
  {
    file: 'src/lib/engines.ts',
    what: 'the runnable-engine list',
    // Two accepted shapes: the ordered `RUNNABLE_ENGINES` tuple the UI pickers
    // map over, and the older `RUNNABLE_ENGINE_IDS` Set literal it is derived
    // from. Reading whichever exists keeps this guard from being the thing
    // that blocks collapsing that duplicate.
    body: (s) => extract(s, /export const RUNNABLE_ENGINES(?::[^=]*)? = \[([^\]]*)\]/)
      ?? extract(s, /export const RUNNABLE_ENGINE_IDS(?::[^=]*)? = new Set(?:<string>)?\(\[([^\]]*)\]/),
    needle: (id) => `'${id}'`,
    fix: 'add the id to RUNNABLE_ENGINE_IDS, or the engine stays detect-only in the UI',
  },
  {
    file: 'server/src/agents/computer/cli-version.ts',
    what: 'ENGINE_VERSION_SPECS',
    body: (s) => extract(s, /export const ENGINE_VERSION_SPECS: Record<string, EngineVersionSpec> = \{([\s\S]*?)\n\}/),
    needle: (id) => `${id}: {`,
    fix: 'add a version spec, or the Computers tab cannot report the installed version',
  },
  {
    file: 'server/src/agents/runtime/byoa-source.ts',
    what: 'BYOA_SOURCES',
    body: (s) => extract(s, /export const BYOA_SOURCES = \[([\s\S]*?)\] as const/),
    needle: (id) => `'byoa-${id}'`,
    // The one that fails silently: normalizeByoaSource() maps anything unknown
    // to 'byoa-claude', so the runs are billed, just to the wrong engine.
    fix: "add 'byoa-<id>' — without it every run of this engine is attributed to Claude in the ledger",
  },
  {
    file: 'server/src/agents/llm-ledger.ts',
    what: 'LlmCallSource',
    body: (s) => extract(s, /export type LlmCallSource = ([^\n]*)/),
    needle: (id) => `'byoa-${id}'`,
    fix: "widen LlmCallSource with 'byoa-<id>'",
  },
  {
    file: 'server/src/agents/observability.ts',
    what: 'TriageSource',
    body: (s) => extract(s, /export type TriageSource = ([^\n]*)/),
    needle: (id) => `'byoa-${id}'`,
    fix: "widen TriageSource with 'byoa-<id>'",
  },
  {
    file: 'src/admin/api.ts',
    what: 'the admin LlmCallSource union',
    body: (s) => extract(s, /export type LlmCallSource = ([^\n]*)/),
    needle: (id) => `'byoa-${id}'`,
    fix: "widen LlmCallSource with 'byoa-<id>'",
  },
  {
    file: 'src/api/client.ts',
    what: 'ApiTriageSource',
    body: (s) => extract(s, /export type ApiTriageSource = ([^\n]*)/),
    needle: (id) => `'byoa-${id}'`,
    fix: "widen ApiTriageSource with 'byoa-<id>'",
  },
  {
    file: 'server/src/agents/computer/registry.ts',
    what: 'ENGINE_BINS',
    body: (s) => extract(s, /const ENGINE_BINS(?::[^=]*)? = \{([\s\S]*?)\n\}/),
    needle: (id) => `${id}:`,
    fix: 'add the binary mapping to ENGINE_BINS',
  },
  {
    file: 'server/src/agents/computer/registry.ts',
    what: 'listAgentsForComputer default model fallback',
    body: (s) => extract(s, /export async function listAgentsForComputer[\s\S]*?return rows\.map\(\(r\) => \{([\s\S]*?)\n\s{2}\}\)/),
    needle: (id) => `r.engine === '${id}'`,
    fix: "add a default model fallback for '<id>' in listAgentsForComputer",
  },
  {
    file: 'server/src/agents/computer/daemon.ts',
    what: 'authFailureHint',
    body: (s) => extract(s, /export function authFailureHint[\s\S]*?\{([\s\S]*?)\n\}/),
    needle: (id) => `engine === '${id}'`,
    fix: "add an auth failure hint for '<id>' in authFailureHint",
  },
  {
    file: 'server/src/agents/computer/daemon.ts',
    what: 'triageModel',
    body: (s) => extract(s, /private triageModel\(\): string \{([\s\S]*?)\n\s{2}\}/),
    needle: (id) => `this.adapter.id === '${id}'`,
    fix: "add triage model resolution for '<id>' in triageModel",
  },
]

/** The spawn guard keys on BINARY names, not engine ids (cursor's binary is
 *  `cursor-agent`), so it is checked against ENGINE_BIN rather than the id. */
function binForId(enginesTs, id) {
  const body = extract(enginesTs, /export const ENGINE_BIN: Record<string, string> = \{([\s\S]*?)\n\}/)
  if (body == null) return null
  const m = body.match(new RegExp(`\\b${id}:\\s*'([^']+)'`))
  return m ? m[1] : null
}

export function scanRepo() {
  const problems = []
  const engineTs = read('server/src/agents/computer/engine.ts')
  const ids = engineIds(engineTs)
  if (!ids || ids.length === 0) {
    return [{ where: 'server/src/agents/computer/engine.ts', why: 'anchor not found: ENGINE_IDS — update this guard alongside the refactor' }]
  }

  const cache = new Map()
  const fileOf = (rel) => {
    if (!cache.has(rel)) cache.set(rel, read(rel))
    return cache.get(rel)
  }

  for (const check of CHECKS) {
    const body = check.body(fileOf(check.file))
    if (body == null) {
      problems.push({ where: check.file, why: `anchor not found: ${check.what} — update this guard alongside the refactor` })
      continue
    }
    for (const id of ids) {
      if (!body.includes(check.needle(id))) {
        problems.push({ where: `${check.file} → ${check.what}`, why: `'${id}' is missing — ${check.fix.replace('<id>', id)}` })
      }
    }
  }

  // The big-brain guard's R4 rule refuses a direct spawn of any supported
  // engine binary. A new engine left out of it can be spawned outside the
  // adapter, which is exactly the classify=small / run=big split it protects.
  // Anchored on the rule's own id rather than on its regex source: the rule
  // number is what the guard documents and is stable across rewrites of the
  // pattern itself.
  const bigBrain = read('scripts/guard-big-brain.mjs')
  const at = bigBrain.indexOf('R4 —')
  const r4 = at < 0 ? null : extract(bigBrain.slice(at, at + 400), /\(([a-z0-9|-]{10,})\)/)
  if (r4 == null) {
    problems.push({ where: 'scripts/guard-big-brain.mjs', why: 'anchor not found: the R4 engine-binary alternation — update this guard alongside the refactor' })
  } else {
    const guarded = new Set(r4.split('|'))
    const enginesTs = fileOf('src/lib/engines.ts')
    for (const id of ids) {
      const bin = binForId(enginesTs, id)
      if (!bin) continue // already reported as a missing ENGINE_BIN entry
      if (!guarded.has(bin)) {
        problems.push({
          where: 'scripts/guard-big-brain.mjs → R4',
          why: `'${bin}' is missing from the engine-binary alternation — a direct spawn of it would go unguarded`,
        })
      }
    }
  }

  return problems
}

// Compare filesystem paths, not a hand-built file:// URL. On Windows
// process.argv[1] is `E:\...` while import.meta.url is `file:///E:/...`, so
// the string form never matched and `npm run guard:engine-registry` exited 0
// without ever calling scanRepo() — the guard silently becoming a no-op is the
// exact failure this file exists to prevent. Same shape guard-big-brain.mjs
// already used.
const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]
if (isMain) {
  const problems = scanRepo()
  if (problems.length === 0) {
    console.log('✅ engine registry guard: every engine in ENGINE_IDS is wired into all of its lists.')
    process.exit(0)
  }
  console.error('🚨 engine registry is half-wired:\n')
  for (const p of problems) console.error(`  ${p.where}\n    ${p.why}`)
  console.error('\nAn engine must be in every list or none — a partly-wired one fails quietly.')
  process.exit(1)
}