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 { liveFor } from '../../engines/live.js'
import { EventEmitter } from 'node:events'
import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
import { AgyNormalizer } from '../../engines/agy/normalizer.js'
import { AmpNormalizer } from '../../engines/amp/normalizer.js'
import { CommandCodeNormalizer } from '../../engines/commandcode/normalizer.js'
import { CopilotNormalizer } from '../../engines/copilot/normalizer.js'
import { CursorNormalizer } from '../../engines/cursor/normalizer.js'
import { GrokNormalizer } from '../../engines/grok/normalizer.js'
import { MuseNormalizer } from '../../engines/muse/normalizer.js'
import { OmpNormalizer } from '../../engines/omp/normalizer.js'
import { PiNormalizer } from '../../engines/pi/normalizer.js'
import type { RegisteredSession } from '../../lib/registry.js'
import type { HistoryEvent, LineEvent, RewrittenEvent, Watcher } from '../../watcher/watcher.js'
import { createIngest, type IngestDeps } from './ingest.js'
import { createSessionNormalizers } from './normalizers.js'
import type { LiveFrame } from '../../engines/worker/liveProtocol.js'
import { engineNow, loadEngine, OTHER_ENGINES } from '../../engines/inProcess.js'
// A test of the line path stands for an attach that has loaded the engines' code before their tails started
// (core/transcripts/attach.ts); a test may say it is not there.
vi.mock('../../engines/inProcess.js', async (real) => {
const actual = await real<typeof import('../../engines/inProcess.js')>()
return { ...actual, engineNow: vi.fn(actual.engineNow) }
})
beforeAll(async () => { for (const engine of OTHER_ENGINES) await loadEngine(engine) })
const CODEX_FAILED = JSON.stringify({ type: 'event_msg', payload: { type: 'task_complete', error: { message: 'rate limited' } } })
const COMMANDCODE_FAILED = JSON.stringify({ type: 'message', message: { role: 'user', content: [{ type: 'text', text: 'Error: 500\nTrace ID: 932a' }] } })
const CLAUDE_PROMPT = JSON.stringify({ type: 'user', message: { role: 'user', content: 'hello' } })
function setup(engines: Record<string, string>, over: Partial<IngestDeps> = {}) {
const sessions = new Map(Object.entries(engines).map(([sessionId, engine]) =>
[sessionId, { agentId: `agent-${sessionId}`, sessionId, engine, transcriptPath: `/t/${sessionId}.jsonl` } as RegisteredSession]))
const normalizers = createSessionNormalizers()
const service = { needsTranscript: vi.fn(() => false), observeTranscript: vi.fn() }
const deps: IngestDeps = {
liveFor,
has: (sessionId) => sessions.has(sessionId),
bySession: (sessionId) => sessions.get(sessionId),
tokenUsage: { changed: vi.fn() },
device: () => service,
runtimeProfiles: { ingest: vi.fn() },
normalizers,
announceTurnAborted: vi.fn(),
emit: vi.fn(),
attachSession: vi.fn(async () => true),
...over,
}
return { deps, sessions, normalizers, service, ingest: createIngest(deps) }
}
const line = (sessionId: string, engine: string, text = '{}'): LineEvent => ({ sessionId, engine, text } as LineEvent)
describe('ingesting a transcript line', () => {
afterEach(() => vi.restoreAllMocks())
it('accepts worker events only for the bound engine, preserving replay and side reads without constructing a parser', () => {
const p = setup({ s1: 'claude' }, { liveFor: () => { throw new Error('worker events are already normalized') } })
const frame: LiveFrame = { raw: CLAUDE_PROMPT, events: [{ type: 'turn_started', payload: { userMessage: 'hello' } }],
profile: true, observe: true, replay: true, turn: { identity: 'worker:turn', turnOpen: true, continued: false } }
p.ingest.acceptFrame('unknown', 'claude', frame)
p.ingest.acceptFrame('s1', 'codex', frame)
expect(p.deps.emit).not.toHaveBeenCalled()
p.ingest.acceptFrame('s1', 'claude', frame)
expect(p.deps.emit).toHaveBeenCalledWith('s1', frame.events, { replay: true })
expect(p.deps.runtimeProfiles.ingest).toHaveBeenCalledWith(p.sessions.get('s1'), frame.raw)
p.ingest.acceptFrame('s1', 'claude', { ...frame, replay: false, failure: 'rate limited' })
expect(p.deps.announceTurnAborted).toHaveBeenCalledWith('s1', 'claude', 'rate limited')
expect(vi.mocked(p.deps.announceTurnAborted).mock.invocationCallOrder[0])
.toBeLessThan(vi.mocked(p.deps.emit).mock.invocationCallOrder[1])
expect(p.deps.emit).toHaveBeenLastCalledWith('s1', frame.events, { replay: false })
expect(p.normalizers.hasState('s1')).toBe(false)
vi.mocked(p.deps.runtimeProfiles.ingest).mockClear()
p.ingest.acceptFrame('s1', 'claude', frame, true)
expect(p.deps.runtimeProfiles.ingest).not.toHaveBeenCalled()
expect(p.deps.tokenUsage.changed).toHaveBeenCalledWith(p.sessions.get('s1'))
expect(p.deps.emit).toHaveBeenLastCalledWith('s1', frame.events, { replay: true })
})
it('takes lines only for a registered session of the engine that wrote them', () => {
const { ingest, deps } = setup({ s1: 'claude', s2: 'codex' })
expect(ingest.ingestLine(line('nobody', 'claude'))).toBeNull()
expect(ingest.ingestLine(line('s1', 'codex'))).toBeNull()
const ghost = setup({}, { has: () => true })
expect(ghost.ingest.ingestLine(line('s9', 'claude'))).toBeNull()
expect(deps.tokenUsage.changed).not.toHaveBeenCalled()
})
it('defers live interpretation, usage and profile effects while a saved binding is held', () => {
const run = setup({ s1: 'claude' })
run.sessions.get('s1')!.identityHold = 'header unavailable'
expect(run.ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))).toBeNull()
expect(run.normalizers.hasState('s1')).toBe(false)
expect(run.deps.tokenUsage.changed).not.toHaveBeenCalled()
expect(run.deps.runtimeProfiles.ingest).not.toHaveBeenCalled()
expect(run.service.needsTranscript).not.toHaveBeenCalled()
})
it('counts tokens, shows the device its raw lines when it asks, and reads the runtime from each line', () => {
const { ingest, deps, service, sessions } = setup({ s1: 'claude' })
ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))
expect(deps.tokenUsage.changed).toHaveBeenCalledWith(sessions.get('s1'))
expect(service.observeTranscript).not.toHaveBeenCalled()
service.needsTranscript.mockReturnValue(true)
ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))
expect(service.observeTranscript).toHaveBeenCalledWith('agent-s1', 's1', 'claude', CLAUDE_PROMPT)
expect(deps.runtimeProfiles.ingest).toHaveBeenCalledWith(sessions.get('s1'), CLAUDE_PROMPT)
const none = setup({ s1: 'claude' }, { device: () => undefined })
expect(none.ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))).toEqual(expect.any(Array))
})
it('gives a line to its engine though the device or the runtime profile cannot take it in, and says so once a session', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const clean = setup({ s1: 'claude' })
const expected = clean.ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))
expect(expected).not.toEqual([])
const { ingest, deps, service } = setup({ s1: 'claude', s2: 'claude' })
service.needsTranscript.mockReturnValue(true)
service.observeTranscript.mockImplementation(() => { throw new Error('evidence unreadable') })
vi.mocked(deps.runtimeProfiles.ingest).mockImplementation(() => { throw 'profile unreadable' })
// The line's events are the ones it has without the two readers: a turn's start, here.
expect(ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))).toEqual(expected)
ingest.ingestLine(line('s1', 'claude', '{}'))
ingest.ingestLine(line('s2', 'claude', CLAUDE_PROMPT))
expect(deps.runtimeProfiles.ingest).toHaveBeenCalledTimes(3)
expect(error.mock.calls).toEqual([
['[transcripts] the device could not take in a line of s1; the line goes on to its engine: evidence unreadable'],
['[transcripts] the runtime profile could not take in a line of s1; the line goes on to its engine: profile unreadable'],
['[transcripts] the device could not take in a line of s2; the line goes on to its engine: evidence unreadable'],
['[transcripts] the runtime profile could not take in a line of s2; the line goes on to its engine: profile unreadable'],
])
})
it('keeps every line of a catch-up batch though a reader throws on the first', () => {
vi.spyOn(console, 'error').mockImplementation(() => {})
const run = setup({ s1: 'claude' })
const watcher = new EventEmitter()
run.ingest.wireWatcher(watcher as unknown as Pick<Watcher, 'on'>)
vi.mocked(run.deps.runtimeProfiles.ingest).mockImplementationOnce(() => { throw new Error('bad record') })
const reply = JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } })
watcher.emit('history', { sessionId: 's1', lines: [line('s1', 'claude', CLAUDE_PROMPT), line('s1', 'claude', reply)] } as HistoryEvent)
const clean = setup({ s1: 'claude' })
const expected = [...clean.ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))!, ...clean.ingest.ingestLine(line('s1', 'claude', reply))!]
expect(vi.mocked(run.deps.emit).mock.calls).toEqual([['s1', expected, { replay: true }]])
})
it('creates each file engine\'s normalizer on the session\'s first line, and keeps it', () => {
const engines = {
cursor: CursorNormalizer, muse: MuseNormalizer, amp: AmpNormalizer, grok: GrokNormalizer,
agy: AgyNormalizer, copilot: CopilotNormalizer, pi: PiNormalizer, omp: OmpNormalizer,
commandcode: CommandCodeNormalizer,
} as const
const run = setup(Object.fromEntries(Object.keys(engines).map((engine) => [engine, engine])))
const maps = {
cursor: run.normalizers.cursorNormalizers, muse: run.normalizers.museNormalizers,
amp: run.normalizers.ampNormalizers, grok: run.normalizers.grokNormalizers, agy: run.normalizers.agyNormalizers,
copilot: run.normalizers.copilotNormalizers, pi: run.normalizers.piNormalizers, omp: run.normalizers.ompNormalizers,
commandcode: run.normalizers.commandcodeNormalizers,
} as Record<keyof typeof engines, Map<string, unknown>>
for (const [engine, Normalizer] of Object.entries(engines) as Array<[keyof typeof engines, new (...args: never[]) => unknown]>) {
expect(run.ingest.ingestLine(line(engine, engine)), engine).toEqual(expect.any(Array))
const first = maps[engine].get(engine)
expect(first, engine).toBeInstanceOf(Normalizer)
run.ingest.ingestLine(line(engine, engine))
expect(maps[engine].get(engine), `${engine} keeps its normalizer`).toBe(first)
}
})
it('reads no events from a file engine\'s lines while its code is unavailable, and makes no normalizer', () => {
const engines = ['cursor', 'muse', 'amp', 'grok', 'agy', 'copilot', 'pi', 'omp', 'commandcode']
const run = setup(Object.fromEntries(engines.map((engine) => [engine, engine])))
vi.mocked(engineNow).mockReturnValue(null)
for (const engine of engines) {
expect(run.ingest.ingestLine(line(engine, engine, engine === 'commandcode' ? COMMANDCODE_FAILED : '{}')), engine).toEqual([])
expect(run.normalizers.hasState(engine), engine).toBe(false)
}
expect(run.deps.announceTurnAborted).not.toHaveBeenCalled()
vi.mocked(engineNow).mockReset()
})
it('creates a live parser once, preserving the terminal fallback', () => {
const run = setup({ s1: 'claude', s2: 'terminal' })
const events = run.ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))!
expect(events.map((event) => event.type)).toContain('turn_started')
const state = run.normalizers.liveParsers.get('s1')
run.ingest.ingestLine(line('s1', 'claude', '{}'))
expect(run.normalizers.liveParsers.get('s1')).toBe(state)
run.ingest.ingestLine(line('s2', 'terminal', '{}'))
expect(run.normalizers.liveParsers.has('s2')).toBe(true)
})
it('announces the reason a Codex or Command Code turn failed', () => {
const run = setup({ cx: 'codex', cc: 'commandcode' })
run.ingest.ingestLine(line('cx', 'codex', CODEX_FAILED))
run.ingest.ingestLine(line('cc', 'commandcode', COMMANDCODE_FAILED))
run.ingest.ingestLine(line('cx', 'codex', '{}'))
run.ingest.ingestLine(line('cc', 'commandcode', '{}'))
expect(vi.mocked(run.deps.announceTurnAborted).mock.calls).toEqual([
['cx', 'codex', 'rate limited'],
['cc', 'commandcode', 'Error: 500\nTrace ID: 932a', 'Error: 500'],
])
})
it('leaves a database engine to its reader when a file line is delivered for it', () => {
const run = setup({ db: 'opencode' })
expect(run.ingest.ingestLine(line('db', 'opencode', CLAUDE_PROMPT))).toEqual([])
expect(run.normalizers.hasState('db')).toBe(false)
})
it('replaces a parser when the same session id is rebound to another engine', () => {
const run = setup({ s1: 'claude' })
run.ingest.ingestLine(line('s1', 'claude', CLAUDE_PROMPT))
const previous = run.normalizers.liveParsers.get('s1')!
run.sessions.get('s1')!.engine = 'codex'
const prompt = JSON.stringify({ type: 'event_msg', payload: { type: 'user_message', message: 'new engine' } })
expect(run.ingest.ingestLine(line('s1', 'codex', prompt))?.find(event => event.type === 'turn_started')?.payload).toEqual({ userMessage: 'new engine' })
expect(run.normalizers.liveParsers.get('s1')).not.toBe(previous)
expect(run.normalizers.liveParsers.get('s1')!.engine).toBe('codex')
expect(previous.turnOpen).toBe(true)
})
})
describe('the watcher wiring', () => {
afterEach(() => vi.restoreAllMocks())
function wired(engines: Record<string, string>, over: Partial<IngestDeps> = {}) {
const run = setup(engines, over)
const watcher = new EventEmitter()
run.ingest.wireWatcher(watcher as unknown as Pick<Watcher, 'on'>)
return { ...run, watcher }
}
it('streams each live line, and contains a line that throws', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const run = wired({ s1: 'claude' })
run.watcher.emit('line', line('s1', 'claude', CLAUDE_PROMPT))
run.watcher.emit('line', line('nobody', 'claude', CLAUDE_PROMPT))
expect(vi.mocked(run.deps.emit).mock.calls).toHaveLength(1)
expect(vi.mocked(run.deps.emit).mock.calls[0][0]).toBe('s1')
vi.mocked(run.deps.tokenUsage.changed).mockImplementationOnce(() => { throw new Error('bad line') })
run.watcher.emit('line', line('s1', 'claude', CLAUDE_PROMPT))
vi.mocked(run.deps.tokenUsage.changed).mockImplementationOnce(() => { throw 'worse' })
run.watcher.emit('line', line('s1', 'claude', CLAUDE_PROMPT))
expect(error.mock.calls).toEqual([
['[cli] line handler error (session s1):', 'bad line'],
['[cli] line handler error (session s1):', 'worse'],
])
})
it('emits a catch-up batch as one replay, and nothing when it holds no events', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const run = wired({ s1: 'claude' })
const batch = (lines: LineEvent[]): HistoryEvent => ({ sessionId: 's1', lines } as HistoryEvent)
run.watcher.emit('history', batch([line('s1', 'claude', CLAUDE_PROMPT), line('nobody', 'claude'), line('s1', 'claude', '{}')]))
run.watcher.emit('history', batch([line('nobody', 'claude')]))
expect(vi.mocked(run.deps.emit).mock.calls).toHaveLength(1)
expect(vi.mocked(run.deps.emit).mock.calls[0][2]).toEqual({ replay: true })
vi.mocked(run.deps.tokenUsage.changed).mockImplementationOnce(() => { throw new Error('bad batch') })
run.watcher.emit('history', batch([line('s1', 'claude', CLAUDE_PROMPT)]))
vi.mocked(run.deps.tokenUsage.changed).mockImplementationOnce(() => { throw 'worse' })
run.watcher.emit('history', batch([line('s1', 'claude', CLAUDE_PROMPT)]))
expect(error.mock.calls).toEqual([
['[cli] history handler error (session s1):', 'bad batch'],
['[cli] history handler error (session s1):', 'worse'],
])
})
it('attaches a transcript rewritten in place again, from its end, and only the session\'s own', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const run = wired({ s1: 'claude' })
const rewritten = (sessionId: string, transcriptPath: string) => ({ sessionId, transcriptPath } as RewrittenEvent)
run.watcher.emit('rewritten', rewritten('nobody', '/t/nobody.jsonl'))
run.watcher.emit('rewritten', rewritten('s1', '/t/other.jsonl'))
expect(run.deps.attachSession).not.toHaveBeenCalled()
run.watcher.emit('rewritten', rewritten('s1', '/t/s1.jsonl'))
expect(run.deps.attachSession).toHaveBeenCalledWith(run.sessions.get('s1'), true)
expect(String(log.mock.calls[0][0])).toContain('transcript rewritten in place — attaching it again from its end')
vi.mocked(run.deps.attachSession).mockRejectedValueOnce(new Error('pane gone')).mockRejectedValueOnce('tmux down')
run.watcher.emit('rewritten', rewritten('s1', '/t/s1.jsonl'))
run.watcher.emit('rewritten', rewritten('s1', '/t/s1.jsonl'))
await new Promise((done) => setTimeout(done, 0))
expect(error.mock.calls.map((call) => call[1])).toEqual(['pane gone', 'tmux down'])
})
})