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 { EngineReadError } from '../../engines/worker/protocol.js'
import { engineTranscriptFor } from '../../engines/transcripts.js'
import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { readAmpThread } from '../../engines/amp/threadExport.js'
import { codexMessagesToEvents } from '../../engines/codex/normalizer.js'
import { codexSubagentResolverFor } from '../../engines/codex/subagent.js'
import { cursorMessagesToEvents, windowCursorLines } from '../../engines/cursor/normalizer.js'
import { loadCursorReplayTaskLinks } from '../../engines/cursor/subagent.js'
import { devinMessagesToEvents, windowDevinMessages } from '../../engines/devin/normalizer.js'
import { readDevinMessages } from '../../engines/devin/reader.js'
import { readHermesMessages } from '../../engines/hermes/reader.js'
import { readKiloMessages } from '../../engines/kilo/reader.js'
import { readOpencodeMessages } from '../../engines/opencode/reader.js'
import { piMessagesToEvents } from '../../engines/pi/normalizer.js'
import { lastActivityAt } from '../../lib/agentFrame.js'
import { sid } from '../../lib/log.js'
import { messagesToEvents, windowRawLines } from '../../lib/normalize.js'
import type { RegisteredSession } from '../../lib/registry.js'
import type { HistoryPage, ThreadPages } from '../../lib/transcriptPages.js'
import { tailFileCapped } from '../../lib/transcriptTail.js'
import { createHistory, wholeHistoryPage } from './history.js'
import { loadEngine } from '../../engines/inProcess.js'
/**
* `session_get`, answered by the core: which reader, replay and window each engine's history goes
* through, and the reply that comes back, field for field.
*
* The engines' own readers, replays and windows are tested with each engine; here each is a fake that
* says who answered. A replay names itself in every event it makes and ends with the end marker, as
* every real replay does; a window names its engine and the record a page starts at in its cursors, and
* reads `stale` as a cursor it cannot find. Transcript reading and sub-agent totals are the real ones.
* The whole path through the socket, with the real engines, is in backendSocket.history.spec.ts and
* backendSocket.cappedHistory.spec.ts.
*/
const fake = vi.hoisted(() => {
const replay = (from: string) => (records: unknown[]) => [
...records.map((record) => ({ type: 'text_delta', payload: { content: `${from}: ${String(record)}` } })),
{ type: 'done', payload: { result: 'success' } },
]
const windowOf = (from: string) => (records: unknown[], { limit, before }: { limit: number; before?: string }) => {
if (before === 'stale') return { window: [], hasMore: false, oldestCursor: null, staleCursor: true }
const end = before ? Number(before.slice(from.length + 1)) : records.length
const start = Math.max(0, end - limit)
return { window: records.slice(start, end), hasMore: start > 0, oldestCursor: `${from}:${start}` }
}
const resolver = (): null => null
return { replay, windowOf, resolver }
})
vi.mock('../../engines/devin/reader.js', async (real) => ({ ...await real<object>(), readDevinMessages: vi.fn(async () => ['d0', 'd1', 'd2', 'd3']) }))
vi.mock('../../engines/hermes/reader.js', async (real) => ({ ...await real<object>(), readHermesMessages: vi.fn(async () => ['h0', 'h1', 'h2', 'h3']) }))
vi.mock('../../engines/opencode/reader.js', async (real) => ({ ...await real<object>(), readOpencodeMessages: vi.fn(async () => ['o0', 'o1', 'o2', 'o3']) }))
vi.mock('../../engines/kilo/reader.js', async (real) => ({ ...await real<object>(), readKiloMessages: vi.fn(async () => ['k0', 'k1', 'k2', 'k3']) }))
vi.mock('../../engines/devin/normalizer.js', async (real) => ({ ...await real<object>(), devinMessagesToEvents: vi.fn(fake.replay('devin')), windowDevinMessages: vi.fn(fake.windowOf('devin')) }))
vi.mock('../../engines/hermes/normalizer.js', async (real) => ({ ...await real<object>(), hermesMessagesToEvents: vi.fn(fake.replay('hermes')), windowHermesMessages: vi.fn(fake.windowOf('hermes')) }))
vi.mock('../../engines/opencode/normalizer.js', async (real) => ({ ...await real<object>(), opencodeMessagesToEvents: vi.fn(fake.replay('opencode')), windowOpencodeMessages: vi.fn(fake.windowOf('opencode')) }))
vi.mock('../../engines/kilo/normalizer.js', async (real) => ({ ...await real<object>(), kiloMessagesToEvents: vi.fn(fake.replay('kilo')), windowKiloMessages: vi.fn(fake.windowOf('kilo')) }))
vi.mock('../../engines/muse/normalizer.js', async (real) => ({ ...await real<object>(), museMessagesToEvents: vi.fn(fake.replay('muse')) }))
vi.mock('../../engines/amp/normalizer.js', async (real) => ({ ...await real<object>(), ampMessagesToEvents: vi.fn(fake.replay('amp')) }))
vi.mock('../../engines/amp/threadExport.js', async (real) => ({ ...await real<object>(), readAmpThread: vi.fn(async () => null), ampThreadToEvents: vi.fn(fake.replay('amp export')) }))
vi.mock('../../engines/grok/normalizer.js', async (real) => ({ ...await real<object>(), grokMessagesToEvents: vi.fn(fake.replay('grok')) }))
vi.mock('../../engines/agy/normalizer.js', async (real) => ({ ...await real<object>(), agyMessagesToEvents: vi.fn(fake.replay('agy')) }))
vi.mock('../../engines/copilot/normalizer.js', async (real) => ({ ...await real<object>(), copilotMessagesToEvents: vi.fn(fake.replay('copilot')) }))
vi.mock('../../engines/pi/normalizer.js', async (real) => ({ ...await real<object>(), piMessagesToEvents: vi.fn(fake.replay('pi')), windowPiLines: vi.fn(fake.windowOf('pi')) }))
vi.mock('../../engines/omp/normalizer.js', async (real) => ({ ...await real<object>(), ompMessagesToEvents: vi.fn(fake.replay('omp')), windowOmpLines: vi.fn(fake.windowOf('omp')) }))
vi.mock('../../engines/commandcode/normalizer.js', async (real) => ({ ...await real<object>(), commandcodeMessagesToEvents: vi.fn(fake.replay('commandcode')), windowCommandCodeLines: vi.fn(fake.windowOf('commandcode')) }))
vi.mock('../../engines/cursor/normalizer.js', async (real) => ({
...await real<object>(),
cursorMessagesToEvents: vi.fn((lines: unknown[]) => fake.replay('cursor')(lines)),
windowCursorLines: vi.fn((lines: unknown[], opts: { limit: number; before?: string }) => ({ ...fake.windowOf('cursor')(lines, opts), startIndex: 7, initialTodos: ['a todo carried in'] })),
}))
vi.mock('../../engines/cursor/subagent.js', async (real) => ({ ...await real<object>(), loadCursorReplayTaskLinks: vi.fn(async () => ['a task link']) }))
vi.mock('../../engines/cursor/home.js', async (real) => ({ ...await real<object>(), cursorConfigDir: vi.fn(() => '/cursor/config'), cursorDataDir: vi.fn(() => '/cursor/data') }))
vi.mock('../../engines/codex/normalizer.js', async (real) => ({ ...await real<object>(), codexMessagesToEvents: vi.fn((lines: unknown[]) => fake.replay('codex')(lines)) }))
vi.mock('../../engines/codex/subagent.js', async (real) => ({ ...await real<object>(), codexSubagentResolverFor: vi.fn(() => fake.resolver) }))
vi.mock('../../engines/claude/normalize.js', async (real) => ({ ...await real<object>(), messagesToEvents: vi.fn(fake.replay('claude')), windowRawLines: vi.fn(fake.windowOf('raw')) }))
vi.mock('../../lib/agentFrame.js', async (real) => ({ ...await real<object>(), lastActivityAt: vi.fn(async () => Date.parse('2026-10-05T08:45:00.000Z')) }))
vi.mock('../../lib/transcriptTail.js', async (real) => {
const actual = await real<typeof import('../../lib/transcriptTail.js')>()
return { ...actual, tailFileCapped: vi.fn(actual.tailFileCapped) }
})
// Each engine's readers are its own code, loaded in this process; a test may say one could not be.
vi.mock('../../engines/inProcess.js', async (real) => {
const actual = await real<typeof import('../../engines/inProcess.js')>()
return { ...actual, loadEngine: vi.fn(actual.loadEngine) }
})
const MTIME = new Date('2026-10-04T12:00:00.000Z')
const TOUCHED = Date.parse('2026-10-05T08:30:00.000Z')
const NOW = Date.parse('2026-10-05T09:00:00.000Z')
const replayed = (from: string, records: readonly unknown[]) => fake.replay(from)([...records])
/** A page that is not the newest: what a replay made of it, without the end marker. */
const older = (from: string, records: readonly unknown[]) => replayed(from, records).slice(0, -1)
const page = (lines: string[], hasMore: boolean, oldestCursor: string | null, staleCursor?: true): HistoryPage =>
({ lines, hasMore, oldestCursor, clipped: false, ...(staleCursor ? { staleCursor } : {}) })
let dir: string
beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'history-')) })
afterEach(() => {
rmSync(dir, { recursive: true, force: true })
vi.restoreAllMocks()
vi.resetAllMocks()
})
const session = (engine: string, over: Partial<RegisteredSession> = {}) => ({
agentId: `agent-${engine}`, sessionId: `${engine}-session`, engine, defaultName: 'Release notes', cwd: '/work/app',
transcriptPath: null, touchedAt: TOUCHED, codexHome: null, ...over,
}) as RegisteredSession
/** A transcript of these lines, last written at MTIME. */
function transcript(lines: string[], name = 'session.jsonl'): string {
const file = join(dir, name)
writeFileSync(file, lines.map((line) => `${line}\n`).join(''))
utimesSync(file, MTIME, MTIME)
return file
}
function setup(s?: RegisteredSession, kept: RegisteredSession[] = [], readerFor = engineTranscriptFor) {
// The pager pages a thread by the rules its engine's reader hands it: a record's cursor (Claude Code's) or a
// line count (Codex's). Each kind is its own mock, so what each engine asked for is checked by kind.
const claude = vi.fn(async (_path: string, _opts: { limit?: number; before?: string }) => page([], false, null))
const codex = vi.fn(async (_path: string, _opts: { limit?: number; before?: string }) => page([], false, null))
const pages = {
claude, codex,
page: vi.fn(async (path: string, rules: ThreadPages, opts: { limit?: number; before?: string }) => rules.cursor === 'record' ? claude(path, opts) : codex(path, opts)),
lineCount: vi.fn(async (_path: string) => 0),
}
const deps = {
resolve: vi.fn((id: string) => (s && (id === s.sessionId || id === s.agentId) ? s : undefined)),
stopped: vi.fn(() => kept),
pages,
readerFor,
dbs: { opencode: '/stores/opencode.db', kilo: '/stores/kilo.db', devin: '/stores/sessions.db' },
hermesDb: vi.fn(async () => '/profiles/work/state.db'),
}
return { ...createHistory(deps), deps, pages }
}
/** The fields every reply about a session carries. Their order on the wire is checked on its own. */
const about = (s: RegisteredSession, timestamp: number | Date) =>
({ id: s.sessionId, title: 'Release notes', timestamp: new Date(timestamp).toISOString(), engine: s.engine })
describe('a shell result in history', () => {
it('never carries the turn stats\' outputTail', async () => {
const s = session('devin')
const end = { type: 'tool_end', payload: { id: 't1', tool: 'Bash', output: 'x', outputTail: 'tail', isError: false, summary: '' } }
vi.mocked(devinMessagesToEvents).mockReturnValueOnce([end] as never).mockReturnValueOnce([end] as never)
const { sessionGet } = setup(s)
for (const ask of [{}, { limit: 2 }]) {
const events = (await sessionGet({ sessionId: s.sessionId, ...ask })).events as Array<{ payload: object }>
expect(events).toEqual([{ type: 'tool_end', payload: { id: 't1', tool: 'Bash', output: 'x', isError: false, summary: '' } }])
}
})
})
describe('an engine whose code could not be loaded', () => {
it('shows an empty conversation, from a store or a transcript, and reads nothing of it', async () => {
const { readDevinMessages } = await import('../../engines/devin/reader.js')
vi.mocked(loadEngine).mockResolvedValue(null as never)
const db = session('devin')
expect(await setup(db).sessionGet({ sessionId: db.sessionId, limit: 5 })).toStrictEqual({ ...about(db, TOUCHED), events: [], hasMore: false, oldestCursor: null })
expect(readDevinMessages).not.toHaveBeenCalled()
const file = session('grok', { transcriptPath: transcript(['g0']) })
expect(await setup(file).sessionGet({ sessionId: file.sessionId })).toStrictEqual({ ...about(file, MTIME), events: [], hasMore: false, oldestCursor: null })
})
// Core reads no engine's lines itself: Claude Code's and Codex's replays are their readers'. A shell keeps no
// transcript (registry.engineKeepsTranscriptFile), so this is only what a row that somehow had one would get.
it('so does an engine with neither a reader nor code of its own here', async () => {
const s = session('terminal', { transcriptPath: transcript(['l0', 'l1']) })
for (const ask of [{}, { limit: 2 }, { limit: 2, before: 'raw:1' }]) {
expect(await setup(s, [], () => undefined).sessionGet({ sessionId: s.sessionId, ...ask })).toStrictEqual({ ...about(s, MTIME), events: [], hasMore: false, oldestCursor: null })
}
const claude = session('claude', { transcriptPath: transcript(['c0']) })
expect(await setup(claude, [], () => undefined).sessionGet({ sessionId: claude.sessionId, limit: 2 })).toStrictEqual({ ...about(claude, MTIME), events: [], hasMore: false, oldestCursor: null })
expect(messagesToEvents).not.toHaveBeenCalled()
expect(windowRawLines).not.toHaveBeenCalled()
})
})
describe('what cannot be served', () => {
it('asks for a session id, and reads only a session the registry knows', async () => {
const { sessionGet, deps } = setup()
expect(await sessionGet({})).toStrictEqual({ error: 'MISSING_SESSION_ID' })
expect(await sessionGet({ sessionId: '' })).toStrictEqual({ error: 'MISSING_SESSION_ID' })
expect(deps.resolve).not.toHaveBeenCalled()
// Never a path: an id that names no registered session names nothing to read.
expect(await sessionGet({ sessionId: '../../outside/secret.jsonl', limit: 5 })).toStrictEqual({ error: 'NOT_FOUND' })
expect(deps.resolve).toHaveBeenCalledWith('../../outside/secret.jsonl')
})
it('answers a session whose engine has written nothing yet with an empty thread, stamped when it was last touched', async () => {
const s = session('claude')
const { sessionGet, pages } = setup(s)
const reply = await sessionGet({ sessionId: s.sessionId, limit: 50 })
expect(reply).toStrictEqual({ ...about(s, TOUCHED), events: [], hasMore: false, oldestCursor: null })
expect(Object.keys(reply)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor'])
expect(pages.claude).not.toHaveBeenCalled()
})
it('a conversation kept as a stopped harness, once nothing live holds it, but never by its harness\'s id', async () => {
const live = session('claude')
const kept = { ...session('claude'), agentId: 'kept-agent', sessionId: 'kept-session' } as RegisteredSession
const { sessionGet, deps } = setup(live, [kept])
expect(await sessionGet({ sessionId: 'kept-session', limit: 50 })).toMatchObject({ id: 'kept-session', engine: 'claude', events: [] })
expect(deps.resolve).toHaveBeenCalledWith('kept-session')
// What is live is answered from the registry, without reading the saved ones.
deps.stopped.mockClear()
expect(await sessionGet({ sessionId: live.sessionId, limit: 50 })).toMatchObject({ id: live.sessionId })
expect(deps.stopped).not.toHaveBeenCalled()
expect(await sessionGet({ sessionId: 'kept-agent', limit: 50 })).toStrictEqual({ error: 'NOT_FOUND' })
})
it('found by agent id too, and still answers with the id it was asked for', async () => {
const s = session('claude')
const { sessionGet } = setup(s)
expect(await sessionGet({ sessionId: s.agentId })).toMatchObject({ id: s.agentId, engine: 'claude' })
})
})
describe('the engines that keep a conversation in a database', () => {
const engines = [
['devin', readDevinMessages, '/stores/sessions.db', ['d0', 'd1', 'd2', 'd3']],
['hermes', readHermesMessages, '/profiles/work/state.db', ['h0', 'h1', 'h2', 'h3']],
['opencode', readOpencodeMessages, '/stores/opencode.db', ['o0', 'o1', 'o2', 'o3']],
['kilo', readKiloMessages, '/stores/kilo.db', ['k0', 'k1', 'k2', 'k3']],
] as const
it.each(engines)('%s: the whole conversation, read from its own store and replayed', async (engine, reader, store, messages) => {
const s = session(engine)
const { sessionGet, deps } = setup(s)
const reply = await sessionGet({ sessionId: s.sessionId })
expect(reply).toStrictEqual({ ...about(s, TOUCHED), events: replayed(engine, messages) })
expect(Object.keys(reply)).toEqual(['id', 'title', 'events', 'timestamp', 'engine'])
expect(reader).toHaveBeenCalledWith(store, s.sessionId)
// Hermes keeps a store per profile, and reads the one its session lives in.
if (engine === 'hermes') expect(deps.hermesDb).toHaveBeenCalledWith(s)
else expect(deps.hermesDb).not.toHaveBeenCalled()
})
it.each(engines)('%s: the newest page, the page before it, and a cursor it cannot find', async (engine, _reader, _store, messages) => {
const s = session(engine)
const { sessionGet } = setup(s)
const newest = await sessionGet({ sessionId: s.sessionId, limit: 2 })
// The newest page ends the thread, so it keeps the end marker; an older page must not carry one.
expect(newest).toStrictEqual({ ...about(s, TOUCHED), events: replayed(engine, messages.slice(2)), hasMore: true, oldestCursor: `${engine}:2` })
expect(Object.keys(newest)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor'])
expect(await sessionGet({ sessionId: s.sessionId, limit: 2, before: `${engine}:2` }))
.toStrictEqual({ ...about(s, TOUCHED), events: older(engine, messages.slice(0, 2)), hasMore: false, oldestCursor: `${engine}:0` })
const stale = await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'stale' })
expect(stale).toStrictEqual({ ...about(s, TOUCHED), events: [], hasMore: false, oldestCursor: null, staleCursor: true })
expect(Object.keys(stale)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor', 'staleCursor'])
})
it('reads a limit that makes no sense as none, the most a page may hold, or rounded down', async () => {
const s = session('devin')
const { sessionGet } = setup(s)
for (const limit of [0, -5, 'ten', null]) expect(await sessionGet({ sessionId: s.sessionId, limit })).not.toHaveProperty('hasMore')
expect(windowDevinMessages).not.toHaveBeenCalled()
await sessionGet({ sessionId: s.sessionId, limit: 10_000 })
expect(windowDevinMessages).toHaveBeenLastCalledWith(['d0', 'd1', 'd2', 'd3'], { limit: 500, before: undefined })
await sessionGet({ sessionId: s.sessionId, limit: 2.7, before: 7 })
expect(windowDevinMessages).toHaveBeenLastCalledWith(['d0', 'd1', 'd2', 'd3'], { limit: 2, before: undefined })
})
it('an older page drops only an end marker: a page that ends otherwise, or holds nothing, is kept as it is', async () => {
const s = session('devin')
const { sessionGet } = setup(s)
const text = { type: 'text_delta', payload: { content: 'mid-turn' } }
vi.mocked(devinMessagesToEvents).mockReturnValueOnce([text] as never).mockReturnValueOnce([])
expect((await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'devin:2' })).events).toEqual([text])
expect((await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'devin:2' })).events).toEqual([])
})
it('a store that cannot be read fails the request, for the socket to answer', async () => {
const s = session('kilo')
const { sessionGet } = setup(s)
vi.mocked(readKiloMessages).mockRejectedValueOnce(new Error('no sqlite3'))
await expect(sessionGet({ sessionId: s.sessionId, limit: 2 })).rejects.toThrow('no sqlite3')
})
})
describe('Claude Code and Codex: only the page asked for is read', () => {
it('Claude Code: a page from the pager, replayed, stamped with the transcript\'s last write', async () => {
const file = transcript(['c1', 'c2', 'c3'])
const s = session('claude', { transcriptPath: file })
const { sessionGet, pages } = setup(s)
pages.claude.mockResolvedValueOnce(page(['c2', 'c3'], true, 'uuid-2'))
const reply = await sessionGet({ sessionId: s.sessionId, limit: 2 })
expect(reply).toStrictEqual({ ...about(s, MTIME), events: replayed('claude', ['c2', 'c3']), hasMore: true, oldestCursor: 'uuid-2' })
expect(Object.keys(reply)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor'])
expect(pages.claude).toHaveBeenCalledWith(file, { limit: 2, before: undefined })
expect(pages.codex).not.toHaveBeenCalled()
})
it('an older page drops its end marker and nothing else; a read with no limit ignores a cursor and keeps it', async () => {
const file = transcript(['c1', 'c2', 'c3'])
const s = session('claude', { transcriptPath: file })
const { sessionGet, pages } = setup(s)
pages.claude.mockResolvedValueOnce(page(['c1'], false, 'uuid-1'))
expect(await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'uuid-2' }))
.toStrictEqual({ ...about(s, MTIME), events: older('claude', ['c1']), hasMore: false, oldestCursor: 'uuid-1' })
expect(pages.claude).toHaveBeenLastCalledWith(file, { limit: 2, before: 'uuid-2' })
// Without a limit, the newest lines that fit a page: a cursor means nothing then, and the reply is the
// full-transcript one, with no cursor while every line fit.
pages.claude.mockResolvedValueOnce(page(['c1', 'c2', 'c3'], false, 'uuid-1'))
const whole = await sessionGet({ sessionId: s.sessionId, before: 'uuid-2' })
expect(whole).toStrictEqual({ ...about(s, MTIME), events: replayed('claude', ['c1', 'c2', 'c3']) })
expect(Object.keys(whole)).toEqual(['id', 'title', 'events', 'timestamp', 'engine'])
expect(pages.claude).toHaveBeenLastCalledWith(file, {})
// Only an end marker is dropped: an older page that ends otherwise, or holds nothing, is kept as it is.
const text = { type: 'text_delta', payload: { content: 'mid-turn' } }
vi.mocked(messagesToEvents).mockReturnValueOnce([text] as never).mockReturnValueOnce([])
expect((await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'uuid-1' })).events).toEqual([text])
expect((await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'uuid-1' })).events).toEqual([])
})
it('without a limit, a thread longer than a page holds answers with the cursor to the rest', async () => {
const s = session('claude', { transcriptPath: transcript(['c1', 'c2', 'c3']) })
const { sessionGet, pages } = setup(s)
pages.claude.mockResolvedValueOnce({ ...page(['c3'], true, 'uuid-3'), clipped: true })
expect(await sessionGet({ sessionId: s.sessionId })).toStrictEqual({ ...about(s, MTIME), events: replayed('claude', ['c3']), hasMore: true, oldestCursor: 'uuid-3' })
})
it('a cursor the pager cannot find is stale, so the client reloads', async () => {
const s = session('claude', { transcriptPath: transcript(['c1']) })
const { sessionGet, pages } = setup(s)
pages.claude.mockResolvedValueOnce(page([], false, null, true))
const reply = await sessionGet({ sessionId: s.sessionId, limit: 5, before: 'not-in-this-file' })
expect(reply).toStrictEqual({ ...about(s, MTIME), events: [], hasMore: false, oldestCursor: null, staleCursor: true })
expect(messagesToEvents).not.toHaveBeenCalled()
})
it('Codex: its own pager and replay, which finds sub-agents under the home the session runs in', async () => {
const file = transcript(['x1', 'x2'])
const s = session('codex', { transcriptPath: file, codexHome: '/homes/codex-work' })
const { sessionGet, pages } = setup(s)
pages.codex.mockResolvedValueOnce(page(['x1', 'x2'], false, 'codex:0'))
expect(await sessionGet({ sessionId: s.sessionId, limit: 5 })).toStrictEqual({ ...about(s, MTIME), events: replayed('codex', ['x1', 'x2']), hasMore: false, oldestCursor: 'codex:0' })
expect(pages.codex).toHaveBeenCalledWith(file, { limit: 5, before: undefined })
expect(codexSubagentResolverFor).toHaveBeenCalledWith('/homes/codex-work')
expect(codexMessagesToEvents).toHaveBeenCalledWith(['x1', 'x2'], fake.resolver)
expect(pages.claude).not.toHaveBeenCalled()
})
it('a transcript that is gone is stamped now', async () => {
vi.spyOn(Date, 'now').mockReturnValue(NOW)
const s = session('claude', { transcriptPath: join(dir, 'gone.jsonl') })
const { sessionGet } = setup(s)
expect(await sessionGet({ sessionId: s.sessionId, limit: 5 })).toStrictEqual({ ...about(s, NOW), events: replayed('claude', []), hasMore: false, oldestCursor: null })
})
})
describe('sub-agent totals, joined from their own transcripts', () => {
// What an async sub-agent wrote: three tool calls over a minute, 22 tokens.
const subagent = [
JSON.stringify({ type: 'user', timestamp: '2026-10-04T10:00:00.000Z', message: { role: 'user', content: 'go' } }),
JSON.stringify({ type: 'assistant', timestamp: '2026-10-04T10:00:05.000Z', message: { content: [{ type: 'tool_use', id: 'a' }, { type: 'tool_use', id: 'b' }], usage: { input_tokens: 10, output_tokens: 5 } } }),
'',
JSON.stringify({ type: 'assistant', timestamp: '2026-10-04T10:01:00.000Z', message: { content: [{ type: 'tool_use', id: 'c' }], usage: { cache_read_input_tokens: 7 } } }),
]
const end = (subagentSummary?: Record<string, unknown>) =>
({ type: 'tool_end', payload: { id: 't', tool: 'Task', output: '', isError: false, summary: '', ...(subagentSummary ? { subagent: subagentSummary } : {}) } })
const writeSubagent = (id: string, lines: string[]) => {
mkdirSync(join(dir, 'session', 'subagents'), { recursive: true })
writeFileSync(join(dir, 'session', 'subagents', `agent-${id}.jsonl`), lines.join('\r\n'))
}
it('fills in only what a launch left out, read a line at a time; a sub-agent with no transcript yet is left as it is', async () => {
writeSubagent('agent7', subagent)
// Counted already: its transcript must not be read again (this one would count one call).
writeSubagent('agent8', [subagent[1]])
const s = session('claude', { transcriptPath: transcript(['c1']) })
const { sessionGet, pages } = setup(s)
pages.claude.mockResolvedValueOnce(page(['c1'], false, null))
vi.mocked(messagesToEvents).mockReturnValueOnce([
{ type: 'text_delta', payload: { content: 'not a tool' } },
end(),
end({ agentType: 'Explore' }),
end({ agentId: 'agent7' }),
end({ agentId: 'agent7', totalDurationMs: 5, totalTokens: 9 }),
end({ agentId: 'agent8', totalToolUseCount: 4 }),
end({ agentId: 'missing' }),
] as never)
const { events } = await sessionGet({ sessionId: s.sessionId, limit: 50 }) as { events: Array<{ payload: { subagent?: unknown } }> }
expect(events.map((event) => event.payload.subagent)).toEqual([
undefined,
undefined,
{ agentType: 'Explore' },
{ agentId: 'agent7', totalToolUseCount: 3, totalDurationMs: 60_000, totalTokens: 22 },
{ agentId: 'agent7', totalToolUseCount: 3, totalDurationMs: 5, totalTokens: 9 },
{ agentId: 'agent8', totalToolUseCount: 4 },
{ agentId: 'missing' },
])
})
it('only Claude Code\'s reader joins them: an engine with its own replay is not joined', async () => {
writeSubagent('agent7', subagent)
const lines = ['l0', 'l1']
for (const limit of [5, undefined]) {
const s = session('pi', { transcriptPath: transcript(lines) })
vi.mocked(piMessagesToEvents).mockReturnValueOnce([end({ agentId: 'agent7' })] as never)
const { events } = await setup(s).sessionGet({ sessionId: s.sessionId, limit }) as { events: Array<{ payload: { subagent?: Record<string, unknown> } }> }
expect(events[0].payload.subagent?.totalToolUseCount, `limit ${limit}`).toBeUndefined()
}
})
})
describe('the other file engines: read from the end, bounded', () => {
const lines = ['l0', 'l1', 'l2', 'l3']
it.each([
['cursor', 'cursor'], ['muse', 'muse'], ['amp', 'amp'], ['grok', 'grok'], ['agy', 'agy'], ['copilot', 'copilot'],
['pi', 'pi'], ['omp', 'omp'], ['commandcode', 'commandcode'],
])('%s: the whole transcript, through its own replay', async (engine, from) => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
const file = transcript(lines)
const s = session(engine, { transcriptPath: file })
const { sessionGet } = setup(s)
const reply = await sessionGet({ sessionId: s.sessionId })
expect(reply).toStrictEqual({ ...about(s, MTIME), events: replayed(from, lines) })
expect(Object.keys(reply)).toEqual(['id', 'title', 'events', 'timestamp', 'engine'])
expect(tailFileCapped).toHaveBeenCalledWith(file)
if (engine === 'cursor') {
expect(loadCursorReplayTaskLinks).toHaveBeenCalledWith('/cursor/config', s.sessionId, '/cursor/data')
expect(cursorMessagesToEvents).toHaveBeenCalledWith(lines, s.sessionId, ['a task link'])
}
})
it.each(['muse', 'amp', 'grok', 'agy', 'copilot'])('%s has no windower: a page is the whole transcript, and says there is no more', async (engine) => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
const s = session(engine, { transcriptPath: transcript(lines) })
const { sessionGet } = setup(s)
const reply = await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'anything' })
expect(reply).toStrictEqual({ ...about(s, MTIME), events: replayed(engine, lines), hasMore: false, oldestCursor: null })
expect(Object.keys(reply)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor'])
// Never the raw window: its cursor and Claude Code's replay would make nothing of these lines.
expect(windowRawLines).not.toHaveBeenCalled()
expect(messagesToEvents).not.toHaveBeenCalled()
})
it('amp: from amp\'s own store when the thread exports, else the local transcript, and the log says which', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const s = session('amp', { sessionId: 'T-0123456789abcdef', transcriptPath: transcript(lines) })
const { sessionGet } = setup(s)
vi.mocked(readAmpThread).mockResolvedValueOnce(['e1', 'e2'] as never).mockResolvedValueOnce(['e3'] as never)
expect((await sessionGet({ sessionId: s.sessionId })).events).toEqual(replayed('amp export', ['e1', 'e2']))
expect((await sessionGet({ sessionId: s.sessionId, limit: 5 })).events).toEqual(replayed('amp export', ['e3']))
expect(readAmpThread).toHaveBeenCalledWith('T-0123456789abcdef')
expect(log).toHaveBeenCalledWith('[history] T-0123456789 amp · 2 message(s) from amp\'s own store')
expect(log).toHaveBeenCalledWith('[history] T-0123456789 amp · 1 message(s) from amp\'s own store')
expect((await sessionGet({ sessionId: s.sessionId, limit: 5 })).events).toEqual(replayed('amp', lines))
expect(warn).toHaveBeenCalledWith('[history] T-0123456789 amp · export unavailable — falling back to the local transcript')
})
it.each([
['cursor', 'cursor', 'cursor'], ['pi', 'pi', 'pi'], ['omp', 'omp', 'omp'],
['commandcode', 'commandcode', 'commandcode'],
])('%s: the newest page, the page before it, and a cursor it cannot find, through its own window', async (engine, window, from) => {
const s = session(engine, { transcriptPath: transcript(lines) })
const { sessionGet } = setup(s)
const newest = await sessionGet({ sessionId: s.sessionId, limit: 2 })
expect(newest).toStrictEqual({ ...about(s, MTIME), events: replayed(from, ['l2', 'l3']), hasMore: true, oldestCursor: `${window}:2` })
expect(Object.keys(newest)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor'])
expect(await sessionGet({ sessionId: s.sessionId, limit: 2, before: `${window}:2` }))
.toStrictEqual({ ...about(s, MTIME), events: older(from, ['l0', 'l1']), hasMore: false, oldestCursor: `${window}:0` })
const stale = await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'stale' })
expect(stale).toStrictEqual({ ...about(s, MTIME), events: [], hasMore: false, oldestCursor: null, staleCursor: true })
expect(Object.keys(stale)).toEqual(['id', 'title', 'events', 'timestamp', 'engine', 'hasMore', 'oldestCursor', 'staleCursor'])
if (engine === 'cursor') {
// A window begins mid-conversation: its replay is told where, and which todos were open there.
expect(cursorMessagesToEvents).toHaveBeenCalledWith(['l2', 'l3'], s.sessionId, ['a task link'], 7, ['a todo carried in'])
}
})
it('cursor: a window that names no start or open todos replays as from the start', async () => {
const s = session('cursor', { transcriptPath: transcript(lines) })
const { sessionGet } = setup(s)
vi.mocked(windowCursorLines).mockReturnValueOnce({ window: ['l3'], hasMore: true, oldestCursor: 'cursor:3' } as never)
await sessionGet({ sessionId: s.sessionId, limit: 1 })
expect(cursorMessagesToEvents).toHaveBeenCalledWith(['l3'], s.sessionId, ['a task link'], 0, [])
})
it('an older page drops only an end marker', async () => {
const s = session('pi', { transcriptPath: transcript(lines) })
const { sessionGet } = setup(s)
const text = { type: 'text_delta', payload: { content: 'mid-turn' } }
vi.mocked(piMessagesToEvents).mockReturnValueOnce([text] as never).mockReturnValueOnce([])
expect((await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'pi:2' })).events).toEqual([text])
expect((await sessionGet({ sessionId: s.sessionId, limit: 2, before: 'pi:2' })).events).toEqual([])
})
it('past the cap: the newest history, and every reply says so, as does the log', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
vi.mocked(tailFileCapped).mockResolvedValue({ lines: ['l3'], truncated: true })
const ask = async (engine: string, payload: Record<string, unknown>) => {
const s = session(engine, { transcriptPath: transcript(lines) })
return { s, reply: await setup(s).sessionGet({ sessionId: s.sessionId, ...payload }) }
}
const whole = await ask('muse', {})
expect(whole.reply).toStrictEqual({ ...about(whole.s, MTIME), events: replayed('muse', ['l3']), truncated: true })
const wholePage = await ask('grok', { limit: 5 })
expect(wholePage.reply).toStrictEqual({ ...about(wholePage.s, MTIME), events: replayed('grok', ['l3']), hasMore: false, oldestCursor: null, truncated: true })
const windowed = await ask('pi', { limit: 5 })
expect(windowed.reply).toStrictEqual({ ...about(windowed.s, MTIME), events: replayed('pi', ['l3']), hasMore: false, oldestCursor: 'pi:0', truncated: true })
const stale = await ask('commandcode', { limit: 5, before: 'stale' })
expect(stale.reply).toStrictEqual({ ...about(stale.s, MTIME), events: [], hasMore: false, oldestCursor: null, staleCursor: true, truncated: true })
expect(warn).toHaveBeenCalledTimes(4)
expect(warn).toHaveBeenCalledWith(`[backend] session_get ${sid('muse-session')}: the transcript is over 64 MB · its oldest history is not shown`)
})
it('a transcript that is gone reads as an empty one, stamped now', async () => {
vi.spyOn(Date, 'now').mockReturnValue(NOW)
const s = session('muse', { transcriptPath: join(dir, 'gone.jsonl') })
const { sessionGet } = setup(s)
expect(await sessionGet({ sessionId: s.sessionId })).toStrictEqual({ ...about(s, NOW), events: replayed('muse', []) })
})
})
describe('the replays with no windower answer both shapes', () => {
it('a whole page for a legacy request, and one that says it is the last for a paginated one', () => {
const events = replayed('grok', ['l0']) as Parameters<typeof wholeHistoryPage>[0]
expect(wholeHistoryPage(events, false)).toStrictEqual({ events })
expect(wholeHistoryPage(events, true)).toStrictEqual({ events, hasMore: false, oldestCursor: null })
})
})
describe('the conversation an agent holds (sessions_list)', () => {
it('asks for an agent, and lists nothing for one it does not know or one whose engine has not bound a conversation', async () => {
const pending = session('claude', { sessionId: '' })
const { sessionsList, pages } = setup(pending)
expect(await sessionsList({})).toStrictEqual({ error: 'MISSING_AGENT_ID' })
expect(await sessionsList({ agentId: 'nobody' })).toStrictEqual({ sessions: [] })
expect(await sessionsList({ agentId: pending.agentId })).toStrictEqual({ sessions: [] })
expect(pages.lineCount).not.toHaveBeenCalled()
})
it('the one conversation, its lines counted by the pager rather than read whole, in the fields it always had', async () => {
const file = transcript(['c1', 'c2'])
const s = session('codex', { transcriptPath: file, registeredAt: Date.parse('2026-10-05T07:00:00.000Z') })
const { sessionsList, pages } = setup(s)
pages.lineCount.mockResolvedValueOnce(42)
const reply = await sessionsList({ agentId: s.agentId }) as { sessions: Array<Record<string, unknown>> }
expect(reply).toStrictEqual({ sessions: [{
id: s.sessionId, title: 'Release notes', timestamp: '2026-10-05T07:00:00.000Z', messageCount: 42,
lastActivity: '2026-10-05T08:45:00.000Z', participants: [],
}] })
expect(Object.keys(reply)).toEqual(['sessions'])
expect(Object.keys(reply.sessions[0])).toEqual(['id', 'title', 'timestamp', 'messageCount', 'lastActivity', 'participants'])
expect(pages.lineCount).toHaveBeenCalledWith(file)
expect(lastActivityAt).toHaveBeenCalledWith(s)
})
it('a conversation kept in a database has no file to count', async () => {
const s = session('opencode', { registeredAt: Date.parse('2026-10-05T07:00:00.000Z') })
const { sessionsList, pages } = setup(s)
expect(await sessionsList({ agentId: s.agentId })).toMatchObject({ sessions: [{ id: s.sessionId, messageCount: 0 }] })
expect(pages.lineCount).not.toHaveBeenCalled()
})
})
describe('asked by agent id', () => {
// The registry finds an agent by its agent id as well as by its session id, and the reply still names
// the id it was asked for. What is read must be the conversation's own, though: an engine's store, its
// export and its task links know the session id alone, and with the agent id read nothing at all.
it('reads a database engine\'s store under the session id', async () => {
const s = session('opencode')
const { sessionGet } = setup(s)
expect(await sessionGet({ sessionId: s.agentId, limit: 2 })).toMatchObject({ id: s.agentId, events: replayed('opencode', ['o2', 'o3']) })
expect(readOpencodeMessages).toHaveBeenCalledWith('/stores/opencode.db', s.sessionId)
})
it('reads Cursor\'s task links, and replays its tasks, under the session id', async () => {
const s = session('cursor', { transcriptPath: transcript(['l0', 'l1']) })
const { sessionGet } = setup(s)
await sessionGet({ sessionId: s.agentId })
await sessionGet({ sessionId: s.agentId, limit: 1 })
expect(loadCursorReplayTaskLinks).toHaveBeenNthCalledWith(1, '/cursor/config', s.sessionId, '/cursor/data')
expect(loadCursorReplayTaskLinks).toHaveBeenNthCalledWith(2, '/cursor/config', s.sessionId, '/cursor/data')
expect(cursorMessagesToEvents).toHaveBeenNthCalledWith(1, ['l0', 'l1'], s.sessionId, ['a task link'])
expect(cursorMessagesToEvents).toHaveBeenNthCalledWith(2, ['l1'], s.sessionId, ['a task link'], 7, ['a todo carried in'])
})
it('exports an Amp thread under the session id', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
const s = session('amp', { sessionId: 'T-0123456789abcdef', transcriptPath: transcript(['l0']) })
const { sessionGet } = setup(s)
await sessionGet({ sessionId: s.agentId })
await sessionGet({ sessionId: s.agentId, limit: 5 })
expect(readAmpThread).toHaveBeenNthCalledWith(1, 'T-0123456789abcdef')
expect(readAmpThread).toHaveBeenNthCalledWith(2, 'T-0123456789abcdef')
})
})
describe('history crossing a reader boundary', () => {
it('rejects results for a changed or removed binding, including an in-place mutation', async () => {
for (const change of ['mutate', 'remove']) {
const s = session('claude', { transcriptPath: '/read.jsonl' })
let finish!: () => void
const waiting = new Promise<void>((r) => { finish = r })
const adapter = { historyPage: async () => { await waiting; return { events: [], timestamp: MTIME.toISOString() } }, lastTurnText: async () => null }
const h = setup(s, [], () => adapter)
const result = h.sessionGet({ sessionId: s.sessionId })
if (change === 'mutate') s.transcriptPath = '/replacement.jsonl'
else h.deps.resolve.mockReturnValue(undefined)
finish()
expect(await result).toEqual({ error: 'ENGINE_STALE_REPLY', retryable: true })
}
})
it('returns explicit retry guidance and never invokes the inline pager on a failed worker read', async () => {
for (const error of [new EngineReadError('ENGINE_REPLY_TOO_LARGE'), new Error('socket failed')]) {
const h = setup(session('codex', { transcriptPath: '/read.jsonl' }), [], () => ({
historyPage: async () => { throw error }, lastTurnText: async () => null,
}))
expect(await h.sessionGet({ sessionId: 'codex-session' })).toEqual(error instanceof EngineReadError
? { error: 'ENGINE_REPLY_TOO_LARGE', retryable: false } : { error: 'ENGINE_UNAVAILABLE', retryable: true })
expect(h.pages.codex).not.toHaveBeenCalled()
}
})
})