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.

feat: add device dump functionality for autonomous device communication

9ef44dfee1c8240ad4c6d0167a90
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 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)) return
const type = frame.type
+ if (type !== 'autonomous_device_request') deviceDump.record('in', 'wire', connId, frame) // requests: decrypted in the relay
if (type === 'machine_selected') return
if (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) return
frame = 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)
return
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 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 session
harness start start the adapter using the saved SSO session
harness 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 because
the 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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) return
const opened = this.crypto.unwrapDown(connId, frame)
const req = opened?.payload as Frame | undefined
if (!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.ts
index 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 const
export 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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 })
+ }
+}