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.9 KB
Raw Blame
/**
 * The fleet: the owner's other machines, and getting to them (docs/design/2026-10-03-harnessd.md,
 * "Devices", step D0). The machine list kept fresh, the keys pinned for the machines linked to this
 * one, the device lane to them (`DeviceLink`, `DeviceFleet`), and the router every turn goes through:
 * which machine an agent is on, and a turn, a stop or an answer reaching it there (fleetRouter.ts).
 *
 * It was built inside the dial's wiring, and the router lived in the dial's host, so ⌘K and the
 * window's voice route reached another machine only through the dial. It is a part of the devices now
 * (services/devices.ts, step 9), beside its main caller: the dial reads a dozen routing facts while it
 * builds each frame (which machine an agent is on, whether it is known, who it is), and those reads
 * stay in line only on the same side of a process boundary as the dial. ⌘K reaches it through the
 * devices' port.
 *
 * It reads the core only through `CoreApi`.
 */
import { env } from '../config/env.js'
import { FAIL, later, type CoreApi, type PortFallbacks, type RouteAnswer, type SendResult, type ForkResult } from '../core/api.js'
import { DeviceFleet } from '../device/deviceFleet.js'
import { DeviceLink } from '../device/deviceLink.js'
import type { MachineListCache } from '../device/machineList.js'
import { MachinePeerStore } from '../lib/e2ee/machinePeers.js'
import { routeVoiceTask, type RouterAgent, type RouterContinuity } from '../lib/voiceRouter.js'
import type { CableAgent, CableMachine, CableMachineSource } from '../cable/cableSession.js'
import type { FleetEvent } from '../cable/machineFleet.js'
import type { AnswerReceipt, ReviewedAnswer } from '../cable/questionInbox.js'
import { FleetRouter } from './fleetRouter.js'

/** A fork and where it was asked: `asked` is false for a refusal made before asking anyone (an agent
 *  never listed, a daemon or a fleet that cannot fork), which nobody needs to hear about. */
export interface ForkOutcome { result: ForkResult; machineId: string; asked: boolean }
/** A machine selected for the dial, or the refusal a person can act on. */
export type SelectResult = { ok: true } | { ok: false; code: string; message: string }

/**
 * Which machine an agent is on, and a turn, a stop or an answer reaching it there: the fleet's router
 * (services/fleetRouter.ts), as the dial asks it. Also the lane to the other machines, which the dial
 * holds while it is plugged in. A refusal is an answer here, never a throw: through the devices' guard,
 * a throw is a failure of the fleet, and counts toward switching it off.
 */
export interface FleetRouting {
  listMachines(): Promise<{ machines: CableMachine[]; source: CableMachineSource }>
  listAgentsFlat(): Promise<CableAgent[]>
  /** When each of this computer's agents last did something, by id (the app's "last used"). */
  activityTimes(): Promise<Map<string, number>>
  agentTotal(): number
  describe(agentId: string): { name: string; engine: string; machine: string } | undefined
  noteAgent(machineId: string, agentId: string): void
  machineOf(agentId: string): string
  knows(agentId: string): boolean
  isLocalAgent(agentId: string): boolean
  sendTurn(agentId: string, text: string): SendResult
  lastRouted(): RouterContinuity | undefined
  stopTurn(agentId: string): void
  canSpeakQuestion(agentId: string): boolean
  answerReviewed(answer: ReviewedAnswer): Promise<AnswerReceipt>
  answer(agentId: string, requestId: string, answers: Record<string, string>): void
  updateAgent(agentId: string, model?: string, effort?: string): void
  recentSummaries(agentId: string): Promise<Array<{ recap: string; text: string; ask: string; fullText?: string }>>
  recentAsks(agentId: string): Promise<string[]>
  listModels(agentId: string): Promise<string[]>
  forkAgent(agentId: string): Promise<ForkOutcome>
  /** Whether a lane to the other machines exists: signed in, with the fleet's own fleet. */
  hasLane(): boolean
  /** Hold the lane for a dial, attached to no machine. Resolves with how it went, and why when the lane said
   *  (cable/machineFleet.ts LANE_*); never rejects. */
  online(): Promise<{ ok: true } | { ok: false; message: string; code?: string }>
  select(machineId: string): Promise<SelectResult>
  release(immediate?: boolean): void
}

/** The fleet as the devices hold it: ⌘K's two requests — which agent a typed task belongs to, on any of
 *  the owner's machines, and delivering it to that agent's own machine — the routing the dial asks of it,
 *  the cards the other machines send, and stopping the lane to them. */
export interface Fleet extends FleetRouting {
  routeTask(text: string): Promise<RouteAnswer>
  routeSend(agentId: string, text: string): SendResult
  /** The other machines' cards, for the dial. Returns how to stop hearing them. */
  onEvent(listener: (event: FleetEvent) => void): () => void
  stop(): void
}

export const FLEET_UNAVAILABLE = 'the fleet service is unavailable'

/**
 * What the devices get when the fleet fails. ⌘K says so, picking no agent and sending nothing; a shutdown
 * goes on; the cards stop. The dial's routing FAILs: the dial routes this computer by itself then, as it
 * does with the fleet off (cable/cableHost.ts), rather than reading a made-up answer as the fleet's.
 */
export const FLEET_FALLBACKS: PortFallbacks<Fleet> = {
  routeTask: later({ agentId: '', machineId: '', name: '', confidence: 0, reason: FLEET_UNAVAILABLE, candidates: [], weighed: 0, machines: 0, via: '' }),
  routeSend: { ok: false, machine: '', reason: FLEET_UNAVAILABLE },
  onEvent: () => {},
  stop: undefined,
  listMachines: later(FAIL), listAgentsFlat: later(FAIL), activityTimes: later(FAIL), agentTotal: FAIL, describe: FAIL, noteAgent: FAIL,
  machineOf: FAIL, knows: FAIL, isLocalAgent: FAIL, sendTurn: FAIL, lastRouted: FAIL, stopTurn: FAIL,
  canSpeakQuestion: FAIL, answerReviewed: later(FAIL), answer: FAIL, updateAgent: FAIL, recentSummaries: later(FAIL),
  recentAsks: later(FAIL), listModels: later(FAIL), forkAgent: later(FAIL), hasLane: FAIL, online: later(FAIL),
  select: later(FAIL), release: FAIL,
}

/**
 * How many agents ⌘K weighs at once.
 *
 * A classifier budget, not a UI one: each candidate spends its name, its machine and three recaps inside
 * one prompt, and past a point the window that decides the pick is more crowded than it is informed.
 * Fifteen is the owner's number; the ordering that decides WHICH fifteen is in routeTask.
 */
const ROUTE_MAX_CANDIDATES = 15
/** What ⌘K gives the classifier before the name matcher answers instead. */
const ROUTE_CLASSIFY_APP_MS = 20_000
/** How often the machine list is read again: the wheel's dots and the agent lists follow it. Every minute until spec
 *  2026-11-02-poll-cost Part 4.4: a change to the account's machines is told (`machines_changed`) and read at once, live
 *  presence comes on the socket (`MachineListCache.applyLive`), and this is the net for a lost push. */
const MACHINE_LIST_REFRESH_MS = 5 * 60_000
/** A list read this recently (by this refresh, or one a notice asked for) is not read again by the timer. */
const MACHINE_LIST_MAX_AGE_MS = 45_000

/** What the fleet needs that is not the core's to give. */
export interface FleetDeps {
  /** The owner's machines: the devices' own copy of the list, read from the core (`account.machines`).
   *  This service keeps it fresh. */
  machines: MachineListCache
  /** The window's tiles on its active tab, in tile order, as it last reported them. */
  desk(): string[]
  /** Read this computer's agents again before a list is built from them (FleetLocal.refresh). */
  refresh?: () => Promise<void>
}

/** Start the fleet: what ⌘K and the dial reach it through. The router itself is returned beside it, for
 *  this service's own tests; nothing else holds it. */
export function startFleet(core: CoreApi, deps: FleetDeps): { fleet: Fleet; router: FleetRouter } {
  // Three independent things, on purpose. The LIST is a REST read that works while the backend socket is
  // down; `local` is derived from the computer id and needs no network at all; and the LANE is a device
  // socket that only exists while the dial is actually looking at another machine.
  //
  // Signed out there is nothing to fetch and a fetch would only earn a 401 that empties the wheel, so the
  // core answers with the one row this daemon can speak for (`account.machines`).
  const refreshMachineList = (): void => { void deps.machines.refresh({ maxAgeMs: MACHINE_LIST_MAX_AGE_MS }) }
  refreshMachineList()
  const machineListTimer = setInterval(refreshMachineList, MACHINE_LIST_REFRESH_MS)
  machineListTimer.unref?.()
  // A machine added, renamed or removed: read now. Who uses a harness here (`harness_shares`) is not the list.
  const stopNotices = core.account.onNotice((notice) => {
    if (notice.type === 'machines_changed' && notice.reason !== 'harness_shares') void deps.machines.refresh({ maxAgeMs: 0 })
  })

  const peers = new MachinePeerStore()
  const link = new DeviceLink({
    // Signed in and sealed through the core (step 10, R3): its tokens are the core's session's, which
    // shares a refresh in flight with the backend link, and its E2EE sessions are the gateway's, under the
    // SAME identity `harness remote-password set` publishes and `harness link connect` proves knowledge
    // against, so one link ceremony covers the desktop app's relay and the dial's lane alike.
    auth: { accessToken: (options) => core.account.accessToken(options) },
    backendWsBase: env.BACKEND_WS_URL,
    computerId: core.machine.computerId(),
    autonomousEnv: core.account.environment(),
    seal: core.account.lane,
    // Read FRESH on every attach: `harness link connect` runs as a separate process, so a value captured
    // at daemon start would keep answering "not linked" until the next restart.
    peer: (machineId) => peers.get(machineId),
    // Read fresh for the same reason: it is '' until the daemon has resolved this computer's machine, and
    // the echo guard must start working the moment it is not.
    localMachineId: () => core.machine.id(),
    log: (line) => console.log(`[device] ${line}`),
  })
  const devices = new DeviceFleet({
    list: deps.machines,
    link,
    // Read FRESH on every call, never cached: `harness link connect` runs as a separate process, so a
    // cached answer would keep saying "not linked" for as long as this daemon lives.
    hasPeerLink: (machineId) => peers.get(machineId) !== null,
    log: (line) => console.log(`[device] ${line}`),
  })
  // This computer's side of every route: the core's own doors, the ones the web and the hooks use.
  const router = new FleetRouter({
    machineName: () => core.machine.name(),
    machineId: () => core.machine.id(),
    computerId: () => core.machine.computerId(),
    sessions: () => [...core.agents.advertised(), ...core.agents.cloud?.() ?? []],
    refresh: deps.refresh,
    displayName: (session) => core.agents.displayName(session),
    runtimeProfile: (session) => core.agents.runtimeProfile(session),
    desk: () => deps.desk(),
    sendTurn: (agentId, text) => core.turns.send(agentId, text),
    stopTurn: (agentId) => core.turns.stop(agentId),
    answer: (agentId, requestId, answers) => core.questions.answer(agentId, requestId, answers),
    answerReviewed: (answer) => core.questions.answerReviewed(answer),
    recent: (agentId, n) => core.turns.recent(agentId, n),
    recentAsks: (agentId) => core.turns.asks(agentId),
    updateAgent: (agentId, model, effort) => core.agents.setRuntime(agentId, model, effort),
    listModels: (agentId) => core.agents.runtimeModels(agentId),
    forkAgent: (agentId) => core.agents.fork(agentId),
    // The lines the dial's host always wrote, under the name people search the log for.
    log: (line) => console.log(`[cable] ${line}`),
  }, devices)
  // Which machine an agent is on, before its list is necessarily read: what lets a question from it be
  // named and, tapped, opened — whichever surface is listening, the dial or none.
  devices.onEvent((event) => { if (event.kind !== 'state') router.noteAgent(event.machineId, event.agentId) })
  const fleet: Fleet = {
    // ⌘K's two requests.
    routeTask: (text) => routeTask(router, text),
    routeSend: (agentId, text) => router.sendTurn(agentId, text),
    // What the dial asks: the router's own answers.
    listMachines: () => router.listMachines(),
    listAgentsFlat: () => router.listAgentsFlat(),
    activityTimes: () => router.activityTimes(),
    agentTotal: () => router.agentTotal(),
    describe: (agentId) => router.describe(agentId),
    noteAgent: (machineId, agentId) => router.noteAgent(machineId, agentId),
    machineOf: (agentId) => router.machineOf(agentId),
    knows: (agentId) => router.knows(agentId),
    isLocalAgent: (agentId) => router.isLocalAgent(agentId),
    sendTurn: (agentId, text) => router.sendTurn(agentId, text),
    lastRouted: () => router.lastRouted(),
    stopTurn: (agentId) => router.stopTurn(agentId),
    canSpeakQuestion: (agentId) => router.canSpeakQuestion(agentId),
    answerReviewed: (answer) => router.answerReviewed(answer),
    answer: (agentId, requestId, answers) => router.answer(agentId, requestId, answers),
    updateAgent: (agentId, model, effort) => router.updateAgent(agentId, model, effort),
    recentSummaries: (agentId) => router.recentSummaries(agentId),
    recentAsks: (agentId) => router.recentAsks(agentId),
    listModels: (agentId) => router.listModels(agentId),
    forkAgent: (agentId) => router.forkAgent(agentId),
    hasLane: () => router.hasLane(),
    online: () => router.online(),
    select: (machineId) => router.select(machineId),
    release: (immediate) => router.release(immediate),
    // The other machines' cards, for the dial's screen. The router notes their machines itself, above.
    onEvent: (listener) => devices.onEvent(listener),
    stop: () => {
      clearInterval(machineListTimer)
      stopNotices()
      link.stop()
    },
  }
  return { fleet, router }
}

/**
 * ⌘K in the window: a typed task, and which agent it belongs to.
 *
 * THE SAME ROUTER THE DIAL USES, given a second caller. routeVoiceTask has never cared that its input
 * arrived as speech — the transcript is just text by the time it sees it — so this is not a port. What
 * is new is the answer coming back to something that can SHOW it: the dial had to act on the pick,
 * the window can ask.
 *
 * EVERY AGENT, EVERY MACHINE. The candidate list is the dial's own — this computer first, then each
 * machine in wheel order — because the agent that fits the words is not always the one on the desk in
 * front of you, and a router that cannot see the others cannot say so.
 *
 * CAPPED AT FIFTEEN, and the cap is about the CLASSIFIER, not about us: every candidate spends its
 * name and three recaps in one prompt, and a list long enough to crowd that window makes the pick
 * worse, not slower.
 *
 * WHICH fifteen is the rail's own order — this computer's agents, then each other machine's — because
 * that is the list the person is looking at while they type, and "the first fifteen" has to mean the
 * first fifteen they can SEE. An earlier cut put open tiles first, on the theory that working on
 * something is a statement about relevance; it is, but it also made the fifteen unpredictable from
 * the screen, and predictable beat clever here (owner's call).
 */
async function routeTask(router: FleetRouter, text: string): Promise<RouteAnswer> {
  // Whatever the daemon knows right now. This also kicks a refresh of the remote machines, so a list
  // that is short because a machine has not been asked yet fills in for the NEXT question rather than
  // holding this one open.
  // FLAT, not the dial's ring: listAgents() re-cuts the same snapshot around the window's open
  // tiles, which is the right answer for a carousel and the wrong one for a list the person reads
  // top to bottom.
  const all = await router.listAgentsFlat()
  const ranked = all.slice(0, ROUTE_MAX_CANDIDATES)
  if (ranked.length < all.length) {
    // Never a silent truncation: a route that could not have picked the right agent must not read
    // like a route that considered it and said no.
    console.log(`[route] ${all.length} agents · weighing the first ${ranked.length} (open tiles first)`)
  }
  // Recaps AFTER the cap, and in parallel: a remote agent's recap is an RPC to its machine, so
  // fetching for agents that were never going to be weighed is latency spent on nothing. They are
  // cached per agent on the fleet side, so a second ⌘K costs no round trip at all.
  const candidates: RouterAgent[] = await Promise.all(ranked.map(async (agent) => ({
    id: agent.id,
    name: agent.name,
    engine: agent.engine,
    machine: agent.machine,
    // THE PERSON'S OWN QUESTIONS, AND NOTHING ELSE.
    //
    // This used to be `turn.ask || turn.recap || turn.text`, cut to sixty characters and joined
    // into one blob — under a prompt heading that told the model every word of it was something
    // the person had asked. For any agent with no recorded question that was false: it was a
    // summary of what the AGENT REPLIED. Measured on this desk, "which year did the second world
    // war end" summarised to "1945." — an answer, labelled as a question, handed to a model asked
    // to recognise a topic. An agent with nothing on record now sends an empty list and is
    // described honestly in the prompt.
    //
    // UNCUT, too. Sixty characters was chosen when fifteen agents each carried three recaps at
    // full length and the prompt timed out; a real machine has four to eight agents, and cutting
    // a Vietnamese sentence at sixty takes the object with it — which is the topic. The bound that
    // matters now lives at the two ends: ASK_MAX_CHARS where the question is recorded, and the
    // endpoint's own per-prompt ceiling.
    prompts: await router.recentAsks(agent.id),
  })))
  // 20s, not the shared 12s: this path answers a person watching a spinner in their own window, and
  // it is under nobody else's deadline — the app's rpc waits longer still. The dial and the web keep
  // the default; overshooting a deadline they DO have would turn a late answer into no answer.
  // …and WHO THIS PERSON WAS JUST TALKING TO. Nothing else in the prompt can supply it: a follow-up
  // question names no agent and often shares no words with the first one, and the recap of the turn
  // it follows may not even exist yet — the answer is still being written while the next question
  // is being asked.
  const decision = await routeVoiceTask(text, candidates, undefined, ROUTE_CLASSIFY_APP_MS, router.lastRouted())
  const named = (id: string) => candidates.find((agent) => agent.id === id)
  // The runners-up in the ROUTER's order when it gave one, and the list's own order when it did not.
  // A picker that has to ask "which agent" is showing a ranking either way; this decides whose.
  const ranking = (decision.scores ?? []).filter((score) => score.agentId !== decision.agentId)
  // EVERY AGENT THAT WAS WEIGHED, not the best two.
  //
  // The picker used to offer three rows — the pick and two runners-up — on the theory that a person
  // who has to be asked wants the shortlist. They do not: when the router is unsure the right agent
  // is often the one it ranked fourth, and a shortlist that cannot show it turns a question into a
  // dead end, with no way out but Esc and typing the task again somewhere else.
  //
  // Ranked first where the router said something, then everything else it looked at in rail order,
  // so the list stays the one the person is reading on screen. Nothing is dropped: the cap that
  // matters is ROUTE_MAX_CANDIDATES above, and `weighed` already says what it did.
  const rankedOthers = ranking
    .map((score) => named(score.agentId))
    .filter((agent): agent is RouterAgent => !!agent)
  const listed = new Set([decision.agentId, ...rankedOthers.map((agent) => agent.id)])
  const others = [...rankedOthers, ...candidates.filter((agent) => !listed.has(agent.id))]
  const fitOf = (id: string) => id === decision.agentId
    ? decision.confidence
    : ranking.find((score) => score.agentId === id)?.confidence ?? 0
  return {
    agentId: decision.agentId,
    machineId: all.find((entry) => entry.id === decision.agentId)?.machineId ?? '',
    name: named(decision.agentId)?.name ?? '',
    confidence: decision.confidence,
    reason: decision.reason,
    // How many agents were actually WEIGHED, and across how many computers. The window says this
    // while it waits, because the question a person has during those seconds is not "how long" —
    // it is "did it even look at the agent I mean". The cap above can hide agents, and until now
    // the only place that was said was this process's log.
    weighed: ranked.length,
    machines: new Set(ranked.map((agent) => agent.machine).filter(Boolean)).size,
    // 'model' or 'heuristic', coarsened from the router's own label. The two arrive at the same low
    // confidence BY DESIGN — an unsure model and a router that could not run must both stop and ask
    // — and that is exactly why the window has to be able to tell them apart when it explains itself.
    via: (decision.via ?? '').startsWith('heuristic') ? 'heuristic' : 'model',
    candidates: [decision.agentId ? named(decision.agentId) : null, ...others]
      .filter((agent): agent is RouterAgent => !!agent)
      .map((agent) => {
        const listed = all.find((entry) => entry.id === agent.id)
        return {
          agentId: agent.id,
          name: agent.name,
          // The machine travels twice, and both are needed: the NAME because two agents called "api"
          // on two computers are otherwise one row twice, and the ID because the window has to open
          // the pane on the machine the agent actually lives on.
          machineId: listed?.machineId ?? '',
          machine: agent.machine ?? '',
          engine: agent.engine ?? '',
          recent: (agent.recentSummary ?? '').slice(0, 120),
          // Drawn as a bar in the picker, never dispatched on. 0 = the router said nothing about
          // this one, which the window renders as no bar rather than as a zero-length one.
          confidence: fitOf(agent.id),
        }
      }),
  }
}