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.

10.2 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'

import { afterEach, describe, expect, it } from 'vitest'

import { externalEvidence } from '../evidence.js'
import { claudeProvider, readClaudeHead } from './claude.js'
import { scanMemo } from './support.js'
import { type ProcessView, UNSETTLED } from './types.js'

const dirs: string[] = []
afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
function home(): string {
  const dir = mkdtempSync(join(tmpdir(), 'externals-claude-'))
  dirs.push(dir)
  return dir
}
function write(path: string, lines: unknown[]): string {
  mkdirSync(join(path, '..'), { recursive: true })
  writeFileSync(path, lines.map((line) => typeof line === 'string' ? line : JSON.stringify(line)).join('\n') + '\n')
  return path
}
const A = '11111111-1111-4111-8111-111111111111'
const B = '22222222-2222-4222-8222-222222222222'
const line = (sessionId: string, entrypoint: string, extra: Record<string, unknown> = {}) => ({
  type: 'user', sessionId, cwd: '/work/dial', entrypoint, timestamp: '2026-09-20T10:00:00Z',
  message: { role: 'user', content: 'fix the dial scroll' }, ...extra,
})
const view = (alive: (pid: number) => boolean): ProcessView => ({
  list: async () => [], openFiles: async () => new Map(), cwds: async () => new Map(), openFilesOf: async () => new Map(), alive,
})

describe('readClaudeHead', () => {
  it('reads a terminal or the Claude app, never a program, a sub-agent or a line it cannot trust', async () => {
    const dir = home()
    const file = (name: string, lines: unknown[]) => write(join(dir, `${name}.jsonl`), lines)
    // The first lines may carry no entrypoint: a mode, a title, a line being written.
    expect(await readClaudeHead(file('t', [{ type: 'permission-mode' }, '{"entrypoint": half', line(A, 'cli')])))
      .toEqual({ sessionId: A, cwd: '/work/dial', origin: 'terminal' })
    expect(await readClaudeHead(file('d', [line(A, 'claude-desktop')]))).toMatchObject({ origin: 'claude-app' })
    expect(await readClaudeHead(file('s', [line(A, 'sdk-cli')]))).toBeNull()
    expect(await readClaudeHead(file('x', [line(A, 'cli', { isSidechain: true })]))).toBeNull()
    expect(await readClaudeHead(file('r', [line(A, 'cli', { cwd: 'relative/path' })]))).toBeNull()
    expect(await readClaudeHead(file('i', [line('short', 'cli')]))).toBeNull()
    // No line says yet: Claude may still be writing it, so it is not judged — unless the file is too
    // long for that.
    expect(await readClaudeHead(file('n', ['["entrypoint"]']))).toBe(UNSETTLED)
    expect(await readClaudeHead(file('e', [{ type: 'summary', summary: 'nothing else' }]))).toBe(UNSETTLED)
    // Past every window without one: not a conversation, for good.
    expect(await readClaudeHead(file('big', [{ type: 'summary', summary: 'x'.repeat(3000) }]), [1024, 2048])).toBeNull()
    // A first prompt with a pasted image runs past the first window: the next, wider one reads it.
    const pasted = line(A, 'cli', { message: { role: 'user', content: [{ type: 'image', source: { data: 'i'.repeat(300 * 1024) } }] } })
    expect(await readClaudeHead(file('pasted', [{ type: 'permission-mode' }, pasted]))).toEqual({ sessionId: A, cwd: '/work/dial', origin: 'terminal' })
  })
})

describe('claudeProvider', () => {
  it("finds a project's own conversations, not a sub-agent's, and not Harness's own byproducts", async () => {
    const root = home()
    const projects = join(root, 'projects')
    write(join(projects, '-work-dial', `${A}.jsonl`), [line(A, 'cli')])
    write(join(projects, '-work-dial', `${B}.jsonl`), [line(B, 'cli', { cwd: '/data/harness/summary-scratch' })])
    write(join(projects, '-work-dial', 'notes.txt'), ['not a transcript'])
    write(join(projects, '-work-dial', A, 'subagents', 'agent-1.jsonl'), [line(A, 'cli')])
    writeFileSync(join(projects, 'stray-file'), '')
    mkdirSync(join(projects, '-work-dial', 'odd.jsonl'))
    symlinkSync(join(root, 'nowhere.jsonl'), join(projects, '-work-dial', 'broken.jsonl'))
    const provider = claudeProvider({ projectsDir: projects, home: root })
    const memo = scanMemo({ excluded: ['/data/harness'] })
    const found = await provider.scan(memo.context())
    expect(found).toEqual([expect.objectContaining({
      sessionId: A, engine: 'claude', cwd: '/work/dial', origin: 'terminal', title: '',
      transcriptPath: join(projects, '-work-dial', `${A}.jsonl`),
    })])
    expect(found[0].mtime).toBeGreaterThan(0)
    // Nothing where nothing is.
    expect(await claudeProvider({ projectsDir: join(root, 'none'), home: root }).scan(memo.context())).toEqual([])
  })

  it('finds a conversation it first saw half-written once Claude has written its first lines', async () => {
    const root = home()
    const projects = join(root, 'projects')
    const path = write(join(projects, '-work-dial', `${B}.jsonl`), [{ type: 'permission-mode' }])
    const provider = claudeProvider({ projectsDir: projects, home: root })
    const memo = scanMemo()
    expect(await provider.scan(memo.context())).toEqual([])
    write(path, [{ type: 'permission-mode' }, line(B, 'cli')])
    expect((await provider.scan(memo.context())).map((s) => s.sessionId)).toEqual([B])
  })

  it('knows its owners from their live process records, and whether they are between turns', async () => {
    const root = home()
    const started = Date.parse('2026-09-27T10:00:00Z')
    write(join(root, 'sessions', '101.json'), [{ pid: 101, sessionId: A, status: 'busy', startedAt: started + 400 }])
    write(join(root, 'sessions', '102.json'), [{ pid: 102, sessionId: B, status: 'idle' }])
    // A crashed Claude's record, its pid now a shell's, and one now a later Claude's.
    write(join(root, 'sessions', '107.json'), [{ pid: 107, sessionId: 'reused-by-a-shell', startedAt: started }])
    write(join(root, 'sessions', '108.json'), [{ pid: 108, sessionId: 'reused-by-claude', startedAt: started }])
    // Alive, but gone from the process list by the time it was read.
    write(join(root, 'sessions', '109.json'), [{ pid: 109, sessionId: 'unlisted' }])
    write(join(root, 'sessions', '103.json'), [{ pid: 103, sessionId: B }])
    write(join(root, 'sessions', '104.json'), ['{ being written'])
    write(join(root, 'sessions', '105.json'), [{ pid: '105', sessionId: B }])
    write(join(root, 'sessions', '106.json'), [{ pid: 106 }])
    write(join(root, 'sessions', 'notes.txt'), ['x'])
    mkdirSync(join(root, 'sessions', 'dir.json'))
    const provider = claudeProvider({ projectsDir: join(root, 'projects'), home: root })
    const running = [
      { pid: 101, ppid: 1, executable: 'claude', args: 'claude --resume x', started },
      { pid: 102, ppid: 1, executable: 'claude', args: 'claude' },
      { pid: 106, ppid: 1, executable: 'claude', args: 'claude', started },
      { pid: 107, ppid: 1, executable: '-zsh', args: '-zsh', started: started + 60_000 },
      { pid: 108, ppid: 1, executable: 'claude', args: 'claude', started: started + 60_000 },
    ]
    const claims = await provider.owners!({ ...view((pid) => [101, 102, 106, 107, 108, 109].includes(pid)), list: async () => running })
    expect(claims.sort((a, b) => a.pid - b.pid)).toEqual([
      { sessionId: A, pid: 101, record: join(root, 'sessions', '101.json') },
      { sessionId: B, pid: 102, record: join(root, 'sessions', '102.json') },
    ])
    expect(await provider.busy!({ pid: 101, record: join(root, 'sessions', '101.json') })).toBe(true)
    expect(await provider.busy!({ pid: 102, record: join(root, 'sessions', '102.json') })).toBe(false)
    // No records at all: nothing is open, and no process is looked at.
    let looked = false
    expect(await claudeProvider({ projectsDir: join(root, 'projects'), home: join(root, 'none') })
      .owners!({ ...view(() => true), list: async () => { looked = true; return [] } })).toEqual([])
    expect(looked).toBe(false)
    // The record gone is the process gone: not mid-turn.
    expect(await provider.busy!({ pid: 9, record: join(root, 'sessions', 'gone.json') })).toBe(false)
  })

  it('places a live Claude with no record by its arguments, or leaves it unplaced with its folder, for admission only', async () => {
    const root = home()
    const started = Date.parse('2026-09-27T10:00:00Z')
    write(join(root, 'sessions', '101.json'), [{ pid: 101, sessionId: A, status: 'idle', startedAt: started + 400 }])
    const provider = claudeProvider({ projectsDir: join(root, 'projects'), home: root })
    const running = [
      { pid: 101, ppid: 1, executable: 'claude', args: 'claude', started },
      { pid: 201, ppid: 1, executable: 'claude', args: `claude --resume ${B}`, started },
      { pid: 202, ppid: 1, executable: 'claude', args: 'claude --append-system-prompt "be brief"', started },
      { pid: 203, ppid: 1, executable: 'claude', args: 'claude --session-id not!an!id', started },
      { pid: 204, ppid: 1, executable: '-zsh', args: `-zsh --resume ${B}`, started },
    ]
    const asked: number[][] = []
    const machine: ProcessView = { ...view(() => true), list: async () => running,
      cwds: async (pids) => { asked.push([...pids]); return new Map([[202, '/work/other']]) } }
    expect(await externalEvidence(() => provider.ownership!(machine))).toEqual({ ok: true, value: {
      claims: [
        { sessionId: A, pid: 101, record: join(root, 'sessions', '101.json') },
        { sessionId: B, pid: 201, record: '', fromArgs: true },
      ],
      // Named or not, a record-less process may have moved on: it stays unplaced beside its claim.
      unresolved: [{ pid: 201, cwd: null, named: B }, { pid: 202, cwd: '/work/other' }, { pid: 203, cwd: null }],
    } })
    expect(asked).toEqual([[201, 202, 203]])
    // The display reader is as it was: exact records only, and no folder is read.
    expect(await provider.ownership!(machine)).toEqual({ claims: [{ sessionId: A, pid: 101, record: join(root, 'sessions', '101.json') }], unresolved: [] })
    expect(asked).toHaveLength(1)
    // Placed by its arguments alone: no record says whether it is mid-turn, so nobody can say.
    expect(await provider.busy!({ pid: 201, record: '' })).toBeNull()
    expect(await provider.confirmOwner!({ sessionId: B, pid: 201, record: '', fromArgs: true }, running[1])).toBeNull()
  })
})