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 { describe, expect, it, vi } from 'vitest'
import { emptyPorts } from '../core/api.js'
import type { HandoffDeps } from '../lib/agentHandoff.js'
import type { RegisteredSession } from '../lib/registry.js'
import { fakeCore } from '../testing/fakeCore.js'
import { HANDOFF_REQUESTS, startHandoff } from './handoff.js'
import { recordReplacement } from '../superTabs/replacements.js'
import { existsSync, mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
const request = { agentId: 'agent', changeId: '0123456789abcdef0123456789abcdef', targetEngine: 'codex' }
const owner = { owner: true, local: true }
describe('the change-agent handoff service', () => {
it('records a completed switch only for the owner with current native facts', async () => {
const dataDir = mkdtempSync(join(tmpdir(), 'handoff-complete-'))
try {
const old = { agentId: 'old', cwd: '/repo', resumeOnly: true }, target = { agentId: 'new', cwd: '/repo', engine: 'claude' }
const core = fakeCore({ dataDir, conversations: { resolve: vi.fn(async id => (id === 'old' ? old : target) as never) } })
const handler = startHandoff(core, undefined, undefined, recordReplacement).agent_handoff_complete!
const payload = { agentId: 'old', replacementId: 'new', changeId: '0123456789abcdef', targetEngine: 'claude' }
expect(await handler(payload, { local: false, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
expect(existsSync(join(dataDir, 'super-tabs'))).toBe(false)
expect(await handler(payload, owner)).toEqual({ ok: true })
expect(existsSync(join(dataDir, 'super-tabs'))).toBe(true)
expect(await handler(payload, owner)).toEqual({ ok: true })
expect(await handler({ ...payload, replacementId: 'old' }, owner)).toMatchObject({ error: 'HANDOFF_UNAVAILABLE' })
const closed = new AbortController(); closed.abort()
expect(await handler(payload, owner, closed.signal)).toMatchObject({ error: 'HANDOFF_UNAVAILABLE' })
} finally { rmSync(dataDir, { recursive: true, force: true }) }
})
// HARNESS_SWARM=off: the edge host hands in no Swarm, and a completed change is the person's alone: nothing is recorded
// for a Super Tab's host, and none of its saved state is written.
it('records nothing for the Swarm while it is off, and still asks the owner', async () => {
const dataDir = mkdtempSync(join(tmpdir(), 'handoff-off-'))
try {
const resolve = vi.fn(async () => null)
const handler = startHandoff(fakeCore({ dataDir, conversations: { resolve } })).agent_handoff_complete!
const payload = { agentId: 'old', replacementId: 'new', changeId: '0123456789abcdef', targetEngine: 'claude' }
expect(await handler(payload, { local: false, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
expect(await handler(payload, owner)).toEqual({ ok: true })
expect(resolve).not.toHaveBeenCalled()
expect(existsSync(join(dataDir, 'super-tabs'))).toBe(false)
} finally { rmSync(dataDir, { recursive: true, force: true }) }
})
it('uses the real provider by default and preserves its unknown-agent answer', async () => {
const handlers = startHandoff(fakeCore())
expect(Object.keys(handlers)).toEqual([...HANDOFF_REQUESTS])
expect(await handlers.agent_handoff_prepare!(request, owner)).toEqual({ error: 'UNKNOWN_AGENT' })
expect(await handlers.agent_handoff_prepare!(request, { owner: false, local: false })).toEqual({ error: 'OWNER_REQUIRED' })
})
it('gives the provider every fact through CoreApi, including database history and stopped ancestors', async () => {
const session = { agentId: 'agent', sessionId: 's', engine: 'claude' } as RegisteredSession
const reader = async () => []
const core = fakeCore({
conversations: {
resolve: vi.fn(async () => session), recentAsks: vi.fn(async () => ['ask']), lastFullText: vi.fn(async () => 'answer'),
recaps: vi.fn(async () => ['recap']), discover: vi.fn(async () => ({ engine: 'claude' as const, sessionId: 's', transcriptPath: '/s.jsonl' })),
findTranscript: vi.fn(async () => '/s.jsonl'), transcriptOk: vi.fn(async () => true),
},
transcripts: { databaseHistory: vi.fn(() => reader) },
})
let deps!: HandoffDeps
const prepare = vi.fn(async (given: HandoffDeps) => { deps = given; return { file: '/handoff', cwd: '/work', gitRepo: true, degraded: [] } })
const answer = await startHandoff(core, emptyPorts(), prepare).agent_handoff_prepare!(request, owner)
expect(answer).toEqual({ agentId: 'agent', file: '/handoff', cwd: '/work', gitRepo: true, degraded: [] })
expect(prepare).toHaveBeenCalledWith(expect.anything(), request)
expect(await deps.resolve('agent')).toBe(session)
expect(core.conversations.resolve).toHaveBeenCalledWith('agent')
expect(deps.readHistory(session)).toBe(reader)
expect(core.transcripts.databaseHistory).toHaveBeenCalledWith(session)
expect(await deps.recentAsks('s', 20)).toEqual(['ask'])
expect(core.conversations.recentAsks).toHaveBeenCalledWith('s', 20)
expect(await deps.lastFullText('s')).toBe('answer')
vi.mocked(core.conversations.lastFullText).mockResolvedValueOnce(null)
expect(await deps.lastFullText('missing')).toBeUndefined()
expect(await deps.recaps!('s', 5)).toEqual(['recap'])
expect(core.conversations.recaps).toHaveBeenCalledWith('s', 5)
expect(await deps.discoverSession!(session)).toEqual({ engine: 'claude', sessionId: 's', transcriptPath: '/s.jsonl' })
expect(core.conversations.discover).toHaveBeenCalledWith('agent')
expect(await deps.findTranscript!('claude', 's', {})).toBe('/s.jsonl')
expect(core.conversations.findTranscript).toHaveBeenCalledWith('claude', 's', {})
expect(await deps.transcriptOk!('claude', '/s.jsonl', null)).toBe(true)
expect(core.conversations.transcriptOk).toHaveBeenCalledWith('claude', '/s.jsonl', null)
})
})
it('retains the exact owner request and revokes publication when its connection closes', async () => {
const result = { file: null, cwd: '/work', gitRepo: false, degraded: [] }
const publish = vi.fn(async () => result), core = fakeCore({ conversations: { publish } })
let deps!: HandoffDeps
const prepare = vi.fn(async (given: HandoffDeps) => { deps = given; return result })
const closed = new AbortController()
await startHandoff(core, undefined, prepare).agent_handoff_prepare!({ ...request, requestId: 'routed' }, owner, closed.signal)
expect(deps.permit!.requestId).toBe('routed')
expect(deps.permit!.current(request)).toBe(true)
for (const other of [{ ...request, agentId: 'other' }, { ...request, changeId: '2'.repeat(32) }, { ...request, targetEngine: 'claude' }]) {
expect(deps.permit!.current(other)).toBe(false)
}
const prepared = { request } as never
expect(await deps.publish!(prepared, { current: () => false })).toEqual(result)
expect(publish).toHaveBeenCalledWith(prepared, deps.permit)
closed.abort(); expect(deps.permit!.current(request)).toBe(false)
})