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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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')
})
})
})