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.

7.8 KB
Raw Blame
import { readdirSync, readFileSync } from 'node:fs'
import { dirname, join, relative } from 'node:path'
import { fileURLToPath } from 'node:url'
import ts from 'typescript'
import { describe, expect, it } from 'vitest'
import { agentOnly, forRecipients, NOTICE_READERS } from './model.js'

// Ken, 2026-10-29: notices written for the Lead or an agent showed in the chats people read, one kind at a time (#2177, then
// the idle stop). Every kind the code writes as a message's source is classified in model.ts NOTICE_READERS; this reads the
// code itself, as cli/src/architecture.spec.ts reads its imports, so a new kind with no line there fails here, not in a chat.

const root = dirname(fileURLToPath(import.meta.url))
const sources = (dir: string): string[] => readdirSync(dir, { withFileTypes: true }).flatMap(entry => entry.isDirectory()
  ? sources(join(dir, entry.name))
  : entry.name.endsWith('.ts') && !/\.test(-support)?\.ts$|\.test-d\.ts$/.test(entry.name) ? [join(dir, entry.name)] : [])

/** The kinds `expression` can give a message's source: its object literals' `kind`, through spreads, calls (json,
 *  forRecipients), conditionals, casts and variables (the file's own, or another's module constants: AGENT_ONLY). A string
 *  counts only as a `kind`'s value. */
function kindsOf(expression: ts.Node, declared: (name: string) => ts.Expression[], inKind = false, seen = new Set<ts.Node>()): string[] {
  if (seen.has(expression)) return []
  seen.add(expression)
  const of = (node: ts.Node, kind = inKind) => kindsOf(node, declared, kind, seen)
  if (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression)) {
    return of(expression.expression)
  }
  if (ts.isConditionalExpression(expression)) return [...of(expression.whenTrue), ...of(expression.whenFalse)]
  if (ts.isBinaryExpression(expression)) return [...of(expression.left), ...of(expression.right)]
  if (ts.isCallExpression(expression)) return expression.arguments.flatMap(argument => of(argument))
  if (ts.isIdentifier(expression)) return declared(expression.text).flatMap(initializer => of(initializer))
  if (ts.isStringLiteralLike(expression)) return inKind ? [expression.text] : []
  if (!ts.isObjectLiteralExpression(expression)) return []
  return expression.properties.flatMap(property => {
    if (ts.isSpreadAssignment(property)) return of(property.expression, false)
    if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'kind') return of(property.initializer, true)
    return []
  })
}

const add = (map: Map<string, ts.Expression[]>, name: string, initializer: ts.Expression) => map.set(name, [...map.get(name) ?? [], initializer])

/** Every notice kind written as a message's source (a `source` property, or the source argument of commands.ts `message`),
 *  with the files that write it. */
function writtenKinds(): Map<string, string[]> {
  const files = sources(root).map(path => ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true))
  const modules = new Map<string, ts.Expression[]>()
  for (const file of files) {
    for (const statement of file.statements) {
      if (!ts.isVariableStatement(statement)) continue
      for (const declaration of statement.declarationList.declarations) {
        if (ts.isIdentifier(declaration.name) && declaration.initializer) add(modules, declaration.name.text, declaration.initializer)
      }
    }
  }
  const written = new Map<string, string[]>()
  for (const file of files) {
    const locals = new Map<string, ts.Expression[]>()
    const at: ts.Node[] = []
    const visit = (node: ts.Node) => {
      // A variable, or a parameter's default.
      if ((ts.isVariableDeclaration(node) || ts.isParameter(node)) && ts.isIdentifier(node.name) && node.initializer) add(locals, node.name.text, node.initializer)
      if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === 'source') at.push(node.initializer)
      if (ts.isShorthandPropertyAssignment(node) && node.name.text === 'source') at.push(node.name)
      // message(conversationId, text, recipients, replyTo, source, ...)
      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'message' && node.arguments[4]) at.push(node.arguments[4])
      ts.forEachChild(node, visit)
    }
    visit(file)
    const declared = (name: string) => locals.get(name) ?? modules.get(name) ?? []
    for (const kind of new Set(at.flatMap(node => kindsOf(node, declared)))) written.set(kind, [...written.get(kind) ?? [], relative(root, file.fileName)])
  }
  return written
}

describe('the notices the Swarm writes into a chat', () => {
  const written = writtenKinds()

  it('finds the notices it is known to write, so a change in how they are written cannot empty this check', () => {
    expect([...written.keys()]).toEqual(expect.arrayContaining(['system', 'agent-only', 'idle', 'review-failed', 'work-lost', 'terminal-alert', 'native']))
  })

  it('classifies every kind it writes, and only those', () => {
    const unclassified = [...written].filter(([kind]) => !Object.hasOwn(NOTICE_READERS, kind)).map(([kind, files]) => `${kind} (${files.join(', ')})`)
    expect(unclassified, 'add each to NOTICE_READERS in model.ts: who reads it?').toEqual([])
    // A kind no longer written keeps its readers for the rows stored before: the server's idle stop (project instructions,
    // phase 4) told only the Lead; the coordinator's progress post, now the project's status card (Dee, 2026-10-31), people;
    // the Shipped line, now the task's own line (taskLine.ts; Quiet Swarm, Dee, 2026-11-02), people; a machine's removal ending,
    // no longer said in any chat (anh Dee, 11-04, #2742), nobody; a task's own row under its requester's name, now only a person's
    // own message (anh Dee, 11-04, 'bot messages', #2925), people; an instructions save's line, now only in the Instructions
    // history (Dee and Ken, 11-05, #3132), people; the card wake-up, now written by the server (anh Dee, 11-06, #3593), the Lead;
    // a proposal's notices and the PM's private line in a person's Buddy chat, now on the card or refused (anh Dee, 11-07, #4558), people.
    const retired = ['idle-stop', 'project-report', 'ship', 'machine-left', 'task-line', 'routing-reflection', 'instructions', 'update-request',
      'proposal-notice', 'proposal-overdue', 'pm-line']
    expect(Object.keys(NOTICE_READERS).filter(kind => !written.has(kind) && !retired.includes(kind))).toEqual([])
    expect(retired.filter(kind => written.has(kind))).toEqual([])
  })

  it('shows people a notice of theirs, and one for an agent only while it reaches none', () => {
    expect(agentOnly({ kind: 'system' }, ['lead'])).toBe(false)
    expect(agentOnly({ kind: 'terminal-alert' }, ['lead'])).toBe(false)
    expect(agentOnly({ kind: 'start-timeout' }, ['lead'])).toBe(false)
    for (const kind of ['idle-stop', 'work-stalled', 'overlap']) {
      expect(agentOnly({ kind }, ['lead'])).toBe(true)
      expect(agentOnly({ kind }, [])).toBe(false)
    }
    expect(agentOnly({ kind: 'agent-only' }, [])).toBe(true)
    // The "<machine> left the Swarm" lines stored before #2742 have no recipients: nobody reads them.
    expect(agentOnly({ kind: 'machine-left', machine: 'Studio' }, [])).toBe(true)
    // A row of a kind people read can still be its recipients' alone; a kind no code knows (stored by a newer server) shows.
    expect(agentOnly(forRecipients({ kind: 'system' }), [])).toBe(true)
    expect(agentOnly({ kind: 'from-a-newer-server' }, ['lead'])).toBe(false)
    expect(agentOnly(undefined, [])).toBe(false)
  })

  it('keeps the PM’s task decision wake out of people’s chat while it reaches the PM', () => {
    expect(agentOnly({ kind: 'task-approval', state: 'approved' }, ['lead'])).toBe(true)
    expect(agentOnly({ kind: 'task-approval', state: 'rejected' }, [])).toBe(false)
  })
})