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.

9.9 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { BackendSocket } from './backendSocket.js'
import { dispatchDown, relaySocket } from './testing/relaySocket.js'
import { codexMessagesToEvents, windowCodexLines } from './engines/codex/normalizer.js'
import { messagesToEvents, subagentStatsFromRawLines, windowRawLines } from './lib/normalize.js'
import { withoutOutputTail } from './lib/cardUpdate.js'
import { registry } from './lib/registry.js'
import { stoppedAgents } from './lib/stoppedAgents.js'
import { tailFile } from './lib/transcriptTail.js'
import { bindHistory } from './testing/socketCore.js'
import { cl, claude, claudeScenario, codexScenario } from './testing/transcriptScenarios.js'

// Transcripts are only served from the engines' own folders. Those default to this computer's real
// ~/.claude and ~/.codex, so they are pointed at throwaway ones before the config is read.
const roots = vi.hoisted(() => {
  const base = `${process.env.TMPDIR || '/tmp'}/history-roots-${process.pid}-${Date.now()}`
  process.env.CLAUDE_PROJECTS_DIR = `${base}/claude-projects`
  process.env.CODEX_HOME = `${base}/codex`
  return { base, claude: process.env.CLAUDE_PROJECTS_DIR, codex: `${process.env.CODEX_HOME}/sessions` }
})
afterAll(() => rmSync(roots.base, { recursive: true, force: true }))

/**
 * `session_get` and `sessions_list` for Claude Code and Codex, through the socket: what a client
 * scrolling a thread gets is what the whole-file read gave it, page for page (lib/transcriptPages.ts).
 */
describe.each([
  ['claude', claudeScenario, windowRawLines, (lines: string[]) => messagesToEvents(lines)],
  ['codex', codexScenario, windowCodexLines, (lines: string[]) => codexMessagesToEvents(lines)],
] as const)('%s history through the socket', (engine, scenario, window, toEvents) => {
  let dir: string
  let socket: BackendSocket
  let frames: Array<{ type: string; payload: Record<string, any> }>
  let agentId: string
  let sessionId: string
  let file: string
  let pane = 7400

  beforeEach(() => {
    const root = engine === 'claude' ? roots.claude : roots.codex
    mkdirSync(root, { recursive: true })
    dir = mkdtempSync(join(root, 'history-'))
    file = join(dir, 'transcript.jsonl')
    const paneId = `%${++pane}`
    sessionId = `${engine}-history-${pane}`
    const lines = scenario()
    if (engine === 'codex') {
      const header = JSON.parse(lines[0])
      header.payload.id = sessionId
      lines[0] = JSON.stringify(header)
    }
    writeFileSync(file, lines.join('\n') + '\n')
    socket = relaySocket('fixture')
    bindHistory(socket)
    frames = []
    socket.registerLocalClient('local:history', { sendFrame: (frame) => { frames.push(frame as never); return true }, sendBinary: () => true })
    agentId = registry.openPendingAgent({ engine, runtimes: [{ backend: 'tmux', paneId }], cwd: dir })!.agentId
    expect(registry.register({ engine, sessionId, transcriptPath: file, tmuxPane: paneId, cwd: dir })).not.toBeNull()
  })

  afterEach(async () => {
    registry.removeAgent(agentId)
    await socket.stop()
    rmSync(dir, { recursive: true, force: true })
  })

  let requests = 0
  async function ask(type: string, payload: Record<string, unknown>): Promise<Record<string, any>> {
    const requestId = `r${++requests}`
    await dispatchDown(socket, { type, payload: { requestId, ...payload } }, 'local:history', 'local')
    return frames.find((frame) => frame.type === `${type}_result` && frame.payload.requestId === requestId)!.payload
  }

  it('is bound to the transcript under test', () => {
    expect(registry.resolve(sessionId)?.transcriptPath).toBe(file)
  })

  it('is served from a conversation kept as a stopped one, once nothing live holds it', async () => {
    const whole = (await ask('session_get', { sessionId })).events
    // What a stop, or a relaunch that had to leave the conversation for a new one, keeps of it.
    stoppedAgents.save(registry.resolve(sessionId)!)
    registry.removeAgent(agentId)
    try {
      expect(registry.resolve(sessionId)).toBeUndefined()
      expect((await ask('session_get', { sessionId })).events).toEqual(whole)
    } finally {
      stoppedAgents.remove(agentId)
    }
    expect((await ask('session_get', { sessionId })).error).toBe('NOT_FOUND')
  })

  it('pages back through the thread exactly as the whole-file read did, cursor for cursor', async () => {
    const lines = await tailFile(file, Infinity)
    for (const limit of [1, 4, 500]) {
      let before: string | undefined
      for (let page = 0; page < lines.length + 1; page++) {
        const reply = await ask('session_get', { sessionId, limit, before })
        const old = window(lines, { limit, before })
        const events = toEvents(old.window)
        if (before && events[events.length - 1]?.type === 'done') events.pop()
        expect(reply.events, `limit ${limit}, page ${page}`).toEqual(JSON.parse(JSON.stringify(events.map(withoutOutputTail))))
        expect({ hasMore: reply.hasMore, oldestCursor: reply.oldestCursor }).toEqual({ hasMore: old.hasMore, oldestCursor: old.oldestCursor })
        if (!old.hasMore || !old.oldestCursor) break
        before = old.oldestCursor
      }
    }
  })

  it('answers a request with no limit with the whole thread, in the reply it always had', async () => {
    const reply = await ask('session_get', { sessionId, before: 'ignored without a limit' })
    expect(reply.events).toEqual(JSON.parse(JSON.stringify(toEvents(await tailFile(file, Infinity)).map(withoutOutputTail))))
    expect(reply).not.toHaveProperty('hasMore')
    expect(reply).not.toHaveProperty('oldestCursor')
  })

  it('says a cursor it cannot find is stale, so the client reloads', async () => {
    const reply = await ask('session_get', { sessionId, limit: 5, before: 'not-a-cursor-in-this-file' })
    expect(reply).toMatchObject({ events: [], hasMore: false, oldestCursor: null, staleCursor: true })
  })

  it('totals a sub-agent from its own transcript, read a line at a time', async () => {
    if (engine !== 'claude') return
    const launch = cl({ type: 'assistant', message: { id: 'mt', role: 'assistant', model: 'claude-opus-5-5', content: [{ type: 'tool_use', id: 'toolu_task', name: 'Task', input: { description: 'look around' } }], stop_reason: 'tool_use' } })
    const result = cl({
      type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_task', content: 'launched' }] },
      toolUseResult: { isAsync: true, status: 'async_launched', agentId: 'agent7' },
    })
    writeFileSync(file, [claude.user('send a helper'), launch, result].join('\n') + '\n')
    const sub = [
      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 } } }),
    ]
    mkdirSync(join(dir, 'transcript', 'subagents'), { recursive: true })
    writeFileSync(join(dir, 'transcript', 'subagents', 'agent-agent7.jsonl'), sub.join('\r\n'))
    const reply = await ask('session_get', { sessionId, limit: 50 })
    const end = reply.events.find((event: { type: string; payload: { subagent?: unknown } }) => event.type === 'tool_end' && event.payload.subagent)
    expect(end.payload.subagent).toMatchObject({ agentId: 'agent7', ...subagentStatsFromRawLines(sub) })
    expect(end.payload.subagent).toMatchObject({ totalToolUseCount: 3, totalDurationMs: 60_000, totalTokens: 22 })
    // Totals the launch already reported stand; only what it left out is filled in.
    const reported = cl({
      type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_task', content: 'launched' }] },
      toolUseResult: { agentId: 'agent7', totalDurationMs: 5, totalTokens: 9 },
    })
    writeFileSync(file, [claude.user('send a helper'), launch, reported].join('\n') + '\n')
    const again = await ask('session_get', { sessionId, limit: 50 })
    const kept = again.events.find((event: { type: string; payload: { subagent?: unknown } }) => event.type === 'tool_end' && event.payload.subagent)
    expect(kept.payload.subagent).toMatchObject({ agentId: 'agent7', totalToolUseCount: 3, totalDurationMs: 5, totalTokens: 9 })
  })

  it('answers for a transcript that is gone as for an empty one', async () => {
    rmSync(file)
    const reply = await ask('session_get', { sessionId, limit: 5 })
    // What the whole-file read made of the empty history it read there: no lines, then the end marker.
    expect(reply.events).toEqual(JSON.parse(JSON.stringify(toEvents([]))))
    expect(reply).toMatchObject({ hasMore: false, oldestCursor: window([], { limit: 5 }).oldestCursor })
    expect(Date.parse(reply.timestamp)).toBeGreaterThan(Date.now() - 60_000)
  })

  it('counts the thread without reading it whole', async () => {
    const reply = await ask('sessions_list', { agentId })
    expect(reply.sessions).toHaveLength(1)
    expect(reply.sessions[0]).toMatchObject({ id: sessionId, messageCount: (await tailFile(file, Infinity)).length })
  })

  it('counts nothing for an agent whose engine keeps no transcript file', async () => {
    const paneId = `%${++pane}`
    const store = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId }], cwd: dir })!.agentId
    try {
      registry.register({ engine: 'opencode', sessionId: `ses_history${pane}`, tmuxPane: paneId, cwd: dir })
      const reply = await ask('sessions_list', { agentId: store })
      expect(reply.sessions).toEqual([expect.objectContaining({ id: `ses_history${pane}`, messageCount: 0 })])
    } finally { registry.removeAgent(store) }
  })
})