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.

18.1 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { emptyPorts, type RecapSession, type TurnLifecycle } from '../core/api.js'
import { SUBAGENT_IDLE_MS, type CommanderMirrorOpts } from '../lib/commander.js'
import { deriveTurnSummary } from '../lib/deviceRecap.js'
import type { LiveEvent } from '../lib/normalize.js'
import type { TierDecision, TierInput } from '../lib/notifyTier.js'
import { fakeCore } from '../testing/fakeCore.js'

const { createRecaps, startRecaps } = await import('./recaps.js')

const dirs: string[] = []
const temp = () => { const dir = mkdtempSync(join(tmpdir(), 'recaps-')); dirs.push(dir); return dir }
const watching = { device: true, active: true }
const nobody = { device: false, active: false }
const s1: RecapSession = { sessionId: 's1', agentId: 'a1', name: 'app', subagent: false }
const started = (userMessage = 'what is the fix?') => ({ type: 'turn_started', payload: { userMessage } }) as LiveEvent
const ended = { type: 'turn_ended', payload: {} } as LiveEvent
const flush = () => new Promise((done) => setTimeout(done, 0))

const decided = (tier: TierDecision['tier']): TierDecision => ({ tier, by: 'test', detail: '', ms: 0 })

function setup(over: Parameters<typeof createRecaps>[1] = {}, core = fakeCore({ dataDir: temp() })) {
  vi.mocked(core.transcripts.lastTurn).mockResolvedValue({ assistantText: 'The fix is in. Tests pass.', userMessage: 'what is the fix?' } as never)
  const recaps = createRecaps(core, { recapForce: false, recapWithoutDevice: () => true, decideTier: async () => decided('list'), ...over })
  const opts = (recaps.mirror as unknown as { opts: CommanderMirrorOpts }).opts
  const tell = (event: TurnLifecycle, seen = watching) => recaps.port.lifecycle(event, seen)
  return { core, recaps, opts, tell }
}

describe('the recaps', () => {
  afterEach(() => {
    vi.restoreAllMocks()
    for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
  })

  it('starts in the core\'s process behind its port', () => {
    const ports = emptyPorts()
    startRecaps(fakeCore({ dataDir: temp() }), ports)
    expect(ports.recaps?.recaps('nobody')).toBeNull()
  })

  it('cuts a turn\'s recap from its final answer, sends the card and the apps\' recap, and keeps it for the core to read', async () => {
    const { core, recaps, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    expect(recaps.port.recaps('s1')).toMatchObject({ asks: ['what is the fix?'], busy: true })
    tell({ kind: 'events', session: s1, events: [ended], replay: false })
    await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalled())
    const summary = await deriveTurnSummary('The fix is in. Tests pass.')
    expect(core.transcripts.lastTurn).toHaveBeenCalledWith('s1')
    expect(vi.mocked(core.clients.turnSummary).mock.calls[0][0]).toMatchObject({ type: 'turn_summary', agentId: 'a1', dbSessionId: 's1', payload: { summary, sessionId: 's1' } })
    const cards = vi.mocked(core.clients.turnCard).mock.calls.map(([frame]) => frame)
    expect(cards.map((frame) => frame.payload.kind)).toEqual(['turn_started', 'processing', 'done', 'summary'])
    // The summary card carries the agent's name for a machine whose tile is not loaded.
    expect(cards[3]).toMatchObject({ type: 'commander_event', agentId: 'a1', dbSessionId: 's1', name: 'app' })
    expect(recaps.port.recaps('s1')).toMatchObject({ busy: false, history: [summary], fullTexts: ['The fix is in. Tests pass.'] })
  })

  it('streams no card with no device watching, and still cuts the recap for the apps', async () => {
    const { core, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    tell({ kind: 'events', session: s1, events: [started()], replay: false }, nobody)
    tell({ kind: 'events', session: s1, events: [ended], replay: false }, nobody)
    await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalled())
    expect(core.clients.turnCard).not.toHaveBeenCalled()
  })

  it('beats a busy card only while the core says the turn is verifiably working', () => {
    const { core, tell } = setup()
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    vi.mocked(core.clients.turnCard).mockClear()
    tell({ kind: 'beat', session: s1, working: false })
    expect(core.clients.turnCard).not.toHaveBeenCalled()
    tell({ kind: 'beat', session: s1, working: true })
    expect(vi.mocked(core.clients.turnCard).mock.calls.map(([frame]) => frame.payload)).toEqual([{ kind: 'processing', text: 'Processing' }])
  })

  it('clears the card on a cancel and a forget, keeping what is stored for a resume', () => {
    const { core, recaps, tell } = setup()
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    vi.mocked(core.clients.turnCard).mockClear()
    tell({ kind: 'cancelled', session: s1 })
    expect(recaps.port.recaps('s1')?.busy).toBe(false)
    tell({ kind: 'forgotten', session: { ...s1, subagent: true } })
    expect(vi.mocked(core.clients.turnCard).mock.calls.map(([frame]) => frame.payload)).toEqual([
      { kind: 'done', text: 'done' }, { kind: 'done', text: 'done', subagent: true },
    ])
    expect(recaps.port.recaps('s1')?.asks).toEqual(['what is the fix?'])
  })

  it('keeps what it was last told of whether a session is a sub-agent\'s, when an event does not say', () => {
    const { core, tell } = setup()
    tell({ kind: 'events', session: { ...s1, subagent: true }, events: [started()], replay: false })
    vi.mocked(core.clients.turnCard).mockClear()
    tell({ kind: 'cancelled', session: { sessionId: 's1', agentId: 'a1' } })
    expect(vi.mocked(core.clients.turnCard).mock.calls[0][0].payload).toEqual({ kind: 'done', text: 'done', subagent: true })
    // A session never told of is anyone's.
    tell({ kind: 'cancelled', session: { sessionId: 's2', agentId: 'a2' } })
    expect(core.clients.turnCard).toHaveBeenCalledTimes(1)
  })

  it('moves a conversation\'s recaps to its new session, and forgets a purged one', async () => {
    const { core, recaps, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    tell({ kind: 'events', session: s1, events: [ended], replay: false })
    await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalled())
    tell({ kind: 'rebound', from: 's1', to: 's9' })
    expect(recaps.port.recaps('s9')?.history).toEqual(recaps.port.recaps('s1')?.history)
    tell({ kind: 'purged', sessionId: 's1' })
    expect(recaps.port.recaps('s1')).toBeNull()
  })

  it('holds a turn\'s "done" notification while a question waits on the person, and lets it go once answered', async () => {
    const { core, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    tell({ kind: 'asked', sessionId: 's1', requestId: 'r1' })
    tell({ kind: 'events', session: s1, events: [ended], replay: false })
    await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalledTimes(1))
    expect(vi.mocked(core.clients.turnSummary).mock.calls[0][0].payload).toMatchObject({ notification: null })
    tell({ kind: 'answered', sessionId: 's1', requestId: 'r1' })
    tell({ kind: 'events', session: s1, events: [started('and now?')], replay: false })
    tell({ kind: 'events', session: s1, events: [ended], replay: false })
    await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalledTimes(2))
    expect(vi.mocked(core.clients.turnSummary).mock.calls[1][0].payload).toMatchObject({ notification: { kind: 'done' } })
  })

  it('says every card again as a device joins, busy only where the core says the turn is working', () => {
    const { core, tell } = setup()
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    tell({ kind: 'events', session: { ...s1, sessionId: 's2', agentId: 'a2' }, events: [started()], replay: false })
    tell({ kind: 'beat', session: s1, working: true })
    vi.mocked(core.clients.turnCard).mockClear()
    tell({ kind: 'rejoined', working: ['s2'] })
    expect(vi.mocked(core.clients.turnCard).mock.calls.map(([frame]) => [frame.dbSessionId, frame.payload.kind])).toEqual([['s2', 'processing']])
  })

  it('recaps, quietly and once, a turn that ended while nobody was listening (attached with its last turn over)', async () => {
    const { core, recaps, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.mocked(core.transcripts.lastTurn).mockResolvedValue({ assistantText: 'Giá vàng PNJ hôm nay: mua 14,00 triệu.', userMessage: 'giá PNJ' } as never)
    tell({ kind: 'settled', session: s1 })
    await vi.waitFor(() => expect(core.clients.turnCard).toHaveBeenCalled())
    const summary = deriveTurnSummary('Giá vàng PNJ hôm nay: mua 14,00 triệu.')
    // History, not news: the tile's recap with no notification, no busy card, nothing for the apps to announce.
    expect(vi.mocked(core.clients.turnCard).mock.calls.map(([frame]) => frame.payload)).toEqual([
      { kind: 'summary', text: 'Giá vàng PNJ hôm nay: mua 14,00 triệu.', recap: 'Giá vàng PNJ hôm nay: mua 14,00 triệu.', notification: null, restored: true },
    ])
    expect(core.clients.turnSummary).not.toHaveBeenCalled()
    expect(recaps.port.recaps('s1')).toMatchObject({ busy: false, history: [summary], asks: ['giá PNJ'], fullTexts: ['Giá vàng PNJ hôm nay: mua 14,00 triệu.'] })
    // Every attach may ask: a turn already recapped is left alone.
    tell({ kind: 'settled', session: s1 })
    await flush(); await flush()
    expect(core.clients.turnCard).toHaveBeenCalledTimes(1)
  })

  it('leaves a turn recapped live alone when its session attaches again', async () => {
    const { core, recaps, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    tell({ kind: 'events', session: s1, events: [ended], replay: false })
    await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalled())
    vi.mocked(core.clients.turnCard).mockClear()
    tell({ kind: 'settled', session: s1 })
    await flush(); await flush()
    expect(core.clients.turnCard).not.toHaveBeenCalled()
    expect(recaps.port.recaps('s1')?.history).toHaveLength(1)
  })

  it('says the cards of every turn still at work, for a dial that just attached', async () => {
    const { recaps, tell } = setup()
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    tell({ kind: 'beat', session: s1, working: true })
    expect(await recaps.port.liveCards()).toEqual([{ type: 'commander_event', agentId: 'a1', dbSessionId: 's1', payload: { kind: 'processing', text: 'Processing' } }])
  })

  it('lets a held turn end go on the engine\'s Stop hook', () => {
    const { recaps, tell } = setup()
    const stopped = vi.spyOn(recaps.mirror, 'noteEngineStopped')
    tell({ kind: 'stopped', sessionId: 's1' })
    expect(stopped).toHaveBeenCalledWith('s1')
  })

  it('gives the mirror the core\'s doors, the device gates as told, and an excerpt for a recap', async () => {
    const { core, opts, tell } = setup({ changed: vi.fn() })
    const frame = { type: 'commander_event' as const, agentId: 'a1', dbSessionId: 's1', payload: {} }
    opts.send(frame)
    opts.sendWeb({ type: 'turn_summary' })
    expect(core.clients.turnCard).toHaveBeenCalledWith(frame)
    expect(core.clients.turnSummary).toHaveBeenCalledWith({ type: 'turn_summary' })
    tell({ kind: 'stopped', sessionId: 's1' }, { device: true, active: false })
    expect(opts.hasDevice()).toBe(true)
    expect(opts.active!()).toBe(false)
    expect(await opts.summarize('The fix is in. Tests pass.')).toEqual(await deriveTurnSummary('The fix is in. Tests pass.'))
    expect(opts.summarizeIsLocal).toBe(true)
    expect(opts.notifyWithoutDevice).toBe(true)
    expect(opts.dataDir).toBe(core.dataDir)
    expect(opts.recapForce).toBe(false)
    expect((opts.alwaysGenerate as () => boolean)()).toBe(true)
    expect(opts.nameFor!('nobody')).toBeUndefined()
    expect(opts.agentIdFor!('nobody')).toBeUndefined()
    expect(opts.isSubagent!('nobody')).toBe(false)
    expect(opts.changed).toBeTypeOf('function')
  })

  it('reads the recap settings from the daemon\'s environment unless told', () => {
    const recaps = createRecaps(fakeCore({ dataDir: temp() }))
    const opts = (recaps.mirror as unknown as { opts: CommanderMirrorOpts }).opts
    expect(typeof opts.recapForce).toBe('boolean')
    expect(typeof (opts.alwaysGenerate as () => boolean)()).toBe('boolean')
  })

  it('counts a Claude Code sub-agent as at work while its own transcript is still growing', () => {
    const { opts, tell } = setup()
    const transcripts = temp()
    const transcriptPath = join(transcripts, 'main.jsonl')
    tell({ kind: 'stopped', sessionId: 's1' })
    tell({ kind: 'cancelled', session: { ...s1, transcriptPath } })
    tell({ kind: 'cancelled', session: { sessionId: 's2', agentId: 'a2' } })
    expect(opts.subagentActive!('s2', 'x'), 'no transcript').toBe(false)
    expect(opts.subagentActive!('s1', 'x'), 'no sub-agent file').toBe(false)
    const file = join(transcriptPath.replace(/\.jsonl$/, ''), 'subagents', 'agent-x.jsonl')
    mkdirSync(join(file, '..'), { recursive: true })
    writeFileSync(file, '{}\n')
    expect(opts.subagentActive!('s1', 'x')).toBe(true)
    const old = (Date.now() - SUBAGENT_IDLE_MS - 60_000) / 1000
    utimesSync(file, old, old)
    expect(opts.subagentActive!('s1', 'x')).toBe(false)
  })

  it('cuts no recap from a turn whose final answer the core cannot read', async () => {
    const { core, tell } = setup()
    vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.mocked(core.transcripts.lastTurn).mockResolvedValue(null)
    tell({ kind: 'events', session: s1, events: [started()], replay: false })
    tell({ kind: 'events', session: s1, events: [ended], replay: false })
    await flush()
    await flush()
    expect(core.clients.turnSummary).not.toHaveBeenCalled()
    expect(vi.mocked(core.clients.turnCard).mock.calls.at(-1)?.[0].payload).toEqual({ kind: 'done', text: 'done' })
  })

  describe('a finished turn\'s tier', () => {
    const turn = async (tell: (event: TurnLifecycle, seen?: typeof watching) => void, seen: typeof watching & { remote?: boolean }, quiet?: boolean) => {
      // The core says the engine, and whether the session is quiet on devices, with every event (core/turns/recaps.ts `session`).
      const session = { ...s1, engine: 'codex', ...(quiet === undefined ? {} : { quietOnDevices: quiet }) }
      tell({ kind: 'events', session, events: [started()], replay: false }, seen)
      tell({ kind: 'events', session, events: [ended], replay: false }, seen)
    }

    it('is decided once, with the agent and its engine, for the dial and the apps while a device listens', async () => {
      vi.spyOn(console, 'log').mockImplementation(() => {})
      const decideTier = vi.fn(async (_input: TierInput) => decided('alert'))
      const { core, tell } = setup({ decideTier })
      await turn(tell, watching)
      await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalled())
      expect(decideTier).toHaveBeenCalledExactlyOnceWith({ agent: 'app', engine: 'codex', recap: expect.any(String),
        durationS: 0, stats: {}, subagent: false, onScreen: false, failed: false, swarm: false })
      expect(vi.mocked(core.clients.turnSummary).mock.calls[0][0]).toMatchObject({ payload: { tier: 'alert' } })
      expect(vi.mocked(core.clients.turnCard).mock.calls.at(-1)?.[0].payload).toMatchObject({ kind: 'summary', tier: 'alert' })
    })

    it('is decided for an app away from this desk with no device, and for nobody when neither listens', async () => {
      vi.spyOn(console, 'log').mockImplementation(() => {})
      const decideTier = vi.fn(async () => decided('list'))
      const away = setup({ decideTier })
      await turn(away.tell, { device: false, active: false, remote: true })
      await vi.waitFor(() => expect(away.core.clients.turnSummary).toHaveBeenCalled())
      expect(vi.mocked(away.core.clients.turnSummary).mock.calls[0][0]).toMatchObject({ payload: { tier: 'list' } })
      expect(decideTier).toHaveBeenCalledTimes(1)
      const alone = setup({ decideTier })
      await turn(alone.tell, { ...nobody, remote: false })
      await vi.waitFor(() => expect(alone.core.clients.turnSummary).toHaveBeenCalled())
      expect(decideTier).toHaveBeenCalledTimes(1)
      expect(vi.mocked(alone.core.clients.turnSummary).mock.calls[0][0].payload).not.toHaveProperty('tier')
    })

    const decidedWith = async (quiet: boolean | undefined) => {
      const log = vi.spyOn(console, 'log').mockImplementation(() => {})
      const backend = vi.fn()
      // A row in the agent list says nothing: the session says it (in the edge host there is no agent list).
      const core = fakeCore({ dataDir: temp(), account: { backend }, agents: { byAgent: vi.fn(() => ({ agentId: 'a1', swarmSkill: { role: 'lead', key: 'k' } }) as never) } })
      const { tell } = setup({ decideTier: undefined }, core)
      await turn(tell, watching, quiet)
      await vi.waitFor(() => expect(core.clients.turnSummary).toHaveBeenCalled())
      expect(backend).not.toHaveBeenCalled()
      return { tier: (vi.mocked(core.clients.turnSummary).mock.calls[0][0].payload as { tier?: string }).tier, log }
    }

    it('decides a harness agent\'s turn alert, with no Jev call', async () => {
      const { tier, log } = await decidedWith(false)
      expect(tier).toBe('alert')
      expect(log).toHaveBeenCalledWith(expect.stringMatching(/^\[recap\] notify · app · alert · rule:turn · turn · \d+ms$/))
    })

    it('decides the turn of a session the core says is quiet on devices silent', async () => {
      const { tier, log } = await decidedWith(true)
      expect(tier).toBe('silent')
      expect(log).toHaveBeenCalledWith(expect.stringMatching(/rule:swarm/))
    })

    it('decides a turn alert when the core says nothing of it', async () => {
      expect((await decidedWith(undefined)).tier).toBe('alert')
    })
  })
})