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.4 KB
Raw Blame
/**
 * The devices in a process of their own (`harness __service devices`, harnessd/services.ts): the dials on
 * this computer's USB ports, the window bridges they speak through, the fleet's router and its lane to the
 * owner's other machines, the voice router and the Devices tab (services/devices.ts), on a link to the core
 * (docs/design/2026-10-06-core-boundary-next.md, step 9, D2).
 *
 * A device is hardware speaking whatever its firmware says, a lane to the backend and a voice router's
 * engine worker: here a device that hangs the event loop, leaks or crashes costs the devices, and the
 * master starts them again, while every agent and window goes on. The serial ports are this process's,
 * one owner each (`O_EXLOCK`, cable/serial.ts).
 *
 * It runs on a core API of its own, over its link (core/devicesLink.ts): what the dial reads in line while
 * it builds a frame (this computer's agents, their names and models, this computer, the sign-in, whether a
 * window is there) is the core's answer to `view`, asked again as the dial's tick or ⌘K builds a list;
 * everything else is asked of the core when it is needed, or told to it. The core keeps what the windows
 * said and tells it again each time this process connects.
 */
import type { BackendNotice } from '../core/api.js'
import { env } from '../config/env.js'
import type { AppSwarms } from '../cable/cableSession.js'
import type { LeadRecap, SwarmCard } from '../superTabs/cards.js'
import type { RecentTurn } from '../cable/cableHost.js'
import type { UnreadNotification } from '../lib/notificationRead.js'
import { validUsage } from '../lib/agentUsageWire.js'
import { AGENT_ACTIONS_OFF, DAEMON_UNKNOWN, DELIVERIES_OFF, emptyPorts, resolveAgent, TERMINALS_OFF, type CoreApi, type CorePorts, type DevicesPort, type ForkResult, type ServiceRequests, type VoiceRouteReply, type WindowFocus } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
import type { RuntimeModelOption } from '../lib/runtimeProfile.js'
import { accountLink } from './accountLink.js'
import { startDevices, type DevicesDeps } from './devices.js'
import { runServiceProcess, type CoreConnection, type ServiceProcess, type ServiceProcessOptions } from './process.js'
import { processCoreApi, UNASKED } from './processCoreApi.js'
import { harnessdEnv } from '../lib/harnessdEnv.js'

/** An agent as the core lists it for the dial: with the name the apps show and the model it runs. */
type Viewed = RegisteredSession & { displayName?: string; runtimeProfile?: string | null }

/** What the core last said of this computer: what the dial reads in line. */
interface View {
  agents: Viewed[]
  machine: { id: string; computerId: string; name: string }
  signedIn: boolean
  environment: string
  hasWindow: boolean
}

export interface DevicesServiceOptions {
  dataDir: string
  socketPath: string
  machineId: string
  token: string
  /** For this service's tests: its start and its link. */
  start?: typeof startDevices
  run?: (options: ServiceProcessOptions) => ServiceProcess
  processEnv?: NodeJS.ProcessEnv
}

const text = (value: unknown): string => (typeof value === 'string' ? value : '')
const strings = (value: unknown): string[] => (Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [])
const object = (value: unknown): Record<string, unknown> => (value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {})
const number = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0)

/** The window that has the person's attention, as the core sent it; nothing for anything else. */
function focusOf(value: unknown): WindowFocus {
  const focus = object(value)
  const voice = object(focus.voice)
  const form = object(focus.form)
  return {
    voice: voice.connId ? { machineId: text(voice.machineId), agentId: text(voice.agentId), connId: text(voice.connId) } : null,
    form: form.connId ? { machineId: text(form.machineId), connId: text(form.connId) } : null,
  }
}

/** `HARNESSD_TEST_FAULTS`, as the devices read it for their own parts (services/devicesGuard.ts). */
function faultsOf(value: string | undefined): ReadonlySet<string> {
  return new Set((value ?? '').split(',').map((entry) => entry.trim()).filter(Boolean))
}

export function runDevicesService(options: DevicesServiceOptions): ServiceProcess {
  const processEnv = options.processEnv ?? harnessdEnv()
  let core: CoreConnection | null = null
  /** Whether a dial watches, as the cable last said: told again to every core this process connects to.
   *  A dial says hello as soon as its port opens, which is often before a core that just started has
   *  this process connected (2026-10-09, a user's log: hello 14:22:54.141, connected 14:22:54.525). Told
   *  only then, the notice was lost: the core made no cards for the dial, which showed Working for turns
   *  that had ended, and no recaps, until the next restart. */
  let dialWatching = false
  let view: View = { agents: [], machine: { id: '', computerId: options.machineId, name: 'This machine' }, signedIn: false, environment: '', hasWindow: false }
  /** One ask of the core's view at a time: the dial's tick and ⌘K asking together share it. */
  let viewing: Promise<void> | null = null
  const refresh = (): Promise<void> => {
    if (viewing) return viewing
    if (!core) return Promise.resolve()
    const asking = core.query('view').then((answer) => {
      if (!Array.isArray(answer.agents)) return
      const machine = object(answer.machine)
      view = {
        agents: answer.agents as Viewed[],
        machine: { id: text(machine.id), computerId: text(machine.computerId) || options.machineId, name: text(machine.name) || 'This machine' },
        signedIn: answer.signedIn === true,
        environment: text(answer.environment),
        hasWindow: answer.hasWindow === true,
      }
    }).catch(() => { /* the core went away; its next connection is asked again */ }).finally(() => { viewing = null })
    viewing = asking
    return asking
  }
  /** What the devices say again to a core that connects (services/devices.ts `onCoreConnected`). */
  let coreConnected: (() => void) | undefined
  const ask = async (query: string, payload: Record<string, unknown> = {}): Promise<Record<string, unknown>> => {
    if (!core) throw new Error('the devices are not connected to the core')
    return core.query(query, payload)
  }
  const tell = (kind: string, payload: Record<string, unknown> = {}): void => { core?.notice?.(kind, payload) }

  // What the devices never ask of the core, answered as every service in its own process answers it.
  /** Who hears the account's notices in this process (the fleet), told them as the core forwards each. */
  const noticeListeners = new Set<(notice: BackendNotice) => void>()
  const unasked = processCoreApi(options.dataDir, 'devices')
  const account = accountLink((query, payload) => ask(query, payload))
  const api: CoreApi = {
    dataDir: options.dataDir,
    conversations: unasked.conversations,
    // Terminals are launched by the core alone (#893).
    terminals: TERMINALS_OFF,
    machine: { id: () => view.machine.id, computerId: () => view.machine.computerId, name: () => view.machine.name },
    agents: {
      all: () => view.agents,
      live: () => view.agents,
      advertised: () => view.agents,
      displayName: (session) => (session as Viewed).displayName ?? '',
      byAgent: (agentId) => view.agents.find((agent) => agent.agentId === agentId),
      resolve: (id) => resolveAgent(view.agents, id),
      terminalAvailable: () => true,
      sync: () => {},
      runtimeModels: async (agentId) => ((await ask('models', { agentId })).models ?? []) as RuntimeModelOption[],
      runtimeProfile: (session) => (session as Viewed).runtimeProfile ?? null,
      setRuntime: (agentId, model, effort) => tell('setRuntime', { agentId, model, effort }),
      fork: async (agentId) => {
        const { requestId: _id, ...result } = await ask('fork', { agentId })
        return result as unknown as ForkResult
      },
      activityText: async (agentId) => {
        const said = (await ask('activityText', { agentId })).text
        return typeof said === 'string' ? said : null
      },
      activitySnapshot: async (agentId) => {
        // A core that predates the query (or has no timer to give) still has the footer.
        const said = (await ask('activitySnapshot', { agentId }).catch((): Record<string, unknown> => ({}))).activity
        if (said && typeof said === 'object' && typeof (said as { text?: unknown }).text === 'string') return said as { text: string; elapsedSeconds?: number }
        const text = (await ask('activityText', { agentId })).text
        return typeof text === 'string' && text ? { text } : null
      },
      // Whether harnesses work is asked by Agent Messages alone.
      activity: UNASKED.activity,
      summaries: UNASKED.summaries,
      // The devices make no agent of their own and show no harness's viewer.
      ...AGENT_ACTIONS_OFF,
    },
    turns: {
      send: (agentId, said) => tell('turn', { agentId, text: said }),
      stop: (agentId) => tell('stop', { agentId }),
      recent: async (agentId, n) => ((await ask('recent', { agentId, n })).turns ?? []) as RecentTurn[],
      asks: async (agentId) => strings((await ask('asks', { agentId })).asks),
      // The devices deliver no turns of their own under an id: a dial's turn is `send`.
      ...DELIVERIES_OFF,
    },
    questions: {
      answer: (agentId, requestId, answers) => tell('answer', { agentId, requestId, answers }),
      answerReviewed: async (answer) => (await ask('answerReviewed', { answer })).ok === true,
    },
    transcripts: unasked.transcripts,
    account: {
      ...unasked.account,
      // The core's sign-in and the gateway's seal, asked at every use: this process holds no credential and
      // no E2EE identity (services/accountLink.ts).
      ...account,
      // The account's notices the core forwards (core/main.ts `onAccountNotice`): the fleet reads the machine list on
      // `machines_changed`, and only every 5 minutes otherwise (spec 2026-11-02 poll cost, Part 4.4).
      onNotice: (listener) => { noticeListeners.add(listener); return () => { noticeListeners.delete(listener) } },
      signedIn: () => view.signedIn,
      environment: () => view.environment,
      machines: async () => {
        const answer = await ask('machines')
        return { status: typeof answer.status === 'number' ? answer.status : 502, body: object(answer.body) }
      },
    },
    clients: {
      ...unasked.clients,
      sendLocal: (frame) => tell('sendLocal', { frame }),
      // Told, not asked: a bridge answers a window that has gone by its own deadline either way.
      sendToWindow: (connId, frame) => { tell('sendToWindow', { connId, frame }); return core !== null },
      hasWindow: () => view.hasWindow,
      devicesChanged: (payload) => tell('devicesChanged', payload),
      dialWatching: (watching) => {
        dialWatching = watching
        tell('dialWatching', { watching })
      },
      windows: () => {},
    },
    usageFresh: async (agentId) => {
      const usage = (await ask('usageFresh', { agentId }).catch((): Record<string, unknown> => ({}))).usage
      return validUsage(usage) ? usage : null
    },
    daemon: DAEMON_UNKNOWN,
    // The Swarm cards' requests to the Super Tab service, through the core (core/devicesLink.ts `super_tabs`).
    superTabRequest: (payload) => ask('super_tabs', payload).catch((): Record<string, unknown> => ({ error: 'SERVICE_UNAVAILABLE' })),
    // The Wi-Fi device beside the dials has a link of its own (services/wifiProcess.ts).
    wifi: unasked.wifi,
  }

  const ports: CorePorts = emptyPorts()
  const deps: DevicesDeps = {
    logsDir: env.HARNESS_LOGS_DIR,
    dialSerials: processEnv.HARNESS_DIAL_SERIALS?.split(',').map((serial) => serial.trim()).filter(Boolean),
    testDialPort: processEnv.HARNESSD_TEST_DIAL_PORT,
    cableDisabled: env.CABLE_DISABLE,
    faults: faultsOf(processEnv.HARNESSD_TEST_FAULTS),
    refresh,
    onCoreConnected: (run) => { coreConnected = run },
  }
  const requests = (options.start ?? startDevices)(api, ports, deps)
  const port = ports.devices as DevicesPort

  /** What the core tells the devices (`service_event`), by kind: the port's own calls, across the link. */
  const heard: Record<string, (payload: Record<string, unknown>) => void> = {
    notice: ({ notice }) => { if (notice && typeof notice === 'object') for (const listener of noticeListeners) listener(notice as BackendNotice) },
    card: ({ frame }) => port.card(object(frame)),
    desk: ({ agentIds, foreground }) => port.desk(strings(agentIds), foreground !== false),
    swarms: ({ swarms }) => port.swarms(swarms && typeof swarms === 'object' ? swarms as AppSwarms : null),
    swarmCards: ({ items }) => port.swarmCards(Array.isArray(items) ? items as SwarmCard[] : []),
    swarmCardRecap: ({ recap }) => port.swarmCardRecap(object(recap) as unknown as LeadRecap),
    unread: ({ items }) => port.unread(Array.isArray(items) ? items as UnreadNotification[] : []),
    appFocus: ({ machineId, agentId }) => port.appFocus(text(machineId), text(agentId)),
    seen: ({ agentId, readToken }) => port.seen(text(agentId), typeof readToken === 'string' ? readToken : undefined),
    settings: ({ id, patch }) => port.settings(text(id), object(patch)),
    windowFocus: ({ focus }) => port.windowFocus(focusOf(focus)),
    windowReply: ({ which, connId, machineId, reply }) =>
      port.windowReply(which === 'form' ? 'form' : which === 'visit' ? 'visit' : 'selection', text(connId), text(machineId), object(reply)),
    voiceReply: ({ voiceId, reply }) => port.voiceReply(text(voiceId), object(reply) as unknown as VoiceRouteReply),
    windowGone: ({ connId }) => port.windowGone(text(connId)),
    scroll: ({ phase, dy, velocity }) => { if (phase === 'down' || phase === 'move' || phase === 'up') port.scroll(phase, number(dy), number(velocity)) },
    engines: ({ engines }) => port.engines(strings(engines)),
    commanders: ({ connected }) => port.commanders(connected === true),
    // Everything at once, as the core keeps it: this process (re)connected, and starts where the windows are.
    // What a window has not said is not said to the dial: a fresh process holds nothing yet, and a dial still
    // attached through a core's restart keeps its tab until the windows, reconnecting, say theirs again.
    // Pushed regardless, an empty tab reached a dial still opening its port, before its greeting, which no
    // build before this one sent (e2e/deviceCompat.e2e.ts).
    state: (state) => {
      const desk = strings(state.desk)
      if (desk.length) port.desk(desk, state.foreground !== false)
      if (state.swarms && typeof state.swarms === 'object') port.swarms(state.swarms as AppSwarms)
      if (Array.isArray(state.unread) && state.unread.length) port.unread(state.unread as UnreadNotification[])
      port.windowFocus(focusOf(state.focus))
      port.engines(strings(state.engines))
      port.commanders(state.commanders === true)
    },
  }

  const devices: ServiceRequests = {
    ...requests,
    // What the core asks of the devices (core/devicesLink.ts), under types only the core sends: no client's
    // request is routed here under these names (core/serviceLinks.ts routes the Devices tab's alone).
    routeTask: async ({ text: task }) => ({ ...await port.routeTask(text(task)) }),
    routeSend: async ({ agentId, text: task }) => ({ ...await port.routeSend(text(agentId), text(task)) }),
    stepFocus: async ({ direction, currentAgentId }) => {
      const step = await port.stepFocus(direction === 'previous' ? 'previous' : 'next', typeof currentAgentId === 'string' ? currentAgentId : undefined)
      return step === 'no_agents' ? { step } : { ...step }
    },
  }

  const service = (options.run ?? runServiceProcess)({
    name: 'devices',
    socketPath: options.socketPath,
    machineId: options.machineId,
    token: options.token,
    requests: devices,
    onEvent: (payload) => {
      const kind = text(payload.kind)
      if (Object.hasOwn(heard, kind)) heard[kind](payload)
    },
    onConnected: (connection) => {
      core = connection
      coreConnected?.()
      if (dialWatching) tell('dialWatching', { watching: true })
      void refresh()
    },
    onDisconnected: () => { core = null },
  })
  return {
    stop: async () => {
      service.stop()
      // The serial ports first and on the way out: a port this process still held would make the next
      // devices process, and esptool, fail as if the hardware had died.
      await port.stop()
    },
  }
}