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 type { RegisteredSession } from '../lib/registry.js'
import { fakeCore } from '../testing/fakeCore.js'
import { VIEWERS_UNAVAILABLE } from './api.js'
import { ON_DEMAND_START_MS } from './serviceLinks.js'
import { createViewersLink, SURFACE_WAIT_MS, VIEWERS_BUFFER_LIMIT } from './viewersLink.js'
const agent = (over: Partial<RegisteredSession> = {}) =>
({ agentId: 'a1', sessionId: 's1', engine: 'claude', dsh: 'acme/blender', cwd: '/work/scene', ...over }) as RegisteredSession
const context = (over: Record<string, unknown> = {}) =>
({ id: 'acme/blender', name: 'Blender', viewerUrl: null, viewerName: 'Blender Viewer', verdict: null, ...over })
function setup(live: RegisteredSession | null = agent(), terminalAvailable = true) {
const core = fakeCore({
agents: {
byAgent: vi.fn(() => live ?? undefined),
terminalAvailable: vi.fn(() => terminalAvailable),
live: vi.fn(() => [agent(), agent({ agentId: 'plain', dsh: undefined }), agent({ agentId: 'a2', dsh: 'acme/kicad' })]),
},
})
const notify = vi.fn(() => true)
const link = createViewersLink(core, notify)
return { core, notify, link, port: link.port }
}
describe('the viewers in their own process, as the core keeps them', () => {
it('tells the process of each agent with a harness it attaches, and of no other', () => {
const { notify, port } = setup()
port.attach(agent())
port.attach(agent({ agentId: 'plain', dsh: undefined }))
// Not held while the process is down: it asks for every agent each time it connects.
expect(notify.mock.calls).toEqual([[{ type: 'service_event', payload: { kind: 'attach', session: agent() } }]])
})
it('answers a frame with the fallbacks until the process has said anything of the agent', () => {
const { port } = setup()
port.attach(agent())
expect(port.frameContext(agent())).toBeNull()
expect(port.forwardingUrl('a1')).toBeNull()
})
it('keeps what the process says of an attached agent, follows its viewer and sends its frame again', () => {
const { core, link, port } = setup()
port.attach(agent())
const said = context({ viewerUrl: 'http://127.0.0.1:7001/' })
expect(link.answer('context', { agentId: 'a1', context: said, forwardingUrl: 'http://127.0.0.1:7001/', requestId: 'q1', query: 'context' })).toEqual({ kept: true })
expect(port.frameContext(agent())).toEqual(said)
expect(port.forwardingUrl('a1')).toBe('http://127.0.0.1:7001/')
expect(core.agents.sync).toHaveBeenCalledWith(agent())
// An agent without a harness has nothing to say on its frame, whatever was kept under its id.
expect(port.frameContext(agent({ dsh: undefined }))).toBeNull()
})
it('a change sends the frame again; no change does nothing', () => {
const { core, link, port } = setup()
port.attach(agent())
link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })
expect(core.agents.sync).toHaveBeenCalledTimes(1)
const verdict = { ready: true, summary: 'ok', errors: 0, warnings: 0, artifact: null, phases: [], updatedAt: null }
link.answer('context', { agentId: 'a1', context: context({ verdict }), forwardingUrl: null })
expect(port.frameContext(agent())).toMatchObject({ verdict })
expect(core.agents.sync).toHaveBeenCalledTimes(2)
expect(link.answer('context', { agentId: 'a1', context: context({ verdict }), forwardingUrl: null })).toEqual({ kept: true })
expect(core.agents.sync).toHaveBeenCalledTimes(2)
})
it('waits for the terminal before sending a frame, which would otherwise read as "agent gone"', () => {
const detached = setup(agent(), false)
detached.port.attach(agent())
detached.link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })
expect(detached.port.frameContext(agent())).toMatchObject({ viewerUrl: 'http://127.0.0.1:7001/' })
expect(detached.core.agents.sync).not.toHaveBeenCalled()
const gone = setup(null)
gone.port.attach(agent())
gone.link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })
expect(gone.core.agents.sync).not.toHaveBeenCalled()
})
it('keeps nothing of an agent it never attached, or detached since: a word said before the detach is older than it', () => {
const { core, link, port } = setup()
expect(link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })).toEqual({ kept: false })
port.attach(agent())
port.detach('a1')
expect(link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })).toEqual({ kept: false })
expect(port.frameContext(agent())).toBeNull()
expect(port.forwardingUrl('a1')).toBeNull()
expect(core.agents.sync).not.toHaveBeenCalled()
// Nor of one it cannot name.
expect(link.answer('context', { agentId: 7, context: context() })).toEqual({ kept: false })
})
it('reads what does not look like a context or a URL as none', () => {
const { link, port } = setup()
port.attach(agent())
link.answer('context', { agentId: 'a1', context: 'not a context', forwardingUrl: 9 })
expect(port.frameContext(agent())).toBeNull()
expect(port.forwardingUrl('a1')).toBeNull()
})
it('a detach forgets the agent, and is held until the process hears it', () => {
const { notify, link, port } = setup()
port.attach(agent())
link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })
port.detach('a1')
expect(notify).toHaveBeenLastCalledWith({ type: 'service_event', payload: { kind: 'detach', agentId: 'a1' } }, { untilDelivered: true })
expect(port.frameContext(agent())).toBeNull()
expect(port.forwardingUrl('a1')).toBeNull()
})
it('answers from what it last knew while the process cannot hear anything', () => {
const { link, notify, port } = setup()
port.attach(agent())
link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })
notify.mockReturnValue(false)
port.attach(agent())
expect(port.frameContext(agent())).toMatchObject({ viewerUrl: 'http://127.0.0.1:7001/' })
expect(port.forwardingUrl('a1')).toBe('http://127.0.0.1:7001/')
})
it('names the agents with a harness when the process asks, and refuses a question it does not know', () => {
const { link } = setup()
expect(link.answer('agents', {})).toEqual({ agents: [agent(), agent({ agentId: 'a2', dsh: 'acme/kicad' })] })
expect(link.answer('session_search', {})).toEqual({ error: 'UNKNOWN_QUERY' })
})
it('stops nothing in the core: the viewers are the process\'s', async () => {
const { notify, port } = setup()
await expect(port.stop()).resolves.toBeUndefined()
expect(notify).not.toHaveBeenCalled()
})
})
describe('a viewer served to a client over its connection, through the viewers\' process', () => {
const streaming = (buffered = 0) => {
const core = fakeCore()
const notify = vi.fn(() => true)
const call = vi.fn(async (_type: string, payload: Record<string, unknown>) => ({ data: 'jpeg', asked: payload }))
const link = createViewersLink(core, notify, { call, buffered: () => buffered })
return { core, notify, call, link, port: link.port }
}
it('tells the process each frame of a client\'s stream as it comes, never held for a process that is down', () => {
const { notify, port } = streaming()
expect(port.stream('c1', 'viewer_request', { streamId: 's1' })).toBe(true)
expect(notify).toHaveBeenCalledWith({ type: 'service_event', payload: { kind: 'stream', connId: 'c1', type: 'viewer_request', frame: { streamId: 's1' } } })
notify.mockReturnValue(false)
expect(port.stream('c1', 'viewer_data', { streamId: 's1' })).toBe(false)
expect(notify).toHaveBeenCalledTimes(2)
})
it('refuses a stream\'s frame while the process is not reading, rather than keep it', () => {
const { notify, port } = streaming(VIEWERS_BUFFER_LIMIT + 1)
expect(port.stream('c1', 'viewer_request', { streamId: 's1' })).toBe(false)
expect(notify).not.toHaveBeenCalled()
})
it('asks the process for a client\'s rendered frame, with the connection it came over, waiting no longer than a client does', async () => {
const { call, port } = streaming()
await expect(port.surface('c1', { surfaceId: 'v' })).resolves.toEqual({ data: 'jpeg', asked: { surfaceId: 'v', connId: 'c1' } })
expect(call).toHaveBeenCalledWith('surface', { surfaceId: 'v', connId: 'c1' }, SURFACE_WAIT_MS)
})
it('without a link to the process, a surface is answered unavailable and a stream is not taken', async () => {
const link = createViewersLink(fakeCore(), vi.fn(() => false))
await expect(link.port.surface('c1', {})).resolves.toEqual(VIEWERS_UNAVAILABLE)
expect(link.port.stream('c1', 'viewer_request', { streamId: 's1' })).toBe(false)
})
it('tells the process a connection went, or every one did', () => {
const { notify, port } = streaming()
port.closed('c1')
port.closed()
expect(notify.mock.calls).toEqual([
[{ type: 'service_event', payload: { kind: 'closed', connId: 'c1' } }],
[{ type: 'service_event', payload: { kind: 'closed' } }],
])
})
it('hands what a stream answers to its connection, and ends the stream in the process when it cannot', () => {
const { core, notify, link } = streaming()
vi.mocked(core.clients.viewerFrame).mockReturnValue(true)
link.notice({ kind: 'viewer', connId: 'c1', type: 'viewer_response', payload: { streamId: 's1', status: 200 } })
expect(core.clients.viewerFrame).toHaveBeenCalledWith('c1', 'viewer_response', { streamId: 's1', status: 200 })
expect(notify).not.toHaveBeenCalled()
vi.mocked(core.clients.viewerFrame).mockReturnValue(false)
link.notice({ kind: 'viewer', connId: 'c1', type: 'viewer_data', payload: { streamId: 's1', data: 'AA==' } })
expect(notify).toHaveBeenCalledWith({ type: 'service_event', payload: {
kind: 'stream', connId: 'c1', type: 'viewer_close', frame: { streamId: 's1', error: 'Viewer connection closed' },
} })
// A close that could not be delivered, or a frame of no stream, needs nothing more.
link.notice({ kind: 'viewer', connId: 'c1', type: 'viewer_close', payload: { streamId: 's1' } })
link.notice({ kind: 'viewer', connId: 'c1', type: 'viewer_data' })
expect(notify).toHaveBeenCalledTimes(1)
expect(core.clients.viewerFrame).toHaveBeenLastCalledWith('c1', 'viewer_data', {})
})
it('ignores a notice that is not a stream\'s frame for a connection', () => {
const { core, link } = streaming()
link.notice({ kind: 'other', connId: 'c1', type: 'viewer_data' })
link.notice({ kind: 'viewer', connId: 7, type: 'viewer_data' })
link.notice({ kind: 'viewer', connId: 'c1' })
expect(core.clients.viewerFrame).not.toHaveBeenCalled()
})
})
describe('the viewers\' process on demand (core/viewersWake.ts)', () => {
const onDemand = (connected = true) => {
const core = fakeCore()
vi.mocked(core.clients.viewerFrame).mockReturnValue(true)
const notify = vi.fn(() => connected)
const wake = vi.fn()
const timers: Array<{ run: () => void; ms: number; cleared: boolean }> = []
const link = createViewersLink(core, notify, { call: vi.fn(async () => ({})), buffered: () => 0 }, {
wake,
startWaitMs: 5_000,
setTimer: (run, ms) => { const timer = { run, ms, cleared: false }; timers.push(timer); return timer },
clearTimer: (timer) => { (timer as { cleared: boolean }).cleared = true },
})
return { core, notify, wake, timers, link, port: link.port }
}
const stream = (connId: string, type: string, streamId = 's1') =>
({ type: 'service_event', payload: { kind: 'stream', connId, type, frame: { streamId } } })
it('asks for the process for an agent with a harness, and not for one without', () => {
const { wake, port } = onDemand()
port.attach(agent({ agentId: 'plain', dsh: undefined }))
expect(wake).not.toHaveBeenCalled()
port.attach(agent())
expect(wake).toHaveBeenCalledWith('a harness here')
})
it('holds a stream that comes before the process ever connected, asks for it once, and tells it every frame in order once it connects', () => {
const { core, notify, wake, timers, link, port } = onDemand()
expect(port.stream('c1', 'viewer_request', { streamId: 's1' })).toBe(true)
expect(port.stream('c2', 'viewer_request', { streamId: 's2' })).toBe(true)
expect(port.stream('c1', 'viewer_data', { streamId: 's1' })).toBe(true)
expect(wake.mock.calls).toEqual([['a viewer stream']])
expect(timers).toHaveLength(1)
expect(timers[0].ms).toBe(5_000)
expect(notify).not.toHaveBeenCalled()
link.connected()
expect(timers[0].cleared).toBe(true)
expect(notify.mock.calls).toEqual([[stream('c1', 'viewer_request')], [stream('c2', 'viewer_request', 's2')], [stream('c1', 'viewer_data')]])
expect(core.clients.viewerFrame).not.toHaveBeenCalled()
// Connected once, a frame is told as it comes, and refused at once while the process is down again.
notify.mockReturnValue(false)
expect(port.stream('c1', 'viewer_data', { streamId: 's1' })).toBe(false)
expect(timers).toHaveLength(1)
})
it('refuses what it held, and every stream after it at once, when the process does not connect within a start\'s wait', () => {
const { core, notify, wake, timers, link, port } = onDemand(false)
port.stream('c1', 'viewer_request', { streamId: 's1' })
port.stream('c1', 'viewer_close', { streamId: 's1' })
port.stream('c1', 'viewer_data', {})
timers[0].run()
// Only the stream's own frames that need an answer are answered: a close and a frame of no stream need none.
expect(core.clients.viewerFrame).toHaveBeenCalledTimes(1)
expect(core.clients.viewerFrame).toHaveBeenCalledWith('c1', 'viewer_close', { streamId: 's1', error: 'Viewer is no longer available' })
expect(port.stream('c1', 'viewer_request', { streamId: 's2' })).toBe(false)
expect(notify).toHaveBeenCalledTimes(1)
expect(wake).toHaveBeenCalledTimes(1)
// It came at last: streams go to it again.
notify.mockReturnValue(true)
link.connected()
expect(port.stream('c1', 'viewer_request', { streamId: 's3' })).toBe(true)
expect(notify).toHaveBeenLastCalledWith(stream('c1', 'viewer_request', 's3'))
})
it('refuses a held frame the process does not take as it connects', () => {
const { core, notify, link, port } = onDemand(false)
port.stream('c1', 'viewer_request', { streamId: 's1' })
link.connected()
expect(notify).toHaveBeenCalledWith(stream('c1', 'viewer_request'))
expect(core.clients.viewerFrame).toHaveBeenCalledWith('c1', 'viewer_close', { streamId: 's1', error: 'Viewer is no longer available' })
})
it('holds no more than a hung process\'s socket may keep: past it, a frame is refused', () => {
const { port } = onDemand()
const chunk = 'A'.repeat(VIEWERS_BUFFER_LIMIT / 2)
expect(port.stream('c1', 'viewer_data', { streamId: 's1', data: chunk })).toBe(true)
expect(port.stream('c1', 'viewer_data', { streamId: 's1', data: chunk })).toBe(false)
expect(port.stream('c1', 'viewer_close', { streamId: 's1' })).toBe(true)
})
it('drops what it held for a connection that closed, or for every one', () => {
const { notify, link, port } = onDemand()
port.stream('c1', 'viewer_request', { streamId: 's1' })
port.stream('c2', 'viewer_request', { streamId: 's2' })
port.closed('c1')
link.connected()
expect(notify.mock.calls).toEqual([
[{ type: 'service_event', payload: { kind: 'closed', connId: 'c1' } }],
[stream('c2', 'viewer_request', 's2')],
])
const again = onDemand()
again.port.stream('c1', 'viewer_request', { streamId: 's1' })
again.port.closed()
again.link.connected()
expect(again.notify.mock.calls).toEqual([[{ type: 'service_event', payload: { kind: 'closed' } }]])
})
it('waits a start\'s wait by default, on the real clock', () => {
vi.useFakeTimers()
try {
const core = fakeCore()
const link = createViewersLink(core, vi.fn(() => false), undefined, { wake: vi.fn() })
link.port.stream('c1', 'viewer_request', { streamId: 's1' })
vi.advanceTimersByTime(ON_DEMAND_START_MS - 1)
expect(core.clients.viewerFrame).not.toHaveBeenCalled()
vi.advanceTimersByTime(1)
expect(core.clients.viewerFrame).toHaveBeenCalledWith('c1', 'viewer_close', { streamId: 's1', error: 'Viewer is no longer available' })
// Connected, the default clock's timer is cleared too.
link.port.stream('c1', 'viewer_request', { streamId: 's2' })
const other = createViewersLink(core, vi.fn(() => true), undefined, { wake: vi.fn() })
other.port.stream('c1', 'viewer_request', { streamId: 's3' })
other.connected()
vi.advanceTimersByTime(ON_DEMAND_START_MS)
expect(core.clients.viewerFrame).toHaveBeenCalledTimes(1)
} finally { vi.useRealTimers() }
})
})