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.

16.8 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { LiveEvent } from '../lib/normalize.js'
import { WIFI_OFF, type RemoteClient, type WifiPort } from './api.js'
import { createWifiCore, WIFI_HELD_MAX, WIFI_HELD_MS } from './wifi.js'

const device = (identity: string, direct = false): RemoteClient => ({ role: 'device', label: 'Desk', identity, direct })

function harness() {
  const port = {
    session: vi.fn(), request: vi.fn(async () => {}), dropped: vi.fn(), revoked: vi.fn(), resume: vi.fn(async () => {}), card: vi.fn(),
    turnStarted: vi.fn(), turnEnded: vi.fn(), stream: vi.fn(), transcript: vi.fn(), delivery: vi.fn(), dispatched: vi.fn(),
    inputStatus: vi.fn(), agentGone: vi.fn(), appFocus: vi.fn(async () => {}), revealed: vi.fn(), receipt: vi.fn(), addon: vi.fn(), stop: vi.fn(),
  } satisfies WifiPort
  let on: WifiPort | null = port
  const clients = new Map<string, RemoteClient>()
  const gateway = { device: vi.fn(), deviceClient: vi.fn(), revokeIdentity: vi.fn() }
  const joined = vi.fn()
  const ready = vi.fn()
  const fullText = vi.fn((agentId: string) => (agentId === 'a' ? 'the whole answer' : undefined))
  const want = vi.fn(() => true)
  const wifi = createWifiCore({ port: () => on, gateway, remoteClient: (connId) => clients.get(connId) ?? null, fullText, joined, ready, want, doors: WIFI_OFF })
  return { wifi, port, clients, gateway, joined, ready, fullText, want, off: () => { on = null }, on: () => { on = port } }
}
/** What `started` hands on after the service was resumed, a few promise turns later. */
const settled = async (): Promise<void> => { for (let i = 0; i < 4; i++) await Promise.resolve() }

describe('the Wi-Fi device, as the core keeps it', () => {
  it('counts a device as watching only while its app said hello on a session still its own, with the service there', () => {
    const { wifi, clients, gateway } = harness()
    clients.set('c1', device('id-1', true))
    clients.set('c2', device('id-2'))
    wifi.api.hello('c1', 'id-1')
    wifi.api.hello('c2', 'id-2')
    expect(gateway.deviceClient).toHaveBeenCalledWith('c1', 'id-1')
    // No service yet: nobody is served, so nobody watches.
    expect(wifi.connected()).toBe(false)
    wifi.started(null)
    expect(wifi.connected()).toBe(true)
    expect(wifi.directSessions()).toBe(1)
    // A session that became another identity's, or a phone's, is not the device that said hello.
    clients.set('c2', { ...device('id-3') })
    clients.set('c1', { ...device('id-1', true), role: 'web' })
    expect(wifi.connected()).toBe(false)
    clients.set('c1', device('id-1', true))
    wifi.api.hello('c1', null)
    expect(gateway.deviceClient).toHaveBeenLastCalledWith('c1', null)
    expect(wifi.connected()).toBe(false)
    wifi.stopped()
    expect(wifi.directSessions()).toBe(0)
  })

  it('seals an answer to a session only while it is still the identity\'s device', () => {
    const { wifi, clients, gateway } = harness()
    clients.set('c1', device('id-1'))
    wifi.api.send('c1', 'id-1', 'autonomous_device_result', { ok: true })
    wifi.api.send('c1', 'id-2', 'autonomous_device_result', { stolen: true })
    wifi.api.send('gone', 'id-1', 'autonomous_device_result', {})
    expect(gateway.device).toHaveBeenCalledTimes(1)
    expect(gateway.device).toHaveBeenCalledWith('c1', 'autonomous_device_result', { ok: true })
  })

  it('passes on the doors, a hello\'s join, its readiness and an unpairing the device asked for', () => {
    const { wifi, gateway, joined, ready } = harness()
    expect(wifi.api.view).toBe(WIFI_OFF.view)
    wifi.api.joined()
    expect(joined).toHaveBeenCalled()
    wifi.api.ready()
    expect(ready).toHaveBeenCalled()
    wifi.api.unpaired('id-1')
    expect(gateway.revokeIdentity).toHaveBeenCalledWith('id-1')
  })

  it('sends an agent\'s transcript lines from its prompt\'s dispatch until the service is done with it as of its last prompt', () => {
    const { wifi, port } = harness()
    expect(wifi.feed.needsTranscript('a', 's', 'claude')).toBe(false)
    wifi.started(null)
    wifi.feed.inputDispatched('a', 'd1', 'hi', 's')
    expect(port.dispatched).toHaveBeenCalledWith('a', 'd1', 'hi', 's')
    // Before the service could ask for it: the prompt's first lines may come at once.
    expect(wifi.feed.needsTranscript('a', 's', 'claude')).toBe(true)
    expect(wifi.feed.needsTranscript('a', 's', 'codex')).toBe(true)
    // Only the engines whose transcripts prove a turn.
    expect(wifi.feed.needsTranscript('a', 's', 'cursor')).toBe(false)
    wifi.feed.observeTranscript('a', 's', 'claude', '{"line":1}')
    expect(port.transcript).toHaveBeenCalledWith('a', 's', 'claude', '{"line":1}')
    // A second prompt the service has not heard of yet: its "done as of the first" leaves it watched.
    wifi.feed.inputDispatched('a', 'd2', 'again', 's')
    wifi.api.transcripts('a', 1)
    expect(wifi.feed.needsTranscript('a', 's', 'claude')).toBe(true)
    wifi.api.transcripts('a', 2)
    expect(wifi.feed.needsTranscript('a', 's', 'claude')).toBe(false)
    // An agent it was never told of.
    wifi.api.transcripts('b', 0)
    expect(wifi.feed.needsTranscript('b', 's', 'claude')).toBe(false)
  })

  it('takes the service\'s own list as it starts, and forgets the counts the last one heard', () => {
    const { wifi } = harness()
    wifi.started(null)
    wifi.feed.inputDispatched('a', 'd1', 'hi')
    wifi.api.watching(['b'])
    expect(wifi.feed.needsTranscript('a', 's', 'claude')).toBe(false)
    expect(wifi.feed.needsTranscript('b', 's', 'claude')).toBe(true)
    wifi.api.transcripts('b', 0)
    expect(wifi.feed.needsTranscript('b', 's', 'claude')).toBe(false)
  })

  it('streams the answer\'s text always and a tool\'s events only for a subscribed agent, and nothing with the service away', () => {
    const { wifi, port } = harness()
    const events = [
      { type: 'turn_started', payload: {} }, { type: 'text_delta', payload: { content: 'hi' } },
      { type: 'tool_start', payload: { id: 't', tool: 'Read', input: {} } }, { type: 'tool_end', payload: { id: 't', tool: 'Read', isError: false } },
      { type: 'thinking_delta', payload: {} }, { type: 'turn_ended', payload: {} },
    ] as unknown as LiveEvent[]
    wifi.feed.stream('a', events)
    expect(port.stream).not.toHaveBeenCalled()
    wifi.started(null)
    wifi.feed.stream('a', events)
    expect(port.stream).toHaveBeenLastCalledWith('a', [events[0], events[1], events[5]])
    wifi.api.streams(['a'])
    wifi.feed.stream('a', events)
    expect(port.stream).toHaveBeenLastCalledWith('a', [events[0], events[1], events[2], events[3], events[5]])
    port.stream.mockClear()
    wifi.feed.stream('a', [events[4]])
    expect(port.stream).not.toHaveBeenCalled()
  })

  it('passes what the agents do and the panes say on to the service, and nothing when it is off', () => {
    const { wifi, port, off } = harness()
    wifi.feed.delivery({ deliveryId: 'd', sessionId: 'a', state: 'delivered' })
    wifi.feed.inputStatus({ deliveryId: 'd', sessionId: 'a', mode: 'queued', phase: 'waiting' } as never)
    wifi.feed.agentGone('a')
    wifi.feed.turnStarted('a')
    wifi.feed.turnEnded('a')
    wifi.feed.turnEnded('b', true)
    expect(port.delivery).toHaveBeenCalledWith({ deliveryId: 'd', sessionId: 'a', state: 'delivered' })
    expect(port.inputStatus).toHaveBeenCalled()
    expect(port.agentGone).toHaveBeenCalledWith('a')
    expect(port.turnStarted).toHaveBeenCalledWith('a')
    expect(port.turnEnded).toHaveBeenCalledWith('a', false)
    expect(port.turnEnded).toHaveBeenCalledWith('b', true)
    off()
    for (const call of [() => wifi.feed.delivery({ deliveryId: 'd', sessionId: 'a', state: 'delivered' }), () => wifi.feed.agentGone('a'),
      () => wifi.feed.observeTranscript('a', 's', 'claude', 'x'), () => wifi.feed.inputDispatched('a', 'd', 't'),
      () => wifi.feed.inputStatus({} as never), () => wifi.feed.turnStarted('a'), () => wifi.feed.turnEnded('a'),
      () => wifi.card({ type: 'commander_event' }), () => wifi.fromGateway.request('c', {}, null), () => wifi.fromGateway.revoked('i'),
      () => wifi.fromGateway.dropped('c'), () => wifi.fromGateway.session('c', device('i')), () => wifi.started(null)]) expect(call()).toBeUndefined()
    wifi.api.streams(['a'])
    expect(wifi.feed.stream('a', [{ type: 'text_delta', payload: { content: 'x' } } as unknown as LiveEvent])).toBeUndefined()
  })

  it('hands a summary card its turn\'s whole answer, and any other card as it is', () => {
    const { wifi, port, fullText } = harness()
    const summary = { type: 'commander_event', agentId: 'a', payload: { kind: 'summary', text: 'short' } }
    wifi.card(summary)
    expect(port.card).toHaveBeenLastCalledWith(summary, 'the whole answer')
    const tool = { type: 'commander_event', agentId: 'a', payload: { kind: 'tool' } }
    wifi.card(tool)
    expect(port.card).toHaveBeenLastCalledWith(tool, undefined)
    wifi.card({ type: 'commander_question', agentId: 'a' })
    wifi.card({ type: 'commander_event', payload: { kind: 'summary' } })
    expect(fullText).toHaveBeenCalledTimes(1)
  })

  it('passes the gateway\'s device sessions on, and forgets a phone\'s', async () => {
    const { wifi, port, gateway } = harness()
    wifi.started(null)
    await settled()
    wifi.fromGateway.session('phone', { role: 'web', label: null, identity: 'p', direct: false })
    wifi.fromGateway.session('phone', null)
    expect(port.session).not.toHaveBeenCalled()
    wifi.fromGateway.session('c1', device('id-1'))
    expect(port.session).toHaveBeenCalledWith('c1', device('id-1'))
    // A device session that became something else is gone, as far as the service knows.
    wifi.fromGateway.session('c1', { role: 'web', label: null, identity: 'p', direct: false })
    expect(port.session).toHaveBeenLastCalledWith('c1', null)
    wifi.fromGateway.session('c1', device('id-1'))
    wifi.fromGateway.session('c1', null)
    expect(port.session).toHaveBeenLastCalledWith('c1', null)
    wifi.fromGateway.request('c1', { type: 'autonomous_device_request' }, { payload: {} })
    expect(port.request).toHaveBeenCalledWith('c1', { type: 'autonomous_device_request' }, { payload: {} })
    // A connection that closed: forgotten here and told to the gateway, said or not by the service.
    wifi.api.hello('c1', 'id-1')
    gateway.deviceClient.mockClear()
    wifi.fromGateway.dropped('c1')
    expect(gateway.deviceClient).toHaveBeenCalledWith('c1', null)
    expect(port.dropped).toHaveBeenCalledWith('c1')
    gateway.deviceClient.mockClear()
    wifi.fromGateway.dropped('c1')
    expect(gateway.deviceClient).not.toHaveBeenCalled()
  })

  it('forgets an unpaired identity\'s sessions and tells the service', () => {
    const { wifi, port, clients } = harness()
    clients.set('c1', device('id-1'))
    clients.set('c2', device('id-2'))
    wifi.api.hello('c1', 'id-1')
    wifi.api.hello('c2', 'id-2')
    wifi.started(null)
    wifi.fromGateway.revoked('id-1')
    expect(port.revoked).toHaveBeenCalledWith('id-1')
    expect(wifi.connected()).toBe(true)
    wifi.fromGateway.revoked('id-2')
    expect(wifi.connected()).toBe(false)
  })

  it('hands a starting service what it holds: the sessions, those still the device that said hello, and the window\'s focus', () => {
    const { wifi, port, clients, gateway } = harness()
    clients.set('c1', device('id-1'))
    clients.set('c2', device('id-2'))
    wifi.fromGateway.session('c1', device('id-1'))
    wifi.fromGateway.session('c2', device('id-2'))
    wifi.api.hello('c1', 'id-1')
    wifi.api.hello('c2', 'id-2')
    // c2's session went to another identity while the service was away: not handed back as id-2's.
    clients.set('c2', device('id-9'))
    wifi.api.focus('old')
    wifi.started({ machineId: 'm', agentId: 'a', connId: 'w' })
    expect(gateway.deviceClient).toHaveBeenCalledWith('c2', null)
    expect(port.resume).toHaveBeenCalledWith({
      sessions: [{ connId: 'c1', client: device('id-1') }, { connId: 'c2', client: device('id-2') }],
      helloed: [{ connId: 'c1', identity: 'id-1' }],
      focus: { machineId: 'm', agentId: 'a', connId: 'w' },
    })
    // The revision is the new service's to say.
    expect(wifi.focusRevision()).toBeUndefined()
    wifi.api.focus('r1')
    expect(wifi.focusRevision()).toBe('r1')
    wifi.stopped()
    expect(wifi.focusRevision()).toBeUndefined()
  })
})

describe('the Wi-Fi device while its service is not there', () => {
  afterEach(() => { vi.useRealTimers() })
  const hello = { type: 'autonomous_device_request' }

  it('asks for its process when a device\'s session comes, and not for a phone\'s or once it is there', async () => {
    const { wifi, want } = harness()
    wifi.fromGateway.session('phone', { role: 'web', label: null, identity: 'p', direct: false })
    wifi.fromGateway.session('c1', null)
    expect(want).not.toHaveBeenCalled()
    wifi.fromGateway.session('c1', device('id-1'))
    expect(want).toHaveBeenCalledTimes(1)
    wifi.started(null)
    wifi.fromGateway.session('c2', device('id-2'))
    expect(want).toHaveBeenCalledTimes(1)
  })

  it('holds what its devices send, asks for it, and hands it on in order once the service has been resumed', async () => {
    const { wifi, port, want } = harness()
    wifi.fromGateway.session('c1', device('id-1'))
    wifi.fromGateway.request('c1', hello, { payload: { n: 1 } })
    wifi.fromGateway.request('c1', hello, { payload: { n: 2 } })
    expect(port.request).not.toHaveBeenCalled()
    expect(want).toHaveBeenCalledTimes(3)
    wifi.started(null)
    // Not before the resume has been said: a request for a session the service has not been handed is lost.
    wifi.fromGateway.request('c1', hello, { payload: { n: 3 } })
    expect(port.request).not.toHaveBeenCalled()
    await settled()
    expect(port.resume).toHaveBeenCalledTimes(1)
    expect(port.request.mock.calls.map((call) => ((call as unknown[])[2] as { payload: { n: number } }).payload.n)).toEqual([1, 2, 3])
    expect(port.resume.mock.invocationCallOrder[0]).toBeLessThan(port.request.mock.invocationCallOrder[0])
    // From then on, straight through; and held again while the service is away (its process starting again).
    wifi.fromGateway.request('c1', hello, { payload: { n: 4 } })
    expect(port.request).toHaveBeenCalledTimes(4)
    wifi.stopped()
    wifi.fromGateway.request('c1', hello, { payload: { n: 5 } })
    expect(port.request).toHaveBeenCalledTimes(4)
    wifi.started(null)
    await settled()
    expect(port.request).toHaveBeenCalledTimes(5)
  })

  it('hands on a request held only as long as its device would wait for it, and holds a bounded number', async () => {
    vi.useFakeTimers()
    const { wifi, port } = harness()
    const sent = (): number[] => port.request.mock.calls.map((call) => ((call as unknown[])[2] as { payload: { n: number } }).payload.n)
    wifi.fromGateway.request('c1', hello, { payload: { n: 0 } })
    vi.advanceTimersByTime(WIFI_HELD_MS + 1)
    wifi.fromGateway.request('c1', hello, { payload: { n: 1 } })
    wifi.started(null)
    await settled()
    // The stale one is dropped: the device retried it by its key, or gave up on it.
    expect(sent()).toEqual([1])
    const bounded = harness()
    for (let n = 0; n <= WIFI_HELD_MAX; n++) bounded.wifi.fromGateway.request('c1', hello, { payload: { n } })
    bounded.wifi.started(null)
    await settled()
    const kept = bounded.port.request.mock.calls.map((call) => ((call as unknown[])[2] as { payload: { n: number } }).payload.n)
    // The oldest beyond the bound goes first.
    expect(kept).toHaveLength(WIFI_HELD_MAX)
    expect(kept[0]).toBe(1)
  })

  it('keeps holding while the service went before it was handed what it held or has no port, and hands it on after a failed resume', async () => {
    const { wifi, port, off, on } = harness()
    wifi.fromGateway.request('c1', hello, { payload: { n: 1 } })
    wifi.started(null)
    wifi.stopped()
    await settled()
    expect(port.request).not.toHaveBeenCalled()
    off()
    wifi.started(null)
    await settled()
    on()
    port.resume.mockRejectedValueOnce(new Error('gone'))
    wifi.started(null)
    await settled()
    expect(port.request).toHaveBeenCalledTimes(1)
  })

  it('waits for the service to serve, asking for it, before a pairing goes through the direct links', async () => {
    vi.useFakeTimers()
    const { wifi, want, ready } = harness()
    const served = wifi.serving(1_000)
    expect(want).toHaveBeenCalledTimes(1)
    wifi.started(null)
    wifi.api.ready()
    expect(ready).toHaveBeenCalled()
    await expect(served).resolves.toBe(true)
    // Serving now: at once, without asking.
    await expect(wifi.serving(1_000)).resolves.toBe(true)
    expect(want).toHaveBeenCalledTimes(1)
    // Gone again: asked for, and not there in time.
    wifi.stopped()
    const late = wifi.serving(1_000)
    vi.advanceTimersByTime(1_001)
    await expect(late).resolves.toBe(false)
    wifi.api.ready()
    // In the core's process, with nothing to ask for: not waited on.
    wifi.stopped()
    want.mockReturnValueOnce(false)
    await expect(wifi.serving(1_000)).resolves.toBe(false)
  })
})