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 { afterEach, describe, expect, it, vi } from 'vitest'
import type { AgentFrame } from '../../lib/agentFrame.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { RuntimeProfileControlError } from '../../lib/runtimeProfileController.js'
import { AGENT_OPENED_THROTTLE_MS, createAgentUpdate, type AgentUpdateDeps } from './update.js'
/**
* `agent_update`, answered by the core: a rename, a model and effort, or an app opening the agent. The
* reply is the frame as it stands after, and it goes out before any window hears of the change.
*/
const NOW = Date.UTC(2026, 9, 5, 9, 0)
const row = (over: Partial<RegisteredSession> = {}) => ({ agentId: 'a1', sessionId: 's1', engine: 'claude', ...over }) as RegisteredSession
function setup(over: Partial<AgentUpdateDeps> = {}, agent: RegisteredSession | null = row()) {
const heard: Array<[string, unknown]> = []
const deps: AgentUpdateDeps = {
registry: {
resolve: vi.fn(() => agent ?? undefined),
rename: vi.fn((_id: string, name: string) => row({ ...agent, defaultName: name })),
markOpened: vi.fn(() => row({ ...agent, lastOpenedAt: NOW })),
terminalAvailable: vi.fn(() => true),
setLaunchModel: vi.fn(() => true),
},
onRuntimeProfileUpdate: vi.fn(async () => {}),
onAgentRename: vi.fn(),
closeAgentService: () => ({ cancel: vi.fn() }),
toProject: vi.fn(async (s: RegisteredSession) => ({ id: s.agentId, name: s.defaultName ?? 'Agent', lastOpenedAt: s.lastOpenedAt ?? null }) as unknown as AgentFrame),
clients: { send: vi.fn((frame) => { heard.push(['send', frame]) }), sendCommander: vi.fn((frame) => { heard.push(['device', frame]) }) },
...over,
}
const ask = (payload: Record<string, unknown>) => createAgentUpdate(deps).agentUpdate(payload, (result) => { heard.push(['reply', result]) })
return { deps, heard, ask }
}
afterEach(() => {
vi.useRealTimers()
vi.restoreAllMocks()
})
describe('what an update must say', () => {
it('which agent, and at least one of a name, a model or an open; a name that is not blank; an agent that exists', async () => {
const { heard, ask, deps } = setup()
await ask({ name: 'x' })
await ask({ agentId: 'a1' })
await ask({ agentId: 'a1', opened: 'yes' })
await ask({ agentId: 'a1', name: ' ' })
await ask({ agentId: 'a1', name: 7 })
expect(heard).toEqual([
['reply', { error: 'MISSING_AGENT_ID' }], ['reply', { error: 'MISSING_UPDATE' }], ['reply', { error: 'MISSING_UPDATE' }],
['reply', { error: 'MISSING_NAME' }], ['reply', { error: 'MISSING_NAME' }],
])
expect(deps.registry.resolve).not.toHaveBeenCalled()
const missing = setup({}, null)
await missing.ask({ agentId: 'nobody', opened: true })
expect(missing.heard).toEqual([['reply', { error: 'AGENT_NOT_FOUND' }]])
})
})
describe('a model and effort', () => {
it('moves the agent and answers with its frame', async () => {
const { heard, ask, deps } = setup()
await ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:claude:opus@high' })
expect(deps.onRuntimeProfileUpdate).toHaveBeenCalledWith('a1', 'runtime-v1:s1:claude:opus@high')
expect(heard).toEqual([['reply', { agent: { id: 'a1', name: 'Agent', lastOpenedAt: null } }]])
expect(Object.keys(heard[0][1] as object)).toEqual(['agent'])
})
// Task #3395: a person's pick is what the session relaunches with (lib/launchOverrides.ts), not the model it was first
// launched with, which a reopen would otherwise put back.
it('records the pick as the model its session relaunches with, its effort only where the engine takes it', async () => {
const { ask, deps } = setup()
await ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:claude:sonnet@high' })
expect(deps.registry.setLaunchModel).toHaveBeenCalledWith('a1', { model: 'sonnet', effort: 'high' })
await ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:claude:opus@ultracode' })
expect(deps.registry.setLaunchModel).toHaveBeenLastCalledWith('a1', { model: 'opus', effort: null })
const codex = setup({}, row({ engine: 'codex' }))
await codex.ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:codex:gpt-6@high' })
expect(codex.deps.registry.setLaunchModel).toHaveBeenCalledWith('a1', null)
// A pick the wire cannot read was the controller's to judge; nothing is recorded for it.
const unread = setup()
await unread.ask({ agentId: 'a1', selectedModel: 'runtime-v1:x' })
expect(unread.deps.registry.setLaunchModel).not.toHaveBeenCalled()
const failed = setup({ onRuntimeProfileUpdate: async () => { throw new RuntimeProfileControlError('BUSY') } })
await failed.ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:claude:sonnet@high' })
expect(failed.deps.registry.setLaunchModel).not.toHaveBeenCalled()
})
it('refuses a profile that is not one, or with nothing to apply it, and says why a move failed', async () => {
const refused = async (over: Partial<AgentUpdateDeps>, selectedModel: unknown) => {
const { heard, ask } = setup(over)
await ask({ agentId: 'a1', selectedModel })
return heard
}
expect(await refused({}, 7)).toEqual([['reply', { error: 'INVALID_RUNTIME_PROFILE' }]])
expect(await refused({ onRuntimeProfileUpdate: null }, 'runtime-v1:x')).toEqual([['reply', { error: 'INVALID_RUNTIME_PROFILE' }]])
expect(await refused({ onRuntimeProfileUpdate: async () => { throw new RuntimeProfileControlError('BUSY') } }, 'runtime-v1:x')).toEqual([['reply', { error: 'BUSY' }]])
expect(await refused({ onRuntimeProfileUpdate: async () => { throw new Error('pane gone') } }, 'runtime-v1:x')).toEqual([['reply', { error: 'INTERNAL' }]])
})
it('logs the name and message of an unexpected profile failure without request contents', async () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const { heard, ask } = setup({ onRuntimeProfileUpdate: async () => { throw new TypeError('engine state disappeared') } })
await ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:claude:private-model@high' })
expect(heard).toEqual([['reply', { error: 'INTERNAL' }]])
expect(error).toHaveBeenCalledExactlyOnceWith('[agent_update] model update failed: TypeError: engine state disappeared')
})
it('gives a non-Error exception a safe description', async () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const { heard, ask } = setup({ onRuntimeProfileUpdate: async () => { throw null } })
await ask({ agentId: 'a1', selectedModel: 'runtime-v1:s1:claude:private-model@high' })
expect(heard).toEqual([['reply', { error: 'INTERNAL' }]])
expect(error).toHaveBeenCalledExactlyOnceWith('[agent_update] model update failed: UnknownError: non-Error exception')
})
})
describe('a rename', () => {
it('renames the agent and its pane, answers first, then tells every window and the device, and logs it', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const { heard, ask, deps } = setup()
await ask({ agentId: 'a1', name: ' Release notes ' })
expect(deps.registry.rename).toHaveBeenCalledWith('a1', 'Release notes')
expect(deps.onAgentRename).toHaveBeenCalledWith(expect.objectContaining({ defaultName: 'Release notes' }), 'Release notes')
const renamed = { type: 'agent_renamed', payload: { agentId: 'a1', name: 'Release notes', engine: 'claude' } }
expect(heard).toEqual([['reply', { agent: { id: 'a1', name: 'Release notes', lastOpenedAt: null } }], ['send', renamed], ['device', renamed]])
expect(log).toHaveBeenCalledWith('[rename] a1 → "Release notes" · broadcast to web + device')
})
it('keeps the row it had when the registry renames nothing, and titles no pane when nothing does', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const { heard, ask, deps } = setup({ onAgentRename: null })
vi.mocked(deps.registry.rename).mockReturnValueOnce(null)
await ask({ agentId: 'a1', name: 'Kept' })
expect(heard[0]).toEqual(['reply', { agent: { id: 'a1', name: 'Agent', lastOpenedAt: null } }])
})
})
describe('an app opening the agent', () => {
it('stamps it on this machine\'s clock, keeps it from being closed unseen, answers, then tells every window but not the device', async () => {
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(NOW)
const cancel = vi.fn()
const { heard, ask, deps } = setup({ closeAgentService: () => ({ cancel }) })
await ask({ agentId: 'a1', opened: true })
expect(cancel).toHaveBeenCalledWith('a1')
expect(deps.registry.markOpened).toHaveBeenCalledWith('a1')
const agent = { id: 'a1', name: 'Agent', lastOpenedAt: NOW }
expect(heard).toEqual([['reply', { agent }], ['send', { type: 'agent_synced', payload: { agent } }]])
})
it('answers a repeat inside the throttle with the frame as it is, stamping and telling no one; a stamp from the future never throttles', async () => {
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(NOW)
const stamped = (lastOpenedAt: number) => setup({ closeAgentService: () => null }, row({ lastOpenedAt }))
const repeat = stamped(NOW - AGENT_OPENED_THROTTLE_MS + 1)
await repeat.ask({ agentId: 'a1', opened: true })
expect(repeat.deps.registry.markOpened).not.toHaveBeenCalled()
expect(repeat.heard).toEqual([['reply', { agent: { id: 'a1', name: 'Agent', lastOpenedAt: NOW - AGENT_OPENED_THROTTLE_MS + 1 } }]])
for (const lastOpenedAt of [NOW - AGENT_OPENED_THROTTLE_MS, NOW + 60_000]) {
const later = stamped(lastOpenedAt)
await later.ask({ agentId: 'a1', opened: true })
expect(later.deps.registry.markOpened).toHaveBeenCalledOnce()
}
})
it('stamps but tells no window of an agent whose terminal this machine cannot see, and keeps its row if the registry stamps nothing', async () => {
const { heard, ask, deps } = setup()
vi.mocked(deps.registry.terminalAvailable).mockReturnValue(false)
vi.mocked(deps.registry.markOpened).mockReturnValueOnce(null)
await ask({ agentId: 'a1', opened: true })
expect(heard).toEqual([['reply', { agent: { id: 'a1', name: 'Agent', lastOpenedAt: null } }]])
})
})