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.

10.3 KB
Raw Blame
/**
 * The Wi-Fi device (lib/autonomous-device/, docs/autonomous-device-integration.md): a paired device that
 * speaks its own protocol over an E2EE session the gateway holds. Its service, its Store preparations and
 * its relay run here, with the dials in the devices' process (step 9, D3), on `CoreApi` alone: a fault in
 * it costs the devices, never a session (docs/design/2026-10-06-core-boundary-next.md).
 *
 * What the service reads in line while it answers (the agents, the Store's evidence on them, whether a
 * window is there) is the core's answer to `view`, asked again before each request and each move of the
 * window's focus, so what it answers is as fresh as when it ran in the core. What the core reads in line
 * of it (which devices said hello, which transcripts and streams it follows, the focus revision) it is
 * told before anything that depends on it leaves here (core/wifi.ts).
 */
import { join } from 'node:path'
import type { CoreApi, CorePorts, RemoteClient, WifiPort, WifiView } from '../core/api.js'
import { startDevicePart } from '../lib/autonomous-device/parts.js'
import { deviceRelayOverGateway } from '../lib/autonomous-device/overGateway.js'
import { DeviceResultJournal } from '../lib/autonomous-device/resultJournal.js'
import { AutonomousDeviceService, type AutonomousDeviceFrame } from '../lib/autonomous-device/service.js'
import { DeviceAddonError } from '../lib/autonomous-device/addons.js'
import { createDeviceStore } from '../lib/autonomous-device/storeRuntime.js'

export { WIFI_FALLBACKS } from '../core/api.js'

export interface WifiDeps {
  /** Swapped in tests, to reach what the service and the Store are given. */
  service?: (options: ConstructorParameters<typeof AutonomousDeviceService>[0]) => AutonomousDeviceService
  store?: typeof createDeviceStore
}

const same = (a: readonly string[], b: readonly string[]): boolean => a.length === b.length && a.every((item, i) => item === b[i])

export function startWifi(core: CoreApi, ports: CorePorts, deps: WifiDeps = {}): void {
  const machineId = core.machine.id()
  let view: WifiView = { agents: [], store: [], hasWindow: false }
  /** One ask of the core at a time: requests arriving together share it, and are answered in order. */
  let viewing: Promise<void> | null = null
  const refresh = (): Promise<void> => {
    viewing ??= core.wifi.view()
      .then((next) => { view = next })
      .catch(() => { /* the core went away: the next ask is answered by its next connection */ })
      .finally(() => { viewing = null })
    return viewing
  }

  /** The device sessions the gateway holds, as the core said. */
  const sessions = new Map<string, RemoteClient>()
  /** A summary card's whole answer, while the service reads it. */
  let fullText: string | undefined
  /** How many of an agent's prompts the core told of: the core stops sending its lines as of the count. */
  const seen = new Map<string, number>()
  let streamed: string[] = []

  const store = (deps.store ?? createDeviceStore)({
    dataDir: core.dataDir, machineId,
    agents: () => view.store,
    create: (packageId, engine, cwd) => core.wifi.create(packageId, engine, cwd),
    reveal: (operationId, agentId) => core.wifi.reveal(operationId, agentId),
  })

  // Built before the relay that speaks for it; a journal that does not parse leaves the Wi-Fi device off,
  // and the devices on (lib/autonomous-device/parts.ts says why).
  const build = deps.service ?? ((options) => new AutonomousDeviceService(options))
  const service = startDevicePart('Wi-Fi device service', () => build({
    store,
    resultJournal: new DeviceResultJournal(join(core.dataDir, 'device-results.json')),
    inputConsumed: (agentId, text) => core.wifi.started(agentId, text),
    machineId,
    requestAppFocus: (agentId, expiresAt, focusRevision) => core.wifi.focusApp(agentId, expiresAt, focusRevision),
    stepFocus: (direction, currentAgentId) => core.wifi.stepFocus(direction, currentAgentId),
    scroll: (phase, dy, velocity) => core.wifi.scroll(phase, dy, velocity),
    agents: () => view.agents,
    submit: (agentId, text, deliveryId) => core.wifi.submit(agentId, text, deliveryId),
    // Told, not asked: the one caller (an unpairing) goes on whatever the answer.
    cancelDelivery: (deliveryId) => { core.wifi.cancel(deliveryId); return true },
    stop: (agentId) => core.wifi.stop(agentId),
    answer: (agentId, requestId, answers) => core.wifi.answer(agentId, requestId, answers),
    recent: (agentId, n) => core.turns.recent(agentId, n),
    fullText: () => fullText,
    emit: (frame, deviceId) => emit(frame, deviceId),
  }))
  if (!service) throw new Error('the Wi-Fi device service could not be started')

  /** Which streams and which transcripts it follows, told to the core as they change. */
  const reportStreams = (): void => {
    const now = service.streamedAgents().sort()
    if (same(now, streamed)) return
    streamed = now
    core.wifi.streams(now)
  }
  const reportTranscript = (agentId: string): void => {
    if (!service.watchesTranscript(agentId)) core.wifi.transcripts(agentId, seen.get(agentId) ?? 0)
  }

  const relay = deviceRelayOverGateway({
    client: (connId) => sessions.get(connId),
    // Only to a session it found here (`client` above): the core checks it is still that identity's.
    send: (connId, type, payload) => {
      // A subscription's answer leaves after the core knows to send its agent's tool events.
      reportStreams()
      core.wifi.send(connId, sessions.get(connId)!.identity, type, payload)
    },
    service, machineId,
    onReady: () => core.wifi.joined(),
    onRemoteRevoke: (identity) => core.wifi.unpaired(identity),
    onClient: (connId, identity) => core.wifi.hello(connId, identity),
  })
  function emit(frame: AutonomousDeviceFrame, deviceId?: string): void {
    // The revision a window's delayed selection is checked against, before anything that carries it.
    if (frame.kind === 'focus.changed') {
      const revision = (frame.payload as { focusRevision?: unknown } | undefined)?.focusRevision
      if (typeof revision === 'string') core.wifi.focus(revision)
    }
    relay.emit(frame, deviceId)
  }

  /** The window's focus moves in the order the windows moved it, each against the agents as they are. */
  let focusing: Promise<void> = Promise.resolve()

  const port: WifiPort = {
    session: (connId, client) => {
      if (client) sessions.set(connId, client)
      else sessions.delete(connId)
    },
    // Answered against the agents as they are now; taken (the relay opens it before its first wait) before
    // anything the core says after it, as it was in the core's process.
    request: async (connId, frame, opened) => {
      await refresh()
      // Answered on its own time; one that fails is that request's, said, and the next is answered.
      relay.handle(connId, frame, opened).catch((error: unknown) => {
        console.warn(`[wifi] a device's request failed · ${error instanceof Error ? error.message : String(error)}`)
      })
    },
    dropped: (connId) => relay.drop(connId),
    revoked: (identity) => relay.revoke(identity),
    resume: async ({ sessions: held, helloed, focus }) => {
      sessions.clear()
      for (const { connId, client } of held) sessions.set(connId, client)
      // A session this run served that the core no longer holds (the core restarted, and the relay with it).
      const kept = new Set(helloed.map(({ connId }) => connId))
      for (const connId of relay.helloed()) if (!kept.has(connId)) relay.drop(connId)
      // The core starts over from what this run follows (it has forgotten, or never knew).
      seen.clear()
      core.wifi.watching(service.transcriptWatches())
      streamed = service.streamedAgents().sort()
      core.wifi.streams(streamed)
      core.wifi.focus(service.focusSnapshot().focusRevision)
      if (focus) port.appFocus(focus.machineId, focus.agentId, focus.connId).catch(() => { /* said by the move itself */ })
      await refresh()
      for (const { connId, identity } of helloed) relay.restore(connId, identity)
      if (helloed.length) core.wifi.joined()
      core.wifi.ready()
    },
    card: (frame, text) => {
      fullText = text
      try { service.commander(frame) } finally { fullText = undefined }
    },
    turnStarted: (agentId) => service.turnStarted(agentId),
    turnEnded: (agentId, aborted) => service.turnEnded(agentId, aborted),
    stream: (agentId, events) => service.stream(agentId, events),
    transcript: (agentId, sessionId, engine, line) => {
      service.observeTranscript(agentId, sessionId, engine, line)
      reportTranscript(agentId)
    },
    delivery: (event) => service.delivery(event),
    dispatched: (agentId, deliveryId, text, sessionId) => {
      seen.set(agentId, (seen.get(agentId) ?? 0) + 1)
      service.inputDispatched(agentId, deliveryId, text, sessionId)
      reportTranscript(agentId)
    },
    inputStatus: (event) => service.inputStatus(event),
    agentGone: (agentId) => {
      service.agentGone(agentId)
      reportTranscript(agentId)
    },
    appFocus: (machineId, agentId, connId) => {
      const moved = focusing.then(refresh).then(() => service.appFocus(machineId, agentId, connId))
      // A move that fails is that move's: the next waits for it, not on it.
      focusing = moved.catch(() => {})
      return moved
    },
    revealed: (operationId, agentId) => store.acknowledgeReveal(operationId, agentId),
    receipt: async (deviceId, idempotencyKey) => ({ receipt: service.receipt(deviceId, idempotencyKey) }),
    addon: async (op, input) => {
      try {
        if (op === 'state') return { result: { devices: service.addons.state(typeof input.deviceId === 'string' ? input.deviceId : undefined) } }
        if (op === 'propose') return { result: { proposal: service.addons.propose(input) } }
        const proposal = service.addons.proposal(typeof input.proposalId === 'string' ? input.proposalId : '')
        // Never sent, or aged out: said as such, so a script can tell it from a proposal.
        if (!proposal) return { error: { code: 'PROPOSAL_UNKNOWN', message: 'No such proposal: never sent, or aged out after ten minutes' } }
        return { result: { proposal } }
      } catch (error) {
        if (error instanceof DeviceAddonError) return { error: { code: error.code, message: error.message } }
        throw error
      }
    },
    stop: async () => store.stopUiDelivery(),
  }
  store.startUiDelivery()
  ports.wifi = port
}