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.

21.8 KB
Raw Blame
// The devices in a process of their own (services/devicesProcess.ts): the core API they run on across their
// link, what the core tells them reaching the devices' port, and what the core asks answered from it.
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { CoreApi, CorePorts, DevicesPort, ServiceRequests } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
import type { DevicesDeps } from './devices.js'
import { runDevicesService } from './devicesProcess.js'
import type { CoreConnection, ServiceProcessOptions } from './process.js'

// The real devices and the real link, as a process started by the master runs them: stood in for here.
const real = vi.hoisted(() => ({ started: [] as unknown[], linked: [] as unknown[] }))
vi.mock('./devices.js', () => ({
  startDevices: (_core: unknown, ports: { devices: unknown }) => { real.started.push(ports); ports.devices = { stop: async () => {} }; return {} },
}))
vi.mock('./process.js', () => ({
  runServiceProcess: (options: unknown) => { real.linked.push(options); return { stop: () => {} } },
}))

/** A devices' port that records what reached it. */
function devicesPort() {
  const calls: Array<[string, unknown[]]> = []
  const record = (name: string) => (...args: unknown[]) => { calls.push([name, args]) }
  const port = {
    card: record('card'), desk: record('desk'), swarms: record('swarms'), swarmCards: record('swarmCards'), swarmCardRecap: record('swarmCardRecap'), unread: record('unread'), appFocus: record('appFocus'),
    seen: record('seen'), settings: record('settings'), windowFocus: record('windowFocus'), windowReply: record('windowReply'),
    voiceReply: record('voiceReply'), windowGone: record('windowGone'), scroll: record('scroll'), engines: record('engines'),
    commanders: record('commanders'),
    routeTask: vi.fn(async (text: string) => ({ agentId: 'a1', machineId: 'm1', name: 'api', confidence: 1, reason: text, candidates: [], weighed: 1, machines: 1, via: 'model' })),
    routeSend: vi.fn(async () => ({ ok: true as const })),
    stepFocus: vi.fn(async (): Promise<{ machineId: string; agentId: string } | 'no_agents'> => ({ machineId: 'm1', agentId: 'a2' })),
    stop: vi.fn(async () => {}),
  } satisfies DevicesPort
  return { port, calls }
}

function setup(over: { processEnv?: NodeJS.ProcessEnv } = {}) {
  const { port, calls } = devicesPort()
  let api!: CoreApi
  let deps!: DevicesDeps
  const tab = { harness_devices_list: vi.fn(async () => ({ protocol: 1 })) }
  const start = vi.fn((core: CoreApi, ports: CorePorts, given: DevicesDeps): ServiceRequests => {
    api = core
    deps = given
    ports.devices = port
    return tab
  })
  let options!: ServiceProcessOptions
  const stop = vi.fn()
  const run = vi.fn((given: ServiceProcessOptions) => { options = given; return { stop } })
  const service = runDevicesService({
    dataDir: '/data', socketPath: '/sock', machineId: 'computer-9', token: 't',
    start, run, processEnv: over.processEnv ?? {},
  })
  const queries: Array<[string, Record<string, unknown> | undefined]> = []
  const notices: Array<[string, Record<string, unknown> | undefined]> = []
  let answers: Record<string, unknown> = {}
  const connection: CoreConnection = {
    query: vi.fn(async (query: string, payload?: Record<string, unknown>) => {
      queries.push([query, payload])
      const answer = answers[query]
      if (answer instanceof Error) throw answer
      return (answer ?? {}) as Record<string, unknown>
    }),
    notice: (kind, payload) => { notices.push([kind, payload]) },
  }
  return {
    service, port, calls, api: () => api, deps: () => deps, options: () => options, stop, tab, queries, notices, connection,
    answer: (query: string, value: unknown) => { answers = { ...answers, [query]: value } },
    connect: () => options.onConnected!(connection),
    event: (payload: Record<string, unknown>) => options.onEvent!(payload),
  }
}

afterEach(() => vi.restoreAllMocks())

describe('the devices in their own process', () => {
  it('start the devices on a link of their own, with what their process\'s environment says', () => {
    const f = setup({ processEnv: { HARNESS_DIAL_SERIALS: ' AA, ,BB ', HARNESSD_TEST_DIAL_PORT: '/dev/ttys042', HARNESSD_TEST_FAULTS: 'dial, fleet.knows ,' } })
    expect(f.options()).toMatchObject({ name: 'devices', socketPath: '/sock', machineId: 'computer-9', token: 't' })
    expect(f.deps()).toMatchObject({ dialSerials: ['AA', 'BB'], testDialPort: '/dev/ttys042' })
    // No credential and no E2EE identity: the account is asked of the core.
    expect(Object.keys(f.deps())).not.toContain('identity')
    expect([...f.deps().faults!]).toEqual(['dial', 'fleet.knows'])
    // The Devices tab's requests are the devices' own, beside what only the core asks.
    expect(Object.keys(f.options().requests).sort()).toEqual(['harness_devices_list', 'routeSend', 'routeTask', 'stepFocus'])
  })

  it('read no serials, dial or faults without them', () => {
    const f = setup({ processEnv: {} })
    expect(f.deps().dialSerials).toBeUndefined()
    expect([...f.deps().faults!]).toEqual([])
    // Their own process's environment by default.
    const was = process.env.HARNESSD_TEST_DIAL_PORT
    process.env.HARNESSD_TEST_DIAL_PORT = '/dev/ttys777'
    try {
      let deps!: DevicesDeps
      runDevicesService({ dataDir: '/data', socketPath: '/sock', machineId: 'c', token: 't',
        start: (_core, ports, given) => { deps = given; ports.devices = devicesPort().port; return {} }, run: () => ({ stop: () => {} }) })
      expect(deps.testDialPort).toBe('/dev/ttys777')
    } finally {
      if (was === undefined) delete process.env.HARNESSD_TEST_DIAL_PORT
      else process.env.HARNESSD_TEST_DIAL_PORT = was
    }
  })

  it('run what the devices registered for a core that connects, each time one does', () => {
    const f = setup()
    const again = vi.fn()
    f.deps().onCoreConnected!(again)
    expect(again).not.toHaveBeenCalled()
    f.connect()
    f.connect()
    expect(again).toHaveBeenCalledTimes(2)
  })

  it('run the devices and their link as the master starts them', () => {
    runDevicesService({ dataDir: '/data', socketPath: '/sock', machineId: 'c', token: 't' })
    expect(real.started).toHaveLength(1)
    expect(real.linked).toEqual([expect.objectContaining({ name: 'devices', socketPath: '/sock', token: 't' })])
  })

  it('stop their link, then the devices, serial ports first', async () => {
    const f = setup()
    await f.service.stop()
    expect(f.stop).toHaveBeenCalled()
    expect(f.port.stop).toHaveBeenCalled()
  })
})

describe('the core\'s view, read in line by the dial', () => {
  const agent = { agentId: 'a1', sessionId: 's1', engine: 'claude', displayName: 'api', runtimeProfile: 'runtime-v1:s1:claude:opus@high' }

  it('is nothing but this computer\'s id before the core is asked', async () => {
    const f = setup()
    const api = f.api()
    expect(api.agents.advertised()).toEqual([])
    expect(api.machine.computerId()).toBe('computer-9')
    expect(api.machine.name()).toBe('This machine')
    expect(api.account.signedIn()).toBe(false)
    // Not connected: refreshing asks nothing, and a question to the core fails at once.
    await f.deps().refresh!()
    expect(f.queries).toEqual([])
    await expect(api.agents.activityText('a1')).rejects.toThrow('the devices are not connected to the core')
  })

  it('is asked as the core connects, and again as the dial\'s tick or ⌘K needs it, one ask at a time', async () => {
    const f = setup()
    f.answer('view', { agents: [agent], machine: { id: 'machine-1', computerId: 'computer-1', name: 'Studio' }, signedIn: true, environment: 'prod', hasWindow: true })
    f.connect()
    await vi.waitFor(() => expect(f.api().agents.advertised()).toHaveLength(1))
    const api = f.api()
    const session = api.agents.advertised()[0]
    expect(api.agents.all()).toEqual([agent])
    expect(api.agents.live()).toEqual([agent])
    expect(api.agents.displayName(session)).toBe('api')
    expect(api.agents.displayName({ agentId: 'x' } as RegisteredSession)).toBe('')
    expect(api.agents.runtimeProfile(session)).toBe('runtime-v1:s1:claude:opus@high')
    expect(api.agents.runtimeProfile({ agentId: 'x' } as RegisteredSession)).toBeNull()
    expect(api.agents.byAgent('a1')).toEqual(agent)
    expect(api.agents.resolve('s1')).toEqual(agent)
    expect(api.agents.terminalAvailable('a1')).toBe(true)
    api.agents.sync(session)
    expect([api.machine.id(), api.machine.computerId(), api.machine.name()]).toEqual(['machine-1', 'computer-1', 'Studio'])
    expect(api.account.signedIn()).toBe(true)
    expect(api.account.environment()).toBe('prod')
    expect(api.clients.hasWindow()).toBe(true)
    // Asked twice at once: one ask.
    const before = f.queries.length
    await Promise.all([f.deps().refresh!(), f.deps().refresh!()])
    expect(f.queries.length).toBe(before + 1)
    // An answer that is not a view changes nothing; one that is missing names keeps the defaults.
    f.answer('view', { error: 'QUERY_FAILED' })
    await f.deps().refresh!()
    expect(api.agents.advertised()).toHaveLength(1)
    f.answer('view', { agents: [], machine: 'nothing' })
    await f.deps().refresh!()
    expect([api.machine.id(), api.machine.computerId(), api.machine.name()]).toEqual(['', 'computer-9', 'This machine'])
    // An ask the core never answers (it went away) leaves the last view.
    f.answer('view', new Error('the core went away'))
    await f.deps().refresh!()
    expect(api.machine.computerId()).toBe('computer-9')
  })
})

describe('the core\'s doors, across the link', () => {
  it('ask the core for what needs an answer, and tell it the rest', async () => {
    const f = setup()
    f.connect()
    const api = f.api()
    f.answer('models', { models: [{ id: 'opus' }] })
    expect(await api.agents.runtimeModels('a1')).toEqual([{ id: 'opus' }])
    f.answer('models', {})
    expect(await api.agents.runtimeModels('a1')).toEqual([])
    f.answer('fork', { requestId: 'r', ok: true, agentId: 'a2' })
    expect(await api.agents.fork('a1')).toEqual({ ok: true, agentId: 'a2' })
    f.answer('activityText', { text: 'Reading' })
    expect(await api.agents.activityText('a1')).toBe('Reading')
    f.answer('activityText', { text: null })
    expect(await api.agents.activityText('a1')).toBeNull()
    f.answer('usageFresh', { usage: { totalTokens: 5, inputTokens: 3, updatedAt: '2026-10-12T00:00:00.000Z' } })
    expect(await api.usageFresh!('a1')).toMatchObject({ inputTokens: 3 })
    f.answer('usageFresh', { usage: 'junk' })
    expect(await api.usageFresh!('a1')).toBeNull()
    f.answer('usageFresh', new Error('the core went away'))
    expect(await api.usageFresh!('a1')).toBeNull()
    f.answer('activitySnapshot', { activity: { text: 'Working', elapsedSeconds: 931 } })
    expect(await api.agents.activitySnapshot!('a1')).toEqual({ text: 'Working', elapsedSeconds: 931 })
    // An older core does not know the query, or has no timer to give: the footer alone is still the footer.
    f.answer('activityText', { text: 'Reading' })
    f.answer('activitySnapshot', { error: 'UNKNOWN_QUERY' })
    expect(await api.agents.activitySnapshot!('a1')).toEqual({ text: 'Reading' })
    f.answer('activitySnapshot', new Error('the core went away'))
    expect(await api.agents.activitySnapshot!('a1')).toEqual({ text: 'Reading' })
    f.answer('activitySnapshot', { activity: null })
    expect(await api.agents.activitySnapshot!('a1')).toEqual({ text: 'Reading' })
    f.answer('activityText', { text: null })
    expect(await api.agents.activitySnapshot!('a1')).toBeNull()
    f.answer('recent', { turns: [{ recap: 'done' }] })
    expect(await api.turns.recent('a1', 2)).toEqual([{ recap: 'done' }])
    f.answer('recent', {})
    expect(await api.turns.recent('a1', 2)).toEqual([])
    f.answer('asks', { asks: ['why?', 7] })
    expect(await api.turns.asks('a1')).toEqual(['why?'])
    f.answer('answerReviewed', { ok: true })
    expect(await api.questions.answerReviewed({ agentId: 'a1' } as never)).toBe(true)
    // The account through the link every service in its own process uses (services/accountLink.ts).
    f.answer('access_token', { token: 'secret' })
    expect(await api.account.accessToken({ force: true })).toBe('secret')
    expect(f.queries.at(-1)).toEqual(['access_token', { force: true }])
    f.answer('lane', { frame: { type: 'message', sealed: true } })
    expect(await api.account.lane.seal('m2', { type: 'message' })).toEqual({ frame: { type: 'message', sealed: true } })
    expect(f.queries.at(-1)).toEqual(['lane', { machineId: 'm2', frame: { type: 'message' }, op: 'seal' }])
    f.answer('machines', { status: 200, body: { data: { machines: [] } } })
    expect(await api.account.machines()).toEqual({ status: 200, body: { data: { machines: [] } } })
    f.answer('machines', { body: 'broken' })
    expect(await api.account.machines()).toEqual({ status: 502, body: {} })
    // The Swarm cards' requests, asked of the core as its own `super_tabs` query; a core that cannot answer is unavailable.
    f.answer('super_tabs', { ok: true })
    expect(await api.superTabRequest!({ action: 'cardsWanted', on: true })).toEqual({ ok: true })
    expect(f.queries.at(-1)).toEqual(['super_tabs', { action: 'cardsWanted', on: true }])
    f.answer('super_tabs', new Error('the core went away'))
    expect(await api.superTabRequest!({ action: 'cardsWanted', on: false })).toEqual({ error: 'SERVICE_UNAVAILABLE' })
    api.agents.setRuntime('a1', 'opus', 'high')
    api.turns.send('a1', 'hello')
    api.turns.stop('a1')
    api.questions.answer('a1', 'r1', { q: 'Coffee' })
    api.clients.sendLocal({ type: 'dial_focus', payload: {} })
    expect(api.clients.sendToWindow('w1', { type: 'dial_form', payload: {} })).toBe(true)
    api.clients.devicesChanged({ revision: 1 })
    api.clients.dialWatching(true)
    // What an experiment acts on the core through, the devices never do.
    api.clients.windows({ type: 'orchestrator_changed', payload: {} })
    expect(api.daemon.port).toBe(0)
    expect(f.notices).toEqual([
      ['setRuntime', { agentId: 'a1', model: 'opus', effort: 'high' }],
      ['turn', { agentId: 'a1', text: 'hello' }],
      ['stop', { agentId: 'a1' }],
      ['answer', { agentId: 'a1', requestId: 'r1', answers: { q: 'Coffee' } }],
      ['sendLocal', { frame: { type: 'dial_focus', payload: {} } }],
      ['sendToWindow', { connId: 'w1', frame: { type: 'dial_form', payload: {} } }],
      ['devicesChanged', { revision: 1 }],
      ['dialWatching', { watching: true }],
    ])
    // What the devices never ask answers as every other service's does.
    expect(api.transcripts.databaseHistory({} as RegisteredSession)).toBeUndefined()
    await expect(api.account.mintGridName()).resolves.toBeNull()
    // Gone from the core: told nothing, and a bridge's ask says it did not go.
    f.options().onDisconnected!()
    api.turns.send('a1', 'lost')
    expect(api.clients.sendToWindow('w1', { type: 'dial_form', payload: {} })).toBe(false)
    expect(f.notices).toHaveLength(8)
  })

  // A dial says hello before its process is connected to a core that just started (2026-10-09, a user's
  // log: hello at 14:22:54.141, connected at 14:22:54.525): the core must still hear that it watches, or it
  // makes no cards for it and the dial shows Working for turns that ended, and no recaps.
  it('tell a core that connects whether a dial is watching, as they last said it', () => {
    const f = setup()
    const api = f.api()
    api.clients.dialWatching(true)
    expect(f.notices).toEqual([])
    f.connect()
    expect(f.notices).toEqual([['dialWatching', { watching: true }]])
    // A core that restarts while the dial stays is told again.
    f.options().onDisconnected!()
    f.connect()
    expect(f.notices).toEqual([['dialWatching', { watching: true }], ['dialWatching', { watching: true }]])
    // No dial any more: a new core starts out knowing that, and is told nothing.
    api.clients.dialWatching(false)
    f.options().onDisconnected!()
    f.connect()
    expect(f.notices).toHaveLength(3)
  })
})

describe('what the core tells the devices, reaching their port', () => {
  // Final review of spec 2026-11-02 poll cost: the fleet reads the machine list on `machines_changed` and only every
  // 5 minutes otherwise, so the account's notices the core forwards must reach it here too.
  it('hands the account notices the core forwards to its listeners', () => {
    const h = setup()
    const heard: unknown[] = []
    const stop = h.api().account.onNotice((notice) => heard.push(notice))
    h.event({ kind: 'notice', notice: { type: 'machines_changed', reason: 'renamed' } })
    expect(heard).toEqual([{ type: 'machines_changed', reason: 'renamed' }])
    stop()
    h.event({ kind: 'notice', notice: { type: 'machines_changed', reason: 'renamed' } })
    expect(heard).toHaveLength(1)
    // A notice that is not an object is nothing to hand on, not a listener's to explain.
    for (const notice of [null, 'renamed', 7]) h.event({ kind: 'notice', notice })
    expect(heard).toHaveLength(1)
  })

  it('is each kind of notice, read as the port takes it', () => {
    const f = setup()
    const focus = { voice: { machineId: 'm1', agentId: 'a1', connId: 'w1' }, form: { machineId: 'm1', connId: 'w1' } }
    for (const payload of [
      { kind: 'card', frame: { type: 'commander_event' } },
      { kind: 'card', frame: 'not one' },
      { kind: 'desk', agentIds: ['a1', 7], foreground: false },
      { kind: 'desk', agentIds: 'nonsense' },
      { kind: 'swarms', swarms: { active: 't1', swarms: [], tiles: [] } },
      { kind: 'swarms', swarms: null },
      { kind: 'swarmCards', items: [{ id: 't1' }] },
      { kind: 'swarmCards', items: 'nonsense' },
      { kind: 'swarmCardRecap', recap: { tabId: 't1' } },
      { kind: 'swarmCardRecap', recap: 'nonsense' },
      { kind: 'unread', items: [{ agentId: 'a1' }] },
      { kind: 'unread', items: 'nonsense' },
      { kind: 'appFocus', machineId: 'm1', agentId: 'a1' },
      { kind: 'seen', agentId: 'a1', readToken: 'tok' },
      { kind: 'seen', agentId: 'a1' },
      { kind: 'settings', id: 'usb', patch: { brightness: 3 } },
      { kind: 'settings', id: 'usb', patch: [1] },
      { kind: 'windowFocus', focus },
      { kind: 'windowFocus', focus: { voice: { connId: 'w2' }, form: 'nonsense' } },
      { kind: 'windowReply', which: 'form', connId: 'w1', machineId: 'm1', reply: { ok: true } },
      { kind: 'windowReply', which: 'visit', connId: 'w1', machineId: 'm1', reply: null },
      { kind: 'windowReply', which: 'anything', connId: 'w1', machineId: 'm1', reply: {} },
      { kind: 'voiceReply', voiceId: 'v1', reply: { t: 'taken' } },
      { kind: 'windowGone', connId: 'w1' },
      { kind: 'scroll', phase: 'move', dy: 2, velocity: Infinity },
      { kind: 'scroll', phase: 'sideways', dy: 2, velocity: 1 },
      { kind: 'engines', engines: ['claude'] },
      { kind: 'commanders', connected: true },
      { kind: 'nothing it knows' },
      { kind: 'constructor' },
    ]) f.event(payload)
    expect(f.calls).toEqual([
      ['card', [{ type: 'commander_event' }]],
      ['card', [{}]],
      ['desk', [['a1'], false]],
      ['desk', [[], true]],
      ['swarms', [{ active: 't1', swarms: [], tiles: [] }]],
      ['swarms', [null]],
      ['swarmCards', [[{ id: 't1' }]]],
      ['swarmCards', [[]]],
      ['swarmCardRecap', [{ tabId: 't1' }]],
      ['swarmCardRecap', [{}]],
      ['unread', [[{ agentId: 'a1' }]]],
      ['unread', [[]]],
      ['appFocus', ['m1', 'a1']],
      ['seen', ['a1', 'tok']],
      ['seen', ['a1', undefined]],
      ['settings', ['usb', { brightness: 3 }]],
      ['settings', ['usb', {}]],
      ['windowFocus', [focus]],
      ['windowFocus', [{ voice: { machineId: '', agentId: '', connId: 'w2' }, form: null }]],
      ['windowReply', ['form', 'w1', 'm1', { ok: true }]],
      ['windowReply', ['visit', 'w1', 'm1', {}]],
      ['windowReply', ['selection', 'w1', 'm1', {}]],
      ['voiceReply', ['v1', { t: 'taken' }]],
      ['windowGone', ['w1']],
      ['scroll', ['move', 2, 0]],
      ['engines', [['claude']]],
      ['commanders', [true]],
    ])
  })

  it('is everything the windows said at once when the devices connect, and nothing they did not', () => {
    const f = setup()
    f.event({ kind: 'state', desk: ['a1'], foreground: true, swarms: { active: 't1', swarms: [], tiles: [] }, unread: [{ agentId: 'a1' }], focus: null, engines: ['codex'], commanders: true })
    expect(f.calls).toEqual([
      ['desk', [['a1'], true]],
      ['swarms', [{ active: 't1', swarms: [], tiles: [] }]],
      ['unread', [[{ agentId: 'a1' }]]],
      ['windowFocus', [{ voice: null, form: null }]],
      ['engines', [['codex']]],
      ['commanders', [true]],
    ])
    // No window yet: the dial is told nothing about one.
    f.calls.length = 0
    f.event({ kind: 'state', desk: [], swarms: null, unread: 'nonsense' })
    expect(f.calls.map(([name]) => name)).toEqual(['windowFocus', 'engines', 'commanders'])
  })
})

describe('what the core asks of the devices', () => {
  it('is ⌘K and the Wi-Fi device\'s step, answered from the devices\' port', async () => {
    const f = setup()
    const asker = { local: true, owner: true }
    const { requests } = f.options()
    expect(await requests.routeTask({ text: 'fix it' }, asker)).toMatchObject({ agentId: 'a1', reason: 'fix it' })
    expect(await requests.routeTask({}, asker)).toMatchObject({ reason: '' })
    expect(await requests.routeSend({ agentId: 'a1', text: 'go' }, asker)).toEqual({ ok: true })
    expect(f.port.routeSend).toHaveBeenCalledWith('a1', 'go')
    expect(await requests.stepFocus({ direction: 'previous', currentAgentId: 'a1' }, asker)).toEqual({ machineId: 'm1', agentId: 'a2' })
    expect(f.port.stepFocus).toHaveBeenLastCalledWith('previous', 'a1')
    f.port.stepFocus.mockResolvedValueOnce('no_agents')
    expect(await requests.stepFocus({ direction: 'sideways', currentAgentId: 7 }, asker)).toEqual({ step: 'no_agents' })
    expect(f.port.stepFocus).toHaveBeenLastCalledWith('next', undefined)
    expect(await requests.harness_devices_list({}, asker)).toEqual({ protocol: 1 })
  })
})