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.

44.4 KB
Raw Blame
import { DeviceResultPayloadSchema } from './resultContract.js'
import { DeviceResultEvidence, inputHash, type ResultEvidence } from './resultEvidence.js'
import type { DeviceResultJournal } from './resultJournal.js'
import type { DeviceInputStatus } from '../../core/deviceInput.js'
import type { AutonomousDeviceStore } from './store.js'
import { DEVICE_STORE_CAPABILITIES, DeviceStoreError } from './storeContract.js'
import { DEVICE_ADDON_CAPABILITIES, DeviceAddonError, DeviceAddons } from './addons.js'
import { createHash, randomUUID } from 'node:crypto'
import type { LiveEvent } from '../normalize.js'
import { AgentStreams, STREAM_KINDS, STREAM_TTL_DEFAULT_SEC, STREAM_TTL_MAX_SEC, StreamRequestError, type StreamKind } from './stream.js'

export type AutonomousDeviceFrame = Record<string, unknown> & { type: string }
export type ReceiptState = 'queued' | 'delivered' | 'started' | 'completed' | 'rejected' | 'unknown'
export interface AutonomousDeviceReceipt {
  idempotencyKey: string; deliveryId: string; operation: string; state: ReceiptState
  agentId: string; machineId: string; serverInstanceId: string; turnId: string | null
  input?: Pick<DeviceInputStatus, 'mode' | 'phase'>
  error: { code: string; message: string } | null; at: number
}
export interface AutonomousDeviceAgent { agentId: string; name: string; engine: string; state: string; packageId?: string | null; workspace?: string | null; runtime?: string }

const AGENT_RECAP_MAX_CHARS = 200
export interface AutonomousDeviceDelivery { deliveryId: string; sessionId: string; state: ReceiptState; reason?: string }
export interface AutonomousDeviceServiceOptions {
  resultJournal?: Pick<DeviceResultJournal, 'load' | 'save'> & Partial<Pick<DeviceResultJournal, 'archive'>>
  inputConsumed?: (agentId: string, text: string) => void
  store?: AutonomousDeviceStore
  machineId: string; serverInstanceId?: string; now?: () => number
  agents: () => AutonomousDeviceAgent[]
  requestAppFocus?: (agentId: string, expiresAt: number, focusRevision: string) => boolean
  /**
   * Turn the app's focus one agent along the desk, the way the USB dial does — same ring, same wrap,
   * same `dial_focus` forward. Resolves to the agent it asked the app to show; the app's own `app_focus`
   * acknowledgment is what makes the move real. `'no_app'` when no Desktop window is connected.
   */
  stepFocus?: (direction: 'next' | 'previous', currentAgentId: string | undefined) => Promise<{ machineId: string; agentId: string } | 'no_agents' | 'no_app'>
  /**
   * One piece of a finger stroke for the focused terminal's scrollback, the way the USB dial's glass
   * reports it — same `dial_scroll` forward, the terminal does the arithmetic. `false` when no Desktop
   * window is connected to scroll.
   */
  scroll?: (phase: 'down' | 'move' | 'up', dy: number, velocity: number) => boolean
  /** Settles once the pane's lock has taken the prompt: the reply carries what it said of it meanwhile. */
  submit: (agentId: string, text: string, deliveryId: string) => void | Promise<void>
  cancelDelivery: (deliveryId: string) => boolean
  stop: (agentId: string) => Promise<boolean>
  answer: (agentId: string, questionRequestId: string, answers: Record<string, string>) => Promise<boolean>
  /** A promise when the turns are asked of the core from another process (services/wifi.ts). */
  recent: (agentId: string, n: number) => unknown[] | Promise<unknown[]>
  /**
   * The newest turn's COMPLETE final answer for an agent, or undefined.
   *
   * Read here rather than taken off the `commander_event` payload on purpose. That frame is broadcast to
   * every device on the account, and the USB dial's own encoder throws above an 8 KiB payload
   * (cable/cableFrame.ts) — widening the shared card to serve one consumer would put a limit nobody
   * looks at between the dial and its turn cards.
   */
  fullText?: (agentId: string) => string | undefined
  /** `deviceId` set: this frame is for that paired device alone (an agent stream), never a broadcast. */
  emit?: (frame: AutonomousDeviceFrame, deviceId?: string) => void
}
interface Entry { deviceId: string; digest: string; receipt: AutonomousDeviceReceipt
  promptHash?: string; reservedAt?: number; dispatchedAt?: number; sessionId?: string; evidenceManaged?: boolean; consumed?: boolean
}
interface ResultRecord { deviceId: string; evidenceId: string; at: number; agentId: string; payload: Record<string, unknown> }
const CAPABILITIES = ['focus.get', 'focus.ensure', 'focus.step', 'scroll', 'agents.list', 'turn.send', 'turn.stop', 'status', 'recap', 'question.answer', 'receipt.get', 'agent.subscribe', 'agent.unsubscribe'] as const
export const AUTONOMOUS_DEVICE_CAPABILITIES: string[] = [...CAPABILITIES]
const MUTATIONS = new Set(['turn.send', 'turn.stop', 'question.answer'])
const STEP_RESULTS_MAX = 512
const SCROLL_PHASES = new Set(['down', 'move', 'up'])
/** Device pixels per report and px/s: generous for any glass, tight enough that a bad value cannot fling a terminal for minutes. */
const SCROLL_DY_MAX = 4096
const SCROLL_VELOCITY_MAX = 100_000
const APP_FOCUS_WAIT_MS = 2000
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
const KEY = /^[A-Za-z0-9_-]{1,64}$/
const TTL = 30 * 60_000
function canonical(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
  if (value && typeof value === 'object') return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`
  return JSON.stringify(value)
}
class RequestError extends Error { constructor(readonly code: string, message: string) { super(message) } }
function fail(code: string, message: string): never { throw new RequestError(code, message) }
function object(value: unknown): value is Record<string, unknown> { return !!value && typeof value === 'object' && !Array.isArray(value) }

/** Pure local-agent facade. Transport authenticates identity; this layer never guesses a target. */
export class AutonomousDeviceService {
  readonly serverInstanceId: string
  private readonly now: () => number
  private readonly entries = new Map<string, Entry>()
  private readonly deliveries = new Map<string, Entry>()
  private readonly turns = new Map<string, Entry>()
  // Transcript adapters expose session boundaries, not engine input/turn IDs. Once
  // inputs overlap, a session-wide done cannot prove which request finished.
  private readonly ambiguousTurns = new Set<string>()
  private readonly openTurns = new Set<string>()
  private readonly pendingStarts = new Set<string>()
  private readonly questions = new Map<string, { requestId: string; questions: unknown; permission?: { dialog: string; resolution: 'desktop' } }>()
  private events: AutonomousDeviceFrame[] = []
  private sequence = 0
  private readonly results = new Map<string, ResultRecord>()
  private readonly transcriptSessions = new Map<string, string>()
  private readonly transcriptAgents = new Set<string>()
  private readonly evidence = new DeviceResultEvidence(
    (agent, text, at) => this.consumeInput(agent, text, at),
    (agent, evidence) => this.recordResult(agent, evidence),
    (agent, ids) => this.evidenceUnknown(agent, ids),
  )
  /** Cheap no-op for ordinary app/orchestrator agents; only dispatched Device work opts in. */
  needsTranscript(agentId: string, sessionId: string, engine: string): boolean {
    if (!this.transcriptAgents.has(agentId) || !['claude', 'codex'].includes(engine)) return false
    let pending = false
    for (const entry of this.deliveries.values()) {
      if (!entry.evidenceManaged || entry.receipt.agentId !== agentId
        || entry.receipt.serverInstanceId !== this.serverInstanceId || entry.dispatchedAt === undefined
        || ['completed', 'rejected'].includes(entry.receipt.state)) continue
      pending = true
      if (!entry.sessionId || entry.sessionId === sessionId) return true
    }
    if (!pending) {
      this.transcriptAgents.delete(agentId)
      this.transcriptSessions.delete(agentId)
      this.evidence.forget(agentId)
    }
    return false
  }
  /** Whether it still reads this agent's transcript: the core sends its lines only while it does (core/wifi.ts). */
  watchesTranscript(agentId: string): boolean { return this.transcriptAgents.has(agentId) }
  /** The agents whose transcripts it reads. */
  transcriptWatches(): string[] { return [...this.transcriptAgents] }
  observeTranscript(agentId: string, sessionId: string, engine: string, line: string): void {
    if (!this.needsTranscript(agentId, sessionId, engine)) return
    if (this.transcriptSessions.get(agentId) !== sessionId) {
      this.evidence.forget(agentId)
      this.transcriptSessions.set(agentId, sessionId)
    }
    this.evidence.ingest(agentId, engine, line)
  }
  inputDispatched(agentId: string, deliveryId: string, text: string, sessionId?: string): void {
    const entry = this.deliveries.get(deliveryId)
    if (!entry?.evidenceManaged || entry.receipt.agentId !== agentId || entry.receipt.serverInstanceId !== this.serverInstanceId || entry.dispatchedAt !== undefined) return
    entry.promptHash = inputHash(text) // exact engine input after slash-command adaptation
    entry.dispatchedAt = this.now()
    entry.sessionId = sessionId || this.transcriptSessions.get(agentId)
    this.persist()
    this.transcriptAgents.add(agentId)
  }
  private consumeInput(agentId: string, text: string, timestamp: number): string | null {
    if (!Number.isFinite(timestamp)) return null
    const hash = inputHash(text)
    const candidates = [...this.entries.values()].filter(e => e.evidenceManaged && !e.consumed
      && (!e.sessionId || e.sessionId === this.transcriptSessions.get(agentId))
      && e.receipt.agentId === agentId && e.receipt.serverInstanceId === this.serverInstanceId
      && !['completed', 'rejected'].includes(e.receipt.state) && e.promptHash === hash && timestamp >= (e.dispatchedAt ?? Infinity))
    // Identical unresolved text cannot be disambiguated using a transcript timestamp alone.
    if (candidates.length !== 1) { this.evidenceUnknown(agentId, candidates.map(e => e.receipt.deliveryId)); return null }
    const entry = candidates[0]
    entry.consumed = true
    this.options.inputConsumed?.(agentId, text)
    this.update(entry, 'started')
    return entry.receipt.deliveryId
  }
  private evidenceUnknown(agentId: string, ids: string[]): void {
    for (const id of ids) {
      const entry = this.deliveries.get(id)
      if (entry?.receipt.agentId === agentId) this.update(entry, 'unknown', 'RESULT_EVIDENCE_MISSING')
    }
  }
  private recordResult(agentId: string, evidence: ResultEvidence): void {
    const evidenceId = `${agentId}:${this.transcriptSessions.get(agentId)}:${evidence.evidenceId}`
    if (this.results.has(evidenceId)) return
    const entries = evidence.inputs.map(id => this.deliveries.get(id))
    const first = entries[0]
    if (!first || entries.some(e => !e || !e.consumed || e.receipt.agentId !== agentId
      || e.deviceId !== first.deviceId || e.receipt.serverInstanceId !== this.serverInstanceId
      || ['completed', 'rejected'].includes(e.receipt.state))) {
      this.evidenceUnknown(agentId, evidence.inputs); return
    }
    this.prune()
    if (entries.length > 64 || this.results.size >= 512 || Buffer.byteLength(evidence.fullText) > 128 * 1024) {
      this.evidenceUnknown(agentId, evidence.inputs); return
    }
    const payload = DeviceResultPayloadSchema.parse({ serverInstanceId: this.serverInstanceId, resultId: randomUUID(),
      correlation: { scope: entries.length === 1 ? 'input' : 'group',
        inputs: entries.map(e => ({ deliveryId: e!.receipt.deliveryId, idempotencyKey: e!.receipt.idempotencyKey })),
        ...(evidence.engineTurnId ? { engineTurnId: evidence.engineTurnId } : {}) },
      outcome: evidence.outcome, fullText: evidence.fullText, kind: 'summary',
      text: evidence.fullText.replace(/\s+/g, ' ').trim().slice(0, AGENT_RECAP_MAX_CHARS),
      ...(entries.length === 1 ? { idempotencyKey: first.receipt.idempotencyKey, turnId: first.receipt.turnId } : {}) })
    if (Buffer.byteLength(JSON.stringify(payload)) > 32 * 1024) { this.evidenceUnknown(agentId, evidence.inputs); return }
    this.results.set(evidenceId, { deviceId: first.deviceId, evidenceId, agentId, at: this.now(), payload })
    // Commit the immutable result and all its proven receipts together before publishing anything.
    const previous = entries.map(e => structuredClone(e!.receipt))
    for (const entry of entries) {
      entry!.receipt.state = evidence.outcome === 'completed' ? 'completed' : 'unknown'
      entry!.receipt.error = evidence.outcome === 'completed' ? null : { code: 'RESULT_NOT_COMPLETED', message: evidence.outcome }
      entry!.receipt.at = this.now()
    }
    try { this.persist() } catch (error) {
      this.results.delete(evidenceId)
      entries.forEach((entry, i) => { entry!.receipt = previous[i] })
      throw error
    }
    // Retain the result envelope before any network callback can fail.
    this.event('turn.summary', agentId, payload)
    for (const entry of entries) this.event('receipt.updated', agentId, { receipt: structuredClone(entry!.receipt), idempotencyKey: entry!.receipt.idempotencyKey })
  }
  canSendResult(deviceId: string, frame: AutonomousDeviceFrame): boolean {
    const payload = frame.payload as Record<string, unknown> | undefined
    return [...this.results.values()].some(r => r.deviceId === deviceId && r.agentId === frame.agentId
      && r.payload.resultId === payload?.resultId && canonical(r.payload) === canonical(payload) && r.at >= this.now() - TTL)
  }
  private persist(): void {
    this.options.resultJournal?.save({ version: 1, machineId: this.options.machineId,
      entries: [...this.entries.values()], results: [...this.results.values()] })
  }
  private focusOwner: string | undefined
  private focused: { machineId: string; agentId: string } | null = null
  private focusCounter = 0
  /** Only explicit app focus updates own this state; disconnects cannot clear a newer owner. */
  appFocus(machineId: string, agentId: string | null, connId: string): void {
    if (agentId === null && this.focusOwner !== connId) return
    if (machineId === this.options.machineId && agentId !== null && !this.options.agents().some(a => a.agentId === agentId)) agentId = null
    this.focusOwner = agentId === null ? undefined : connId
    if (agentId === null ? this.focused === null : this.focused?.machineId === machineId && this.focused?.agentId === agentId) return
    this.focused = agentId === null ? null : { machineId, agentId }
    this.focusCounter++
    this.event('focus.changed', undefined, this.focusSnapshot())
  }
  focusSnapshot(): { focus: { machineId: string; agentId: string; name?: string } | null; focusRevision: string } {
    const local = this.focused?.machineId === this.options.machineId
    const agent = local ? this.options.agents().find(a => a.agentId === this.focused?.agentId) : undefined
    if (local && !agent) {
      this.focused = null
      this.focusOwner = undefined
      this.focusCounter++
      const snapshot = { focus: null, focusRevision: `${this.serverInstanceId}:${this.focusCounter}` }
      this.event('focus.changed', undefined, snapshot)
      return snapshot
    }
    return { focus: this.focused ? { ...this.focused, ...(agent ? { name: agent.name } : {}) } : null,
      focusRevision: `${this.serverInstanceId}:${this.focusCounter}` }
  }
  private ensuringFocus: Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> | undefined
  /** Settled `focus.step` outcomes by (device, idempotencyKey): a retried gesture is one tick, not two. */
  private readonly steps = new Map<string, { deviceId: string; digest: string; result: Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> }>()

  private stepFocus(deviceId: string, req: Record<string, unknown>): Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> {
    if (req.direction !== 'next' && req.direction !== 'previous') fail('INVALID_REQUEST', 'direction must be next or previous')
    if (!KEY.test(String(req.idempotencyKey ?? ''))) fail('INVALID_REQUEST', 'Invalid idempotencyKey')
    if (typeof req.focusRevision !== 'string' || !req.focusRevision) fail('INVALID_REQUEST', 'focusRevision must be a nonempty string')
    const digest = createHash('sha256').update(canonical({ ...req, requestId: null, idempotencyKey: null })).digest('hex')
    const key = this.key(deviceId, String(req.idempotencyKey))
    const previous = this.steps.get(key)
    if (previous) {
      if (previous.digest !== digest) fail('IDEMPOTENCY_CONFLICT', 'Key already belongs to a different operation or payload')
      return previous.result
    }
    const result = this.performStep(req.direction, req.focusRevision)
    result.catch(() => undefined) // settled either way; the retry re-awaits it
    this.steps.set(key, { deviceId, digest, result })
    // ponytail: FIFO eviction, no TTL — a step result is a snapshot, nothing waits on it like a receipt.
    if (this.steps.size > STEP_RESULTS_MAX) this.steps.delete(this.steps.keys().next().value as string)
    return result
  }

  private async performStep(direction: 'next' | 'previous', focusRevision: string): Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> {
    const before = this.focusSnapshot()
    if (focusRevision !== before.focusRevision) fail('FOCUS_CHANGED', 'App focus changed before the step; nothing was moved')
    if (!this.options.stepFocus) fail('FOCUS_UNAVAILABLE', 'Stepping focus is not wired on this machine')
    const target = await this.options.stepFocus(direction, before.focus?.agentId)
    if (target === 'no_agents') fail('NO_AGENTS', 'No agent is on the desk to step to')
    if (target === 'no_app') fail('FOCUS_UNAVAILABLE', 'Open Harness Desktop to select an agent')
    // A desk of one: the only neighbour is the agent already in front — nothing to move, nothing to await.
    if (before.focus?.machineId === target.machineId && before.focus.agentId === target.agentId) return before
    return this.waitForAppFocus(Date.now() + APP_FOCUS_WAIT_MS, s => s.focusRevision !== before.focusRevision)
  }

  /**
   * A stroke is a stream, not a mutation: no idempotency key, no receipt, nothing retained. A lost `move`
   * is a shorter scroll; a lost `up` is what the next `down` closes on the app side, as for the dial.
   */
  private scroll(req: Record<string, unknown>): void {
    const phase = req.phase
    if (typeof phase !== 'string' || !SCROLL_PHASES.has(phase)) fail('INVALID_REQUEST', 'phase must be down, move or up')
    const dy = req.dy ?? 0, velocity = req.velocity ?? 0
    if (!Number.isInteger(dy) || Math.abs(dy as number) > SCROLL_DY_MAX) fail('INVALID_REQUEST', `dy must be an integer within ±${SCROLL_DY_MAX}`)
    if (!Number.isInteger(velocity) || Math.abs(velocity as number) > SCROLL_VELOCITY_MAX) fail('INVALID_REQUEST', `velocity must be an integer within ±${SCROLL_VELOCITY_MAX}`)
    if (!this.options.scroll) fail('FOCUS_UNAVAILABLE', 'Scrolling is not wired on this machine')
    if (!this.options.scroll(phase as 'down' | 'move' | 'up', dy as number, velocity as number)) fail('FOCUS_UNAVAILABLE', 'Open Harness Desktop to scroll a terminal')
  }

  /** Enable-time fallback only. The desktop must acknowledge its selected pane. */
  private ensureFocus(): Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> {
    const current = this.focusSnapshot()
    if (current.focus) return Promise.resolve(current)
    if (this.ensuringFocus) return this.ensuringFocus
    const first = this.options.agents()[0]
    if (!first) fail('NO_AGENTS', 'No local agent is available')
    const expiresAt = Date.now() + APP_FOCUS_WAIT_MS
    if (!this.options.requestAppFocus?.(first.agentId, expiresAt, current.focusRevision)) {
      fail('FOCUS_UNAVAILABLE', 'Open Harness Desktop to select an agent')
    }
    this.ensuringFocus = this.waitForAppFocus(expiresAt, s => !!s.focus).finally(() => { this.ensuringFocus = undefined })
    return this.ensuringFocus
  }

  private async waitForAppFocus(expiresAt: number, done: (s: ReturnType<AutonomousDeviceService['focusSnapshot']>) => boolean): Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> {
    for (;;) {
      const snapshot = this.focusSnapshot()
      if (done(snapshot)) return snapshot
      if (Date.now() >= expiresAt) fail('FOCUS_UNAVAILABLE', 'Harness Desktop did not acknowledge focus')
      await new Promise(resolve => setTimeout(resolve, 20))
    }
  }
  constructor(private readonly options: AutonomousDeviceServiceOptions) {
    this.serverInstanceId = options.serverInstanceId ?? randomUUID()
    this.now = options.now ?? Date.now
    this.streams = new AgentStreams({ machineId: options.machineId, serverInstanceId: this.serverInstanceId,
      send: (deviceId, frame) => this.options.emit?.(frame, deviceId) })
    this.addons = new DeviceAddons({ machineId: options.machineId, serverInstanceId: this.serverInstanceId,
      send: (deviceId, frame) => this.options.emit?.(frame, deviceId), now: this.now })
    let snapshot = options.resultJournal?.load()
    // Written on this computer under ANOTHER machine id: a sign-in to another account, a switch of
    // backend, a machine re-registered. Its dedupe cannot apply here — every request naming that
    // machine is refused as MACHINE_MISMATCH before a reservation is looked up — so it is set aside,
    // not trusted and not treated as corruption. Throwing here kept the whole daemon in safe mode
    // after a legitimate identity change, with every terminal on this computer down with it.
    if (object(snapshot) && typeof snapshot.machineId === 'string' && snapshot.machineId
      && snapshot.machineId !== options.machineId) {
      const owner = snapshot.machineId
      // Keeping a copy is a courtesy to a switch back; failing to keep one must not bring back the very
      // start-up failure this avoids. The fresh journal's first save replaces the file either way.
      let kept: string | undefined
      try { kept = options.resultJournal?.archive?.(owner) } catch { /* not kept */ }
      console.log(`[device] result journal belongs to machine ${owner.slice(0, 8)} — ${kept ? `kept as ${kept}` : 'discarded'}, starting fresh`)
      snapshot = undefined
    }
    if (snapshot !== undefined) {
      if (!object(snapshot) || snapshot.version !== 1 || snapshot.machineId !== options.machineId
        || !Array.isArray(snapshot.entries) || !Array.isArray(snapshot.results)) throw new Error('Invalid Device result journal; refusing to lose delivery dedupe')
      for (const entry of snapshot.entries as Entry[]) {
        if (!entry.deviceId || !entry.digest || !entry.receipt?.deliveryId || !entry.receipt.idempotencyKey) throw new Error('Invalid Device receipt journal')
        if (!['completed', 'rejected'].includes(entry.receipt.state)) {
          entry.receipt.state = 'unknown'; entry.receipt.error = { code: 'DAEMON_RESTART', message: 'Reconcile original delivery; never resend automatically' }
        }
        this.entries.set(this.key(entry.deviceId, entry.receipt.idempotencyKey), entry)
        this.deliveries.set(entry.receipt.deliveryId, entry)
      }
      for (const record of snapshot.results as ResultRecord[]) {
        if (!record.deviceId || !record.evidenceId || !record.payload?.resultId) throw new Error('Invalid Device result journal')
        this.results.set(record.evidenceId, record)
      }
      this.prune()
      this.persist()
      // New transport instance/sequence; immutable payload retains its originating instance.
      for (const record of this.results.values()) this.retainEvent('turn.summary', record.agentId, record.payload)
    }
  }
  private readonly streams: AgentStreams
  /** What devices publish for this computer's agents, and the proposals the agents send back (addons.ts). */
  readonly addons: DeviceAddons
  /** Live events of one agent, for its subscribers only. Never recorded in the replay log. */
  stream(agentId: string, events: readonly LiveEvent[]): void { this.streams.ingest(agentId, events) }
  /** The agents a device subscribed to: the core sends their tools' events too (core/wifi.ts). */
  streamedAgents(): string[] { return this.streams.agents() }
  /** The device's last link closed: its subscriptions end with it, and a reconnect subscribes again. */
  deviceOffline(deviceId: string): void { this.streams.dropDevice(deviceId); this.addons.offline(deviceId) }

  private subscription(deviceId: string, type: 'agent.subscribe' | 'agent.unsubscribe', req: Record<string, unknown>): Record<string, unknown> {
    const fields = type === 'agent.subscribe' ? ['type', 'requestId', 'machineId', 'agentId', 'ttlSec', 'include'] : ['type', 'requestId', 'subscriptionId']
    if (Object.keys(req).some(k => !fields.includes(k))) fail('INVALID_REQUEST', 'Unknown request field')
    if (type === 'agent.unsubscribe') {
      if (!UUID.test(String(req.subscriptionId))) fail('INVALID_REQUEST', 'subscriptionId must be a UUIDv4')
      return { unsubscribed: this.streams.unsubscribe(deviceId, String(req.subscriptionId)) }
    }
    if (typeof req.agentId !== 'string' || !req.agentId || typeof req.machineId !== 'string') fail('MISSING_TARGET', 'machineId and agentId are required')
    if (req.machineId !== this.options.machineId) fail('MACHINE_MISMATCH', 'Only the paired machine is available')
    const ttlSec = req.ttlSec ?? STREAM_TTL_DEFAULT_SEC
    if (!Number.isInteger(ttlSec) || (ttlSec as number) < 1 || (ttlSec as number) > STREAM_TTL_MAX_SEC) fail('INVALID_REQUEST', `ttlSec must be an integer from 1 to ${STREAM_TTL_MAX_SEC}`)
    const include = req.include ?? STREAM_KINDS
    if (!Array.isArray(include) || !include.length || new Set(include).size !== include.length
      || include.some(k => !(STREAM_KINDS as readonly unknown[]).includes(k))) fail('INVALID_REQUEST', `include must be distinct values of ${STREAM_KINDS.join(', ')}`)
    const agentId = req.agentId
    if (!this.options.agents().some(a => a.agentId === agentId)) fail('AGENT_NOT_FOUND', 'Agent is not available on the paired machine')
    try {
      return { machineId: this.options.machineId, agentId, include, ...this.streams.subscribe(deviceId, agentId, ttlSec as number, new Set(include as StreamKind[])) }
    } catch (e) {
      if (e instanceof StreamRequestError) fail(e.code, e.message)
      throw e
    }
  }
  private key(deviceId: string, key: string): string { return `${deviceId}:${key}` }
  /** The newest `recap` turn's headline for an agent, or undefined when no turn has been summarised. */
  private async latestRecap(agentId: string): Promise<string | undefined> {
    const first = (await this.options.recent(agentId, 1))[0]
    const recap = object(first) && typeof first.recap === 'string' ? first.recap.replace(/\s+/g, ' ').trim() : ''
    return recap ? recap.slice(0, AGENT_RECAP_MAX_CHARS) : undefined
  }
  receipt(deviceId: string, key: string): AutonomousDeviceReceipt | null {
    this.prune()
    const value = this.entries.get(this.key(deviceId, key))?.receipt
    return value ? structuredClone(value) : null
  }
  private prune(): void {
    for (const [key, result] of this.results) if (this.now() - result.at > TTL) this.results.delete(key)
    for (const [key, entry] of this.entries) {
      if (['completed', 'rejected'].includes(entry.receipt.state) && this.now() - entry.receipt.at > TTL) {
        this.entries.delete(key); this.deliveries.delete(entry.receipt.deliveryId)
      }
    }
  }
  private reserveCapacity(): void {
    if (this.entries.size < 512) return
    // Evict only settled work. Dropping a live/ambiguous reservation permits duplicate execution.
    let oldest: [string, Entry] | undefined
    for (const candidate of this.entries) {
      if (!['completed', 'rejected'].includes(candidate[1].receipt.state)) continue
      if (!oldest || candidate[1].receipt.at < oldest[1].receipt.at) oldest = candidate
    }
    if (!oldest) fail('BACKPRESSURE', 'Receipt capacity contains unresolved work; reconcile before sending more')
    this.entries.delete(oldest[0]); this.deliveries.delete(oldest[1].receipt.deliveryId)
  }
  private update(entry: Entry, state: ReceiptState, code?: string): void {
    if (['completed', 'rejected'].includes(entry.receipt.state)) return
    if ((state === 'delivered' || state === 'started') && entry.receipt.state === 'started') return
    entry.receipt.state = state
    entry.receipt.at = this.now()
    entry.receipt.error = code ? { code, message: code === 'NOT_CONFIRMED' ? 'Delivery could not be confirmed; inspect the agent before retrying.' : code } : null
    if (state === 'started') entry.receipt.turnId ??= randomUUID()
    if (state === 'started' && !entry.evidenceManaged) {
      const agentId = entry.receipt.agentId
      const previous = this.turns.get(agentId)
      if (this.openTurns.has(agentId) || this.ambiguousTurns.has(agentId) || (previous && previous !== entry)) {
        this.ambiguousTurns.add(agentId)
        this.turns.delete(agentId)
        if (previous) this.update(previous, 'unknown', 'OVERLAPPING_INPUTS')
        this.update(entry, 'unknown', 'OVERLAPPING_INPUTS')
        return
      }
      this.turns.set(agentId, entry)
      this.pendingStarts.add(agentId)
    }
    this.event('receipt.updated', entry.receipt.agentId, { receipt: structuredClone(entry.receipt), idempotencyKey: entry.receipt.idempotencyKey })
  }
  agentGone(agentId: string): void {
    this.transcriptAgents.delete(agentId)
    this.evidence.forget(agentId)
    this.transcriptSessions.delete(agentId)
    this.turns.delete(agentId)
    this.openTurns.delete(agentId)
    this.pendingStarts.delete(agentId)
    this.ambiguousTurns.delete(agentId)
    for (const entry of this.deliveries.values()) {
      if (entry.receipt.agentId === agentId && entry.receipt.operation === 'turn.send'
        && !['completed', 'rejected'].includes(entry.receipt.state)) this.update(entry, 'unknown', 'AGENT_GONE')
    }
  }
  inputStatus(event: DeviceInputStatus): void {
    const entry = this.deliveries.get(event.deliveryId)
    if (!entry || entry.receipt.agentId !== event.sessionId) return
    if (['completed', 'rejected'].includes(entry.receipt.state)) return
    entry.receipt.input = { mode: event.mode, phase: event.phase }
    this.event('receipt.updated', event.sessionId, { receipt: structuredClone(entry.receipt), idempotencyKey: entry.receipt.idempotencyKey })
  }
  delivery(event: AutonomousDeviceDelivery): void {
    const entry = this.deliveries.get(event.deliveryId)
    if (!entry || entry.receipt.agentId !== event.sessionId) return
    this.update(entry, event.state, event.reason)
  }
  revoke(deviceId: string): void {
    this.options.store?.revoke(deviceId)
    for (const [key, entry] of this.entries) if (entry.deviceId === deviceId) {
      this.options.cancelDelivery(entry.receipt.deliveryId)
      this.deliveries.delete(entry.receipt.deliveryId)
      if (this.turns.get(entry.receipt.agentId) === entry) this.turns.delete(entry.receipt.agentId)
      this.entries.delete(key)
    }
    for (const [key, step] of this.steps) if (step.deviceId === deviceId) this.steps.delete(key)
    this.streams.dropDevice(deviceId)
    this.addons.revoke(deviceId)
    for (const [key, result] of this.results) if (result.deviceId === deviceId) this.results.delete(key)
    this.persist()
    // A newly paired identity cannot replay the previous device's request receipts.
    this.events = []
  }
  private retainEvent(kind: string, agentId: string | undefined, payload: Record<string, unknown>): AutonomousDeviceFrame {
    const frame: AutonomousDeviceFrame = { type: 'event', eventId: ++this.sequence, serverInstanceId: this.serverInstanceId,
      machineId: this.options.machineId, ...(agentId ? { agentId } : {}), kind, payload: structuredClone(payload) }
    this.events.push(frame)
    if (this.events.length > 500) this.events.shift()
    return frame
  }
  event(kind: string, agentId: string | undefined, payload: Record<string, unknown>): void {
    if (kind === 'receipt.updated') this.persist()
    const frame = this.retainEvent(kind, agentId, payload)
    this.options.emit?.(structuredClone(frame))
  }
  resume(resume?: { serverInstanceId?: unknown; cursor?: unknown }): { resumed: boolean; cursor: number } {
    const cursor = resume?.cursor
    return { resumed: resume?.serverInstanceId === this.serverInstanceId && Number.isSafeInteger(cursor)
      && (cursor as number) >= (Number(this.events[0]?.eventId ?? this.sequence + 1) - 1) && (cursor as number) <= this.sequence,
    cursor: this.sequence }
  }
  replay(resume: { serverInstanceId?: unknown; cursor?: unknown } | undefined, send: (frame: AutonomousDeviceFrame) => unknown): void {
    if (!this.resume(resume).resumed) {
      send({ type: 'resync', reason: resume?.serverInstanceId === this.serverInstanceId ? 'cursor_too_old' : 'instance_changed', serverInstanceId: this.serverInstanceId, cursor: this.sequence })
      // Reconcile immutable retained results even when the ordinary event cursor expired.
      for (const record of this.results.values()) if (record.at >= this.now() - TTL) send(this.retainEvent('turn.summary', record.agentId, structuredClone(record.payload)))
      return
    }
    for (const event of this.events) if (Number(event.eventId) > Number(resume?.cursor)) send(structuredClone(event))
  }
  turnStarted(agentId: string): void {
    this.openTurns.add(agentId)
    if (!this.pendingStarts.delete(agentId)) {
      const previous = this.turns.get(agentId)
      if (previous) {
        this.turns.delete(agentId)
        this.ambiguousTurns.add(agentId)
        this.update(previous, 'unknown', 'OVERLAPPING_INPUTS')
      }
    }
    const entry = this.turns.get(agentId)
    this.event('turn.started', agentId, entry ? { turnId: entry.receipt.turnId, idempotencyKey: entry.receipt.idempotencyKey } : {})
  }
  turnEnded(agentId: string, aborted = false): void {
    // Session-wide close is not evidence for Device native inputs. Raw engine evidence owns completion.
    for (const entry of this.entries.values()) if (entry.evidenceManaged && entry.receipt.agentId === agentId
      && entry.receipt.state === 'started') this.update(entry, 'unknown', aborted ? 'TURN_INTERRUPTED' : 'RESULT_EVIDENCE_MISSING')
    this.ambiguousTurns.delete(agentId)
    this.openTurns.delete(agentId)
    this.pendingStarts.delete(agentId)
    const entry = this.turns.get(agentId)
    if (entry) {
      this.update(entry, aborted ? 'unknown' : 'completed', aborted ? 'TURN_INTERRUPTED' : undefined)
      this.turns.delete(agentId)
    }
    this.event(aborted ? 'turn.error' : 'turn.done', agentId, entry ? { turnId: entry.receipt.turnId, idempotencyKey: entry.receipt.idempotencyKey } : {})
  }
  commander(frame: Record<string, unknown>): void {
    const agentId = typeof frame.agentId === 'string' ? frame.agentId : undefined
    const p = object(frame.payload) ? frame.payload : {}
    if (frame.type === 'commander_question' && agentId && typeof p.requestId === 'string') {
      const permission = object(p.permission) && typeof p.permission.dialog === 'string' && p.permission.resolution === 'desktop'
        ? { dialog: p.permission.dialog, resolution: 'desktop' as const } : undefined
      const metadata = permission ? { permission } : {}
      this.questions.set(agentId, { requestId: p.requestId, questions: p.questions, ...metadata })
      const candidates = [...this.entries.values()].filter(e => e.receipt.agentId === agentId && e.consumed
        && e.receipt.serverInstanceId === this.serverInstanceId
        && !['completed', 'rejected'].includes(e.receipt.state))
      const single = candidates.length === 1 ? candidates[0] : this.turns.get(agentId)
      this.event('question.open', agentId, { questionRequestId: p.requestId, questions: p.questions, ...metadata,
        ...(single ? { idempotencyKey: single.receipt.idempotencyKey, turnId: single.receipt.turnId } : {}) })
    } else if (frame.type === 'commander_question_close' && agentId) {
      if (this.questions.get(agentId)?.requestId === p.requestId) this.questions.delete(agentId)
      this.event('question.close', agentId, { questionRequestId: p.requestId })
    } else if (frame.type === 'commander_event' && agentId && ['summary', 'tool', 'error'].includes(String(p.kind))) {
      // Device native results already use turn.summary with exact engine evidence. The
      // legacy mirror's asynchronous/latest recap must never emit a second final reply.
      // Other engines and sessions without native Device reservations keep their path.
      this.prune()
      if (p.kind === 'summary' && ([...this.entries.values()].some(e => e.evidenceManaged && e.receipt.agentId === agentId)
        || [...this.results.values()].some(r => r.agentId === agentId))) return
      const full = p.kind === 'summary' ? this.options.fullText?.(agentId) : undefined
      this.event(p.kind === 'summary' ? 'turn.summary' : p.kind === 'tool' ? 'turn.tool' : 'agent.error', agentId, full ? { ...p, fullText: full } : p)
    }
  }
  get capabilities(): string[] { return [...AUTONOMOUS_DEVICE_CAPABILITIES, 'input.status.v1', ...(this.options.store ? DEVICE_STORE_CAPABILITIES : []), ...DEVICE_ADDON_CAPABILITIES] }
  async request(deviceId: string, req: Record<string, unknown>): Promise<AutonomousDeviceFrame> {
    const type = typeof req.type === 'string' ? req.type : 'invalid'
    const response = (data: Record<string, unknown>): AutonomousDeviceFrame => ({ type: `${type}_result`, requestId: req.requestId, ...data })
    let reserved: Entry | undefined
    try {
      if (!UUID.test(String(req.requestId))) fail('INVALID_REQUEST', 'requestId must be a UUIDv4')
      if (type === 'input.status.v1' || !this.capabilities.includes(type)) fail('UNSUPPORTED_CAPABILITY', 'Operation is not supported')
      if ((DEVICE_STORE_CAPABILITIES as readonly string[]).includes(type)) return response(await this.options.store!.request(deviceId, req))
      if ((DEVICE_ADDON_CAPABILITIES as readonly string[]).includes(type)) return response(this.addons.request(deviceId, req))
      if (type === 'agent.subscribe' || type === 'agent.unsubscribe') return response(this.subscription(deviceId, type, req))
      const allowed = ['type', 'requestId', ...(['agents.list', 'focus.get', 'focus.ensure'].includes(type) ? [] : type === 'receipt.get' ? ['idempotencyKey'] : type === 'focus.step' ? ['direction', 'idempotencyKey', 'focusRevision'] : type === 'scroll' ? ['phase', 'dy', 'velocity'] : ['machineId', 'agentId']),
        ...(MUTATIONS.has(type) ? ['idempotencyKey'] : []), ...(type === 'turn.send' ? ['text', 'focusRevision'] : type === 'question.answer' ? ['questionRequestId', 'answers', 'focusRevision'] : type === 'recap' ? ['n'] : [])]
      if (Object.keys(req).some(k => !allowed.includes(k))) fail('INVALID_REQUEST', 'Unknown request field')
      if (type === 'receipt.get') {
        if (!KEY.test(String(req.idempotencyKey ?? ''))) fail('INVALID_REQUEST', 'Invalid idempotencyKey')
        return response({ receipt: this.receipt(deviceId, String(req.idempotencyKey)) })
      }
      if (type === 'focus.get') return response(this.focusSnapshot())
      if (type === 'focus.ensure') return response(await this.ensureFocus())
      if (type === 'focus.step') return response(await this.stepFocus(deviceId, req))
      if (type === 'scroll') { this.scroll(req); return response({}) }
      if ('focusRevision' in req && (typeof req.focusRevision !== 'string' || !req.focusRevision)) fail('INVALID_REQUEST', 'focusRevision must be a nonempty string')
      if (type === 'agents.list') {
        return response({ machineId: this.options.machineId, agents: await Promise.all(this.options.agents().map(async a => {
          const recap = await this.latestRecap(a.agentId)
          return { ...a, machineId: this.options.machineId, ...(recap ? { recap } : {}) }
        })) })
      }
      if (typeof req.agentId !== 'string' || !req.agentId || typeof req.machineId !== 'string') fail('MISSING_TARGET', 'machineId and agentId are required')
      if (req.machineId !== this.options.machineId) fail('MACHINE_MISMATCH', 'Only the paired machine is available')
      const agentId = req.agentId as string
      if (type === 'turn.send' && (typeof req.text !== 'string' || !req.text.trim())) fail('INVALID_REQUEST', 'text must be nonempty')
      if (type === 'turn.send' && Buffer.byteLength(String(req.text)) > 16384) fail('PAYLOAD_TOO_LARGE', 'Prompt exceeds 16 KiB')
      if (type === 'question.answer' && (typeof req.questionRequestId !== 'string' || !req.questionRequestId || !object(req.answers)
        || !Object.keys(req.answers).length || Object.values(req.answers).some(v => typeof v !== 'string'))) fail('INVALID_REQUEST', 'questionRequestId and string answers are required')
      if (MUTATIONS.has(type) && !KEY.test(String(req.idempotencyKey ?? ''))) fail('INVALID_REQUEST', 'Invalid idempotencyKey')
      const digest = createHash('sha256').update(canonical({ ...req, requestId: null, idempotencyKey: null })).digest('hex')
      const key = this.key(deviceId, String(req.idempotencyKey))
      this.prune()
      const previous = MUTATIONS.has(type) ? this.entries.get(key) : undefined
      if (previous) {
        if (previous.digest !== digest) fail('IDEMPOTENCY_CONFLICT', 'Key already belongs to a different operation or payload')
        return response({ status: 'duplicate', receipt: structuredClone(previous.receipt) })
      }
      if ('focusRevision' in req) {
        const snapshot = this.focusSnapshot()
        if (req.focusRevision !== snapshot.focusRevision || snapshot.focus?.machineId !== req.machineId || snapshot.focus?.agentId !== agentId) {
          fail('FOCUS_CHANGED', 'App focus changed before dispatch; no operation was reserved')
        }
      }
      const agent = this.options.agents().find(a => a.agentId === agentId)
      if (!agent) fail('AGENT_NOT_FOUND', 'Agent is not available on the paired machine')
      if (type === 'status') return response({ machineId: this.options.machineId, agentId, state: agent.state, openQuestion: this.questions.get(agentId) ?? null })
      if (type === 'recap') {
        const n = req.n ?? 3
        if (!Number.isInteger(n) || Number(n) < 1 || Number(n) > 5) fail('INVALID_REQUEST', 'n must be from 1 to 5')
        return response({ machineId: this.options.machineId, agentId, turns: await this.options.recent(agentId, Number(n)) })
      }
      if (type === 'question.answer' && this.questions.get(agentId)?.requestId !== req.questionRequestId) fail('QUESTION_STALE', 'Question is no longer open')
      this.reserveCapacity()
      const entry: Entry = { deviceId, digest, ...(type === 'turn.send' && ['claude', 'codex'].includes(agent.engine) ? { promptHash: inputHash(String(req.text)), reservedAt: this.now(), evidenceManaged: true } : {}), receipt: { idempotencyKey: String(req.idempotencyKey), deliveryId: randomUUID(), operation: type,
        machineId: this.options.machineId, agentId, state: 'queued', turnId: null, serverInstanceId: this.serverInstanceId, error: null, at: this.now() } }
      this.entries.set(key, entry); this.deliveries.set(entry.receipt.deliveryId, entry); reserved = entry
      this.persist() // durable reservation MUST precede any engine write
      try {
        if (type === 'turn.send') await this.options.submit(agentId, String(req.text), entry.receipt.deliveryId)
        else {
          const ok = type === 'turn.stop' ? await this.options.stop(agentId) : await this.options.answer(agentId, String(req.questionRequestId), req.answers as Record<string, string>)
          if (this.entries.get(key) !== entry) {
            // A reserved mutation always has a receipt, even if its authorization disappears.
            return response({ status: 'accepted', receipt: { ...structuredClone(entry.receipt), state: 'unknown', at: this.now(), error: { code: 'REVOKED', message: 'Pairing was revoked during the command; execution may already have occurred' } } })
          }
          this.update(entry, ok ? 'completed' : 'unknown', ok ? undefined : 'NOT_CONFIRMED')
          if (ok && type === 'question.answer') this.questions.delete(agentId)
        }
      } catch {
        if (this.entries.get(key) === entry) this.update(entry, 'unknown', 'NOT_CONFIRMED')
      }
      if (this.entries.get(key) !== entry) return response({ status: 'accepted', receipt: { ...structuredClone(entry.receipt), state: 'unknown', at: this.now(), error: { code: 'REVOKED', message: 'Pairing was revoked during the command; execution may already have occurred' } } })
      return response({ status: 'accepted', receipt: structuredClone(entry.receipt) })
    } catch (e) {
      if (reserved) {
        reserved.receipt.state = 'unknown'; reserved.receipt.at = this.now()
        reserved.receipt.error = { code: 'INTERNAL', message: 'Reserved operation could not be confirmed' }
        return response({ status: 'accepted', receipt: structuredClone(reserved.receipt) })
      }
      const known = e instanceof RequestError || e instanceof DeviceStoreError || e instanceof DeviceAddonError
      return response({ error: { code: known ? e.code : 'INTERNAL', message: known ? e.message : 'Request failed' } })
    }
  }
}