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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat: add device dump functionality for autonomous device communication
9ef44dfee1c8240ad4c6d0167a90
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex ec3d02266..da3f119f1 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -1,6 +1,7 @@import type { HarnessShareOwner } from './sharing/owner.js'import { SHARE_REQUEST_TYPES } from './sharing/protocol.js'import { AutonomousDeviceRelay } from './lib/autonomous-device/relay.js'+import { deviceDump } from './lib/autonomous-device/dump.js'import type { AutonomousDeviceService, AutonomousDeviceFrame } from './lib/autonomous-device/service.js'/*** BackendSocket — the CLI's dial-out connection to the backend's `/api/adapter-ws`.@@ -621,12 +622,18 @@ export class BackendSocket {private readonly directDeviceSinks = new Map<string, (frame: Record<string, unknown>) => void>()private readonly directDevicePins = new Map<string, string>()onDirectDeviceRevoked?: (fingerprint: string) => void+ /** A connection that is, or is pairing as, an Autonomous device — what the device dump records. */+ private isDeviceConn(connId: string): boolean {+ return this.directDeviceSinks.has(connId) || this.e2ee.sessionRole(connId) === 'device'+ || (this.e2ee.pendingConnection() === connId && this.e2ee.pendingPair()?.role === 'device')+ }attachDirectDevice(connId: string, send: (frame: Record<string, unknown>) => void): void { this.directDeviceSinks.set(connId, send) }detachDirectDevice(connId: string): void { this.directDeviceSinks.delete(connId); this.directDevicePins.delete(connId); this.e2ee.dropSession(connId); this.autonomousDeviceRelay?.drop(connId); this.onCommanderPresenceChanged?.(this.hasCommander()) }pairedDirectFingerprint(connId: string): string | null { const pub = this.directDevicePins.get(connId); return pub ? fingerprint(b64d(pub)) : null }async receiveDirectDevice(connId: string, frame: Record<string, unknown>, pairingAllowed: boolean): Promise<void> {if (!this.directDeviceSinks.has(connId)) returnconst type = frame.type+ if (type !== 'autonomous_device_request') deviceDump.record('in', 'wire', connId, frame) // requests: decrypted in the relayif (type === 'machine_selected') returnif (type === 'autonomous_device_request') { await this.autonomousDeviceRelay?.handle(connId, frame); return }const controls = pairingAllowed ? ['e2e_pair_intent', 'e2e_pair_cancel', 'e2e_pake', 'e2e_hello', 'e2e_status'] : ['e2e_hello', 'e2e_status']@@ -646,7 +653,7 @@ export class BackendSocket {}directAutonomousDeviceSessions(): number { return this.autonomousDeviceRelay?.count(id => this.directDeviceSinks.has(id)) ?? 0 }autonomousDeviceConnected(): boolean { return this.autonomousDeviceRelay?.connected() ?? false }- emitAutonomousDeviceEvent(frame: AutonomousDeviceFrame): void { this.autonomousDeviceRelay?.emit(frame) }+ emitAutonomousDeviceEvent(frame: AutonomousDeviceFrame, deviceId?: string): void { this.autonomousDeviceRelay?.emit(frame, deviceId) }/** Live backend link state (local dashboard + E2EE gating). */isConnected(): boolean {@@ -970,6 +977,8 @@ export class BackendSocket {}sendTo(connId: string, frame: Frame): void {+ // Handshake frames only: device RPC, legacy replies and broadcasts are recorded in the clear where built.+ if (typeof frame.type === 'string' && frame.type.startsWith('e2e_') && deviceDump.enabled && this.isDeviceConn(connId)) deviceDump.record('out', 'wire', connId, frame)const direct = this.directDeviceSinks.get(connId)if (direct) { direct(frame); return }const local = this.localClients.get(connId)@@ -1041,6 +1050,7 @@ export class BackendSocket {sendCommander(frame: Frame): void {this.onOutboundCommander?.(frame)if (env.LOG_FRAMES) logFrame('→', 'device', frame)+ deviceDump.record('out', 'commander', undefined, frame)this.enqueue({ t: 'up', webEligible: false, commanderEligible: true, frame: this.e2ee.wrapCommander(frame) })}@@ -1282,6 +1292,7 @@ export class BackendSocket {* is never returned plaintext: even legacy backend nodeRequest (`connId === ''`) gets only an error. */private emitReply(connId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void {const resultType = `${type}_result`+ if (connId && deviceDump.enabled && this.e2ee.sessionRole(connId) === 'device') deviceDump.record('out', 'legacy', connId, { type: resultType, payload: { requestId, ...payload } })// Before the E2EE wrap: an RPC reply is only readable here.if (env.LOG_FRAMES && !type.startsWith('grid_fleet_') && type !== 'agent_read_file' && type !== 'project_preview' && type !== 'git_project_info' && !SHARE_REQUEST_TYPES.has(type)) logFrame('→', connId ? `conn:${sid(connId)}` : 'backend', { type: resultType, payload: { requestId, ...payload } })if (this.localClients.has(connId)) {@@ -1359,7 +1370,11 @@ export class BackendSocket {this.sendTo(connId, { type: 'local_protocol_error', payload: { error: 'LOCAL_E2EE_UNSUPPORTED' } })return}+ const deviceBefore = deviceDump.enabled && (this.isDeviceConn(connId) || (type === 'e2e_pair_intent' && (frame.payload as { role?: unknown } | undefined)?.role === 'device'))+ if (deviceBefore) deviceDump.record('in', 'wire', connId, frame)this.e2ee.handleFrame(connId, frame)+ // A reconnecting device is only known as one once its hello has been accepted.+ if (!deviceBefore && deviceDump.enabled && this.isDeviceConn(connId)) deviceDump.record('in', 'wire', connId, frame)return}if (type === 'autonomous_device_request') {@@ -1378,6 +1393,7 @@ export class BackendSocket {if (!dec) returnframe = dec}+ if (!local && deviceDump.enabled && this.e2ee.sessionRole(connId) === 'device') deviceDump.record('in', 'legacy', connId, frame)if (!local && TERMINAL_P2P_SIGNAL_TYPES.has(type)) {await this.terminalP2p.handleSignal(connId, type, frame.payload)returndiff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 525b1e806..06d31172b 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -349,6 +349,10 @@ Machine:harness auth status --json print {loggedIn,...} for this computer's saved sessionharness start start the adapter using the saved SSO sessionharness start -f run the adapter in the FOREGROUND (for a supervisor; logs to stdout)+ harness start --device-dump[=<file>]+ record every frame to/from the paired Autonomous device, decrypted, as+ JSON lines (default ~/.harness/logs/device-dump-<time>.jsonl). Contains+ prompts and answers in the clear — diagnostics only. Stop the daemon first.harness start --repair also re-verify the managed Node runtime and repoint the launcher at it(normally done once by the installer; use this if a start fails becausethe launcher points at a Node that no longer runs)@@ -2597,6 +2601,8 @@ async function runForeground(session: AuthSession): Promise<void> {}}mirror.ingest(events, sessionId)+ // Subscribed devices only (lib/autonomous-device/stream.ts). A transcript re-read is history, not live.+ if (!opts?.replay) autonomousDeviceService?.stream(agentIdFor(sessionId), events)}for (const queued of queuedSessionEvents.splice(0)) emitSessionEvents(queued.sessionId, queued.events, queued.opts)const cursorSubagents = new CursorSubagentManager(env.CURSOR_HOME, emitSessionEvents)@@ -5475,7 +5481,7 @@ async function runForeground(session: AuthSession): Promise<void> {answer: (agentId, requestId, answers) => questions.answer({ agentId, requestId, answers, allowPermissions: false }),recent: (id, n) => mirror.recent(registry.byAgent(id)?.sessionId ?? id, n),fullText: id => mirror.lastFullText(registry.byAgent(id)?.sessionId ?? id),- emit: frame => backend.emitAutonomousDeviceEvent(frame),+ emit: (frame, deviceId) => backend.emitAutonomousDeviceEvent(frame, deviceId),})if (appVoiceFocus) autonomousDeviceService.appFocus(appVoiceFocus.machineId, appVoiceFocus.agentId, appVoiceFocus.connId)backend.setAutonomousDeviceService(autonomousDeviceService)@@ -6492,9 +6498,14 @@ switch (cmd) {case 'logout':logout().catch(onError)break- case 'start':+ case 'start': {+ // `--device-dump[=<file>]`: the daemon (this process with -f, else the detached child, which inherits+ // the environment) records every frame to/from a paired Autonomous device — see lib/autonomous-device/dump.ts.+ const dump = flags.find((f) => f === '--device-dump' || f.startsWith('--device-dump='))+ if (dump) process.env.HARNESS_DEVICE_DUMP = dump === '--device-dump' ? '1' : resolve(dump.slice('--device-dump='.length))startCommand(foreground, repair).catch(onError)break+ }case 'join':console.error('`harness join` has been removed. Run `harness login`, then `harness start`.')process.exit(1)diff --git a/cli/src/lib/autonomous-device/dump.spec.ts b/cli/src/lib/autonomous-device/dump.spec.tsnew file mode 100644index 000000000..1e970383d--- /dev/null+++ b/cli/src/lib/autonomous-device/dump.spec.ts@@ -0,0 +1,38 @@+import { describe, expect, it } from 'vitest'+import { mkdtempSync, readFileSync, statSync, existsSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { DeviceDump, resolveDumpPath } from './dump.js'++describe('device dump', () => {+ it('is off unless configured, and never creates a file then', () => {+ for (const value of [undefined, '', '0', 'false']) expect(resolveDumpPath(value, '/logs')).toBeNull()+ const dump = new DeviceDump(() => undefined)+ dump.record('in', 'rpc', 'conn', { type: 'x' })+ expect(dump.enabled).toBe(false)+ })++ it('defaults to a timestamped file in the logs dir', () => {+ expect(resolveDumpPath('1', '/logs')).toMatch(/^\/logs\/device-dump-\d{8}-\d{6}\.jsonl$/)+ expect(resolveDumpPath('/tmp/x.jsonl', '/logs')).toBe('/tmp/x.jsonl')+ })++ it('writes one private JSON line per frame, labelled with direction, transport and layer', () => {+ const file = join(mkdtempSync(join(tmpdir(), 'dump-')), 'nested', 'd.jsonl')+ const dump = new DeviceDump(() => file)+ dump.record('in', 'rpc', 'autonomous-direct:abc', { type: 'autonomous_device_request', payload: { type: 'hello' } })+ dump.record('out', 'commander', undefined, { type: 'commander_event', payload: { kind: 'done' } })+ dump.record('out', 'wire', 'relay-conn', { type: 'e2e_welcome', payload: { key: new Uint8Array([1, 2]) } })+ dump.close()+ expect(existsSync(file)).toBe(true)+ expect(statSync(file).mode & 0o777).toBe(0o600)+ const lines = readFileSync(file, 'utf8').trim().split('\n').map(l => JSON.parse(l))+ expect(lines.map(l => [l.dir, l.via, l.layer, l.type])).toEqual([+ ['in', 'direct', 'rpc', 'autonomous_device_request'],+ ['out', 'broadcast', 'commander', 'commander_event'],+ ['out', 'relay', 'wire', 'e2e_welcome'],+ ])+ expect(lines[0].frame.payload).toEqual({ type: 'hello' })+ expect(lines[2].frame.payload.key).toEqual({ base64: 'AQI=' })+ })+})diff --git a/cli/src/lib/autonomous-device/dump.ts b/cli/src/lib/autonomous-device/dump.tsnew file mode 100644index 000000000..e8621c0b7--- /dev/null+++ b/cli/src/lib/autonomous-device/dump.ts@@ -0,0 +1,93 @@+import { closeSync, mkdirSync, openSync, writeSync } from 'node:fs'+import { dirname, join, resolve } from 'node:path'+import { env } from '../../config/env.js'++/**+ * Diagnostic dump of every frame between this daemon and a paired Autonomous device, one JSON object+ * per line. OFF unless `HARNESS_DEVICE_DUMP` is set (`harness start --device-dump[=<file>]` sets it).+ *+ * ⚠️ Frames are recorded in the CLEAR — before the E2EE wrap on the way out, after the unwrap on the+ * way in — so the file holds prompts, answers, tool arguments and file paths. Created 0600; delete it+ * when done. Frames still sealed on the wire (the handshake, a reply this daemon wrapped elsewhere) are+ * recorded as they travel.+ *+ * `layer` says which protocol a line belongs to:+ * rpc device RPC proto 1 (`autonomous_device_request/_result/_event`), decrypted+ * legacy browser-shaped RPCs a device session sends (agents_list, message, …) and their replies+ * commander device-audience broadcast (commander_event/question, agent_*), before group encryption+ * wire anything else to/from a device connection as it travels (e2e_* handshake, rekey, …)+ */+export type DumpDirection = 'in' | 'out'+export type DumpLayer = 'rpc' | 'legacy' | 'commander' | 'wire'+const MAX_BYTES = 256 * 1024 * 1024++function stamp(d = new Date()): string {+ const p = (n: number) => String(n).padStart(2, '0')+ return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`+}+/** `1`/`true` → a fresh file in the logs dir; anything else non-empty → that path. */+export function resolveDumpPath(value: string | undefined, logsDir = env.HARNESS_LOGS_DIR): string | null {+ const v = value?.trim()+ if (!v || v === '0' || v === 'false') return null+ return v === '1' || v === 'true' ? join(logsDir, `device-dump-${stamp()}.jsonl`) : resolve(v)+}+function replacer(_key: string, value: unknown): unknown {+ if (value instanceof Uint8Array) return { base64: Buffer.from(value).toString('base64') }+ return value+}++export class DeviceDump {+ private fd: number | null = null+ private bytes = 0+ private resolved = false+ private path: string | null = null+ constructor(private readonly source: () => string | undefined = () => process.env.HARNESS_DEVICE_DUMP) {}++ /** Resolved lazily: `harness start -f` sets the variable after this module is imported. */+ get enabled(): boolean {+ if (!this.resolved) {+ this.resolved = true+ this.path = resolveDumpPath(this.source())+ if (this.path) {+ try {+ mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })+ this.fd = openSync(this.path, 'a', 0o600)+ console.log(`[device-dump] recording device traffic IN THE CLEAR to ${this.path}`)+ } catch (e) {+ console.error(`[device-dump] cannot open ${this.path}: ${e instanceof Error ? e.message : e}`)+ this.path = null+ }+ }+ }+ return this.fd !== null+ }+ get file(): string | null { return this.enabled ? this.path : null }++ record(dir: DumpDirection, layer: DumpLayer, connId: string | undefined, frame: unknown): void {+ if (!this.enabled) return+ const type = frame && typeof frame === 'object' && typeof (frame as { type?: unknown }).type === 'string' ? (frame as { type: string }).type : undefined+ const via = !connId ? 'broadcast' : connId.startsWith('autonomous-direct:') ? 'direct' : 'relay'+ let line: string+ try {+ line = JSON.stringify({ ts: new Date().toISOString(), dir, via, layer, ...(connId ? { conn: connId } : {}), ...(type ? { type } : {}), frame }, replacer) + '\n'+ } catch {+ line = JSON.stringify({ ts: new Date().toISOString(), dir, via, layer, conn: connId, type, error: 'unserializable frame' }) + '\n'+ }+ try {+ const size = Buffer.byteLength(line)+ if (this.bytes + size > MAX_BYTES) {+ writeSync(this.fd!, JSON.stringify({ ts: new Date().toISOString(), note: `size cap ${MAX_BYTES} bytes reached; recording stopped` }) + '\n')+ this.close()+ return+ }+ writeSync(this.fd!, line)+ this.bytes += size+ } catch { this.close() }+ }+ close(): void {+ if (this.fd !== null) { try { closeSync(this.fd) } catch { /* already gone */ } }+ this.fd = null+ }+}++export const deviceDump = new DeviceDump()diff --git a/cli/src/lib/autonomous-device/relay.ts b/cli/src/lib/autonomous-device/relay.tsindex 554195280..e5542359d 100644--- a/cli/src/lib/autonomous-device/relay.ts+++ b/cli/src/lib/autonomous-device/relay.ts@@ -1,5 +1,6 @@import { isWrapped } from '../e2ee/core.js'import type { E2eeManager } from '../e2ee/manager.js'+import { deviceDump } from './dump.js'import { type AutonomousDeviceService, type AutonomousDeviceFrame } from './service.js'type Frame = Record<string, unknown>@@ -14,16 +15,18 @@ export class AutonomousDeviceRelay {connected(): boolean { return this.count() > 0 }private sendTo(connId: string, identity: string, type: string, payload: Frame): void {if (this.crypto.sessionIdentity(connId) !== identity || this.crypto.sessionRole(connId) !== 'device') return+ deviceDump.record('out', 'rpc', connId, { type, payload })const wrapped = this.crypto.wrapTarget(connId, type, payload)if (wrapped) this.send(connId, wrapped)}async handle(connId: string, frame: Frame): Promise<void> {- for (const [id, client] of this.clients) if (this.crypto.sessionIdentity(id) !== client.identity) this.clients.delete(id)+ for (const [id, client] of this.clients) if (this.crypto.sessionIdentity(id) !== client.identity) this.drop(id)const identity = this.crypto.sessionIdentity(connId)if (!identity || this.crypto.sessionRole(connId) !== 'device' || !isWrapped(frame.payload) || frame.dbSessionId !== undefined) returnconst opened = this.crypto.unwrapDown(connId, frame)const req = opened?.payload as Frame | undefinedif (!req || typeof req !== 'object' || Array.isArray(req)) return+ deviceDump.record('in', 'rpc', connId, { type: frame.type, payload: req })const reply = (payload: Frame) => this.sendTo(connId, identity, 'autonomous_device_result', payload)if (req.type === 'hello') {if (req.proto !== 1 || typeof req.requestId !== 'string') { reply({ type: 'hello_result', requestId: req.requestId, error: { code: 'PROTO_UNSUPPORTED', message: 'Protocol 1 required' } }); return }@@ -64,8 +67,15 @@ export class AutonomousDeviceRelay {}this.sendTo(connId, identity, 'autonomous_device_event', event)}- emit(event: AutonomousDeviceFrame): void { for (const [connId, client] of this.clients) this.sendEvent(connId, client.identity, event) }- drop(connId: string): void { this.clients.delete(connId) }+ /** `deviceId` set: an agent stream frame, sent to that identity's links and no other. */+ emit(event: AutonomousDeviceFrame, deviceId?: string): void {+ for (const [connId, client] of this.clients) if (!deviceId || client.identity === deviceId) this.sendEvent(connId, client.identity, event)+ }+ drop(connId: string): void {+ const client = this.clients.get(connId)+ this.clients.delete(connId)+ if (client && ![...this.clients.values()].some(c => c.identity === client.identity)) this.service.deviceOffline(client.identity)+ }/** App-side revoke: tell the device while its authenticated session still exists (the E2eeManager drops* the session right after), so it clears its own pin instead of showing "paired / disconnected" forever.* Best-effort: a device that is offline learns it on reconnect, when its e2e_hello gets e2e_denied. */diff --git a/cli/src/lib/autonomous-device/service.ts b/cli/src/lib/autonomous-device/service.tsindex 6ac85294f..1d60d8118 100644--- a/cli/src/lib/autonomous-device/service.ts+++ b/cli/src/lib/autonomous-device/service.ts@@ -1,6 +1,8 @@import type { AutonomousDeviceStore } from './store.js'import { DEVICE_STORE_CAPABILITIES, DeviceStoreError } from './storeContract.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'@@ -44,10 +46,11 @@ export interface AutonomousDeviceServiceOptions {* looks at between the dial and its turn cards.*/fullText?: (agentId: string) => string | undefined- emit?: (frame: AutonomousDeviceFrame) => void+ /** `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 }-const CAPABILITIES = ['focus.get', 'focus.ensure', 'focus.step', 'scroll', 'agents.list', 'turn.send', 'turn.stop', 'status', 'recap', 'question.answer', 'receipt.get'] as const+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 constexport const AUTONOMOUS_DEVICE_CAPABILITIES: string[] = [...CAPABILITIES]const MUTATIONS = new Set(['turn.send', 'turn.stop', 'question.answer'])const STEP_RESULTS_MAX = 512@@ -180,6 +183,37 @@ export class AutonomousDeviceService {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) })+ }+ private readonly streams: AgentStreams+ /** 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 device's last link closed: its subscriptions end with it, and a reconnect subscribes again. */+ deviceOffline(deviceId: string): void { this.streams.dropDevice(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. */@@ -237,6 +271,7 @@ export class AutonomousDeviceService {this.entries.delete(key)}for (const [key, step] of this.steps) if (step.deviceId === deviceId) this.steps.delete(key)+ this.streams.dropDevice(deviceId)// A newly paired identity cannot replay the previous device's request receipts.this.events = []}@@ -295,6 +330,7 @@ export class AutonomousDeviceService {if (!UUID.test(String(req.requestId))) fail('INVALID_REQUEST', 'requestId must be a UUIDv4')if (!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 (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')diff --git a/cli/src/lib/autonomous-device/stream.spec.ts b/cli/src/lib/autonomous-device/stream.spec.tsnew file mode 100644index 000000000..b4b6e482d--- /dev/null+++ b/cli/src/lib/autonomous-device/stream.spec.ts@@ -0,0 +1,197 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { randomUUID } from 'node:crypto'+import { AgentStreams, STREAM_MAX_PER_DEVICE } from './stream.js'+import { AutonomousDeviceRelay } from './relay.js'+import { AutonomousDeviceService, type AutonomousDeviceFrame } from './service.js'+import type { LiveEvent } from '../normalize.js'++const ALL = new Set(['tool', 'text', 'final'] as const)+const text = (content: string): LiveEvent => ({ type: 'text_delta', payload: { content } })+const toolStart: LiveEvent = { type: 'tool_start', payload: { id: 't1', tool: 'Bash', input: { command: 'ls -la' } } }+const toolEnd: LiveEvent = { type: 'tool_end', payload: { id: 't1', tool: 'Bash', output: 'secret listing', isError: false, summary: '', durationSeconds: 2 } }++function hub() {+ const sent: Array<{ deviceId: string; frame: AutonomousDeviceFrame }> = []+ const streams = new AgentStreams({ machineId: 'machine', serverInstanceId: 'instance', send: (deviceId, frame) => sent.push({ deviceId, frame }) })+ const kinds = () => sent.map(s => s.frame.kind)+ return { streams, sent, kinds }+}++describe('AgentStreams', () => {+ beforeEach(() => { vi.useFakeTimers() })+ afterEach(() => { vi.useRealTimers() })++ it('sends nothing for an agent nobody subscribed to', () => {+ const h = hub()+ h.streams.ingest('agent', [{ type: 'turn_started', payload: { userMessage: 'hi' } }, toolStart, text('a'), toolEnd, { type: 'turn_ended', payload: {} }])+ vi.advanceTimersByTime(1000)+ expect(h.sent).toEqual([])+ })++ it('streams tool calls without their output, coalesced text, then the whole final answer', () => {+ const h = hub()+ h.streams.ingest('agent', [{ type: 'turn_started', payload: { userMessage: 'hi' } }, text('Before subscribing. ')])+ const { subscriptionId } = h.streams.subscribe('dev', 'agent', 60, ALL)+ h.streams.ingest('agent', [toolStart, text('Hel'), text('lo')])+ expect(h.kinds()).toEqual(['stream.tool'])+ vi.advanceTimersByTime(250)+ h.streams.ingest('agent', [toolEnd, { type: 'turn_ended', payload: {} }])+ expect(h.sent.map(s => [s.frame.kind, s.frame.payload])).toEqual([+ ['stream.tool', { phase: 'start', toolUseId: 't1', tool: 'Bash', input: '{"command":"ls -la"}' }],+ ['stream.text', { text: 'Hello' }],+ ['stream.tool', { phase: 'end', toolUseId: 't1', tool: 'Bash', isError: false, durationSeconds: 2 }],+ // A mid-turn subscriber still gets the complete answer, including text written before it joined.+ ['stream.final', { text: 'Before subscribing. Hello' }],+ ])+ expect(JSON.stringify(h.sent)).not.toContain('secret listing')+ expect(h.sent.every(s => s.deviceId === 'dev' && s.frame.subscriptionId === subscriptionId)).toBe(true)+ expect(h.sent.map(s => s.frame.seq)).toEqual([1, 2, 3, 4])+ })++ it('flushes pending text before a tool card so the order on the device matches the turn', () => {+ const h = hub()+ h.streams.subscribe('dev', 'agent', 60, ALL)+ h.streams.ingest('agent', [text('Let me look.'), toolStart])+ expect(h.kinds()).toEqual(['stream.text', 'stream.tool'])+ })++ it('honours include', () => {+ const h = hub()+ h.streams.subscribe('dev', 'agent', 60, new Set(['final'] as const))+ h.streams.ingest('agent', [{ type: 'turn_started', payload: { userMessage: '' } }, toolStart, text('x'), { type: 'turn_ended', payload: { aborted: true } }])+ vi.advanceTimersByTime(1000)+ expect(h.sent.map(s => [s.frame.kind, s.frame.payload])).toEqual([['stream.final', { aborted: true }]])+ })++ it('expires on the daemon clock: pending text is delivered, then stream.end, then silence', () => {+ const h = hub()+ h.streams.subscribe('dev', 'agent', 5, ALL)+ vi.advanceTimersByTime(4900)+ h.streams.ingest('agent', [text('last words')])+ vi.advanceTimersByTime(100)+ expect(h.sent.map(s => [s.frame.kind, s.frame.payload])).toEqual([['stream.text', { text: 'last words' }], ['stream.end', { reason: 'expired' }]])+ h.streams.ingest('agent', [toolStart, text('late'), { type: 'turn_ended', payload: {} }])+ vi.advanceTimersByTime(1000)+ expect(h.sent).toHaveLength(2)+ expect(h.streams.count()).toBe(0)+ })++ it('replaces a subscription to the same agent and caps distinct agents per device', () => {+ const h = hub()+ const first = h.streams.subscribe('dev', 'a1', 60, ALL)+ const second = h.streams.subscribe('dev', 'a1', 60, ALL)+ expect(h.sent.map(s => [s.frame.subscriptionId, s.frame.kind, s.frame.payload])).toEqual([[first.subscriptionId, 'stream.end', { reason: 'replaced' }]])+ expect(second.subscriptionId).not.toBe(first.subscriptionId)+ for (let i = 1; i < STREAM_MAX_PER_DEVICE; i++) h.streams.subscribe('dev', `other-${i}`, 60, ALL)+ expect(() => h.streams.subscribe('dev', 'one-too-many', 60, ALL)).toThrow(expect.objectContaining({ code: 'SUBSCRIPTION_LIMIT' }))+ // The cap is per device.+ expect(() => h.streams.subscribe('dev2', 'one-too-many', 60, ALL)).not.toThrow()+ })++ it('only the owner can unsubscribe; dropping a device ends silently', () => {+ const h = hub()+ const { subscriptionId } = h.streams.subscribe('dev', 'agent', 60, ALL)+ expect(h.streams.unsubscribe('intruder', subscriptionId)).toBe(false)+ expect(h.streams.unsubscribe('dev', subscriptionId)).toBe(true)+ expect(h.streams.unsubscribe('dev', subscriptionId)).toBe(false)+ expect(h.kinds()).toEqual(['stream.end'])+ h.streams.subscribe('dev', 'agent', 60, ALL)+ h.streams.ingest('agent', [text('queued')])+ h.streams.dropDevice('dev')+ vi.advanceTimersByTime(1000)+ expect(h.kinds()).toEqual(['stream.end'])+ })++ it('bounds the final answer and tool input sizes', () => {+ const h = hub()+ h.streams.subscribe('dev', 'agent', 60, new Set(['tool', 'final'] as const))+ h.streams.ingest('agent', [{ type: 'tool_start', payload: { id: 't', tool: 'Write', input: { content: 'é'.repeat(5000) } } },+ { type: 'turn_started', payload: { userMessage: '' } }, text('é'.repeat(20000)), { type: 'turn_ended', payload: {} }])+ const [tool, final] = h.sent.map(s => s.frame.payload as Record<string, unknown>)+ expect(Buffer.byteLength(tool.input as string)).toBeLessThanOrEqual(1024)+ expect(Buffer.byteLength(final.text as string)).toBeLessThanOrEqual(16384)+ expect(final.text as string).not.toContain('�')+ expect(final.truncated).toBe(true)+ })+})++describe('agent.subscribe over the device RPC', () => {+ beforeEach(() => { vi.useFakeTimers() })+ afterEach(() => { vi.useRealTimers() })++ function fixture() {+ const identities: Record<string, string> = { a: 'device-a', b: 'device-b' }+ const send = vi.fn()+ const crypto = { sessionRole: () => 'device' as const, sessionIdentity: (c: string) => identities[c] ?? null,+ unwrapDown: (_c: string, frame: Record<string, unknown>) => ({ ...frame, payload: (frame.payload as { __e2e: unknown }).__e2e }),+ wrapTarget: (_c: string, type: string, payload: Record<string, unknown>) => ({ type, payload: { __e2e: payload } }) }+ let relay: AutonomousDeviceRelay | undefined+ const service = new AutonomousDeviceService({ machineId: 'machine', agents: () => [{ agentId: 'agent', name: 'Agent', engine: 'codex', state: 'idle' }],+ submit: vi.fn(), cancelDelivery: () => true, stop: async () => true, answer: async () => true, recent: () => [],+ emit: (frame, deviceId) => relay?.emit(frame, deviceId) })+ relay = new AutonomousDeviceRelay(crypto, send, service, 'machine')+ const request = async (conn: string, payload: Record<string, unknown>) => {+ const requestId = randomUUID()+ await relay!.handle(conn, { type: 'autonomous_device_request', payload: { __e2e: { requestId, ...payload } } })+ return send.mock.calls.map(([, f]) => (f as { payload: { __e2e: Record<string, unknown> } }).payload.__e2e).find(r => r.requestId === requestId)!+ }+ const streamFrames = (conn: string) => send.mock.calls.filter(([c, f]) => c === conn && typeof (f as { payload: { __e2e: { kind?: string } } }).payload.__e2e.kind === 'string'+ && (f as { payload: { __e2e: { kind: string } } }).payload.__e2e.kind.startsWith('stream.')).map(([, f]) => (f as { payload: { __e2e: AutonomousDeviceFrame } }).payload.__e2e)+ return { relay, service, request, streamFrames, send }+ }+ const target = { machineId: 'machine', agentId: 'agent' }++ it('advertises the capability and validates the request strictly', async () => {+ const f = fixture()+ const hello = await f.request('a', { type: 'hello', proto: 1 })+ expect(hello.capabilities).toEqual(expect.arrayContaining(['agent.subscribe', 'agent.unsubscribe']))+ expect((await f.request('a', { type: 'agent.subscribe', ...target, ttlSec: 301 })).error).toMatchObject({ code: 'INVALID_REQUEST' })+ expect((await f.request('a', { type: 'agent.subscribe', ...target, ttlSec: 1.5 })).error).toMatchObject({ code: 'INVALID_REQUEST' })+ expect((await f.request('a', { type: 'agent.subscribe', ...target, include: ['text', 'text'] })).error).toMatchObject({ code: 'INVALID_REQUEST' })+ expect((await f.request('a', { type: 'agent.subscribe', ...target, include: ['thinking'] })).error).toMatchObject({ code: 'INVALID_REQUEST' })+ expect((await f.request('a', { type: 'agent.subscribe', ...target, extra: 1 })).error).toMatchObject({ code: 'INVALID_REQUEST' })+ expect((await f.request('a', { type: 'agent.subscribe', machineId: 'elsewhere', agentId: 'agent' })).error).toMatchObject({ code: 'MACHINE_MISMATCH' })+ expect((await f.request('a', { type: 'agent.subscribe', machineId: 'machine', agentId: 'ghost' })).error).toMatchObject({ code: 'AGENT_NOT_FOUND' })+ const ok = await f.request('a', { type: 'agent.subscribe', ...target })+ expect(ok).toMatchObject({ type: 'agent.subscribe_result', agentId: 'agent', include: ['tool', 'text', 'final'], ttlMs: 60_000 })+ })++ it('streams to the subscribing device only, and keeps stream frames out of the replay log', async () => {+ const f = fixture()+ await f.request('a', { type: 'hello', proto: 1 }); await f.request('b', { type: 'hello', proto: 1 })+ const sub = await f.request('a', { type: 'agent.subscribe', ...target, ttlSec: 10 })+ f.service.stream('agent', [toolStart])+ expect(f.streamFrames('a')).toMatchObject([{ kind: 'stream.tool', subscriptionId: sub.subscriptionId }])+ expect(f.streamFrames('b')).toEqual([])+ const resumed = await f.request('a', { type: 'hello', proto: 1, resume: { serverInstanceId: f.service.serverInstanceId, cursor: 0 } })+ expect(resumed).toMatchObject({ resumed: true, cursor: 0 })+ expect(f.streamFrames('a')).toHaveLength(1)+ })++ it('ends when the time runs out, on unsubscribe, and when the last link closes', async () => {+ const f = fixture()+ await f.request('a', { type: 'hello', proto: 1 })+ const sub = await f.request('a', { type: 'agent.subscribe', ...target, ttlSec: 2 })+ vi.advanceTimersByTime(2000)+ f.service.stream('agent', [toolStart])+ expect(f.streamFrames('a').map(e => e.kind)).toEqual(['stream.end'])+ expect(await f.request('a', { type: 'agent.unsubscribe', subscriptionId: sub.subscriptionId })).toMatchObject({ unsubscribed: false })++ const again = await f.request('a', { type: 'agent.subscribe', ...target })+ expect(await f.request('a', { type: 'agent.unsubscribe', subscriptionId: again.subscriptionId })).toMatchObject({ unsubscribed: true })++ await f.request('a', { type: 'agent.subscribe', ...target })+ f.relay.drop('a')+ f.service.stream('agent', [toolStart])+ expect(f.streamFrames('a').map(e => e.kind)).toEqual(['stream.end', 'stream.end'])+ })++ it('ends a revoked device\'s subscriptions', async () => {+ const f = fixture()+ await f.request('a', { type: 'hello', proto: 1 })+ await f.request('a', { type: 'agent.subscribe', ...target })+ f.relay.revoke('device-a')+ f.service.stream('agent', [toolStart])+ expect(f.streamFrames('a')).toEqual([])+ })+})diff --git a/cli/src/lib/autonomous-device/stream.ts b/cli/src/lib/autonomous-device/stream.tsnew file mode 100644index 000000000..d4d6bf1dd--- /dev/null+++ b/cli/src/lib/autonomous-device/stream.ts@@ -0,0 +1,153 @@+import { randomUUID } from 'node:crypto'+import type { LiveEvent } from '../normalize.js'+import type { AutonomousDeviceFrame } from './service.js'++/**+ * Opt-in, expiring live view of one agent for one paired device: tool calls, answer text as it is+ * written, and the turn's final answer. Nothing streams without a subscription, and the daemon — not+ * the device — owns the clock: at `expiresAt` the subscription ends and no further frame is sent.+ *+ * Stream frames are deliberately NOT in the service's replay log. A burst of text would evict the+ * receipts and focus changes that log exists for, and a subscription is bound to the live link: a+ * device that reconnects subscribes again.+ */+export type StreamKind = 'tool' | 'text' | 'final'+export type StreamEndReason = 'expired' | 'unsubscribed' | 'replaced'+export const STREAM_KINDS: readonly StreamKind[] = ['tool', 'text', 'final']+export const STREAM_TTL_MAX_SEC = 300+export const STREAM_TTL_DEFAULT_SEC = 60+/** Per device. Re-subscribing to the same agent replaces, so this bounds distinct agents watched at once. */+export const STREAM_MAX_PER_DEVICE = 2+/** Text is coalesced to at most one frame per window, or sooner once this many bytes are waiting. */+const TEXT_FLUSH_MS = 250+const TEXT_FLUSH_BYTES = 4096+/** Bounds the per-agent turn text kept for `stream.final`, and the final frame itself. */+const FINAL_MAX_BYTES = 16384+const TOOL_INPUT_MAX_BYTES = 1024++export interface AgentStreamsOptions {+ machineId: string+ serverInstanceId: string+ send: (deviceId: string, frame: AutonomousDeviceFrame) => void+ now?: () => number+}+export class StreamRequestError extends Error { constructor(readonly code: string, message: string) { super(message) } }++interface Subscription {+ id: string; deviceId: string; agentId: string; include: ReadonlySet<StreamKind>+ expiresAt: number; seq: number; expiry: ReturnType<typeof setTimeout>+ text: string; flush: ReturnType<typeof setTimeout> | undefined+}++/** Cut to at most `max` UTF-8 bytes without splitting a code point. */+function clip(text: string, max: number): { text: string; truncated: boolean } {+ if (Buffer.byteLength(text) <= max) return { text, truncated: false }+ let out = Buffer.from(text).subarray(0, max).toString('utf8')+ if (out.endsWith('�')) out = out.slice(0, -1)+ return { text: out, truncated: true }+}+function toolInput(input: unknown): string {+ if (input === undefined) return ''+ try { return clip(typeof input === 'string' ? input : JSON.stringify(input) ?? '', TOOL_INPUT_MAX_BYTES).text } catch { return '' }+}++export class AgentStreams {+ private readonly subs = new Map<string, Subscription>()+ /** The open turn's answer text per agent, kept whether or not anyone watches, so a mid-turn subscriber still gets the whole final. */+ private readonly turnText = new Map<string, string>()+ private readonly now: () => number+ constructor(private readonly options: AgentStreamsOptions) { this.now = options.now ?? Date.now }++ subscribe(deviceId: string, agentId: string, ttlSec: number, include: ReadonlySet<StreamKind>): { subscriptionId: string; expiresAt: number; ttlMs: number } {+ const existing = [...this.subs.values()].find(s => s.deviceId === deviceId && s.agentId === agentId)+ // The old subscription's frames all carry its own id, so the device can tell the two apart.+ if (existing) this.end(existing, 'replaced')+ else if ([...this.subs.values()].filter(s => s.deviceId === deviceId).length >= STREAM_MAX_PER_DEVICE) {+ throw new StreamRequestError('SUBSCRIPTION_LIMIT', `At most ${STREAM_MAX_PER_DEVICE} agents can be watched at once`)+ }+ const ttlMs = ttlSec * 1000+ const sub: Subscription = { id: randomUUID(), deviceId, agentId, include, expiresAt: this.now() + ttlMs, seq: 0,+ expiry: setTimeout(() => this.end(sub, 'expired'), ttlMs), text: '', flush: undefined }+ sub.expiry.unref?.()+ this.subs.set(sub.id, sub)+ return { subscriptionId: sub.id, expiresAt: sub.expiresAt, ttlMs }+ }++ /** False when the id is unknown, already ended, or belongs to another device — indistinguishable on purpose. */+ unsubscribe(deviceId: string, subscriptionId: string): boolean {+ const sub = this.subs.get(subscriptionId)+ if (!sub || sub.deviceId !== deviceId) return false+ this.end(sub, 'unsubscribed')+ return true+ }++ /** The device can no longer be reached (unpaired, or its last link closed): end silently. */+ dropDevice(deviceId: string): void {+ for (const sub of [...this.subs.values()]) if (sub.deviceId === deviceId) this.end(sub)+ }++ /** Live events for one agent, in order. Replayed history must not be passed here. */+ ingest(agentId: string, events: readonly LiveEvent[]): void {+ for (const e of events) {+ if (e.type === 'turn_started') this.turnText.set(agentId, '')+ else if (e.type === 'text_delta') {+ const kept = (this.turnText.get(agentId) ?? '') + e.payload.content+ // Past the cap the final is already truncated; keep the head, stop growing.+ this.turnText.set(agentId, Buffer.byteLength(kept) > FINAL_MAX_BYTES + 4 ? clip(kept, FINAL_MAX_BYTES + 4).text : kept)+ for (const sub of this.watching(agentId, 'text')) this.queueText(sub, e.payload.content)+ } else if (e.type === 'tool_start') {+ for (const sub of this.watching(agentId, 'tool')) {+ this.flushText(sub)+ this.send(sub, 'stream.tool', { phase: 'start', toolUseId: e.payload.id, tool: e.payload.tool, input: toolInput(e.payload.input) })+ }+ } else if (e.type === 'tool_end') {+ for (const sub of this.watching(agentId, 'tool')) {+ this.flushText(sub)+ this.send(sub, 'stream.tool', { phase: 'end', toolUseId: e.payload.id, tool: e.payload.tool, isError: e.payload.isError,+ ...(e.payload.durationSeconds !== undefined ? { durationSeconds: e.payload.durationSeconds } : {}) })+ }+ } else if (e.type === 'turn_ended') {+ const final = clip((this.turnText.get(agentId) ?? '').trim(), FINAL_MAX_BYTES)+ this.turnText.delete(agentId)+ for (const sub of this.watching(agentId)) this.flushText(sub)+ for (const sub of this.watching(agentId, 'final')) {+ this.send(sub, 'stream.final', e.payload.aborted ? { aborted: true } : { text: final.text, ...(final.truncated ? { truncated: true } : {}) })+ }+ }+ }+ }++ count(): number { return this.subs.size }++ private watching(agentId: string, kind?: StreamKind): Subscription[] {+ const at = this.now()+ return [...this.subs.values()].filter(s => s.agentId === agentId && s.expiresAt > at && (!kind || s.include.has(kind)))+ }+ private queueText(sub: Subscription, content: string): void {+ sub.text += content+ if (Buffer.byteLength(sub.text) >= TEXT_FLUSH_BYTES) { this.flushText(sub); return }+ if (!sub.flush) { sub.flush = setTimeout(() => this.flushText(sub), TEXT_FLUSH_MS); sub.flush.unref?.() }+ }+ private flushText(sub: Subscription): void {+ if (sub.flush) { clearTimeout(sub.flush); sub.flush = undefined }+ if (!sub.text) return+ const text = sub.text+ sub.text = ''+ this.send(sub, 'stream.text', { text })+ }+ /** Idempotent. With a reason the device is told; without one it is unreachable anyway. */+ private end(sub: Subscription, reason?: StreamEndReason): void {+ if (!this.subs.has(sub.id)) return+ clearTimeout(sub.expiry)+ // Text written before the deadline was inside the window: deliver it, then close.+ if (reason) this.flushText(sub)+ else if (sub.flush) clearTimeout(sub.flush)+ if (reason) this.send(sub, 'stream.end', { reason })+ this.subs.delete(sub.id)+ }+ private send(sub: Subscription, kind: string, payload: Record<string, unknown>): void {+ if (!this.subs.has(sub.id)) return+ this.options.send(sub.deviceId, { type: 'event', serverInstanceId: this.options.serverInstanceId, machineId: this.options.machineId,+ agentId: sub.agentId, subscriptionId: sub.id, seq: ++sub.seq, kind, payload })+ }+}