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.

58.5 KB
Raw Blame
// Everything the cable session needs from the rest of the daemon, in one place.
//
// The session owns the protocol and nothing else; this owns the answers. Keeping them apart is what lets
// the protocol be tested against a fake host — the alternative is a suite that needs tmux, a microphone
// and a network to prove that `hello` gets a `welcome`.
//
// Nothing here is new machinery. The agent list is the registry the web and the backend socket already
// read, the router is the one the backend already calls for remote machines, and the turn events arrive
// as the very `commander_event` cards the WiFi device receives — teed at the socket rather than emitted
// again here, so the two device surfaces cannot drift.
//
// Which machine an agent is on, and every turn, stop and answer sent to it, is the fleet's router
// (services/fleetRouter.ts), shared with ⌘K and the window's voice route. This host asks it through the
// core's port (`wiring.fleet`), never holding it (step D1): a dial in a process of its own asks the same
// port across the service link. It keeps a router of its own for this computer alone, and uses it
// whenever the fleet cannot answer — off, or its call failed — as the dial did before the fleet was a
// service. Its tests give it a bare fleet to route over by itself.
import { join } from 'node:path'
import { notificationReadToken, type UnreadNotification } from '../lib/notificationRead.js'

import type { RegisteredSession } from '../lib/registry.js'
import { fetchRelease, loadImage, shouldOffer, type FirmwareRelease } from './fwPush.js'
import { routeVoiceTask, type RouterAgent, type RouterContinuity } from '../lib/voiceRouter.js'
import { env } from '../config/env.js'
import { FleetRouter } from '../services/fleetRouter.js'
import type { ForkResult } from '../core/api.js'
import type { FleetRouting } from '../services/fleet.js'
import { ServiceUnavailableError } from '../core/serviceHost.js'

import { PLAYER_STATES, type PlayerSession } from './playerLibrary.js'
import type { CardChat, CardSide, LeadRecap, SaidOnCard, SwarmCard } from '../superTabs/cards.js'
import type { ActivitySnapshot, AppSwarms, SuperTabAsk, CableAgent, CableHost, CableMachine, CableMachineSource, CableSwarm, CableTile, DialStatus, OpenReason, RouteDecision } from './cableSession.js'
import type { WindowRoute } from './windowRoute.js'
import type { SelectionCommand, SelectionResult } from './windowSelection.js'
import type { VisitCommand, VisitResult } from './windowVisit.js'
import type { FormCommand, FormResult } from './windowForm.js'
import type { PetStore } from './pets/store.js'
import { LANE_SESSION_OVER, LANE_TOKEN_UNAVAILABLE, type MachineFleet } from './machineFleet.js'
import type { ReviewedAnswer, AnswerReceipt } from './questionInbox.js'
import { isTier, type Tier } from '../lib/notifyTier.js'

/** One completed turn's recap, as the mirror keeps them. */

export interface RecentTurn {
  recap?: string
  text?: string
  /** What the USER asked on that turn. The topic lives here; the recap holds the answer. */
  ask?: string
  /** The turn's whole answer when the mirror still holds it: what a `recap: 'long-v1'` device reads. */
  fullText?: string
}

export interface CableHostWiring {
  /** The live agents the apps are shown, and the name they show for each: the router this host keeps for
   *  this computer reads them (the core's `agents.advertised` and `agents.displayName`). */
  sessions: () => RegisteredSession[]
  displayName: (session: RegisteredSession) => string
  /** Exact live terminal footer for a local agent; absent when no footer is visible. */
  activityText?: (agentId: string) => Promise<string | null>
  /** `activityText` plus the footer's timer and the assistant's latest paragraph. */
  activitySnapshot?: (agentId: string) => Promise<ActivitySnapshot | null>
  /** The person's own last questions to a LOCAL agent, newest first. */
  recentAsks: (agentId: string) => string[] | Promise<string[]>
  /** Read the agents again before a list is built from them (see FleetLocal.refresh). */
  refresh?: () => Promise<void>
  machineName: () => string
  /** This computer's machineId, or '' when the daemon has never resolved one (signed out). */
  machineId: () => string
  /** A stable id for this computer, used to name the local row when there is no machineId yet. */
  computerId: () => string
  /** Whether this computer holds an account. False → the dial serves THIS computer alone: the cloud
   *  lane (the other machines, and voice) is what an account buys, and it is not dialled without one. */
  signedIn?: () => boolean
  /** The account's sign-in, for the transcriber: the core's (`account.accessToken`), never one of this
   *  host's own. Absent, voice says to sign in. */
  accessToken?: (opts?: { force?: boolean; failedToken?: string }) => Promise<string>
  /** The account's environment, which the transcriber checks the upload against. */
  environment?: () => string
  /** A dial is on the wire on this computer, or none is any more: the core streams the turn cards and
   *  makes the recaps for it, as for a device watching through the backend. */
  watching?: (on: boolean) => void
  /** Deliver text into an agent. The SAME path the web and the WiFi device use — see cli.ts. */
  sendTurn: (agentId: string, text: string) => void
  stopTurn: (agentId: string) => void
  answer: (agentId: string, requestId: string, answers: Record<string, string>) => void
  answerReviewed?: (answer: ReviewedAnswer) => Promise<boolean>
  /** Recaps of an agent's last `n` completed turns — for routing, and for redrawing a reattached dial. */
  recent: (agentId: string, n: number) => RecentTurn[] | Promise<RecentTurn[]>
  /** The opaque runtime-v1 profile, which is where the dial's Model/Effort chips come from. */
  runtimeProfile?: (session: RegisteredSession) => string | null
  updateAgent?: (agentId: string, model?: string, effort?: string) => void
  /** The runtime catalog, from the same provider the web and the WiFi device read. */
  listModels?: (agentId: string) => Promise<Array<{ id: string }>>
  /** The dial moved to another agent — the desktop window should show that agent on its own machine. */
  focused?: (machineId: string, agentId: string) => void
  /**
   * A notification was tapped: the window gives that agent a tile of its own. With `reason`
   * `'question'` it was a question screen instead, and the window only brings the agent forward.
   */
  opened?: (machineId: string, agentId: string, reason?: OpenReason) => void
  notificationRead?: (machineId: string, agentId: string, readToken: string) => void
  /** A fork the dial asked for is open: the window puts it beside its source and focuses it. */
  forked?: (machineId: string, agentId: string, sourceAgentId: string) => void
  /** The dial asked for a fork of a LOCAL agent — see lib/forkAgent.ts. Resolves to the new agent's id. */
  forkAgent?: (agentId: string) => Promise<{ ok: true; agentId: string } | { ok: false; error: string; detail?: string }>
  /** The dial picked a swarm: the window switches to it. */
  swarmSelected?: (swarmId: string) => void
  /** A Harness Pro came with Swarm cards (true) or the last one went (false): the core reads the Swarms only meanwhile. */
  swarmCardsWanted?: (on: boolean) => void
  /** One Lead's last message, read on request; null when it could not be read. */
  swarmCardRecap?: (tabId: string, leadId: string, chat?: CardChat) => Promise<LeadRecap | null>
  /** The recap a device (one cable `session`) has open, or null once closed. */
  swarmCardOpen?: (session: string, tabId: string, leadId: string | null, chat?: CardChat) => void
  /** Words for a Lead that runs here, posted as the person in its Swarm chat; not `said` when the harness leads no project,
   *  `refused` with the backend's reason when it refused the post. */
  swarmSay?: (harnessId: string, text: string, chat?: CardChat, chatId?: string, reviewed?: boolean) => Promise<SaidOnCard>
  /** A device picked a Lead: the window opens that Swarm tab and project. */
  superTabSelected?: (superTabId: string, projectId: string, chat?: CardSide) => void
  /** A finger on the dial's glass, in pieces, while it is down; `superTabId` when it scrolls that Swarm's chat (a Pro's Lead view). */
  scrolled?: (phase: 'down' | 'move' | 'up', dy: number, velocity: number, superTabId?: string) => void
  /** The dial came, went, or started taking an update — see CableSession's onDialStatus. */
  dialStatus?: (status: DialStatus) => void
  appFocus?: CableHost['appFocus']
  /** Offer a spoken task to the desktop window's palette. Omitted when there is no window plumbing. */
  routeInWindow?: (text: string, cmd?: string) => Promise<WindowRoute>
  selectPassage?: (command: SelectionCommand) => Promise<SelectionResult>
  clearSelection?: () => void
  visit?: (command: VisitCommand) => Promise<VisitResult>
  clearVisit?: () => void
  form?: (command: FormCommand) => Promise<FormResult>
  clearForm?: () => void
  log: (line: string) => void
  /**
   * Which machine an agent is on, and getting a turn, a stop or an answer there: the fleet service's
   * routing, through the core's port (core/api.ts `FleetRouting`). Read at every call, and null while the
   * fleet is off. Absent, this host routes by itself.
   */
  fleet?: () => FleetRouting | null
  /** The custom pets kept on this computer; the dial's session reads the mapping and packs from it. */
  pets?: () => PetStore | null
}

/** Whether an id is the router's placeholder for a machine with no id yet (`cable:` and the computer id;
 *  see services/fleetRouter.ts) rather than a machine the backend has heard of. */
function isPlaceholder(id: string): boolean {
  return id.startsWith('cable:')
}

/** How long a keepalive may be answered from the last manifest read — see firmwareFor. */
const RELEASE_KEEP_MS = 30 * 60_000
/**
 * The wait before trying the plug-in's lane again, doubling to the cap: the same backoff as the lane's own reconnect
 * (deviceLink.ts reconnectLater). Diego, 11-01: a first open lost to a refresh that failed in a network blip was
 * never tried again, and the wheel had no other Mac until the dial was replugged.
 */
const LANE_RETRY_MS = 1_000
const LANE_RETRY_MAX_MS = 30_000

/** How a pick of a machine ended: `code` is the daemon's, `message` is shown to a person (CableHost.selectMachine). */
type MachinePick = { ok: true } | { ok: false; code: string; message: string }

/** A pick on its way; `replaced` when it took over from another still running. */
interface PendingPick { machineId: string; replaced: boolean; done: Promise<MachinePick> }

/** A pick's end that says no about that machine and nothing about the lane (deviceFleet.ts select and codeFor). */
const REFUSALS = new Set(['NEEDS_LINK', 'UNKNOWN_MACHINE', 'NOT_YOURS', 'BILLING'])

export class DaemonCableHost implements CableHost {
  /**
   * This host's own router: over the bare fleet it is given (its tests), or over none, for this computer
   * alone. Asked whenever the fleet service cannot answer — see route.
   */
  private readonly local: FleetRouter

  /**
   * The machine whose agents are on the dial right now. Defaults to — and falls back to — the local one:
   * it is the only machine that is certainly reachable, so it is the honest thing to land on.
   *
   * Held in memory only. The dial deliberately does not remember a selection across its own reboot (a
   * restored id is meaningless until you know whose computer the cable is in), and this side does not
   * remember across a daemon restart either — that is when the registry reloads anyway.
   */
  private selected = ''
  /**
   * The newest pick still on its way to a remote machine, until it settles. Only it may move `selected`: a pick waiting on
   * a slow machine lands up to 15 s later, by when the person may be elsewhere (Diego's Buddy, 11-02). Which pick it is, not
   * just which machine: going away and back to one machine looks the same by name, and the first landing says nothing of
   * the last. The announce on plug-in names it rather than `selected`: announcing the older machine would replace the newer
   * choice at the lane (deviceLink.ts select).
   */
  private pending: PendingPick | null = null

  /** Counts plug-ins: a lane open that lands after an unplug or a replug belongs to an older one and does nothing. */
  private plugIn = 0
  /** The next try at the lane for this plug-in, after an open that failed; cleared by an unplug or a replug. */
  private laneRetry: NodeJS.Timeout | null = null
  private laneTries = 0

  /** The last good manifest read per OTA key, for keepalives — see firmwareFor. */
  private readonly releases = new Map<string, { release: FirmwareRelease; at: number }>()

  /**
   * `fleet` is a bare lane to the other machines for this host's own router — its tests give it one. A
   * daemon gives none: its dial reaches the fleet service's router through the core (`wiring.fleet`).
   * With neither, the wheel is the local row and nothing else.
   */
  constructor(private readonly wiring: CableHostWiring, fleet?: MachineFleet) {
    this.local = new FleetRouter({
      ...wiring,
      // The same set `agents_list` answers the apps with — see the router's localAgents.
      sessions: () => wiring.sessions(),
      displayName: (session) => wiring.displayName(session),
      desk: () => this.desk,
    }, fleet)
  }

  /**
   * Ask the fleet service's router through the core's port, or this host's own when the fleet is off or
   * its call came back unavailable (a failing port's fallback, core/api.ts FLEET_FALLBACKS). Either way the
   * answer is a router's, refusals included: the dial never reads a made-up answer as the fleet's.
   */
  private viaFleet<T>(ask: (routing: FleetRouting) => T): T {
    const fleet = this.wiring.fleet?.()
    if (!fleet) return ask(this.local)
    const unavailable = (error: unknown): T => {
      if (error instanceof ServiceUnavailableError) return ask(this.local)
      throw error
    }
    let answer: T
    try {
      answer = ask(fleet)
    } catch (error) {
      return unavailable(error)
    }
    return answer instanceof Promise ? answer.catch(unavailable) as T : answer
  }

  /** The identity of the computer at the other end of the cable. */
  localMachine(): { id: string; name: string } {
    return { id: this.localId(), name: this.wiring.machineName() }
  }

  private localId(): string {
    return this.local.localId()
  }

  /** Whether the dial is looking at THIS computer. Everything forks on this one question. */
  isLocalSelected(): boolean {
    return this.selectedMachine() === this.localId()
  }

  selectedMachine(): string {
    return this.selected || this.localId()
  }

  /** The local row, then the fleet's — the router's list, which ⌘K reads too. */
  listMachines(): Promise<{ machines: CableMachine[]; source: CableMachineSource }> {
    return this.viaFleet((r) => r.listMachines())
  }

  /** The machine the newest pick is still on its way to, or '' when none is. */
  pendingPick(): string {
    return this.pending?.machineId ?? ''
  }

  async selectMachine(machineId: string): Promise<MachinePick> {
    if (machineId === this.localId()) {
      this.selected = machineId
      this.pending = null
      // Let go of the REMOTE machine after a linger, keeping the socket — then announce where the dial
      // actually is. `activeMachineId` on the account is then true for this machine too, instead of
      // silently going stale on whatever was selected last.
      this.viaFleet((r) => r.release())
      void this.announceSelection()
      return { ok: true }
    }
    if (!this.viaFleet((r) => r.hasLane())) {
      return { ok: false, code: 'UNAVAILABLE', message: 'Sign in on this computer to reach other machines' }
    }
    // A second pick of the machine already on its way shares its one answer, as the lane's select does. Each caller may be
    // the only one left to tell the dial: an app follow's answer is dropped once a newer focus arrives (reviews of #2504).
    if (this.pending?.machineId === machineId) return this.pending.done
    // Set before the select starts, so a fleet call that fails at once still finds it and clears it.
    const entry: PendingPick = { machineId, replaced: this.pending !== null, done: null as unknown as Promise<MachinePick> }
    this.pending = entry
    entry.done = this.pickMachine(entry)
    return entry.done
  }

  private async pickMachine(entry: PendingPick): Promise<MachinePick> {
    const { machineId } = entry
    let selected: Awaited<ReturnType<FleetRouting['select']>>
    let newest = false
    try {
      selected = await this.viaFleet((r) => r.select(machineId))
    } finally {
      newest = this.pending === entry
      if (newest) this.pending = null
    }
    if (!newest) {
      // Replaced, however it ended: a machine the person left failing late is no news to them. A newer pick of this same
      // machine (away and back) speaks for this one too: the dial waits on that machine, and an error would end its wait.
      if (this.pending?.machineId === machineId) return this.pending.done
      if (this.selected === machineId) return { ok: true }
      return { ok: false, code: 'SUPERSEDED', message: 'Another machine was chosen' }
    }
    if (!selected.ok) {
      // The lane may still be where the pick this one replaced took it: the fleet refuses an unlinked machine before asking
      // the lane, so the dial stayed here while the backend and any reconnect stayed on the machine the person left (reviews
      // of #2504). Said again now, as picking this machine again would not: it is already selected. Only for a refusal, and
      // only with a pick replaced: that one was still running, so the lane is up. Any other failure may be the lane's end (a
      // revoke, a 4403, an unplug), and telling it anything would dial straight back past what it decided.
      if (entry.replaced && REFUSALS.has(selected.code)) {
        void this.announceSelection().catch((err) => this.wiring.log(`cable: could not announce (${(err as Error).message})`))
      }
      return selected
    }
    this.selected = machineId
    return { ok: true }
  }

  /**
   * The dial is on the wire again.
   *
   * If it left looking at another machine, the cloud lane has to be back UP before the state push that
   * follows — that push calls listAgents(), which for a remote machine is an RPC over exactly this lane.
   * Awaiting it here would block the greeting, so it is fired and the push retries on the next tick if
   * it loses the race; a failure marks the machine unreachable rather than pretending it has no agents.
   */
  onDialAttached(): void {
    this.wiring.watching?.(true)
    this.stopLaneRetry()
    this.laneTries = 0
    this.openLane(++this.plugIn, 'cable: dial on the wire — opening the cloud lane')
  }

  private openLane(plugIn: number, line: string): void {
    if (!this.viaFleet((r) => r.hasLane())) return
    // Signed out there is no lane to open: the socket is authenticated, so dialling it would fail once
    // per plug-in and log a failure for something nobody asked for. The dial still works — it is on the
    // cable, and everything it shows on this computer is served in-process. A retry stops here too.
    if (this.wiring.signedIn?.() === false) {
      this.wiring.log('cable: dial on the wire — this computer only (not signed in)')
      return
    }
    this.wiring.log(line)
    void (async () => {
      // The socket first, and unconditionally: it is what makes the machine wheel's dots live, and it is
      // held for as long as the dial is plugged in whether or not anything is selected.
      let online: { ok: true } | { ok: false; message: string; code?: string }
      try {
        online = await this.viaFleet((r) => r.online())
      } catch (err) {
        online = { ok: false, message: (err as Error).message }
      }
      if (!online.ok) {
        // A session that is over is not tried again: each try would be a refused refresh and two log lines every 30 s
        // until someone signs in (security review 2 on #2483). The next sign-in and plug-in open it.
        if (online.code === LANE_SESSION_OVER) {
          this.wiring.log(`cable: could not open the lane (${online.message}) — other machines are unavailable until the next sign-in`)
          return
        }
        this.wiring.log(`cable: could not open the lane (${online.message})`)
        // Only a token that could not be read is tried again from here: it left the lane no socket, so nothing else
        // would (deviceLink.ts readToken). A socket that failed is the lane's own reconnect's, and trying it here too
        // ran two backoffs against a backend that is down (security review 2 on #2483).
        if (online.code === LANE_TOKEN_UNAVAILABLE) this.retryLane(plugIn)
        return
      }
      // Unplugged or replugged while it opened: the newer plug-in announces for itself, and an unplugged dial is
      // nowhere to announce.
      if (plugIn !== this.plugIn) return
      this.laneTries = 0
      await this.announceSelection()
    })().catch((err) => this.wiring.log(`cable: could not open the lane (${(err as Error).message})`))
  }

  private retryLane(plugIn: number): void {
    if (plugIn !== this.plugIn) return
    this.stopLaneRetry()
    const delay = Math.min(LANE_RETRY_MAX_MS, LANE_RETRY_MS * 2 ** Math.min(this.laneTries++, 5))
    this.laneRetry = setTimeout(() => {
      this.laneRetry = null
      if (plugIn === this.plugIn) this.openLane(plugIn, 'cable: trying the cloud lane again')
    }, delay)
  }

  private stopLaneRetry(): void {
    if (this.laneRetry) { clearTimeout(this.laneRetry); this.laneRetry = null }
  }

  /**
   * Tell the backend which machine the dial is on.
   *
   * Sent for the LOCAL machine too. It costs one frame and it is the only thing that makes
   * `DeviceBinding.activeMachineId` true rather than "whatever was selected last" — which is what the web
   * and the mobile app read to say where a dial is.
   *
   * Skipped only for the placeholder id, which is not a machineId and means nothing to the backend.
   */
  private async announceSelection(): Promise<void> {
    if (!this.viaFleet((r) => r.hasLane())) return
    const machineId = this.pendingPick() || this.selectedMachine()
    if (isPlaceholder(machineId)) return
    const selected = await this.viaFleet((r) => r.select(machineId))
    // Never fatal. The local machine in particular must stay usable with no backend at all — it is the
    // one machine the cable can vouch for on its own. Replaced by a newer select is not a failure: that
    // one tells the backend where the dial is.
    if (!selected.ok && selected.code !== 'SUPERSEDED') this.wiring.log(`cable: could not announce ${machineId} (${selected.message})`)
  }

  /**
   * The dial is gone — cable pulled, or the far end stopped answering.
   *
   * Drop the lane NOW rather than lingering. The daemon holds it on the dial's behalf and nothing else in
   * this process uses it, so keeping it open leaves the account showing a device attached to a machine
   * while the dial sits unplugged in a drawer — and every card that machine produces would be relayed to
   * a screen that is not there.
   */
  onDialGone(): void {
    this.plugIn++
    this.stopLaneRetry()
    this.wiring.watching?.(false)
    this.wiring.clearSelection?.()
    this.wiring.clearVisit?.()
    this.wiring.clearForm?.()
    this.viaFleet((r) => r.release(true))
  }

  /**
   * The last status the session reported, kept so a window that connects AFTER the dial was plugged
   * in can be told at once. Without this the row would say "no device" until the next unplug.
   */
  private dialStatusNow: DialStatus = { attached: false }

  onDialStatus(status: DialStatus): void {
    this.dialStatusNow = status
    this.wiring.dialStatus?.(status)
  }

  pets(): PetStore | null {
    return this.wiring.pets?.() ?? null
  }

  currentDialStatus(): DialStatus {
    return this.dialStatusNow
  }

  selectPassage(command: SelectionCommand): Promise<SelectionResult> {
    return this.wiring.selectPassage?.(command) ?? Promise.resolve({ ok: false, error: 'Update Harness to select text.' })
  }

  machineName(): string {
    return this.wiring.machineName()
  }

  appName(): string {
    return 'harness'
  }

  voiceLang(): string {
    // A PROPOSAL, not a decision. The dial keeps its own choice in NVS and states it on every capture —
    // the person holding it may well speak something other than this laptop is set to.
    const locale = process.env.LANG ?? ''
    return locale.startsWith('vi') ? 'vi' : 'en'
  }

  appFocus(): { machineId: string; agentId: string } | undefined {
    return this.wiring.appFocus?.()
  }

  /**
   * The window's tiles on its active tab, in tile order. This IS the dial's list — see listAgents. A
   * router this host builds for itself reads it to hold a tile whose machine dropped out; the fleet
   * service's router reads the window's own report of it.
   */
  private desk: string[] = []

  /** Last logged shape of the tab's list, so the line prints on change only. */
  private deskShape = ''

  /**
   * The window changed which agents have a tile, or what order they are in.
   *
   * Order is the payload, not just membership: the dial walks the same grid the
   * eyes are on, so the tiles come first in the carousel and in their own order.
   */
  setDesk(agentIds: string[]): void {
    this.desk = [...agentIds]
  }

  /** The window's swarms, or null once it has gone — see setSwarms. */
  private swarms: AppSwarms | null = null

  /**
   * The window described its swarms (or, with null, went away).
   *
   * Null is what tells the dial the window is SHUT: an empty desk with a window behind it is an empty
   * tab, an empty desk with none is a closed app, and the two draw different screens — see listAgents.
   */
  setSwarms(swarms: AppSwarms | null): void {
    this.swarms = swarms
  }

  /** What the window still has unread, newest first. Empty until a window says otherwise. */
  private unread: UnreadNotification[] = []

  setUnread(items: UnreadNotification[]): void {
    this.unread = items
  }

  listUnread(): UnreadNotification[] {
    return this.unread
  }

  readNotification(agentId: string, readToken: string): void {
    if (!notificationReadToken(readToken)) return
    const item = this.unread.find(n => n.agentId === agentId && n.readToken === readToken)
    if (!item?.machineId) return
    // Keep it until the window confirms through app_unread. Retrying is safe;
    // the window checks the same identity again, even across remote machines.
    this.wiring.notificationRead?.(item.machineId, agentId, readToken)
  }

  listSwarms(): { selected: string; swarms: CableSwarm[]; tiles: CableTile[] } {
    const app = this.swarms
    if (!app) return { selected: '', swarms: [], tiles: [] }
    return {
      selected: app.active,
      swarms: app.swarms.map((s) => ({ id: s.id, name: s.name, agents: s.agentIds.length, agentIds: s.agentIds, panes: s.panes, ...(s.superTabId ? { superTabId: s.superTabId } : {}) })),
      tiles: app.tiles,
    }
  }

  /** The Swarm cards the core last handed the devices; a device that attaches later is shown them (superTabs/inCore/cards.ts replays). */
  private cards: SwarmCard[] | null = null

  setSwarmCards(items: SwarmCard[]): void {
    this.cards = items
  }

  swarmCards(): SwarmCard[] | null {
    return this.cards
  }

  swarmCardsWanted(on: boolean): void {
    this.wiring.swarmCardsWanted?.(on)
  }

  swarmCardRecap(tabId: string, leadId: string, chat: CardChat = false): Promise<LeadRecap | null> {
    return this.wiring.swarmCardRecap?.(tabId, leadId, chat) ?? Promise.resolve(null)
  }

  swarmCardOpen(session: string, tabId: string, leadId: string | null, chat: CardChat = false): void {
    this.wiring.swarmCardOpen?.(session, tabId, leadId, chat)
  }

  swarmSay(harnessId: string, text: string, chat: CardChat = false, chatId?: string, reviewed = false): Promise<SaidOnCard> {
    const pinned: [chatId?: string, reviewed?: boolean] = chatId ? (reviewed ? [chatId, true] : [chatId]) : []
    return this.wiring.swarmSay?.(harnessId, text, chat, ...pinned) ?? Promise.resolve({ said: false })
  }

  superTabSelected(superTabId: string, projectId: string, chat?: CardSide): void {
    if (chat) this.wiring.superTabSelected?.(superTabId, projectId, chat)
    else this.wiring.superTabSelected?.(superTabId, projectId)
  }

  /**
   * The active tab when it is a Swarm, with its open project or '' when none is (its Chat with PM, a DM, or a Swarm
   * not loaded yet); `fromDevice` when the announce was a device's own pick. A Swarm tab with no project used to read
   * as no Swarm at all, and the dial stayed on "Nothing on this tab" while the window showed the Swarm. `conversationId`: the
   * conversation it has open there, when the window names one, which the round dial's face follows, and `threadRoot` the
   * thread whose pane is on screen beside it.
   */
  activeSwarmProject(): { superTabId: string; projectId: string; conversationId?: string; threadRoot?: string; fromDevice: boolean } | null {
    const app = this.swarms
    const tab = app?.swarms.find((s) => s.id === app.active)
    return app && tab?.superTabId ? { superTabId: tab.superTabId, projectId: tab.projectId ?? '',
      ...(tab.conversationId ? { conversationId: tab.conversationId, ...(tab.threadRoot ? { threadRoot: tab.threadRoot } : {}) } : {}),
      fromDevice: app.fromDevice === true } : null
  }

  selectSwarm(swarmId: string): void {
    if (!swarmId || !this.swarms?.swarms.some((s) => s.id === swarmId)) {
      this.wiring.log(`cable: ignored select for unknown swarm ${swarmId || '(empty)'}`)
      return
    }
    this.wiring.log(`cable: swarm → ${swarmId}`)
    this.wiring.swarmSelected?.(swarmId)
  }

  /**
   * THE DIAL HOLDS THE ACTIVE TAB'S PANES AND NOTHING ELSE.
   *
   * It used to get every agent on every machine — the window's tiles first as the ring, the rest tagged
   * "off-ring, still sent" for the overview count and the pull-down switcher. That is what let a
   * reconnect refill 78 agents into a screen that shows one: ten seconds under one display lock, the task
   * watchdog, a reboot (PR #79 painted it once; this stops sending it). The count now travels as a number
   * (`agentTotal`), the switcher is gone, and a notification for an agent the dial does not hold carries
   * its own name.
   *
   * Three answers, and each is a state the dial draws:
   *   - no window (`swarms === null`)      → `[]`; the dial shows "Run OpenHarness on your computer".
   *   - a window with an empty tab         → `[]`; the dial shows "Nothing on this tab".
   *   - a window with panes                → those agents, in tile order; a tile whose machine dropped out
   *                                          is held from the router's `knownAgents` (see listAgentsFlat).
   */
  async listAgents(): Promise<CableAgent[]> {
    return (await this.listAgentSnapshot()).agents
  }

  async listAgentSnapshot(): Promise<{ agents: CableAgent[]; tab: string; total: number }> {
    const flat = await this.listAgentsFlat()
    const byId = new Map(flat.map((a) => [a.id, a]))
    // app_panes and app_swarms are separate messages. Never label the new panes
    // with the previous tab (or vice versa) between those two arrivals. The
    // swarm announcement already contains membership in the same tile order.
    const app = this.swarms
    const tab = app?.active ?? ''
    const ids = app?.swarms.find(s => s.id === tab)?.agentIds ?? []
    const out = ids.map(id => byId.get(id)).filter((a): a is CableAgent => !!a)
    // One line per CHANGE. The failure this catches is silent by nature: tiles whose ids this daemon does
    // not know drop out of the list, which looks exactly like the window never having opened them.
    const shape = app === null
      ? '(no window)'
      : out.length ? out.map((a) => a.id.slice(0, 4)).join(' ') : '(empty tab)'
    if (shape !== this.deskShape) {
      this.deskShape = shape
      this.wiring.log(`cable: tab ${shape} · ${flat.length} in all`)
    }
    return { agents: out, tab, total: this.viaFleet((r) => r.agentTotal()) }
  }

  /** How many agents the account has across every machine — the overview's number, sent beside the
   *  tab's list rather than as 70 rows the dial would hold for a digit. See the router's agentTotal. */
  agentTotal(): number {
    return this.viaFleet((r) => r.agentTotal())
  }

  /** The active tab's id, or '' with no window. Travels on `agents.end` so the dial can tell an empty
   *  tab from a shut window — the two draw different screens. */
  activeSwarm(): string {
    return this.swarms?.active ?? ''
  }

  /**
   * Name, engine and machine of an agent this daemon has ever listed — for a `summary` or `question`
   * about one the dial no longer holds. See the router's describe.
   */
  describe(agentId: string): { name: string; engine: string; machine: string } | undefined {
    return this.viaFleet((r) => r.describe(agentId))
  }

  async activityText(agentId: string): Promise<string | null> {
    if (!this.viaFleet((r) => r.isLocalAgent(agentId))) return null
    if (this.wiring.activityText) return await this.wiring.activityText(agentId) ?? null
    return (await this.wiring.activitySnapshot?.(agentId))?.text ?? null
  }

  async activitySnapshot(agentId: string): Promise<ActivitySnapshot | null> {
    if (!this.viaFleet((r) => r.isLocalAgent(agentId))) return null
    if (this.wiring.activitySnapshot) return await this.wiring.activitySnapshot(agentId)
    const text = await this.wiring.activityText?.(agentId)
    return text ? { text } : null
  }

  /**
   * Every agent the router knows, as the library pages it. The desktop's closed sessions and per-session
   * status are not ported (cable.md, open point 1): each is `idle`. A local agent's age is its last activity, which
   * the Pro's Recent list is ordered by; another machine's is unknown.
   */
  async playerLibrary(): Promise<PlayerSession[]> {
    const [agents, times] = await Promise.all([this.listAgentsFlat(), this.viaFleet((r) => r.activityTimes())])
    return agents.map((a) => ({ id: a.id, name: a.name, engine: a.engine ?? '', machineId: a.machineId ?? '',
      status: PLAYER_STATES[5], lastActivityAt: times?.get(a.id) ?? null }))
  }

  /** A card arrived from a machine for an agent — see the router's noteAgent. */
  noteAgent(machineId: string, agentId: string): void {
    this.viaFleet((r) => r.noteAgent(machineId, agentId))
  }

  /**
   * EVERY agent in LIST order — this computer first, then each machine in wheel order. The router's flat
   * list, the one ⌘K weighs a typed task against; `listAgents()` is the DIAL's view of the same snapshot,
   * re-cut around the tiles the window has open.
   */
  listAgentsFlat(): Promise<CableAgent[]> {
    return this.viaFleet((r) => r.listAgentsFlat())
  }

  /** Which machine an agent lives on, or '' — never a guess. See the router's machineOf. */
  private machineOf(agentId: string): string {
    return this.viaFleet((r) => r.machineOf(agentId))
  }

  openAgent(agentId: string, reason?: OpenReason): void {
    const machineId = this.machineOf(agentId)
    if (!machineId) {
      // Same rule as focus: an agent id without its machine is not routable, and guessing is how a
      // remote move used to land on a local agent.
      this.wiring.log(`cable: ignored open for unknown agent ${agentId}`)
      return
    }
    this.wiring.log(`cable: open ${machineId}/${agentId} (${reason ?? 'notification'})`)
    this.wiring.opened?.(machineId, agentId, reason)
  }

  form(command: FormCommand): Promise<FormResult> {
    return this.wiring.form?.(command) ?? Promise.resolve({ ok: false, active: false, error: 'Update Harness for New Harness.' })
  }

  visit(command: VisitCommand): Promise<VisitResult> {
    const machineId = command.agentId ? this.machineOf(command.agentId) : undefined
    if ((command.op === 'open' || command.op === 'latest') && !machineId) return Promise.resolve({ ok: false, active: false, error: 'That harness is no longer available.' })
    return this.wiring.visit?.({ ...command, machineId }) ??
      Promise.resolve({ ok: false, active: false, error: 'Update Harness to visit an alert.' })
  }

  /**
   * Fork an agent from the dial: the same `agent_fork` the window sends, on the agent's own machine, and
   * then an `open` for the new agent so the window gives it a tile — the fork's whole point on the dial
   * is "this one, again, beside it", and the person's hand is on the dial, not the mouse.
   */
  forkAgent(agentId: string): Promise<ForkResult> {
    // On the agent's own machine, through the router, which notes the new agent there. A fork it
    // actually asked for is said, and opened in the window.
    return this.viaFleet((r) => r.forkAgent(agentId)).then(({ result, machineId, asked }) => {
      if (!asked) return result
      if (result.ok) {
        this.wiring.log(`cable: fork ${machineId}/${agentId} → ${result.agentId}`)
        if (this.wiring.forked) this.wiring.forked(machineId, result.agentId, agentId)
        else this.wiring.opened?.(machineId, result.agentId)
      } else {
        this.wiring.log(`cable: fork ${machineId}/${agentId} refused (${result.error}${result.detail ? `: ${result.detail}` : ''})`)
      }
      return result
    })
  }

  /** Whether this daemon's last list held that agent — see CableHost.knows. */
  knows(agentId: string): boolean {
    return this.viaFleet((r) => r.knows(agentId))
  }

  /**
   * Deliver a turn, and SAY whether it could be — through the router, on the agent's own machine, with
   * the refusal for a machine whose last request did not come back. See the router's sendTurn.
   */
  sendTurn(agentId: string, text: string): { ok: true } | { ok: false; machine: string; reason: string } {
    return this.viaFleet((r) => r.sendTurn(agentId, text))
  }

  /** Who the last delivered turn went to, and how long ago — by any of the router's callers. */
  lastRouted(): RouterContinuity | undefined {
    return this.viaFleet((r) => r.lastRouted())
  }

  stopTurn(agentId: string): void {
    this.viaFleet((r) => r.stopTurn(agentId))
  }

  canSpeakQuestion(agentId: string): boolean {
    return this.viaFleet((r) => r.canSpeakQuestion(agentId))
  }

  answerReviewed(answer: ReviewedAnswer): Promise<AnswerReceipt> {
    return this.viaFleet((r) => r.answerReviewed(answer))
  }

  answer(agentId: string, requestId: string, answers: Record<string, string>): void {
    this.viaFleet((r) => r.answer(agentId, requestId, answers))
  }


  focus(agentId: string): void {
    // A statement about where the user is looking, and the desktop window follows it: turning the dial to
    // an agent switches the terminal on screen to the same one. The daemon still has no window of its own
    // — it forwards, and the app decides what following means for it.
    // FORWARDED FOR EVERY AGENT, including one running on another computer. That used to be refused on
    // the grounds that there was no window here to move — which stopped being true when the desktop app
    // grew panes for remote machines. The hand is still at THIS desk; the pane it wants in front of it
    // may simply belong to a machine somewhere else, and the app is the side that decides what it can do
    // about an agent it does not have.
    const machineId = this.machineOf(agentId)
    if (!machineId) {
      // An agent id without its machine is not routable. Guessing the selected or local machine is how a
      // remote dial move used to yank the desktop back to a local agent.
      this.wiring.log(`cable: ignored focus for unknown agent ${agentId}`)
      return
    }
    // No edge to name any more: the carousel only walks agents the window already has a tile for, so a
    // focus arriving from the dial is always about a tile that exists. Which tile to REPLACE was the
    // only question the old arcs answered, and there is nothing left to replace.
    this.wiring.log(`cable: focus ${machineId}/${agentId}`)
    this.wiring.focused?.(machineId, agentId)
  }

  /**
   * One tick of the carousel, for a device that has no ring of its own: the paired Autonomous device
   * asks for "next"/"previous" and this picks the neighbour the USB dial's thumb would land on — the same
   * walk (`listAgents()`, the tab in tile order), the same wrap at either end, and the same `focus()`
   * forward to the app. With no current agent on the tab the walk starts at its first (next) or last
   * (previous) tile.
   */
  async stepFocus(direction: 'next' | 'previous', currentAgentId?: string): Promise<{ machineId: string; agentId: string } | 'no_agents'> {
    const walk = (await this.listAgents()).map((a) => a.id)
    if (walk.length === 0) return 'no_agents'
    const at = currentAgentId ? walk.indexOf(currentAgentId) : -1
    const agentId = at < 0
      ? walk[direction === 'next' ? 0 : walk.length - 1]
      : walk[(at + (direction === 'next' ? 1 : walk.length - 1)) % walk.length]
    this.focus(agentId)
    return { machineId: this.machineOf(agentId), agentId }
  }

  scrolled(phase: 'down' | 'move' | 'up', dy: number, velocity: number, superTabId?: string): void {
    // THE ENDS ARE LOGGED, THE MIDDLE IS NOT. A stroke is a `down`, a dozen `move`s and an `up`, several
    // times a second: logging the middle buries every other line in the file. But the failure this
    // protocol is most exposed to is a stroke that never CLOSES — the far side then holds a drag forever
    // and its list stops answering the mouse — and that failure is invisible without a matching pair to
    // look for. Two lines per swipe buys the one thing worth seeing.
    if (phase !== 'move') {

      this.wiring.log(phase === 'down' ? 'cable: scroll ↓' : `cable: scroll ↑ (v=${velocity})`)
    }
    if (superTabId) this.wiring.scrolled?.(phase, dy, velocity, superTabId)
    else this.wiring.scrolled?.(phase, dy, velocity)
  }

  updateAgent(agentId: string, model?: string, effort?: string): void {
    this.viaFleet((r) => r.updateAgent(agentId, model, effort))
  }

  /** The last few turns, newest first, in the shape the dial's tile draws — from the agent's own machine. */
  recentSummaries(agentId: string): Promise<Array<{ recap: string; text: string; ask: string; fullText?: string }>> {
    return this.viaFleet((r) => r.recentSummaries(agentId))
  }

  /** The person's own last questions to an agent, newest first — what the router ranks on. */
  recentAsks(agentId: string): Promise<string[]> {
    return this.viaFleet((r) => r.recentAsks(agentId))
  }

  listModels(agentId: string): Promise<string[]> {
    return this.viaFleet((r) => r.listModels(agentId))
  }

  /**
   * The image to offer, or null for "nothing to do".
   *
   * Null covers four different situations on purpose, because the device reacts to all of them the same
   * way — by carrying on: it is current, it is running a dev build that must not be touched, the manifest
   * is unreachable, or WE DO NOT KNOW WHICH BOARD THIS IS. An update is an opportunity here, never a
   * condition of working.
   *
   * That fourth case is the one with teeth. The manifest has always been per-board, but this call used to
   * take the default key and so always resolved the round dial's entry — harmless while a dial was the
   * only thing that could plug in, and a brick the moment a Pro could: its ESP32-P4 cannot run an
   * ESP32-S3 image, and the cable that would let us put it right is the firmware that just stopped.
   */
  async firmwareFor(runningVersion: string, key: string, keepalive = false): Promise<{ version: string; image: Buffer; sha256: string } | null> {
    if (env.CABLE_FW_DISABLE) return null
    // A plugged-in dial greets every fifteen seconds, and each greeting read the manifest from GCS: 240 GETs
    // an hour per device, with the pets' sync waiting behind each one (2026-10-29). A keepalive is answered
    // from the last good read for half an hour, so a new image reaches a dial already plugged in within that;
    // a new dial, image or connection reads at once. A failed read is not kept, so the next greeting retries.
    const kept = this.releases.get(key)
    let release = keepalive && kept && Date.now() - kept.at < RELEASE_KEEP_MS ? kept.release : null
    if (!release) {
      release = await fetchRelease(env.CABLE_FW_MANIFEST_URL, key)
      if (release) this.releases.set(key, { release, at: Date.now() })
      else this.releases.delete(key)
    }
    if (!release || !shouldOffer(runningVersion, release.version)) return null
    const image = await loadImage(release, join(env.ADAPTER_DATA_DIR, 'firmware'), key)
    if (!image) return null
    return { version: release.version, image, sha256: release.sha256 }
  }

  /**
   * Which agent the spoken words belong to.
   *
   * The daemon's own router: it scores by name and recent activity, and classifies with an engine CLI the
   * machine is ALREADY running when the score cannot separate the top two. No key, no relay, no network —
   * which is the whole reason voice on the cable does not inherit the hosted path's failure modes.
   */
  /**
   * Give the window first refusal on a spoken task.
   *
   * A pass-through by design: everything interesting — whether a window is even attached, the two-phase
   * wait, the deadlines — belongs to the router in windowRoute.ts, which is testable without a socket.
   * This exists so the session can ask through the same host it asks everything else through.
   */
  async routeInWindow(text: string, cmd?: string): Promise<WindowRoute> {
    if (!this.wiring.routeInWindow) return { t: 'unavailable' }
    try {
      return await this.wiring.routeInWindow(text, cmd)
    } catch (err) {
      // Never let a broken window path swallow a sentence a person spoke: fall back to routing here.
      this.wiring.log(`cable: the window route failed (${(err as Error).message}) — routing here`)
      return { t: 'unavailable' }
    }
  }

  async route(transcript: string, agents: CableAgent[]): Promise<RouteDecision> {
    // Each agent's recaps come from ITS OWN machine — recentSummaries routes by agentId. Scored against
    // the wrong machine's history, a spoken turn is routed by what some other computer's agents were last
    // doing, which is both wrong and completely invisible, because the router always answers with
    // something. The machine name travels too, so two agents with the same name on two computers are
    // distinguishable by the only thing that separates them.
    const candidates: RouterAgent[] = await Promise.all(agents.map(async (a) => ({
      id: a.id,
      name: a.name,
      engine: a.engine,
      machine: a.machine,

      // THE QUESTION, not the answer. A recap summarises what the agent replied — "1945." is a correct
      // recap and a useless routing signal, and the next question about the same conversation matches
      // nothing in it.
      //
      // TWO FIELDS, because two routers read this. The backend is sent `prompts` and is told plainly
      // when an agent has none; the local ladder below it still reads `recentSummary`, where a recap
      // standing in for a missing ask is the best it has. Mixing the two into one field is what let a
      // summary of the agent's own replies reach a prompt that called them the person's questions.
      prompts: await this.recentAsks(a.id),
      recentSummary: (await this.recentSummaries(a.id))
        .map((r) => r.ask || r.recap || r.text || '')
        .filter(Boolean)
        .join(' · '),
    })))
    const decision = await routeVoiceTask(transcript, candidates, undefined, undefined, this.lastRouted())
    return { agentId: decision.agentId, confidence: decision.confidence, reason: decision.reason }
  }

  /**
   * Transcribe one capture.
   *
   * The dial records and the daemon transcribes. The device holds no cloud credential and never talks to
   * one; THIS side has an account — `harness login` leaves a real SSO session behind, and the endpoint is
   * gated by it like every other control-plane call.
   *
   * No shared secret, deliberately. This repository is public, so a key baked into it is a key everybody
   * has; a bearer token is issued per person, expires on its own and can be revoked.
   *
   * The 401 retry is not defensive padding. A token can expire between the moment the user pressed the
   * dial's button and the moment the upload finishes — a long dictation is minutes — and losing a spoken
   * sentence to a clock is the one failure the person cannot work around.
   */
  async transcribe(pcm: Buffer, sampleRate: number, lang: string): Promise<string> {
    // The text reaches the dial's glass as a toast, so it is addressed to the person holding it, not to
    // a terminal: signing in happens on the computer, and that is the one thing they need to know.
    const accessToken = this.wiring.accessToken
    if (!accessToken || this.wiring.signedIn?.() === false) throw new Error('Sign in on your computer to use voice')
    const autonomousEnv = this.wiring.environment?.() ?? ''

    const url = `${this.backendHttpBase()}${env.CABLE_STT_PATH}?lang=${encodeURIComponent(lang)}`
    // The WAV is built ONCE: it is the same bytes on a retry, and re-encoding megabytes to say the same
    // thing twice is time taken out of a person's turn.
    const boundary = `harness-${Math.random().toString(36).slice(2)}`
    const body = multipart(wav(pcm, sampleRate), 'voice.wav', 'audio/wav', boundary)

    const post = async (token: string) =>
      fetch(url, {
        method: 'POST',
        headers: {
          authorization: `Bearer ${token}`,
          'x-autonomous-env': autonomousEnv,
          'content-type': `multipart/form-data; boundary=${boundary}`,
        },
        body,
      })

    let token = await accessToken()
    let res = await post(token)
    if (res.status === 401) {
      // `failedToken` is what makes this one refresh rather than a loop: the manager only refreshes when
      // the token that failed is still the current one, so two callers racing a stale token do not each
      // burn a refresh.
      await res.body?.cancel()
      token = await accessToken({ force: true, failedToken: token })
      res = await post(token)
    }
    if (!res.ok) {
      const failure = await transcriptionFailure(res)
      // Keep the backend error category and edge request id, never the audio, transcript, token or raw
      // response. A bare 403 previously disappeared into a device toast with no way to diagnose it.
      this.wiring.log(`cable: stt HTTP ${res.status} code=${failure.code} kind=${failure.kind} request=${failure.request}`)
      throw new Error(failure.message)
    }

    const json = (await res.json()) as { success?: boolean; data?: { transcript?: string }; error?: { message?: string } }
    if (!json.success) throw new Error(json.error?.message ?? 'Transcription failed')
    return json.data?.transcript ?? ''
  }

  /** The control plane, derived from the socket URL the daemon already talks to. */
  private backendHttpBase(): string {
    return env.BACKEND_WS_URL.replace(/\/$/, '').replace(/^wss:/, 'https:').replace(/^ws:/, 'http:')
  }

  log(line: string): void {
    this.wiring.log(line)
  }
}

/** Turn known service failures into short device instructions without reflecting response contents. */
async function transcriptionFailure(res: Response): Promise<{ message: string; code: string; kind: string; request: string }> {
  const contentType = res.headers.get('content-type') ?? ''
  const kind = res.headers.get('cf-mitigated') === 'challenge' ? 'challenge'
    : contentType.includes('application/json') ? 'json' : contentType.includes('text/html') ? 'html' : 'other'
  let code = 'unknown'
  if (contentType.includes('application/json')) {
    const body = await res.json().catch(() => null) as { error?: { code?: unknown } } | null
    const candidate = body?.error?.code
    if (typeof candidate === 'string' && [
      'AUTONOMOUS_ENV_MISMATCH', 'AUTONOMOUS_ENV_NOT_ALLOWED', 'UNAUTHORIZED',
      'AUTH_SERVICE_UNAVAILABLE', 'STT_FAILED', 'BAD_REQUEST',
    ].includes(candidate)) code = candidate
  } else {
    await res.body?.cancel()
  }
  const ray = res.headers.get('cf-ray') ?? ''
  const request = /^[a-f0-9]{16}-[A-Z]{3,8}$/.test(ray) ? ray : 'unknown'
  const message = res.status === 401 || code === 'AUTONOMOUS_ENV_MISMATCH' || code === 'AUTONOMOUS_ENV_NOT_ALLOWED'
    ? 'Sign in again on your computer to use voice'
    : res.status === 403 ? 'Voice service rejected upload (403). Try again'
    : res.status === 429 ? 'Voice service busy. Try again shortly'
    : res.status >= 500 ? 'Voice service unavailable. Try again'
    : `Transcription failed (HTTP ${res.status})`
  return { message, code, kind, request }
}

/**
 * Wrap raw 16-bit little-endian mono PCM in a WAV header.
 *
 * A self-describing container rather than raw samples, and the server depends on it: it forwards the file
 * under its own Content-Type with NO encoding or sample-rate hints, precisely so the container can state
 * its own rate. Headerless PCM would be read as if the first 44 bytes were audio.
 */
export function wav(pcm: Buffer, sampleRate: number): Buffer {
  const header = Buffer.alloc(44)
  header.write('RIFF', 0)
  header.writeUInt32LE(36 + pcm.length, 4)
  header.write('WAVE', 8)
  header.write('fmt ', 12)
  header.writeUInt32LE(16, 16) // fmt chunk size
  header.writeUInt16LE(1, 20) // PCM
  header.writeUInt16LE(1, 22) // mono
  header.writeUInt32LE(sampleRate, 24)
  header.writeUInt32LE(sampleRate * 2, 28) // byte rate: rate * channels * 2
  header.writeUInt16LE(2, 32) // block align
  header.writeUInt16LE(16, 34) // bits per sample
  header.write('data', 36)
  header.writeUInt32LE(pcm.length, 40)
  return Buffer.concat([header, pcm])
}

/**
 * One file as multipart/form-data, in the shape the endpoint's `req.file()` expects.
 *
 * Every newline is CRLF: the format requires it, and a bare \n produces a body some parsers accept and
 * Fastify's does not — surfacing as "Missing audio file" for a request that plainly contains one.
 */
export function multipart(file: Buffer, filename: string, mimeType: string, boundary: string): Buffer {
  const head = Buffer.from(
    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${filename}"\r\n` +
      `Content-Type: ${mimeType}\r\n\r\n`,
    'utf8',
  )
  return Buffer.concat([head, file, Buffer.from(`\r\n--${boundary}--\r\n`, 'utf8')])
}

/**
 * A tool card as one short step line ("Read · cableSession.ts") for a `steps-v1` device's working screen, or null.
 *
 * The working screen otherwise has only the assistant's prose to show, and a turn that is all tool calls
 * has none. A path argument keeps its last segment.
 */
export function cableStepFor(
  frame: { type?: string; agentId?: string; payload?: { kind?: string; text?: string; recap?: string } },
): { agentId: string; step: string } | null {
  if (frame.type !== 'commander_event' || !frame.agentId || frame.payload?.kind !== 'tool') return null
  const tool = (frame.payload.text ?? '').trim()
  if (!tool) return null
  let arg = (frame.payload.recap ?? '').replace(/[\r\n\t]+/g, ' ').trim()
  if (/^[~.]?\/\S+$/.test(arg)) arg = arg.replace(/\/+$/, '').split('/').at(-1) ?? arg
  const step = arg ? `${tool} \u00b7 ${arg}` : tool
  return { agentId: frame.agentId, step: [...step].slice(0, 120).join('') }
}

/**
 * Translate one device-bound `commander_event` into the cable's vocabulary.
 *
 * Returns null for cards the dial has no use for. The kinds are the WiFi device's own, unchanged: a new
 * kind reaches the cable the day it reaches the socket.
 */
export function cableEventFor(
  frame: { type?: string; agentId?: string; payload?: { kind?: string; text?: string; recap?: string; subagent?: unknown; restored?: unknown; update?: unknown; fullText?: unknown; failed?: unknown; tier?: unknown } },
): { kind: 'processing' | 'done' | 'summary' | 'error'; agentId: string; text: string; recap: string; subagent: boolean; update?: string; fullText?: string; failed?: boolean; tier?: Tier } | null {
  if (frame.type !== 'commander_event' || !frame.agentId) return null
  const kind = frame.payload?.kind
  if (kind !== 'processing' && kind !== 'done' && kind !== 'summary' && kind !== 'error') return null
  // `subagent`: a sub-agent's turn end — the tile redraws, nobody is told (CommanderMirrorOpts.isSubagent). A
  // `restored` recap (a turn that ended unseen, CommanderMirror.catchUp) is drawn the same way: history, not news.
  const silent = frame.payload?.subagent === true || frame.payload?.restored === true
  const update = frame.payload?.update
  const fullText = frame.payload?.fullText
  // `tier`: how loudly the turn tells, decided once by the recaps (services/recaps.ts) for every screen.
  const tier = frame.payload?.tier
  return { kind, agentId: frame.agentId, text: frame.payload?.text ?? '', recap: frame.payload?.recap ?? '', subagent: silent,
    ...(kind === 'processing' && typeof update === 'string' ? { update } : {}),
    ...(kind === 'summary' && frame.payload?.failed === true ? { failed: true } : {}),
    ...(kind === 'summary' && typeof fullText === 'string' && fullText ? { fullText } : {}),
    ...(kind === 'summary' && isTier(tier) ? { tier } : {}) }
}

/**
 * Translate one device-bound `commander_question` into the dial's `question`.
 *
 * A sibling of `cableEventFor` rather than a branch inside it, because the shapes have nothing in common
 * — this one carries a requestId and an option list, not a card. Until this existed the dial's whole
 * question screen was complete, wired and unreachable: nothing on this side ever produced the message.
 */
export function cableQuestionFor(
  frame: { type?: string; agentId?: string; payload?: { requestId?: string; questions?: unknown; superTab?: unknown; attention?: unknown } },
): { agentId: string; requestId: string; questions: unknown; superTab?: SuperTabAsk } | null {
  if (frame.type !== 'commander_question' || !frame.agentId) return null
  const requestId = frame.payload?.requestId
  const questions = frame.payload?.questions
  if (typeof requestId !== 'string' || !requestId || !Array.isArray(questions)) return null
  // A Super Tab member waiting on a person (superTabs/inCore/attention.ts): the tab's name and what it needs ride along.
  const superTab = frame.payload?.superTab, attention = frame.payload?.attention
  const tab = typeof superTab === 'string' && superTab && (attention === 'decision' || attention === 'stuck') ? { superTab, attention } as SuperTabAsk : null
  return { agentId: frame.agentId, requestId, questions, ...(tab ? { superTab: tab } : {}) }
}

/**
 * Translate one device-bound `commander_question_close` into the dial's `question.close`.
 *
 * The other half of `cableQuestionFor`. A question is a TUI dialog in a pane, not a server-side object,
 * so "somebody answered it" reaches this daemon as "the dialog is no longer on the pane" — and every
 * client still drawing it has to be told, or it sits waiting for an answer nobody can give any more.
 */
export function cableQuestionCloseFor(
  frame: { type?: string; agentId?: string; payload?: { requestId?: string } },
): { agentId: string; requestId: string } | null {
  if (frame.type !== 'commander_question_close' || !frame.agentId) return null
  const requestId = frame.payload?.requestId
  if (typeof requestId !== 'string' || !requestId) return null
  return { agentId: frame.agentId, requestId }
}