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 { execFileSync } from 'node:child_process'
import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { env } from '../config/env.js'
import { HANDOFF_REQUESTS, type CoreApi } from '../core/api.js'
import { databaseHistory } from '../lib/databaseHistory.js'
import { createHandoffPublisher } from '../core/handoffPublication.js'
import type { PreparedHandoff } from '../lib/handoffAuthority.js'
import { startHandoff } from './handoff.js'
import { handoffCoreApi, runHandoffService } from './handoffProcess.js'
import { runServiceProcess, type ServiceProcessOptions } from './process.js'
vi.mock('./process.js', () => ({ runServiceProcess: vi.fn(() => ({ stop: vi.fn() })) }))
// The SQLite binding, faked: an OpenCode store with one turn in it, and a count of the times it was loaded.
// `ses_handoff1` is an OpenCode 1 conversation (message and part rows, nothing in session_message) and
// `ses_handoff2` an OpenCode 2 one (session_message rows only).
const binding = vi.hoisted(() => ({ loads: 0, reads: [] as Array<{ path: string; sql: string; params: unknown[] }> }))
vi.mock('../lib/sqliteBuiltin.js', () => {
binding.loads++
const part = (type: string, text: string) => JSON.stringify({ type, text })
return {
builtinSqlite: () => class {},
readBuiltin: (_database: unknown, path: string, sql: string, params: unknown[]) => {
binding.reads.push({ path, sql, params })
if (sql.includes('FROM session_message')) {
const v2 = (id: string, type: string, seq: number, data: Record<string, unknown>) => ({ mid: id, mtype: type, mseq: seq, mtc: seq, mdata: JSON.stringify(data) })
return { ok: true, via: 'builtin', rows: params[0] === 'ses_handoff2' ? [
v2('msg_1', 'user', 0, { text: 'add a search box' }),
v2('msg_2', 'assistant', 1, { content: [{ type: 'text', text: 'Added the search box.' }], finish: 'stop' }),
v2('msg_3', 'idle', 2, { outcome: 'succeeded' }),
] : [] }
}
return { ok: true, via: 'builtin', rows: [
{ mid: 'msg_1', mtc: 1, mdata: JSON.stringify({ role: 'user' }), pid: 'prt_1', pdata: part('text', 'add a login page') },
{ mid: 'msg_2', mtc: 2, mdata: JSON.stringify({ role: 'assistant' }), pid: 'prt_2', pdata: part('text', 'Added the login page.') },
] }
},
}
})
afterEach(() => vi.clearAllMocks())
describe('the handoff in the edge host', () => {
it.each(['UNKNOWN_AGENT', 'NO_PROJECT', 'BAD_CHANGE_ID', 'BUSY', 'TIMEOUT',
'IDENTITY_UNAVAILABLE', 'HANDOFF_UNAVAILABLE', 'CHANGE_CONFLICT'])('preserves a typed %s reply across the service boundary', async error => {
const core = handoffCoreApi('/data', async () => ({ error }))
await expect(core.conversations.resolve('selected')).rejects.toMatchObject({ code: error })
})
it('queries current retained records, recaps, and verified paths with their exact arguments', async () => {
let value: unknown = { agentId: 'stopped', engine: 'claude' }
const ask = vi.fn(async () => ({ value }))
const core = handoffCoreApi('/data', ask)
expect(core.dataDir).toBe('/data')
expect(core.transcripts.databaseHistory).toBe(databaseHistory)
expect(core.transcripts.databaseHistory({ engine: 'claude' } as never)).toBeUndefined()
expect(await core.conversations.resolve('stopped')).toBe(value)
expect(ask).toHaveBeenLastCalledWith('resolve', { id: 'stopped' })
value = { agentId: 'new' }
expect(await core.conversations.resolve('stopped')).toBe(value)
value = ['ask']
expect(await core.conversations.recentAsks('s', 20)).toEqual(['ask'])
expect(ask).toHaveBeenLastCalledWith('recentAsks', { id: 's', n: 20 })
value = ['recap']
expect(await core.conversations.recaps('s', 5)).toEqual(['recap'])
expect(ask).toHaveBeenLastCalledWith('recaps', { id: 's', n: 5 })
value = 'whole answer'
expect(await core.conversations.lastFullText('s')).toBe(value)
expect(ask).toHaveBeenLastCalledWith('lastFullText', { id: 's' })
value = { engine: 'claude', sessionId: 's', transcriptPath: '/s.jsonl', ignored: true }
expect(await core.conversations.discover('a')).toEqual({ engine: 'claude', sessionId: 's', transcriptPath: '/s.jsonl' })
expect(ask).toHaveBeenLastCalledWith('discover', { id: 'a' })
value = '/codex/s.jsonl'
expect(await core.conversations.findTranscript('codex', 's', { codexHome: '/home' })).toBe(value)
expect(ask).toHaveBeenLastCalledWith('findTranscript', { engine: 'codex', id: 's', codexHome: '/home' })
value = true
expect(await core.conversations.transcriptOk('codex', '/path', null)).toBe(true)
expect(ask).toHaveBeenLastCalledWith('transcriptOk', { engine: 'codex', path: '/path', codexHome: null })
})
it('holds malformed or unavailable query replies, while preserving explicit absence', async () => {
for (const answer of [{}, { error: 'QUERY_FAILED' }]) {
const core = handoffCoreApi('/data', async () => answer)
for (const work of [
() => core.conversations.resolve('gone'), () => core.conversations.recentAsks('s', 20),
() => core.conversations.recaps('s', 5), () => core.conversations.lastFullText('s'),
() => core.conversations.discover('a'), () => core.conversations.findTranscript('codex', 's', {}),
() => core.conversations.transcriptOk('codex', '/path', null),
]) await expect(work()).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
}
const empty = handoffCoreApi('/data', async () => ({ value: null }))
expect(await empty.conversations.resolve('gone')).toBeNull()
expect(await empty.conversations.lastFullText('s')).toBeNull()
expect(await empty.conversations.discover('a')).toBeNull()
expect(await empty.conversations.findTranscript('codex', 's', {})).toBeNull()
for (const value of [{}, { engine: 7 }, { engine: 'unknown' }, { engine: 'claude' }, { engine: 'claude', sessionId: 's' }]) {
await expect(handoffCoreApi('/data', async () => ({ value })).conversations.discover('a')).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
}
await expect(handoffCoreApi('/data', async () => ({ value: ['ask', 7] })).conversations.recentAsks('s', 20)).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
await expect(handoffCoreApi('/data', async () => { throw new Error('disconnected') }).conversations.resolve('a')).rejects.toThrow('disconnected')
})
it('uses each current connection and the normal service runner, without a real socket in tests', async () => {
let options!: ServiceProcessOptions, api!: CoreApi
const stop = vi.fn()
const running = runHandoffService({
dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't',
run: given => { options = given; return { stop } },
start: core => { api = core; return { agent_handoff_prepare: async () => ({ value: await core.conversations.resolve('a') }) } },
})
expect(options).toMatchObject({ name: 'handoff', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
expect(api.daemon.machineId()).toBe('m')
await expect(api.conversations.resolve('a')).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
const query = vi.fn(async () => ({ value: { agentId: 'a' } }))
options.onConnected!({ query })
expect(await options.requests.agent_handoff_prepare!({}, { local: true, owner: true })).toEqual({ value: { agentId: 'a' } })
expect(query).toHaveBeenLastCalledWith('resolve', { id: 'a' })
options.onConnected!({ query: async () => ({ value: null }) })
expect(await api.conversations.resolve('a')).toBeNull()
running.stop()
expect(stop).toHaveBeenCalledOnce()
runHandoffService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
expect(Object.keys(vi.mocked(runServiceProcess).mock.calls.at(-1)![0].requests)).toEqual([...HANDOFF_REQUESTS])
})
// HARNESS_SWARM: a member's replacement is recorded by the Swarm's side, which its process loads only while it is on.
it('hands the change-agent handoff the Swarm\'s record while it is on, and none without it', () => {
const start = vi.fn((..._args: Parameters<typeof startHandoff>) => ({}))
const recordReplacement = vi.fn()
const base = { dataDir: '/data', socketPath: '/s', machineId: 'm', token: 't', run: () => ({ stop: vi.fn() }), start }
runHandoffService({ ...base, swarm: { recordReplacement } })
runHandoffService(base)
expect(start.mock.calls.map(call => call[3])).toEqual([recordReplacement, undefined])
})
it('reads SQLite only for a store-backed conversation and hands that one over', async () => {
const ws = mkdtempSync(join(tmpdir(), 'handoff-store-'))
try {
execFileSync('git', ['init', '-q'], { cwd: ws })
const agents: Record<string, Record<string, unknown>> = {
claude: { agentId: 'claude-1', sessionId: 's1', engine: 'claude', cwd: ws, transcriptPath: null, registeredAt: Date.now() - 60_000 },
opencode: { agentId: 'opencode-1', sessionId: 'ses_handoff1', engine: 'opencode', cwd: ws, transcriptPath: null, registeredAt: Date.now() - 60_000 },
opencode2: { agentId: 'opencode-2', sessionId: 'ses_handoff2', engine: 'opencode', cwd: ws, transcriptPath: null, registeredAt: Date.now() - 60_000 },
}
const publicationErrors: unknown[] = []
const commit = createHandoffPublisher({ directory: join(ws, 'daemon-data'),
resolve: id => Object.values(agents).find(agent => agent.agentId === id) as never,
ownedByOther: () => false, isRecentlyDeleted: () => false })
const publish = async (prepared: PreparedHandoff) => {
try { return await commit(prepared, { current: () => true }) } catch (error) { publicationErrors.push(error); throw error }
}
const core = handoffCoreApi(join(ws, 'daemon-data'), async (query, payload) => ({
value: query === 'publish' ? await publish(payload.prepared as PreparedHandoff) : query === 'resolve' ? Object.values(agents).find((agent) => agent.agentId === payload.id) ?? null
: query === 'recentAsks' || query === 'recaps' ? [] : null,
}))
// The eager SQLite module does not open a database for a file-backed conversation.
expect(core.transcripts.databaseHistory(agents.claude as never)).toBeUndefined()
expect(core.transcripts.databaseHistory({ ...agents.claude, engine: 'codex' } as never)).toBeUndefined()
const prepare = startHandoff(core).agent_handoff_prepare!
const asker = { local: true, owner: true }
await prepare({ agentId: 'claude-1', changeId: 'c'.repeat(32), targetEngine: 'codex' }, asker)
expect(binding.loads).toBe(1)
expect(binding.reads).toEqual([])
// OpenCode reads through the same binding and hands over the turn the store holds: OpenCode 2's
// session_message first, and for an OpenCode 1 conversation, which has no rows there, its message rows.
const database = join(env.OPENCODE_DATA_DIR, 'opencode.db')
const handed = await prepare({ agentId: 'opencode-1', changeId: 'a'.repeat(32), targetEngine: 'claude' }, asker) as { file: string | null }
expect(binding.loads).toBe(1)
expect(binding.reads).toEqual([
{ path: database, sql: expect.stringContaining('FROM session_message m'), params: ['ses_handoff1'] },
{ path: database, sql: expect.stringContaining('FROM message m'), params: ['ses_handoff1'] },
])
expect(publicationErrors).toEqual([])
expect(handed).toMatchObject({ file: expect.any(String) })
expect(readFileSync(join(ws, handed.file!), 'utf8')).toContain('add a login page')
// An OpenCode 2 conversation is handed over from session_message alone.
binding.reads.length = 0
const handed2 = await prepare({ agentId: 'opencode-2', changeId: 'b'.repeat(32), targetEngine: 'claude' }, asker) as { file: string | null }
expect(binding.reads).toEqual([{ path: database, sql: expect.stringContaining('FROM session_message m'), params: ['ses_handoff2'] }])
expect(publicationErrors).toEqual([])
expect(readFileSync(join(ws, handed2.file!), 'utf8')).toContain('add a search box')
} finally { rmSync(ws, { recursive: true, force: true }) }
// A real git repository and SQLite store: 1.6 s alone, 5.5 s in a full test:core run on a busy Mac (2026-11-07, #4252),
// past vitest's 5 s default.
}, 20_000)
})
it('refuses malformed read/publication replies and never sends a revoked publication', async () => {
const request = { agentId: 'a', changeId: '1'.repeat(32), targetEngine: 'claude' }
const result = { cwd: '/work', file: null, gitRepo: false, degraded: [] }
const prepared = { request, result } as never
const ask = vi.fn(async () => ({ value: result as unknown })), core = handoffCoreApi('/private-fixture', ask)
await expect(core.conversations.publish(prepared, { current: () => false })).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
expect(ask).not.toHaveBeenCalled()
expect(await core.conversations.publish(prepared, { requestId: 'routed', current: () => true })).toEqual(result)
expect(ask).toHaveBeenLastCalledWith('publish', { prepared, originRequestId: 'routed' })
// A compaction summary the record could not include is reported, not refused (lib/compactSummary.ts).
const unsummarized = { ...result, degraded: ['summary'] }
ask.mockResolvedValueOnce({ value: unsummarized })
expect(await core.conversations.publish(prepared, { requestId: 'routed', current: () => true })).toEqual(unsummarized)
for (const value of [null, {}, { ...result, cwd: '/other' }, { ...result, file: 'other' }, { ...result, gitRepo: null }, { ...result, degraded: null }, { ...result, degraded: ['unknown'] }]) {
ask.mockResolvedValueOnce({ value })
await expect(core.conversations.publish(prepared, { current: () => true })).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
}
for (const [method, args, value, code] of [
['resolve', ['a'], {}, 'IDENTITY_UNAVAILABLE'],
['lastFullText', ['s'], 3, 'HANDOFF_UNAVAILABLE'],
['findTranscript', ['codex', 's', {}], 3, 'HANDOFF_UNAVAILABLE'],
['transcriptOk', ['codex', '/file', null], null, 'IDENTITY_UNAVAILABLE'],
['recaps', ['s', 5], {}, 'HANDOFF_UNAVAILABLE'],
] as const) {
ask.mockResolvedValueOnce({ value })
await expect((core.conversations[method] as (...args: any[]) => Promise<unknown>)(...args)).rejects.toMatchObject({ code })
}
ask.mockResolvedValueOnce({ error: 'IDENTITY_UNAVAILABLE' } as never)
await expect(core.conversations.resolve('a')).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
})