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.

Autonomous Device ↔ Harness CLI: LAN link contract and implementation (#24)

Leoc4de3189b80c
diff --git a/cli/README.md b/cli/README.md
index 1a7ffb3cf..8c3bb67c7 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -239,3 +239,26 @@ connected*, the adapter runs a disposable one-shot from the session's own CLI en
body ≤200`, shows a `Summarizing…` indicator while it runs, persists it per session
(`${ADAPTER_DATA_DIR}/summaries.json`), and returns it on `project_recent` at device boot. A newer
turn aborts a stale recap.
+
+## Pair an Autonomous device directly
+
+Harness discovers the OS's existing `_autonomous._tcp` advertisement. Select a discovered device
+and enter the code displayed on it; no IP address or device backend login is needed.
+
+```sh
+harness autonomous-device discover --json
+harness autonomous-device pair --device '<discovery-id>' --code-stdin
+harness autonomous-device status --json
+harness autonomous-device list --json
+harness autonomous-device revoke '<full fingerprint from list>'
+```
+
+Desktop writes the code to stdin and closes stdin. Terminal users may use
+`pair <device-code> --device <discovery-id>`. Mac connects directly to the advertised OS endpoint,
+reusing the original Harness E2eeManager and identity store. Saved associations rediscover/reconnect
+automatically. Revoke closes only the selected device connection. Existing Harness Mac login/start
+requirements remain unchanged; the running daemon's direct device transport works offline from
+its backend. Browser/dial behavior and Buddy are unchanged.
+
+See [the contract](../docs/autonomous-device-integration.md) and
+[Vietnamese guide](../docs/vi/autonomous-device-integration_vi.md).
diff --git a/cli/package-lock.json b/cli/package-lock.json
index 32586ab2b..1cdb373c2 100644
--- a/cli/package-lock.json
+++ b/cli/package-lock.json
@@ -12,6 +12,7 @@
"@noble/ciphers": "^1.3.0",
"@noble/curves": "^1.9.7",
"@noble/hashes": "^1.8.0",
+ "bonjour-service": "^1.4.4",
"chokidar": "^4.0.0",
"dotenv": "^17.2.3",
"werift": "0.24.4",
@@ -1311,6 +1312,16 @@
],
"license": "MIT"
},
+ "node_modules/bonjour-service": {
+ "version": "1.4.4",
+ "resolved": "https://registry.npmjs.org/bonjour-service/-/bonjour-service-1.4.4.tgz",
+ "integrity": "sha512-jCZcVv7eoc4QesRscwEZtSROBen+6LpKAmBIsQYQrsAeVHLyMXWX/t6eIV5KiRZYNUBl8eVqImEEMQ8L5+c/Kw==",
+ "license": "MIT",
+ "dependencies": {
+ "fast-deep-equal": "^3.1.3",
+ "multicast-dns": "^7.2.5"
+ }
+ },
"node_modules/buffer": {
"version": "6.0.3",
"resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz",
@@ -1487,6 +1498,12 @@
"node": ">=12.0.0"
}
},
+ "node_modules/fast-deep-equal": {
+ "version": "3.1.3",
+ "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+ "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+ "license": "MIT"
+ },
"node_modules/fdir": {
"version": "6.5.0",
"resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
diff --git a/cli/package.json b/cli/package.json
index a899ea16c..e2b443bd7 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -21,6 +21,7 @@
"@noble/ciphers": "^1.3.0",
"@noble/curves": "^1.9.7",
"@noble/hashes": "^1.8.0",
+ "bonjour-service": "^1.4.4",
"chokidar": "^4.0.0",
"dotenv": "^17.2.3",
"werift": "0.24.4",
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 7e7acc561..bbf5af05b 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -803,3 +803,34 @@ describe('agent_retarget clearGrid', () => {
expect(seen).toHaveLength(0)
})
})
+
+describe('Autonomous direct isolation from existing relay/browser behavior', () => {
+ it('permits offline PAKE only for the exact live direct pending connection', async () => {
+ const backend = new BackendSocket('direct-offline-test')
+ const send = vi.fn()
+ backend.attachDirectDevice('autonomous-direct:test', send)
+ const pairId = Buffer.alloc(16, 1).toString('base64')
+ backend.e2ee.handleFrame('browser', { type: 'e2e_pair_intent', payload: { pairId, role: 'web', label: 'Browser' } })
+ expect(await backend.pair('K7P4X9')).toEqual({ ok: false, error: 'BACKEND_DOWN' })
+ await backend.receiveDirectDevice('autonomous-direct:test', { type: 'e2e_pair_intent', payload: { pairId, role: 'device', label: 'Autonomous device' } }, true)
+ const paired = backend.pair('K7P4X9')
+ expect(send).toHaveBeenCalledWith(expect.objectContaining({ type: 'e2e_pake' }))
+ await backend.receiveDirectDevice('autonomous-direct:test', { type: 'e2e_pair_cancel', payload: { pairId } }, true)
+ expect(await paired).toEqual({ ok: false, error: 'CANCELLED' })
+ backend.detachDirectDevice('autonomous-direct:test')
+ })
+ it('never dispatches setup/password/admin/terminal frames from a discovered endpoint', async () => {
+ const backend = new BackendSocket('direct-whitelist-test')
+ backend.attachDirectDevice('autonomous-direct:test', vi.fn())
+ const handle = vi.spyOn(backend.e2ee, 'handleFrame').mockReturnValue(true)
+ for (const type of ['e2e_setup_claim', 'e2e_pw_pair_intent', 'e2e_pw_pake', 'terminal_open', 'machine_revoked', '__clients']) {
+ await backend.receiveDirectDevice('autonomous-direct:test', { type, payload: {} }, true)
+ }
+ expect(handle).not.toHaveBeenCalled()
+ await backend.receiveDirectDevice('autonomous-direct:test', { type: 'e2e_pair_intent', payload: {} }, false)
+ expect(handle).not.toHaveBeenCalled()
+ await backend.receiveDirectDevice('autonomous-direct:test', { type: 'e2e_hello', payload: {} }, false)
+ expect(handle).toHaveBeenCalledOnce()
+ backend.detachDirectDevice('autonomous-direct:test')
+ })
+})
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 7e5589f82..8606bb8d3 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -1,3 +1,5 @@
+import { AutonomousDeviceRelay } from './lib/autonomous-device/relay.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`.
*
@@ -58,7 +60,7 @@ import {
TerminalHopDirection,
type TerminalBinaryClear,
} from './lib/terminalBinary.js'
-import { ENCRYPTED_RPC_RESULT_TYPES, isEncryptedDownType, isWrapped } from './lib/e2ee/core.js'
+import { b64d, fingerprint, ENCRYPTED_RPC_RESULT_TYPES, isEncryptedDownType, isWrapped } from './lib/e2ee/core.js'
import { DEVICE_RECENT_SAFE_FRAME_BYTES, fitRecentReplyPayloadForDevice } from './lib/deviceRecentTrim.js'
import { shouldReplayCommander } from './lib/commanderReplay.js'
import { RuntimeProfileControlError, type RuntimeProfileErrorCode } from './lib/runtimeProfileController.js'
@@ -376,7 +378,10 @@ export class BackendSocket {
this.commanderCount = commander
this.commanderActive = active
if (hadCommander !== (commander > 0)) this.onCommanderPresenceChanged?.(commander > 0)
- if (commander <= 0) this.e2ee.dropSessionsByRole('device')
+ if (commander <= 0) {
+ if (this.directDeviceSinks.size) this.e2ee.dropSessionsByRole('device', id => this.directDeviceSinks.has(id))
+ else this.e2ee.dropSessionsByRole('device')
+ }
}
/** True while at least one device (commander) client is connected — gates the LLM recap. */
@@ -407,6 +412,29 @@ export class BackendSocket {
return this.e2ee.deviceConnected()
}
+ private readonly directDeviceSinks = new Map<string, (frame: Record<string, unknown>) => void>()
+ private readonly directDevicePins = new Map<string, string>()
+ onDirectDeviceRevoked?: (fingerprint: string) => void
+ 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 === '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']
+ if ((type === 'e2e_pake' || type === 'e2e_pair_cancel') && this.e2ee.pendingConnection() !== connId) return
+ if (typeof type === 'string' && controls.includes(type)) this.e2ee.handleFrame(connId, frame)
+ }
+ private autonomousDeviceRelay?: AutonomousDeviceRelay
+ setAutonomousDeviceService(service: AutonomousDeviceService): void {
+ this.autonomousDeviceRelay = new AutonomousDeviceRelay(this.e2ee, (connId, frame) => this.sendTo(connId, frame), service, this.machineId, () => this.onCommanderJoin?.())
+ }
+ 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) }
+
/** Live backend link state (local dashboard + E2EE gating). */
isConnected(): boolean {
return this.ws?.readyState === WebSocket.OPEN
@@ -443,6 +471,9 @@ export class BackendSocket {
sendTo: (connId, frame) => this.sendTo(connId, frame),
sendUser: (frame) => this.sendUser(frame),
isConnected: () => this.isConnected(),
+ isConnectionAvailable: connId => this.directDeviceSinks.has(connId) || this.isConnected(),
+ onIdentityPaired: (connId, pub) => { if (this.directDeviceSinks.has(connId)) this.directDevicePins.set(connId, pub) },
+ onIdentityRevoked: identity => { this.autonomousDeviceRelay?.revoke(identity); this.onDirectDeviceRevoked?.(fingerprint(b64d(identity))) },
})
this.terminalP2p = new TerminalP2pResponderPool({
sendSignal: (connId, type, payload) => this.sendP2pSignal(connId, type, payload),
@@ -637,6 +668,8 @@ export class BackendSocket {
/** Send an up-frame to exactly ONE web connection (E2EE pairing/welcome + targeted RPC replies). */
sendTo(connId: string, frame: Frame): void {
+ const direct = this.directDeviceSinks.get(connId)
+ if (direct) { direct(frame); return }
const local = this.localClients.get(connId)
if (local) {
if (!local.sendFrame(frame)) void this.unregisterLocalClient(connId)
@@ -953,6 +986,10 @@ export class BackendSocket {
this.e2ee.handleFrame(connId, frame)
return
}
+ if (type === 'autonomous_device_request') {
+ if (!local) await this.autonomousDeviceRelay?.handle(connId, frame)
+ return
+ }
// Client→adapter encrypted frames: chat messages plus trusted web control actions. Plaintext
// passes through for legacy/device transition paths; undecryptable ciphertext is dropped.
if (!local && isEncryptedDownType(type)) {
@@ -1005,6 +1042,7 @@ export class BackendSocket {
// The backend is authoritative for the outer connId. Drop both kinds of
// connection-scoped state immediately; otherwise a dead Desktop keeps a
// terminal controller lease until the 30-second heartbeat timeout.
+ this.autonomousDeviceRelay?.drop(connId)
this.e2ee.dropSession(connId)
await this.terminalP2p.closeConnection(connId, 'client_disconnected', false)
this.p2pPendingOpens.delete(connId)
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 9495f8a3a..1068c29ec 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1,4 +1,6 @@
#!/usr/bin/env node
+import { fingerprint as e2eeCoreFingerprint, b64d as e2eeCoreDecode } from './lib/e2ee/core.js'
+import { AutonomousDeviceDirect } from './lib/autonomous-device/direct.js'
/**
* machine-adapter CLI (the `harness` command) — connect this computer to a "remote" agent.
*
@@ -89,6 +91,9 @@ import { readTerminalConfigSnapshot, writeTerminalConfigSnapshot } from './lib/t
import { Watcher, type LineEvent } from './watcher/watcher.js'
import { chooseHookAgent, startHookServer } from './hookServer.js'
import { BackendSocket } from './backendSocket.js'
+import { AutonomousDeviceService } from './lib/autonomous-device/service.js'
+import { autonomousDeviceLocalRequest } from './lib/autonomous-device/localApi.js'
+import { runAutonomousDeviceCommand } from './lib/autonomous-device/command.js'
import { attachLocalWsServer, LOCAL_WS_PATH, LOCAL_WS_PROTOCOL_VERSION } from './localWsServer.js'
import { RemoteRelayPool } from './lib/remoteRelay.js'
import { TERMINAL_BINARY_VERSION } from './lib/terminalBinary.js'
@@ -268,6 +273,7 @@ Grid (the fleet of AI engines the \`grid\` CLI serves — needs \`grid\` on PATH
Browser end-to-end encryption:
harness browser-link print a reusable 7-day setup link for browsers
+ harness autonomous-device <command> pair/status/list/revoke an Autonomous device
harness pair <code> pair a BROWSER (code shown on the machine page)
harness pairings list paired clients
harness unpair <#|fp> unpair one browser (by list number or fingerprint)
@@ -1249,6 +1255,8 @@ async function runForeground(session: AuthSession): Promise<void> {
}
}
}
+ let autonomousDeviceDirect: AutonomousDeviceDirect | undefined
+ let autonomousDeviceService: AutonomousDeviceService | undefined
let backendRef: BackendSocket | undefined
let fullReconcile: (announceDevice?: boolean) => Promise<void> = async () => {}
@@ -1282,7 +1290,7 @@ async function runForeground(session: AuthSession): Promise<void> {
let openPaneAgents = new Set<string>()
const cableWatchingLocal = (): boolean => cableRef?.isConnected === true
- const deviceIsWatching = (): boolean => backend.hasCommander() || cableWatchingLocal()
+ const deviceIsWatching = (): boolean => backend.hasCommander() || cableWatchingLocal() || backend.autonomousDeviceConnected()
/** Anyone who can DRAW a question: a device, a cabled dial, or a desktop window on this computer. */
const someoneCanAnswer = (): boolean => deviceIsWatching() || backend.hasLocalClient()
const terminalStreams = new TerminalStreamManager({
@@ -1659,6 +1667,7 @@ async function runForeground(session: AuthSession): Promise<void> {
}
const input = new SessionInputController({
getSession: (id) => registry.resolve(id),
+ onDelivery: (event) => autonomousDeviceService?.delivery(event),
validateRuntime: validateTerminal,
inject: submitTerminalAction,
sendKey: keyTerminalAction,
@@ -1974,6 +1983,7 @@ async function runForeground(session: AuthSession): Promise<void> {
)
console.log(`[turn] ${sid(sessionId)} started · engine=${registry.bySession(sessionId)?.engine ?? 'claude'} · bytes=${Buffer.byteLength(event.payload.userMessage, 'utf8')}`)
input.onTurnStarted(agentIdFor(sessionId), event.payload.userMessage)
+ autonomousDeviceService?.turnStarted(agentId)
startHeartbeat(sessionId)
questionWatcher.start(sessionId) // Claude opens its dialog INSIDE a turn
// ...and anything already drawn belongs to the turn BEFORE this one.
@@ -1988,6 +1998,7 @@ async function runForeground(session: AuthSession): Promise<void> {
`[turn] ${sid(sessionId)} ended${event.payload.aborted ? ' · aborted (interrupted)' : ''}` +
`${startedAt ? ` · ${Date.now() - startedAt}ms` : ''}`,
)
+ autonomousDeviceService?.turnEnded(agentId, event.payload.aborted === true)
input.onTurnEnded(agentIdFor(sessionId))
// Command Code asks AFTER the turn: `ask_user_question` ends the turn (its Stop hook fires), the
// dialog goes up, and the answer opens a NEW turn. Stopping the watcher here is what left the
@@ -2398,6 +2409,26 @@ async function runForeground(session: AuthSession): Promise<void> {
}
const { server: hookServer, port: hookPort } = await startHookServer(env.PORT, {
+ onAutonomousDeviceRequest: async (method, target, body) => {
+ if (!autonomousDeviceService) return { status: 503, body: { error: { code: 'UNAVAILABLE', message: 'Autonomous device service is starting' } } }
+ return autonomousDeviceLocalRequest({
+ discover: async () => ({ devices: await autonomousDeviceDirect!.discover() }),
+ pairStart: ({ code, device }) => autonomousDeviceDirect!.pair(device, code),
+ pairStatus: () => {
+ const pending = backend.pendingPair()
+ return pending?.role === 'device' ? { state: pending.active ? 'running' : 'waiting', pairId: pending.pairId, deviceLabel: pending.label, expiresAt: pending.expiresAt } : { state: 'idle' }
+ },
+ list: () => ({ devices: backend.listPairs().filter(p => p.role === 'device').map(p => ({ ...p, id: p.fingerprint })) }),
+ status: () => ({ transport: 'direct', connected: backend.directAutonomousDeviceSessions() > 0, paired: backend.listPairs().filter(p => p.role === 'device').length, sessions: backend.directAutonomousDeviceSessions(), proto: 1 }),
+ revoke: ({ id }) => {
+ if (!backend.listPairs().some(p => p.role === 'device' && p.fingerprint === id)) throw Object.assign(new Error('Device pairing not found'), { code: 'UNKNOWN_DEVICE' })
+ const result = backend.revoke(id)
+ if (!result.ok) throw Object.assign(new Error(result.error), { code: result.error })
+ return { revoked: 1 }
+ },
+ receipt: target => ({ receipt: autonomousDeviceService!.receipt(target.deviceId, target.idempotencyKey) }),
+ }, method, target, body)
+ },
resolveHookAgent: async ({ engine, runtimeHints, callerPid }) => {
if (!callerPid) return null
const resolved: TerminalRuntimeRef[] = []
@@ -3007,9 +3038,9 @@ async function runForeground(session: AuthSession): Promise<void> {
}, PANE_TITLE_SYNC_MS)
// A device joined mid-turn (count rise or join generation; no adapter heartbeat) → replay live state.
- backend.onCommanderJoin = () => { mirror.replayAll(); questionWatcher.reset() } // re-announce an open question
+ backend.onCommanderJoin = () => { setSummaryPoolDeviceConnected(deviceIsWatching()); mirror.replayAll(); questionWatcher.reset() } // re-announce an open question
backend.onCommanderPresenceChanged = (connected) => {
- setSummaryPoolDeviceConnected(connected)
+ setSummaryPoolDeviceConnected(connected || backend.autonomousDeviceConnected())
setVoiceRouterDeviceConnected(connected) // warm the voice-router worker while a device is connected
}
@@ -3017,7 +3048,7 @@ async function runForeground(session: AuthSession): Promise<void> {
// heartbeat and mark the turn closed here (mirrors the hosted runtime stopping its heartbeat on cancel). We do
// NOT emit turn_ended: the web clears its own dots on cancel, and a turn_ended would fire a device
// recap for a killed turn. The next real prompt reopens a fresh turn.
- backend.onCancel = (id) => {
+ const cancelAgent = (id: string, confirmed = false): Promise<boolean> => {
const record = registry.resolve(id)
const sessionId = record?.sessionId ?? id
const st = turnStates.get(sessionId)
@@ -3035,11 +3066,14 @@ async function runForeground(session: AuthSession): Promise<void> {
devinReaders.get(sessionId)?.closeTurn()
commandcodeNormalizers.get(sessionId)?.closeTurn()
cursorSubagents.forget(sessionId)
- input.cancel(record?.agentId ?? sessionId)
+ const cancelled = confirmed ? input.cancelConfirmed(record?.agentId ?? sessionId) : (input.cancel(record?.agentId ?? sessionId), Promise.resolve(true))
+ autonomousDeviceService?.turnEnded(record?.agentId ?? sessionId, true)
stopHeartbeat(sessionId)
questionWatcher.stop(sessionId)
mirror.cancel(sessionId) // close the device's "Working…" tile (bare done, no recap) — a cancel emits no turn_ended
+ return cancelled
}
+ backend.onCancel = id => { void cancelAgent(id) }
/**
* Web requested a new agent (`agent_create`): spawn a fresh tmux session running the chosen engine in
@@ -3511,7 +3545,7 @@ async function runForeground(session: AuthSession): Promise<void> {
}
}
- backend.onMessage = (id, content) => {
+ const submitAgent = (id: string, content: string, deliveryId?: string): void => {
const record = registry.resolve(id)
const sessionId = record?.sessionId ?? id
const engine = record?.engine ?? 'claude'
@@ -3524,8 +3558,9 @@ async function runForeground(session: AuthSession): Promise<void> {
console.log(`[msg] ${sid(sessionId)} slash-command adapted for engine=${engine}`)
}
console.log(`[msg] ${sid(sessionId)} recv · engine=${engine} · bytes=${Buffer.byteLength(adapted, 'utf8')}`)
- input.submit(record?.agentId ?? sessionId, adapted)
+ input.submit(record?.agentId ?? sessionId, adapted, deliveryId)
}
+ backend.onMessage = (id, content) => submitAgent(id, content)
// Keep the log file under its cap. This daemon writes it through an inherited stdout fd, so a size
// check on a timer is the only place that can see it grow — `prepareLogFile` at spawn time alone
@@ -3581,6 +3616,7 @@ async function runForeground(session: AuthSession): Promise<void> {
hookServer.close()
shutdownSummaryPool()
shutdownVoiceRouter()
+ autonomousDeviceDirect?.stop()
await backend.stop() // graceful WS close → releases the Redis machine-owner claim
await new Promise((r) => setTimeout(r, 1000)) // grace before the same-machine reclaim
@@ -3679,6 +3715,7 @@ async function runForeground(session: AuthSession): Promise<void> {
hookServer.close()
shutdownSummaryPool()
shutdownVoiceRouter()
+ autonomousDeviceDirect?.stop()
await backend.stop()
try { if (readPid() === process.pid) rmSync(PID_FILE, { force: true }) } catch { /* ignore */ }
process.exit(0)
@@ -3803,9 +3840,36 @@ async function runForeground(session: AuthSession): Promise<void> {
const cable = new CableSession(cableHost, join(env.ADAPTER_DATA_DIR, 'dial.log'))
cableRef = cable
+ autonomousDeviceService = new AutonomousDeviceService({
+ machineId: backend.machineId,
+ agents: () => registry.advertised().map(s => ({ agentId: s.agentId, name: projectDisplayName(s), engine: s.engine,
+ state: turnStartedAt.has(s.sessionId) ? 'running' : 'idle' })),
+ submit: submitAgent,
+ cancelDelivery: id => input.cancelDelivery(id),
+ stop: id => cancelAgent(id, true),
+ answer: (agentId, requestId, answers) => questions.answer({ agentId, requestId, answers, allowPermissions: false }),
+ recent: (id, n) => mirror.recent(registry.byAgent(id)?.sessionId ?? id, n),
+ emit: frame => backend.emitAutonomousDeviceEvent(frame),
+ })
+ backend.setAutonomousDeviceService(autonomousDeviceService)
+ autonomousDeviceDirect = new AutonomousDeviceDirect({
+ machineId: backend.machineId, label: hostname(),
+ receive: (connId, frame, pairing) => backend.receiveDirectDevice(connId, frame, pairing),
+ attach: (connId, send) => backend.attachDirectDevice(connId, send),
+ detach: connId => backend.detachDirectDevice(connId),
+ pending: () => backend.pendingPair(), pendingConnection: () => backend.e2ee.pendingConnection(),
+ authenticatedFingerprint: connId => { const pub = backend.e2ee.sessionIdentity(connId); return pub ? e2eeCoreFingerprint(e2eeCoreDecode(pub)) : null },
+ pairedFingerprint: connId => backend.pairedDirectFingerprint(connId),
+ pair: code => backend.pair(code), paired: () => backend.listPairs(),
+ }, env.ADAPTER_DATA_DIR)
+ backend.onDirectDeviceRevoked = fp => autonomousDeviceDirect?.revoked(fp)
+ autonomousDeviceDirect.start()
+
+
// Every card bound for the WiFi device goes down the cable too, translated once. Teeing beats emitting
// again at each call site: a new event kind reaches the dial the day it reaches the socket.
backend.onOutboundCommander = (frame) => {
+ autonomousDeviceService?.commander(frame as Record<string, unknown>)
// THIS COMPUTER'S cards, by definition — and every one of them belongs to a tile that is on the
// carousel, because the carousel now spans machines. The old guard dropped them whenever the wheel
// was pointed elsewhere, which would now silence this machine's own agents.
@@ -4773,6 +4837,9 @@ switch (cmd) {
else runForeground(session).catch(onError)
break
}
+ case 'autonomous-device':
+ runAutonomousDeviceCommand(rest, env.ADAPTER_DATA_DIR, env.PORT).then(code => { process.exitCode = code }).catch(onError)
+ break
case 'pair':
pairCommand(args[0]).catch(onError)
break
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index d14b029bd..e0a695d03 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -49,6 +49,8 @@ export interface PairOutcome {
}
export interface HookServerHandlers {
+ onAutonomousDeviceRequest?: (method: string, target: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
onRegistered: (
entry: RegisteredSession,
meta: {
@@ -337,6 +339,21 @@ export function startHookServer(
const localOk = req.headers['x-adapter-local'] === '1'
const hookOk = hookCredentialMatches(hookCredential, req.headers['x-harness-hook-token'])
+ if (url.startsWith('/api/autonomous-device/')) {
+ const peer = req.socket.remoteAddress
+ const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1'
+ const bearer = req.headers.authorization?.startsWith('Bearer ') ? req.headers.authorization.slice(7) : undefined
+ if (!loopback || req.headers.origin || !hookCredentialMatches(hookCredential, bearer)) {
+ json(403, { error: { code: 'FORBIDDEN', message: 'Authenticated native loopback client required' } }); return
+ }
+ if (!handlers.onAutonomousDeviceRequest) { json(503, { error: { code: 'UNAVAILABLE', message: 'Autonomous device service unavailable' } }); return }
+ let body: unknown
+ if (req.method !== 'GET') {
+ try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
+ }
+ const result = await handlers.onAutonomousDeviceRequest(req.method ?? '', req.url ?? '', body)
+ json(result.status, result.body); return
+ }
if (req.method === 'GET' && url === '/api/health') {
json(200, { ok: true, version: VERSION }); return
}
diff --git a/cli/src/lib/askQuestion.ts b/cli/src/lib/askQuestion.ts
index 9b3c7ea0b..00d6245d5 100644
--- a/cli/src/lib/askQuestion.ts
+++ b/cli/src/lib/askQuestion.ts
@@ -59,6 +59,7 @@ export interface QuestionRow {
export interface QuestionView {
kind: 'question'
+ permission?: boolean
question: string
rows: QuestionRow[]
multi: boolean
@@ -128,13 +129,16 @@ export function shapeQuestions(questions: unknown): ShapedQuestion[] {
* Claude and Command Code share one shape (see parseQuestionPane); devin draws a different one and gets
* its own parser rather than more branches in here.
*/
+function permissionView(view: PaneView): PaneView {
+ return view?.kind === 'question' ? { ...view, permission: true } : view
+}
export function parseEngineQuestionPane(engine: AgentEngine, capture: string): PaneView {
// Devin's two dialogs are told apart by one word in the footer (`↵ select` vs `↵ confirm`), so they can
// never both match. Only one can be on screen anyway: answering either replaces it with a summary line.
- if (engine === 'devin') return parseDevinQuestionPane(capture) ?? parseDevinPermissionPane(capture)
+ if (engine === 'devin') return parseDevinQuestionPane(capture) ?? permissionView(parseDevinPermissionPane(capture))
// Cursor has no ask-the-user tool, so its permission prompt is the ONLY dialog it ever draws — and it
// numbers nothing, stating each row's key in the row instead.
- if (engine === 'cursor') return parseCursorPermissionPane(capture)
+ if (engine === 'cursor') return permissionView(parseCursorPermissionPane(capture))
// Muse pairs each option with a description on the same line and floats a live Preview box above the
// rows — both confuse the shared parser, so it reads its own. Its PERMISSION prompt is a different
// dialog entirely (`Would you like to allow this network access?` over `1. Yes, proceed (y)` rows under
@@ -142,11 +146,15 @@ export function parseEngineQuestionPane(engine: AgentEngine, capture: string): P
// reads exactly, so it falls through rather than getting a parser of its own.
if (engine === 'muse') return parseMuseQuestionPane(capture) ?? parseQuestionPane(capture)
// Amp's is a permission prompt with unnumbered rows — nothing the shared parser can anchor on.
- if (engine === 'amp') return parseAmpQuestionPane(capture)
+ if (engine === 'amp') return permissionView(parseAmpQuestionPane(capture))
// Kilo's is the same kind of prompt but laid out HORIZONTALLY, sharing its line with the key hints —
// it is a fork of opencode that did not keep opencode's dialog.
- if (engine === 'kilo') return parseKiloQuestionPane(capture)
- if (engine === 'grok') return parseGrokQuestionPane(capture)
+ if (engine === 'kilo') return permissionView(parseKiloQuestionPane(capture))
+ if (engine === 'grok') {
+ const view = parseGrokQuestionPane(capture)
+ // Grok prints this footer only for tool approval, never its questionnaire.
+ return /always-approve|Ctrl\+o:/i.test(capture) ? permissionView(view) : view
+ }
// agy's ask-the-user dialog anchors on `Question N/M:` under an `↑/↓ Navigate` footer, which the
// shared parser cannot see. Its PERMISSION prompt is numbered rows under `Do you want to proceed?`
// and the shared parser reads that one exactly, so it falls through.
@@ -166,7 +174,7 @@ export function parseEngineQuestionPane(engine: AgentEngine, capture: string): P
// than copied. Tried FIRST because that dialog numbers nothing: the shared parser would still match
// its `enter confirm` footer and then walk up into whatever numbered rows the scrollback holds.
const permission = parseKiloQuestionPane(capture)
- if (permission) return permission
+ if (permission) return permissionView(permission)
const plain = unframe(capture)
return opencodeReview(plain) ?? parseQuestionPane(plain)
}
@@ -432,7 +440,7 @@ export function parsePermissionPane(lines: string[]): { view: QuestionView; inde
// Single-select, and no free-text row: every option here is a choice to be TAPPED. Verified on live
// panes for claude, codex, devin and grok \u2014 one digit selects and submits, exactly as `rowKeys` assumes.
return {
- view: { kind: 'question', question: permissionTitle(lines, start), rows, multi: false, typeRow: null },
+ view: { kind: 'question', permission: true, question: permissionTitle(lines, start), rows, multi: false, typeRow: null },
index: start,
}
}
@@ -563,6 +571,7 @@ export interface AskQuestionDeps {
}
export interface QuestionAnswerPayload {
+ allowPermissions?: boolean
requestId?: string
sessionId?: string
agentId?: string
@@ -614,7 +623,7 @@ export class AskQuestionController {
}
this.driving.add(sessionId)
try {
- const ok = await this.drive(terminalTarget, answers, this.deps.getSession(sessionId)?.engine ?? 'claude')
+ const ok = await this.drive(terminalTarget, answers, this.deps.getSession(sessionId)?.engine ?? 'claude', payload.allowPermissions !== false)
this.pending.delete(requestId)
console.log(`[question] ${sessionId.slice(0, 8)} answered from device · ${ok ? 'submitted' : 'FAILED'}`)
return ok
@@ -625,7 +634,7 @@ export class AskQuestionController {
}
/** Key the answers into the pane's dialog, question by question, ending on the review screen. */
- private async drive(terminalTarget: string, answers: Record<string, string>, engine: AgentEngine): Promise<boolean> {
+ private async drive(terminalTarget: string, answers: Record<string, string>, engine: AgentEngine, allowPermissions = true): Promise<boolean> {
const wait = this.deps.wait ?? sleep
const used = new Set<string>()
let lastQuestion = ''
@@ -639,7 +648,9 @@ export class AskQuestionController {
// Nothing on screen: either the dialog was never open, or the last keystroke submitted it.
return answered > 0
}
+ if (!allowPermissions && view.kind === 'question' && view.permission) return false
if (view.kind === 'review') {
+ if (!allowPermissions && answered === 0) return false
return this.deps.sendKey(terminalTarget, view.submitRow)
}
// The same question still showing after we acted on it: give the TUI one more beat to repaint,
diff --git a/cli/src/lib/autonomous-device/command.spec.ts b/cli/src/lib/autonomous-device/command.spec.ts
new file mode 100644
index 000000000..6d4421d6e
--- /dev/null
+++ b/cli/src/lib/autonomous-device/command.spec.ts
@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Readable } from 'node:stream'
+import { runAutonomousDeviceCommand } from './command.js'
+vi.mock('../hookAuth.js', () => ({ readHookCredential: () => 'hook-test-credential' }))
+afterEach(() => vi.restoreAllMocks())
+describe('Autonomous device pairing command direction', () => {
+ it('refuses the removed LAN listener and blanket revoke options', async () => {
+ const fetch = vi.spyOn(globalThis, 'fetch')
+ vi.spyOn(console, 'log').mockImplementation(() => {})
+ expect(await runAutonomousDeviceCommand(['listen'], '/unused', 18473)).toBe(1)
+ expect(await runAutonomousDeviceCommand(['revoke', '--all'], '/unused', 18473)).toBe(1)
+ expect(fetch).not.toHaveBeenCalled()
+ })
+ it('takes the device code from stdin and binds it to the displayed pending intent', async () => {
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ state: 'running' })))
+ const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+ vi.spyOn(process, 'stdin', 'get').mockReturnValue(Readable.from(['K7P4X9\n']) as typeof process.stdin)
+ const device = 'os._autonomous._tcp.local'
+ expect(await runAutonomousDeviceCommand(['pair', '--code-stdin', '--device', device], '/unused', 18473)).toBe(0)
+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body))).toEqual({ code: 'K7P4X9', device })
+ expect(log.mock.calls.flat().join()).not.toContain('K7P4X9')
+ })
+ it('refuses missing code or simultaneous positional and stdin sources', async () => {
+ const fetch = vi.spyOn(globalThis, 'fetch'), log = vi.spyOn(console, 'log').mockImplementation(() => {})
+ expect(await runAutonomousDeviceCommand(['pair'], '/unused', 18473)).toBe(1)
+ expect(await runAutonomousDeviceCommand(['pair', 'K7P4X9', '--code-stdin'], '/unused', 18473)).toBe(1)
+ expect(fetch).not.toHaveBeenCalled()
+ expect(log.mock.calls.flat().join()).not.toContain('K7P4X9')
+ })
+})
diff --git a/cli/src/lib/autonomous-device/command.ts b/cli/src/lib/autonomous-device/command.ts
new file mode 100644
index 000000000..9c0abca6c
--- /dev/null
+++ b/cli/src/lib/autonomous-device/command.ts
@@ -0,0 +1,48 @@
+import { readHookCredential } from '../hookAuth.js'
+
+/** Native UI writes the displayed device code to stdin so it never appears in process arguments. */
+async function stdinCode(): Promise<string> {
+ let value = ''
+ for await (const chunk of process.stdin) {
+ value += String(chunk)
+ if (value.length > 64) throw new Error('code input too long')
+ }
+ return value.trim()
+}
+export async function runAutonomousDeviceCommand(argv: string[], dataDir: string, port: number): Promise<number> {
+ const json = argv.includes('--json'), args: string[] = []
+ let device: string | undefined
+ const flags = new Set<string>()
+ let invalid = false
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ if (a === '--device') { if (device !== undefined || !argv[i + 1] || argv[i + 1].startsWith('--')) invalid = true; else device = argv[++i] }
+ else if (a.startsWith('--')) { if (!['--json', '--code-stdin'].includes(a) || flags.has(a)) invalid = true; flags.add(a) }
+ else args.push(a)
+ }
+ const verb = args[0] ?? 'status', fromStdin = flags.has('--code-stdin')
+ const route = ({ discover: 'discover', status: 'status', list: 'list', pair: 'pair/start', 'pair-status': 'pair/status', revoke: 'revoke' } as Record<string, string>)[verb]
+ const print = (value: unknown) => console.log(JSON.stringify(value, null, json ? undefined : 2))
+ if (invalid || !route || (verb === 'pair' && !device) || ((fromStdin || device !== undefined) && verb !== 'pair')
+ || args.length !== (verb === 'pair' ? fromStdin ? 1 : 2 : verb === 'revoke' ? 2 : args[0] ? 1 : 0)) {
+ print({ error: { code: 'INVALID_ARGUMENT', message: 'Usage: harness autonomous-device pair <code> --device <id> | pair --code-stdin --device <id> | discover | pair-status | list | status | revoke <fingerprint> [--json]' } })
+ return 1
+ }
+ const credential = readHookCredential(dataDir)
+ if (!credential) { print({ error: { code: 'DAEMON_UNAVAILABLE', message: 'Start Harness with harness start first.' } }); return 1 }
+ const mutation = ['pair', 'revoke'].includes(verb)
+ try {
+ const body = verb === 'pair' ? { code: fromStdin ? await stdinCode() : args[1], ...(device ? { device } : {}) }
+ : verb === 'revoke' ? { id: args[1] } : {}
+ const result = await fetch(`http://127.0.0.1:${port}/api/autonomous-device/${route}`, {
+ method: mutation ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(45_000),
+ headers: { Authorization: `Bearer ${credential}`, ...(mutation ? { 'Content-Type': 'application/json' } : {}) },
+ ...(mutation ? { body: JSON.stringify(body) } : {}),
+ })
+ print(await result.json())
+ return result.ok ? 0 : 1
+ } catch {
+ print({ error: { code: 'DAEMON_UNAVAILABLE', message: 'Could not reach the Harness Autonomous device API or read pairing input. Start or update Harness CLI.' } })
+ return 1
+ }
+}
diff --git a/cli/src/lib/autonomous-device/direct.spec.ts b/cli/src/lib/autonomous-device/direct.spec.ts
new file mode 100644
index 000000000..7d63b783b
--- /dev/null
+++ b/cli/src/lib/autonomous-device/direct.spec.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { WebSocketServer } from 'ws'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { once } from 'node:events'
+import { b64e, fingerprint, newIdentity } from '../e2ee/core.js'
+import { AutonomousDeviceDirect, type DirectDeviceHost } from './direct.js'
+const clean: Array<() => void> = []
+afterEach(() => { for (const fn of clean.splice(0)) fn() })
+async function fixture() {
+ const dir = mkdtempSync(join(tmpdir(), 'autonomous-direct-')); clean.push(() => rmSync(dir, { recursive: true, force: true }))
+ const wss = new WebSocketServer({ port: 0, host: '127.0.0.1' }); await once(wss, 'listening')
+ clean.push(() => { for (const ws of wss.clients) ws.terminate(); wss.close() })
+ const row = { id: 'device._autonomous._tcp.local', name: 'Device', host: '127.0.0.1', port: (wss.address() as { port: number }).port }
+ const identity = newIdentity(), fp = fingerprint(identity.pub)
+ let pending: string | null = null, authenticated: string | null = null, attempts = 0
+ const receive = vi.fn(async (connId: string, frame: Record<string, unknown>) => { if (frame.type === 'e2e_pair_intent') pending = connId; if (frame.type === 'e2e_hello') authenticated = fp })
+ const host: DirectDeviceHost = { machineId: 'machine', label: 'Mac', receive, attach: () => {}, detach: () => { pending = null; authenticated = null },
+ pending: () => pending ? { pairId: 'pair', role: 'device' } : null, pendingConnection: () => pending,
+ pair: async code => { attempts++; if (code === 'WRONG1') return { ok: false, error: 'CODE_MISMATCH' }; authenticated = fp; return { ok: true, label: 'Device', fingerprint: 'computer-fingerprint' } },
+ authenticatedFingerprint: () => authenticated, pairedFingerprint: () => fp, paired: () => [{ role: 'device', fingerprint: fp }] }
+ wss.on('connection', ws => ws.once('message', () => ws.send(JSON.stringify({ type: 'e2e_pair_intent', payload: {} }))))
+ const discovery = vi.fn(async () => [row])
+ const direct = new AutonomousDeviceDirect(host, dir, discovery); clean.unshift(() => direct.stop())
+ return { direct, host, wss, row, identity, fp, receive, dir, discovery, attempts: () => attempts }
+}
+describe('direct Autonomous device endpoint selection', () => {
+ it('only pairs a discovered selected device and starts a fresh socket after a wrong code', async () => {
+ const f = await fixture()
+ await expect(f.direct.pair('manual-host', 'CODE12')).rejects.toMatchObject({ code: 'DEVICE_NOT_FOUND' })
+ expect(f.attempts()).toBe(0)
+ await expect(f.direct.pair(f.row.id, 'WRONG1')).rejects.toMatchObject({ code: 'CODE_MISMATCH' })
+ await new Promise(resolve => setTimeout(resolve, 20))
+ expect(await f.direct.pair(f.row.id, 'CODE12')).toMatchObject({ state: 'paired', fingerprint: f.fp })
+ expect(f.attempts()).toBe(2)
+ f.direct.revoked(f.fp)
+ expect(f.direct.connected()).toBe(0)
+ })
+ it('does not persist success if PAKE identity has not authenticated its session', async () => {
+ const f = await fixture()
+ f.host.pair = async () => { for (const ws of f.wss.clients) ws.close(); return { ok: true, label: 'Device', fingerprint: 'computer' } }
+ await expect(f.direct.pair(f.row.id, 'CODE12')).rejects.toThrow('session did not authenticate')
+ expect(f.direct.connected()).toBe(0)
+ })
+ it('refuses a reconnect identity different from the saved discovered association', async () => {
+ const f = await fixture(); await f.direct.pair(f.row.id, 'CODE12'); f.direct.stop()
+ await new Promise(resolve => setTimeout(resolve, 20)); f.receive.mockClear()
+ f.wss.removeAllListeners('connection')
+ const impostor = b64e(newIdentity().pub)
+ f.wss.on('connection', ws => ws.once('message', () => ws.send(JSON.stringify({ type: 'e2e_hello', payload: { identityPub: impostor } }))))
+ const next = new AutonomousDeviceDirect(f.host, f.dir, f.discovery); clean.unshift(() => next.stop()); next.start()
+ await vi.waitFor(() => expect(f.discovery).toHaveBeenCalledTimes(2))
+ await new Promise(resolve => setTimeout(resolve, 50))
+ expect(f.receive).not.toHaveBeenCalled()
+ })
+})
diff --git a/cli/src/lib/autonomous-device/direct.ts b/cli/src/lib/autonomous-device/direct.ts
new file mode 100644
index 000000000..790d77c74
--- /dev/null
+++ b/cli/src/lib/autonomous-device/direct.ts
@@ -0,0 +1,123 @@
+import { b64d, fingerprint } from '../e2ee/core.js'
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import { renameSync, writeFileSync } from 'node:fs'
+import WebSocket from 'ws'
+import { hardenPrivateStateFileIfPresent, readPrivateStateFile, secureStateDirectory } from '../secureState.js'
+import { discoverDevices, type DiscoveredDevice } from './discovery.js'
+import type { PairResult } from '../e2ee/manager.js'
+export interface DirectDeviceHost {
+ machineId: string
+ label: string
+ receive(connId: string, frame: Record<string, unknown>, pairingAllowed: boolean): Promise<void>
+ attach(connId: string, send: (frame: Record<string, unknown>) => void): void
+ detach(connId: string): void
+ authenticatedFingerprint(connId: string): string | null
+ pairedFingerprint(connId: string): string | null
+ pending(): { pairId: string; role: string } | null
+ pendingConnection(): string | null
+ pair(code: string): Promise<PairResult>
+ paired(): Array<{ fingerprint: string; role: string }>
+}
+interface Association { discoveryId: string; fingerprint: string }
+interface Link { ws: WebSocket; connId: string; ready: Promise<void> }
+/** Outbound direct sockets share the daemon's original E2eeManager; metadata contains no keys. */
+export class AutonomousDeviceDirect {
+ private readonly links = new Map<string, Link>()
+ private readonly candidates = new Map<string, DiscoveredDevice>()
+ private associations: Association[] = []
+ private timer?: ReturnType<typeof setInterval>
+ private discovering?: Promise<DiscoveredDevice[]>
+ private stopping = false
+ private pairing = false
+ private readonly file: string
+ constructor(private readonly host: DirectDeviceHost, private readonly dataDir: string, private readonly discovery = discoverDevices) {
+ secureStateDirectory(dataDir); this.file = join(dataDir, 'autonomous-device-connections.json')
+ if (hardenPrivateStateFileIfPresent(this.file, 65536)) {
+ const value: unknown = JSON.parse(readPrivateStateFile(this.file, 65536))
+ if (!Array.isArray(value) || value.some(r => !r || typeof r.discoveryId !== 'string' || typeof r.fingerprint !== 'string')) throw new Error('Invalid device connection metadata')
+ this.associations = value
+ }
+ }
+ private save(): void {
+ secureStateDirectory(this.dataDir); hardenPrivateStateFileIfPresent(this.file, 65536)
+ const temp = `${this.file}.${randomUUID()}.tmp`; writeFileSync(temp, JSON.stringify(this.associations), { mode: 0o600, flag: 'wx' }); renameSync(temp, this.file)
+ }
+ discover(): Promise<DiscoveredDevice[]> {
+ if (!this.discovering) this.discovering = this.discovery().then(rows => { this.candidates.clear(); for (const row of rows) this.candidates.set(row.id, row); return rows }).finally(() => { this.discovering = undefined })
+ return this.discovering
+ }
+ start(): void { this.stopping = false; void this.reconnect(); this.timer = setInterval(() => void this.reconnect(), 15000); this.timer.unref() }
+ stop(): void { this.stopping = true; if (this.timer) clearInterval(this.timer); for (const link of this.links.values()) link.ws.terminate(); this.links.clear() }
+ connected(): number { return [...this.links.values()].filter(l => l.ws.readyState === WebSocket.OPEN).length }
+ async pair(device: string, code: string): Promise<Record<string, unknown>> {
+ if (this.pairing) throw Object.assign(new Error('Pairing already active'), { code: 'BUSY' })
+ this.pairing = true
+ let success = false
+ try {
+ await this.discover()
+ const candidate = this.candidates.get(device)
+ if (!candidate) throw Object.assign(new Error('Selected device is no longer discoverable'), { code: 'DEVICE_NOT_FOUND' })
+ const old = this.links.get(device); if (old) { old.ws.terminate(); this.links.delete(device) }
+ await this.connect(candidate, true)
+ const link = this.links.get(device)!
+ const deadline = Date.now() + 10000
+ while (this.host.pendingConnection() !== link.connId && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 50))
+ if (this.host.pendingConnection() !== link.connId || this.host.pending()?.role !== 'device') throw Object.assign(new Error('Open pairing on the selected device'), { code: 'NO_INTENT' })
+ const result = await this.host.pair(code)
+ if (!result.ok) throw Object.assign(new Error(result.error), { code: result.error })
+ const peerFingerprint = this.host.pairedFingerprint(link.connId)
+ if (!peerFingerprint) throw new Error('Paired device identity unavailable')
+ const authDeadline = Date.now() + 15000
+ while (!this.host.authenticatedFingerprint(link.connId) && Date.now() < authDeadline && link.ws.readyState === WebSocket.OPEN) await new Promise(resolve => setTimeout(resolve, 25))
+ if (this.host.authenticatedFingerprint(link.connId) !== peerFingerprint) throw new Error('Paired device session did not authenticate')
+ this.associations = this.associations.filter(a => a.discoveryId !== device && a.fingerprint !== peerFingerprint)
+ this.associations.push({ discoveryId: device, fingerprint: peerFingerprint }); this.save()
+ success = true
+ return { state: 'paired', label: result.label, fingerprint: peerFingerprint ?? result.fingerprint }
+ } finally { this.pairing = false; if (!success) { this.links.get(device)?.ws.terminate(); this.links.delete(device) } }
+ }
+ revoked(fingerprint: string): void {
+ const ids = this.associations.filter(a => a.fingerprint === fingerprint).map(a => a.discoveryId)
+ this.associations = this.associations.filter(a => a.fingerprint !== fingerprint)
+ for (const id of ids) { this.links.get(id)?.ws.terminate(); this.links.delete(id) }
+ this.save()
+ }
+ private async reconnect(): Promise<void> {
+ if (this.stopping || this.pairing || !this.associations.length) return
+ try {
+ const trusted = new Set(this.host.paired().filter(p => p.role === 'device').map(p => p.fingerprint))
+ for (const a of [...this.associations]) if (!trusted.has(a.fingerprint)) this.revoked(a.fingerprint)
+ await this.discover()
+ if (this.stopping || this.pairing) return
+ for (const a of this.associations) { const candidate = this.candidates.get(a.discoveryId); if (candidate && !this.links.has(a.discoveryId)) await this.connect(candidate).catch(() => {}) }
+ } catch { /* Offline discovery retries without changing trust. */ }
+ }
+ private connect(candidate: DiscoveredDevice, pairingAllowed = false): Promise<void> {
+ const existing = this.links.get(candidate.id); if (existing) return existing.ready
+ const url = new URL(`http://${candidate.host.includes(':') ? `[${candidate.host}]` : candidate.host}:${candidate.port}`); url.protocol = 'ws:'; url.pathname = '/api/harness/ws'
+ const ws = new WebSocket(url, { maxPayload: 65536, handshakeTimeout: 10000 }), connId = `autonomous-direct:${randomUUID()}`
+ const expected = pairingAllowed ? undefined : this.associations.find(a => a.discoveryId === candidate.id)?.fingerprint
+ const authTimer = setTimeout(() => { if (!this.host.authenticatedFingerprint(connId)) ws.terminate() }, 20000)
+ ws.once('close', () => clearTimeout(authTimer))
+ const ready = new Promise<void>((resolve, reject) => {
+ const timer = setTimeout(() => { ws.terminate(); reject(new Error('Device connection timed out')) }, 10000)
+ ws.once('open', () => {
+ clearTimeout(timer)
+ this.host.attach(connId, frame => { if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(frame)) })
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: this.host.machineId, label: this.host.label } })); resolve()
+ })
+ ws.once('error', error => { clearTimeout(timer); reject(error) })
+ ws.once('close', () => { clearTimeout(timer); reject(new Error('Device connection closed')); this.host.detach(connId); if (this.links.get(candidate.id)?.ws === ws) this.links.delete(candidate.id) })
+ })
+ ws.on('message', raw => { try { const frame = JSON.parse(raw.toString()) as Record<string, unknown>; if (frame && typeof frame === 'object' && !Array.isArray(frame)) void (async () => {
+ if (expected && frame.type === 'e2e_hello') {
+ const payload = frame.payload as { identityPub?: unknown } | undefined
+ if (typeof payload?.identityPub !== 'string' || fingerprint(b64d(payload.identityPub)) !== expected) { ws.close(4401); return }
+ }
+ await this.host.receive(connId, frame, pairingAllowed && this.pairing)
+ if (this.host.authenticatedFingerprint(connId)) clearTimeout(authTimer)
+ })().catch(() => ws.close(1011)) } catch { ws.close(1007) } })
+ this.links.set(candidate.id, { ws, connId, ready }); return ready
+ }
+}
diff --git a/cli/src/lib/autonomous-device/discovery.ts b/cli/src/lib/autonomous-device/discovery.ts
new file mode 100644
index 000000000..abc8eb2e3
--- /dev/null
+++ b/cli/src/lib/autonomous-device/discovery.ts
@@ -0,0 +1,20 @@
+import Bonjour from 'bonjour-service'
+import { isIP } from 'node:net'
+export interface DiscoveredDevice { id: string; name: string; host: string; port: number }
+/** Reuse the OS's existing Avahi _autonomous._tcp advertisement. Discovery grants no trust. */
+export function discoverDevices(durationMs = 3000): Promise<DiscoveredDevice[]> {
+ return new Promise((resolve, reject) => {
+ const found = new Map<string, DiscoveredDevice>()
+ let done = false
+ const bonjour = new Bonjour({}, (error: Error) => finish(error))
+ const browser = bonjour.find({ type: 'autonomous', protocol: 'tcp' }, service => {
+ const host = service.addresses?.find(a => isIP(a) === 4) ?? service.host
+ if (service.fqdn && host && service.port > 0 && service.port <= 65535) found.set(service.fqdn, { id: service.fqdn, name: service.name, host, port: service.port })
+ })
+ const timer = setTimeout(() => finish(), durationMs)
+ function finish(error?: Error) {
+ if (done) return; done = true; clearTimeout(timer); browser.stop(); bonjour.destroy()
+ if (error) reject(error); else resolve([...found.values()].sort((a, b) => a.name.localeCompare(b.name)))
+ }
+ })
+}
diff --git a/cli/src/lib/autonomous-device/localApi.spec.ts b/cli/src/lib/autonomous-device/localApi.spec.ts
new file mode 100644
index 000000000..eea4f6927
--- /dev/null
+++ b/cli/src/lib/autonomous-device/localApi.spec.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest'
+import { autonomousDeviceLocalRequest, type AutonomousDeviceManagement } from './localApi.js'
+
+const id = Buffer.alloc(32, 255).toString('base64')
+function fixture() {
+ return {
+ discover: vi.fn().mockReturnValue({ devices: [] }),
+ pairStart: vi.fn().mockResolvedValue({ state: 'running' }),
+ pairStatus: vi.fn().mockReturnValue({ state: 'waiting' }),
+ list: vi.fn().mockReturnValue({ devices: [] }),
+ status: vi.fn().mockReturnValue({ proto: 1 }),
+ revoke: vi.fn().mockReturnValue({ revoked: 1 }),
+ receipt: vi.fn().mockReturnValue({ receipt: null }),
+ } satisfies AutonomousDeviceManagement
+}
+
+describe('device local management validation', () => {
+ it('passes the human-entered device code and returns service data without an extra envelope', async () => {
+ const service = fixture()
+ expect(await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/pair/start', { code: 'ABC234', device: 'os._autonomous._tcp.local' }))
+ .toEqual({ status: 200, body: { state: 'running' } })
+ expect(service.pairStart).toHaveBeenCalledWith({ code: 'ABC234', device: 'os._autonomous._tcp.local' })
+ })
+
+ it.each([null, [], true, { replace: 'true' }, { replace: 1 }, { replace: true, all: true }])(
+ 'never opens a pairing window for invalid input %j', async body => {
+ const service = fixture()
+ expect((await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/pair/start', body)).status).toBe(400)
+ expect(service.pairStart).not.toHaveBeenCalled()
+ },
+ )
+
+ it.each([{}, { all: false }, { all: 'true' }, { all: true, id }, { id: '' }, { id: 'unknown' }, { id, replace: true }])(
+ 'never revokes for ambiguous or invalid input %j', async body => {
+ const service = fixture()
+ expect((await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/revoke', body)).status).toBe(400)
+ expect(service.revoke).not.toHaveBeenCalled()
+ },
+ )
+
+ it('revokes only a full existing-manager fingerprint and refuses blanket all', async () => {
+ const service = fixture(), fingerprint = 'ABCD·1234·5678·90EF'
+ expect((await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/revoke', { id: fingerprint })).status).toBe(200)
+ expect(service.revoke).toHaveBeenCalledWith({ id: fingerprint })
+ expect((await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/revoke', { all: true })).status).toBe(400)
+ })
+
+ it('decodes escaped identity characters and scopes receipt lookup to both identifiers', async () => {
+ const service = fixture()
+ const query = new URLSearchParams({ deviceId: id, idempotencyKey: 'device-1' })
+ expect(await autonomousDeviceLocalRequest(service, 'GET', `/api/autonomous-device/receipt?${query}`))
+ .toEqual({ status: 200, body: { receipt: null } })
+ expect(service.receipt).toHaveBeenCalledWith({ deviceId: id, idempotencyKey: 'device-1' })
+ })
+
+ it.each([
+ '', 'deviceId=x&idempotencyKey=y',
+ `deviceId=${encodeURIComponent(id)}&idempotencyKey=x&idempotencyKey=y`,
+ `deviceId=${encodeURIComponent(id)}&idempotencyKey=x&all=true`,
+ `deviceId=${encodeURIComponent(id)}&idempotencyKey=${'x'.repeat(65)}`,
+ `deviceId=${encodeURIComponent(id)}&idempotencyKey=a%20b`,
+ ])('refuses malformed or duplicate receipt query %s', async query => {
+ const service = fixture()
+ expect((await autonomousDeviceLocalRequest(service, 'GET', `/api/autonomous-device/receipt?${query}`)).status).toBe(400)
+ expect(service.receipt).not.toHaveBeenCalled()
+ })
+
+ it.each([
+ ['GET', '/api/autonomous-device/pair/start', undefined, 405],
+ ['POST', '/api/autonomous-device/unknown', undefined, 404],
+ ['GET', '/api/autonomous-device/status?all=true', undefined, 400],
+ ['GET', '/api/autonomous-device/status', {}, 400],
+ ['POST', '/api/autonomous-device/pair/cancel', { all: true }, 404],
+ ['GET', '//other/api/autonomous-device/status', undefined, 400],
+ ])('rejects unsupported routing %s %s', async (method, path, body, status) => {
+ const service = fixture()
+ expect((await autonomousDeviceLocalRequest(service, method as string, path as string, body)).status).toBe(status)
+ for (const handler of Object.values(service)) expect(handler).not.toHaveBeenCalled()
+ })
+
+ it('maps already-paired to conflict and hides unexpected internal errors', async () => {
+ const service = fixture()
+ service.pairStart.mockRejectedValue(Object.assign(new Error('A device is already paired'), { code: 'ALREADY_PAIRED' }))
+ expect(await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/pair/start', { code: 'ABC234', device: 'os._autonomous._tcp.local' }))
+ .toEqual({ status: 409, body: { error: { code: 'ALREADY_PAIRED', message: 'A device is already paired' } } })
+ service.pairStart.mockRejectedValue(new Error('secret-file-content'))
+ expect(await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/pair/start', { code: 'ABC234', device: 'os._autonomous._tcp.local' }))
+ .toEqual({ status: 500, body: { error: { code: 'INTERNAL_ERROR', message: 'Autonomous device management request failed' } } })
+ })
+
+ it('routes all read-only and cancel operations', async () => {
+ const service = fixture()
+ for (const [method, path, name] of [
+ ['GET', 'pair/status', 'pairStatus'],
+ ['GET', 'list', 'list'], ['GET', 'status', 'status'],
+ ] as const) {
+ expect((await autonomousDeviceLocalRequest(service, method, `/api/autonomous-device/${path}`)).status).toBe(200)
+ expect(service[name]).toHaveBeenCalledOnce()
+ }
+ })
+})
diff --git a/cli/src/lib/autonomous-device/localApi.ts b/cli/src/lib/autonomous-device/localApi.ts
new file mode 100644
index 000000000..6a70e2703
--- /dev/null
+++ b/cli/src/lib/autonomous-device/localApi.ts
@@ -0,0 +1,101 @@
+/** Thin local facade for the existing relay pairing manager. */
+export interface AutonomousDeviceManagement {
+ discover(): unknown | Promise<unknown>
+ pairStart(options: { code: string; device: string }): unknown | Promise<unknown>
+ pairStatus(): unknown | Promise<unknown>
+ list(): unknown | Promise<unknown>
+ status(): unknown | Promise<unknown>
+ revoke(target: { id: string }): unknown | Promise<unknown>
+ receipt(target: { deviceId: string; idempotencyKey: string }): unknown | Promise<unknown>
+}
+
+export interface AutonomousDeviceLocalResponse { status: number; body: unknown }
+
+const routes: Record<string, string> = {
+ '/api/autonomous-device/discover': 'GET',
+ '/api/autonomous-device/pair/start': 'POST',
+ '/api/autonomous-device/pair/status': 'GET',
+ '/api/autonomous-device/list': 'GET',
+ '/api/autonomous-device/status': 'GET',
+ '/api/autonomous-device/revoke': 'POST',
+ '/api/autonomous-device/receipt': 'GET',
+}
+
+const errorStatus: Record<string, number> = {
+ BAD_REQUEST: 400, UNKNOWN_DEVICE: 404, ALREADY_PAIRED: 409, BUSY: 409,
+ DEVICE_NOT_FOUND: 404, BAD_CODE: 400, NO_INTENT: 409, STALE_PAIR: 409, CODE_MISMATCH: 403, BACKEND_DOWN: 503, TIMEOUT: 504, RATE_LIMITED: 429, EXPIRED: 410, CANCELLED: 409,
+}
+
+function failure(status: number, code: string, message: string): AutonomousDeviceLocalResponse {
+ return { status, body: { error: { code, message } } }
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function deviceId(value: unknown): value is string {
+ // Autonomous device identities are canonical base64 Ed25519 public keys (32 bytes).
+ return typeof value === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(value)
+ && Buffer.from(value, 'base64').toString('base64') === value
+}
+
+/** The caller must enforce loopback, Origin refusal, and the hook credential first. */
+export async function autonomousDeviceLocalRequest(
+ service: AutonomousDeviceManagement, method: string, requestTarget: string, body?: unknown,
+): Promise<AutonomousDeviceLocalResponse> {
+ const bad = () => failure(400, 'BAD_REQUEST', 'Invalid device management request')
+ let url: URL
+ try {
+ if (!requestTarget.startsWith('/') || requestTarget.startsWith('//')) return bad()
+ url = new URL(requestTarget, 'http://localhost')
+ } catch { return bad() }
+ if (url.hash) return bad()
+ const expected = routes[url.pathname]
+ if (!expected) return failure(404, 'NOT_FOUND', 'Unknown device management endpoint')
+ if (method !== expected) return failure(405, 'METHOD_NOT_ALLOWED', 'Method not allowed')
+ if (method === 'GET' && body !== undefined) return bad()
+ if (url.pathname !== '/api/autonomous-device/receipt' && url.search) return bad()
+ const input = body === undefined ? {} : body
+ if (!object(input)) return bad()
+ const keys = Object.keys(input)
+ let call: () => unknown | Promise<unknown>
+ switch (url.pathname) {
+ case '/api/autonomous-device/pair/start':
+ if (keys.some(key => !['code', 'device'].includes(key)) || typeof input.code !== 'string' || input.code.length > 32 || typeof input.device !== 'string' || !input.device || input.device.length > 255) return bad()
+ call = () => service.pairStart({ code: input.code as string, device: input.device as string })
+ break
+ case '/api/autonomous-device/revoke':
+ if (keys.length !== 1 || keys[0] !== 'id' || typeof input.id !== 'string' || !/^[A-F0-9]{4}(?:·[A-F0-9]{4}){3}$/.test(input.id)) return bad()
+ const id = input.id
+ call = () => service.revoke({ id })
+ break
+ case '/api/autonomous-device/receipt': {
+ const query = url.searchParams
+ if ([...query.keys()].some(key => key !== 'deviceId' && key !== 'idempotencyKey')
+ || query.getAll('deviceId').length !== 1 || query.getAll('idempotencyKey').length !== 1) return bad()
+ const id = query.get('deviceId')
+ const key = query.get('idempotencyKey')
+ if (!deviceId(id) || !key || !/^[A-Za-z0-9_-]{1,64}$/.test(key)) return bad()
+ call = () => service.receipt({ deviceId: id, idempotencyKey: key })
+ break
+ }
+ default:
+ if (keys.length) return bad()
+ switch (url.pathname) {
+ case '/api/autonomous-device/discover': call = () => service.discover(); break
+ case '/api/autonomous-device/pair/status': call = () => service.pairStatus(); break
+ case '/api/autonomous-device/list': call = () => service.list(); break
+ default: call = () => service.status()
+ }
+ }
+ try {
+ return { status: 200, body: await call() }
+ } catch (error) {
+ if (object(error) && typeof error.code === 'string' && Object.hasOwn(errorStatus, error.code)) {
+ return failure(errorStatus[error.code], error.code,
+ typeof error.message === 'string' ? error.message : 'Autonomous device management request failed')
+ }
+ return failure(500, 'INTERNAL_ERROR', 'Autonomous device management request failed')
+ }
+}
diff --git a/cli/src/lib/autonomous-device/relay.spec.ts b/cli/src/lib/autonomous-device/relay.spec.ts
new file mode 100644
index 000000000..db161a059
--- /dev/null
+++ b/cli/src/lib/autonomous-device/relay.spec.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest'
+import { AutonomousDeviceRelay } from './relay.js'
+import { AutonomousDeviceService } from './service.js'
+import { randomUUID } from 'node:crypto'
+function fixture() {
+ let role = 'device', identity: string | null = 'trusted-device'
+ const submit = vi.fn(), cancel = vi.fn(() => true), send = vi.fn()
+ const crypto = { sessionRole: () => role as 'device' | 'web', sessionIdentity: () => identity,
+ 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 } }) }
+ const service = new AutonomousDeviceService({ machineId: 'machine', agents: () => [{ agentId: 'agent', name: 'Agent', engine: 'codex', state: 'idle' }], submit, cancelDelivery: cancel, stop: async () => true, answer: async () => true, recent: () => [] })
+ const relay = new AutonomousDeviceRelay(crypto, send, service, 'machine')
+ const request = (payload: Record<string, unknown>) => relay.handle('conn', { type: 'autonomous_device_request', payload: { __e2e: payload } })
+ return { relay, request, send, submit, service, cancel, setRole: (r: string) => { role = r }, revoke: () => { identity = null } }
+}
+describe('Autonomous device existing E2EE relay seam', () => {
+ it('requires existing device-role trust and encrypted payload before calling the service', async () => {
+ const f = fixture(); f.setRole('web')
+ await f.request({ type: 'hello', proto: 1, requestId: randomUUID() })
+ expect(f.send).not.toHaveBeenCalled()
+ f.setRole('device'); await f.relay.handle('conn', { type: 'autonomous_device_request', payload: { type: 'hello' } })
+ expect(f.send).not.toHaveBeenCalled()
+ await f.request({ type: 'hello', proto: 1, requestId: randomUUID() })
+ expect(f.send.mock.calls[0][1]).toMatchObject({ type: 'autonomous_device_result', payload: { __e2e: { type: 'hello_result', proto: 1 } } })
+ })
+ it('uses pinned identity for dedupe and drops revoked queued work', async () => {
+ const f = fixture(); await f.request({ type: 'hello', proto: 1, requestId: randomUUID() })
+ const req = { type: 'turn.send', requestId: randomUUID(), machineId: 'machine', agentId: 'agent', idempotencyKey: 'one', text: 'hello' }
+ await f.request(req); await f.request({ ...req, requestId: randomUUID() })
+ expect(f.submit).toHaveBeenCalledTimes(1)
+ expect(f.service.receipt('trusted-device', 'one')?.state).toBe('queued')
+ f.relay.revoke('trusted-device'); f.revoke()
+ expect(f.cancel).toHaveBeenCalledOnce()
+ expect(f.service.receipt('trusted-device', 'one')).toBeNull()
+ await f.request(req); expect(f.submit).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/cli/src/lib/autonomous-device/relay.ts b/cli/src/lib/autonomous-device/relay.ts
new file mode 100644
index 000000000..50aeeeb1f
--- /dev/null
+++ b/cli/src/lib/autonomous-device/relay.ts
@@ -0,0 +1,57 @@
+import { isWrapped } from '../e2ee/core.js'
+import type { E2eeManager } from '../e2ee/manager.js'
+import { AUTONOMOUS_DEVICE_CAPABILITIES, type AutonomousDeviceService, type AutonomousDeviceFrame } from './service.js'
+
+type Frame = Record<string, unknown>
+/** Application RPC over the existing relay E2EE session. No socket, identity, PAKE or trust of its own. */
+export class AutonomousDeviceRelay {
+ private readonly clients = new Map<string, { identity: string; tokens: number; at: number; active: number }>()
+ constructor(private readonly crypto: Pick<E2eeManager, 'sessionIdentity' | 'sessionRole' | 'unwrapDown' | 'wrapTarget'>,
+ private readonly send: (connId: string, frame: Frame) => void,
+ private readonly service: AutonomousDeviceService, private readonly machineId: string, private readonly onReady?: () => void) {}
+ count(include: (connId: string) => boolean = () => true): number { return [...this.clients].filter(([id, client]) => include(id) && this.crypto.sessionIdentity(id) === client.identity && this.crypto.sessionRole(id) === 'device').length }
+ 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
+ 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)
+ 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
+ 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 }
+ const current = this.clients.get(connId)
+ this.clients.set(connId, current?.identity === identity ? current : { identity, tokens: 20, at: Date.now(), active: 0 })
+ const resume = req.resume as { serverInstanceId?: unknown; cursor?: unknown } | undefined
+ reply({ type: 'hello_result', requestId: req.requestId, proto: 1, machineId: this.machineId, serverInstanceId: this.service.serverInstanceId, capabilities: AUTONOMOUS_DEVICE_CAPABILITIES, ...this.service.resume(resume) })
+ this.service.replay(resume, event => this.sendEvent(connId, identity, event))
+ this.onReady?.()
+ return
+ }
+ const client = this.clients.get(connId)
+ if (!client || client.identity !== identity) { reply({ type: `${req.type}_result`, requestId: req.requestId, error: { code: 'HELLO_REQUIRED', message: 'Send application hello first' } }); return }
+ const now = Date.now(); client.tokens = Math.min(20, client.tokens + Math.max(0, now - client.at) / 1000); client.at = now
+ const error = client.tokens < 1 ? 'RATE_LIMITED' : client.active >= 4 ? 'BACKPRESSURE' : null
+ if (error) { reply({ type: `${req.type}_result`, requestId: req.requestId, error: { code: error, message: error } }); return }
+ client.tokens--; client.active++
+ try { reply(await this.service.request(identity, req)) } finally { client.active-- }
+ }
+ private sendEvent(connId: string, identity: string, event: AutonomousDeviceFrame): void {
+ const p = event.payload as Frame | undefined
+ if (typeof p?.idempotencyKey === 'string') {
+ const own = this.service.receipt(identity, p.idempotencyKey)
+ const receipt = p.receipt as Frame | undefined
+ if (!own || (receipt && receipt.deliveryId !== own.deliveryId) || (p.turnId && p.turnId !== own.turnId)) return
+ }
+ 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) }
+ revoke(identity: string): void { for (const [connId, client] of this.clients) if (client.identity === identity) this.clients.delete(connId); this.service.revoke(identity) }
+}
diff --git a/cli/src/lib/autonomous-device/service.spec.ts b/cli/src/lib/autonomous-device/service.spec.ts
new file mode 100644
index 000000000..7ad53faba
--- /dev/null
+++ b/cli/src/lib/autonomous-device/service.spec.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest'
+import { randomUUID } from 'node:crypto'
+import { AutonomousDeviceService, type AutonomousDeviceFrame } from './service.js'
+
+function fixture(now?: () => number) {
+ const submit = vi.fn(), stop = vi.fn(async () => true), answer = vi.fn(async () => true)
+ const events: AutonomousDeviceFrame[] = []
+ const service = new AutonomousDeviceService({ now, machineId: 'machine', agents: () => [{ agentId: 'agent', name: 'Project', engine: 'claude', state: 'idle' }],
+ submit, stop, answer, cancelDelivery: vi.fn(() => true), recent: () => [], emit: f => events.push(f) })
+ const send = (fields: Record<string, unknown> = {}) => ({ type: 'turn.send', requestId: randomUUID(), machineId: 'machine', agentId: 'agent', text: 'hello', idempotencyKey: 'intent1', ...fields })
+ return { service, submit, stop, answer, events, send }
+}
+
+describe('Autonomous device local-agent service', () => {
+ it('reserves before dispatch and deduplicates concurrent sends without selecting another agent', async () => {
+ const f = fixture()
+ const [a, b] = await Promise.all([f.service.request('device', f.send()), f.service.request('device', f.send())])
+ expect(f.submit).toHaveBeenCalledTimes(1)
+ expect(a.status).toBe('accepted'); expect(b.status).toBe('duplicate')
+ expect(a.receipt).toEqual(b.receipt)
+ expect(f.submit.mock.calls[0].slice(0, 2)).toEqual(['agent', 'hello'])
+ })
+ it('rejects reuse for a different operation, target or payload', async () => {
+ const f = fixture()
+ await f.service.request('device', f.send())
+ for (const changes of [{ text: 'different' }, { agentId: 'other' }, { type: 'turn.stop', text: undefined }]) {
+ const req: Record<string, unknown> = f.send(changes); if (req.text === undefined) delete req.text
+ const result = await f.service.request('device', req)
+ expect(result.error).toMatchObject({ code: 'IDEMPOTENCY_CONFLICT' })
+ }
+ expect(f.submit).toHaveBeenCalledTimes(1)
+ })
+ it('never dispatches outside the paired machine or to an unavailable agent', async () => {
+ const f = fixture()
+ expect((await f.service.request('device', f.send({ machineId: 'other' }))).error).toMatchObject({ code: 'MACHINE_MISMATCH' })
+ expect((await f.service.request('device', f.send({ agentId: 'missing' }))).error).toMatchObject({ code: 'AGENT_NOT_FOUND' })
+ expect(f.submit).not.toHaveBeenCalled()
+ })
+ it('preserves uncertain delivery and exposes the latest receipt on duplicate', async () => {
+ const f = fixture(); await f.service.request('device', f.send())
+ const deliveryId = f.submit.mock.calls[0][2]
+ f.service.delivery({ deliveryId, sessionId: 'agent', state: 'unknown', reason: 'NOT_CONFIRMED' })
+ expect(f.service.receipt('device', 'intent1')?.state).toBe('unknown')
+ expect(f.service.receipt('another-device', 'intent1')).toBeNull()
+ expect((await f.service.request('device', f.send())).receipt).toMatchObject({ state: 'unknown' })
+ expect(f.submit).toHaveBeenCalledTimes(1)
+ })
+ it('correlates completion only to the delivery whose start was observed', async () => {
+ const f = fixture(); await f.service.request('device', f.send())
+ f.service.turnEnded('agent')
+ expect(f.service.receipt('device', 'intent1')?.state).toBe('queued')
+ f.service.delivery({ deliveryId: f.submit.mock.calls[0][2], sessionId: 'agent', state: 'started' })
+ f.service.turnEnded('agent')
+ expect(f.service.receipt('device', 'intent1')).toMatchObject({ state: 'completed', turnId: expect.any(String) })
+ })
+ it('resyncs an old instance and replays only newer events for the current one', () => {
+ const f = fixture(); f.service.event('agents.changed', undefined, {})
+ const send = vi.fn()
+ f.service.replay({ serverInstanceId: 'old', cursor: 500 }, send)
+ expect(send).toHaveBeenCalledWith(expect.objectContaining({ type: 'resync', reason: 'instance_changed' }))
+ send.mockClear(); f.service.replay({ serverInstanceId: f.service.serverInstanceId, cursor: 0 }, send)
+ expect(send).toHaveBeenCalledWith(expect.objectContaining({ type: 'event', eventId: 1 }))
+ })
+ it('rejects stale questions and validates all answer fields', async () => {
+ const f = fixture()
+ const req = { type: 'question.answer', requestId: randomUUID(), machineId: 'machine', agentId: 'agent', idempotencyKey: 'q1', questionRequestId: 'question1', answers: { branch: 'main' } }
+ expect((await f.service.request('device', req)).error).toMatchObject({ code: 'QUESTION_STALE' })
+ f.service.commander({ type: 'commander_question', agentId: 'agent', payload: { requestId: 'question1', questions: [] } })
+ expect((await f.service.request('device', { ...req, requestId: randomUUID() })).receipt).toMatchObject({ state: 'completed' })
+ expect((await f.service.request('device', { ...req, requestId: randomUUID(), answers: { branch: 'other' } })).error).toMatchObject({ code: 'IDEMPOTENCY_CONFLICT' })
+ expect(f.answer).toHaveBeenCalledTimes(1)
+ })
+})
+
+
+describe('Autonomous device receipt result contract and bounded cache', () => {
+ it('reports reserved delivery rejection inside an accepted receipt', async () => {
+ const f = fixture()
+ f.submit.mockImplementation((_agent: string, _text: string, deliveryId: string) => {
+ f.service.delivery({ deliveryId, sessionId: 'agent', state: 'rejected', reason: 'AGENT_NOT_FOUND' })
+ })
+ expect(await f.service.request('device', f.send())).toMatchObject({ status: 'accepted', receipt: { state: 'rejected', error: { code: 'AGENT_NOT_FOUND' } } })
+ })
+ it('retains a receipt if authorization is revoked while an async mutation completes', async () => {
+ const f = fixture()
+ let complete!: (ok: boolean) => void
+ f.stop.mockImplementation(() => new Promise<boolean>(resolve => { complete = resolve }))
+ const response = f.service.request('device', { type: 'turn.stop', requestId: randomUUID(), machineId: 'machine', agentId: 'agent', idempotencyKey: 'stop' })
+ f.service.revoke('device'); complete(true)
+ expect(await response).toMatchObject({ status: 'accepted', receipt: { state: 'unknown', error: { code: 'REVOKED' } } })
+ expect(f.service.receipt('device', 'stop')).toBeNull()
+ })
+ it('evicts the oldest settled receipt under capacity pressure and retains unresolved ones', async () => {
+ let now = 1
+ const f = fixture(() => now++)
+ for (let i = 0; i < 512; i++) {
+ await f.service.request('device', f.send({ idempotencyKey: `key${i}` }))
+ if (i > 0) f.service.delivery({ deliveryId: f.submit.mock.calls[i][2], sessionId: 'agent', state: 'rejected' })
+ }
+ expect((await f.service.request('device', f.send({ idempotencyKey: 'new' }))).status).toBe('accepted')
+ expect(f.service.receipt('device', 'key0')?.state).toBe('queued')
+ expect(f.service.receipt('device', 'key1')).toBeNull()
+ expect((await f.service.request('device', f.send({ idempotencyKey: 'key0' }))).status).toBe('duplicate')
+ })
+ it('refuses new work if all 512 reservations remain ambiguous or live', async () => {
+ const f = fixture()
+ for (let i = 0; i < 512; i++) await f.service.request('device', f.send({ idempotencyKey: `key${i}` }))
+ expect((await f.service.request('device', f.send({ idempotencyKey: 'overflow' }))).error).toMatchObject({ code: 'BACKPRESSURE' })
+ expect(f.submit).toHaveBeenCalledTimes(512)
+ })
+})
diff --git a/cli/src/lib/autonomous-device/service.ts b/cli/src/lib/autonomous-device/service.ts
new file mode 100644
index 000000000..3329ded97
--- /dev/null
+++ b/cli/src/lib/autonomous-device/service.ts
@@ -0,0 +1,217 @@
+import { createHash, randomUUID } from 'node:crypto'
+
+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
+ error: { code: string; message: string } | null; at: number
+}
+export interface AutonomousDeviceAgent { agentId: string; name: string; engine: string; state: string }
+export interface AutonomousDeviceDelivery { deliveryId: string; sessionId: string; state: ReceiptState; reason?: string }
+export interface AutonomousDeviceServiceOptions {
+ machineId: string; serverInstanceId?: string; now?: () => number
+ agents: () => AutonomousDeviceAgent[]
+ submit: (agentId: string, text: string, deliveryId: string) => void
+ cancelDelivery: (deliveryId: string) => boolean
+ stop: (agentId: string) => Promise<boolean>
+ answer: (agentId: string, questionRequestId: string, answers: Record<string, string>) => Promise<boolean>
+ recent: (agentId: string, n: number) => unknown[]
+ emit?: (frame: AutonomousDeviceFrame) => void
+}
+interface Entry { deviceId: string; digest: string; receipt: AutonomousDeviceReceipt }
+const CAPABILITIES = ['agents.list', 'turn.send', 'turn.stop', 'status', 'recap', 'question.answer', 'receipt.get'] as const
+export const AUTONOMOUS_DEVICE_CAPABILITIES: string[] = [...CAPABILITIES]
+const MUTATIONS = new Set(['turn.send', 'turn.stop', 'question.answer'])
+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>()
+ private readonly questions = new Map<string, { requestId: string; questions: unknown }>()
+ private events: AutonomousDeviceFrame[] = []
+ private sequence = 0
+ constructor(private readonly options: AutonomousDeviceServiceOptions) {
+ this.serverInstanceId = options.serverInstanceId ?? randomUUID()
+ this.now = options.now ?? Date.now
+ }
+ private key(deviceId: string, key: string): string { return `${deviceId}:${key}` }
+ 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, 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' && 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()
+ this.turns.set(entry.receipt.agentId, entry)
+ }
+ this.event('receipt.updated', entry.receipt.agentId, { receipt: structuredClone(entry.receipt), idempotencyKey: entry.receipt.idempotencyKey })
+ }
+ delivery(event: AutonomousDeviceDelivery): void {
+ const entry = this.deliveries.get(event.deliveryId)
+ if (!entry) return
+ this.update(entry, event.state, event.reason)
+ }
+ revoke(deviceId: string): void {
+ 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)
+ }
+ // A newly paired identity cannot replay the previous device's request receipts.
+ this.events = []
+ }
+ event(kind: string, agentId: string | undefined, payload: Record<string, unknown>): void {
+ const frame: AutonomousDeviceFrame = { type: 'event', eventId: ++this.sequence, serverInstanceId: this.serverInstanceId,
+ machineId: this.options.machineId, ...(agentId ? { agentId } : {}), kind, payload }
+ this.events.push(frame)
+ if (this.events.length > 500) this.events.shift()
+ this.options.emit?.(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 })
+ return
+ }
+ for (const event of this.events) if (Number(event.eventId) > Number(resume?.cursor)) send(event)
+ }
+ turnStarted(agentId: string): void {
+ 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 {
+ 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') {
+ this.questions.set(agentId, { requestId: p.requestId, questions: p.questions })
+ this.event('question.open', agentId, { questionRequestId: p.requestId, questions: p.questions })
+ } 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))) {
+ this.event(p.kind === 'summary' ? 'turn.summary' : p.kind === 'tool' ? 'turn.tool' : 'agent.error', agentId, p)
+ }
+ }
+ 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 (!AUTONOMOUS_DEVICE_CAPABILITIES.includes(type)) fail('UNSUPPORTED_CAPABILITY', 'Operation is not supported')
+ const allowed = ['type', 'requestId', ...(type === 'agents.list' ? [] : type === 'receipt.get' ? ['idempotencyKey'] : ['machineId', 'agentId']),
+ ...(MUTATIONS.has(type) ? ['idempotencyKey'] : []), ...(type === 'turn.send' ? ['text'] : type === 'question.answer' ? ['questionRequestId', 'answers'] : 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 === 'agents.list') return response({ machineId: this.options.machineId, agents: this.options.agents().map(a => ({ ...a, machineId: this.options.machineId })) })
+ 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) })
+ }
+ 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: 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, 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
+ try {
+ if (type === 'turn.send') 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) })
+ }
+ return response({ error: { code: e instanceof RequestError ? e.code : 'INTERNAL', message: e instanceof RequestError ? e.message : 'Request failed' } })
+ }
+ }
+}
diff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.ts
index 73e491167..0f03f91aa 100644
--- a/cli/src/lib/e2ee/manager.ts
+++ b/cli/src/lib/e2ee/manager.ts
@@ -106,6 +106,9 @@ export interface E2eeManagerDeps {
sendUser?: (frame: Frame) => void
/** Is the backend link up right now (for onPair BACKEND_DOWN)? */
isConnected: () => boolean
+ isConnectionAvailable?: (connId: string) => boolean
+ onIdentityPaired?: (connId: string, identityPub: string) => void
+ onIdentityRevoked?: (identityPub: string) => void
}
export class E2eeManager {
@@ -149,15 +152,17 @@ export class E2eeManager {
}
}
hasSession(connId: string): boolean { return this.sessions.has(connId) }
+ sessionIdentity(connId: string): string | null { return this.sessions.get(connId)?.webIdentityPub ?? null }
sessionRole(connId: string): C.PairRole | null { return this.sessions.get(connId)?.role ?? null }
deviceConnected(): boolean { return [...this.sessions.values()].some((s) => s.role === 'device') }
- dropSessionsByRole(role: C.PairRole): void {
+ dropSessionsByRole(role: C.PairRole, preserve: (connId: string) => boolean = () => false): void {
for (const [connId, s] of [...this.sessions.entries()]) {
- if (s.role === role) this.sessions.delete(connId)
+ if (s.role === role && !preserve(connId)) this.sessions.delete(connId)
}
}
/** A browser currently waiting to pair (for the local dashboard), or null. `active` = CPace running. */
+ pendingConnection(): string | null { return this.slot?.connId ?? null }
pendingPair(): PendingPairInfo | null {
if (!this.slot) return null
return {
@@ -198,6 +203,7 @@ export class E2eeManager {
private revokeIdentity(identityPub: string): void {
this.store.removePaired(identityPub)
+ try { this.deps.onIdentityRevoked?.(identityPub) } catch { /* Optional device cleanup must not interrupt trust revocation. */ }
this.denyAndDropSessionsFor(identityPub)
this.rotateGroupKey()
}
@@ -229,6 +235,7 @@ export class E2eeManager {
revokeAll(): { count: number } {
const count = this.store.count()
for (const s of [...this.sessions.entries()]) { this.deny(s[0]); this.sessions.delete(s[0]) }
+ for (const paired of this.store.list()) { try { this.deps.onIdentityRevoked?.(paired.identityPub) } catch { /* Continue revoking every stored identity. */ } }
this.store.clear()
this.rotateGroupKey()
return { count }
@@ -512,7 +519,7 @@ export class E2eeManager {
if (!slot) { resolve({ ok: false, error: 'NO_INTENT' }); return }
if (slot.active) { resolve({ ok: false, error: 'BUSY' }); return }
if (this.now() > slot.expiresAt) { this.slot = null; resolve({ ok: false, error: 'EXPIRED' }); return }
- if (!this.deps.isConnected()) { resolve({ ok: false, error: 'BACKEND_DOWN' }); return }
+ if (!(this.deps.isConnectionAvailable?.(slot.connId) ?? this.deps.isConnected())) { resolve({ ok: false, error: 'BACKEND_DOWN' }); return }
clearTimeout(slot.ttlTimer)
const ci = C.pairContext(this.deps.machineId, slot.role)
@@ -556,6 +563,7 @@ export class E2eeManager {
if (!C.pairBindVerify(C.b64d(webId.id), slot.active.th, C.b64d(webId.sig))) { this.failPair('CODE_MISMATCH'); return true }
// pin the paired client identity
this.store.addPaired(webId.id, slot.label, this.now(), slot.role)
+ this.deps.onIdentityPaired?.(connId, webId.id)
const fp = this.fingerprint()
this.deps.sendTo(connId, { type: 'e2e_pake', payload: { pairId: slot.pairIdB64, round: 5, ok: true, fingerprint: fp } })
const resolve = slot.active.resolve
diff --git a/cli/src/lib/sessionInput.spec.ts b/cli/src/lib/sessionInput.spec.ts
index a4c0d3195..ce548e5c0 100644
--- a/cli/src/lib/sessionInput.spec.ts
+++ b/cli/src/lib/sessionInput.spec.ts
@@ -467,3 +467,208 @@ describe('SessionInputController', () => {
controller.forget('s1')
})
})
+
+describe('delivery correlation', () => {
+ afterEach(() => vi.useRealTimers())
+
+ function setup(overrides: Partial<ConstructorParameters<typeof SessionInputController>[0]> = {}) {
+ const onDelivery = vi.fn()
+ const inject = vi.fn(async () => true)
+ const controller = new SessionInputController({
+ getSession: () => session(), validateRuntime: async () => true,
+ inject, sendKey: async () => true, onError: vi.fn(), onDelivery, ...overrides,
+ })
+ return { controller, onDelivery, inject }
+ }
+
+ it('correlates a matching observed turn after successful delivery', async () => {
+ const { controller, onDelivery } = setup()
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.waitFor(() => expect(onDelivery).toHaveBeenCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'delivered' }))
+ controller.onTurnStarted('s1', 'hello')
+ expect(onDelivery.mock.calls.map(([event]) => event.state)).toEqual(['queued', 'delivered', 'started'])
+ controller.forget('s1')
+ })
+
+ it('buffers a turn observed before the paste promise resolves', async () => {
+ let release!: (value: boolean) => void
+ const { controller, onDelivery } = setup({ inject: () => new Promise<boolean>((resolve) => { release = resolve }) })
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.waitFor(() => expect(release).toBeTypeOf('function'))
+ controller.onTurnStarted('s1', 'hello')
+ release(true)
+ await vi.waitFor(() => expect(onDelivery.mock.calls.map(([event]) => event.state)).toEqual(['queued', 'delivered', 'started']))
+ controller.forget('s1')
+ })
+
+ it('does not attribute a different human prompt to the delivery', async () => {
+ const { controller, onDelivery } = setup()
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.waitFor(() => expect(onDelivery).toHaveBeenCalledTimes(2))
+ controller.onTurnStarted('s1', 'different')
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'unknown', reason: 'prompt_mismatch' })
+ controller.forget('s1')
+ })
+
+ it('revokes a queued delivery without touching the terminal', () => {
+ const { controller, onDelivery, inject } = setup()
+ controller.setTurnOpen('s1', true)
+ controller.submit('s1', 'hello', 'delivery-1')
+ expect(controller.cancelDelivery('delivery-1')).toBe(true)
+ controller.onTurnEnded('s1')
+ expect(inject).not.toHaveBeenCalled()
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'rejected', reason: 'cancelled' })
+ controller.forget('s1')
+ })
+
+ it('revokes during runtime validation before any paste', async () => {
+ let release!: (value: boolean) => void
+ const { controller, inject } = setup({ validateRuntime: () => new Promise<boolean>((resolve) => { release = resolve }) })
+ controller.submit('s1', 'hello', 'delivery-1')
+ expect(controller.cancelDelivery('delivery-1')).toBe(true)
+ release(true)
+ await Promise.resolve()
+ await Promise.resolve()
+ expect(inject).not.toHaveBeenCalled()
+ controller.forget('s1')
+ })
+
+ it('reports queue saturation and expiration without pasting', () => {
+ vi.useFakeTimers()
+ const { controller, onDelivery, inject } = setup()
+ controller.setTurnOpen('s1', true)
+ for (let i = 0; i < 9; i++) controller.submit('s1', 'hello', `delivery-${i}`)
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-8', state: 'rejected', reason: 'queue_full' })
+ vi.setSystemTime(Date.now() + 5 * 60_000 + 1)
+ controller.onTurnEnded('s1')
+ expect(onDelivery.mock.calls.filter(([event]) => event.reason === 'queue_expired')).toHaveLength(8)
+ expect(inject).not.toHaveBeenCalled()
+ controller.forget('s1')
+ })
+
+ it.each([
+ ['missing agent', { getSession: () => undefined }, 'agent_gone'],
+ ['missing process', { validateRuntime: async () => false }, 'runtime_gone_pre_paste'],
+ ['failed paste', { inject: async () => false }, 'paste_failed'],
+ ] as const)('rejects %s before successful delivery', async (_label, overrides, reason) => {
+ const { controller, onDelivery } = setup(overrides)
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.waitFor(() => expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'rejected', reason }))
+ controller.forget('s1')
+ })
+
+ it('reports ambiguous paste as unknown and never repastes', async () => {
+ vi.useFakeTimers()
+ const inject = vi.fn(async (): Promise<TerminalActionResult> => ({ state: 'unknown', dispatch: 'possibly_executed', reason: 'timeout' }))
+ const { controller, onDelivery } = setup({ inject })
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.advanceTimersByTimeAsync(1_600)
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'unknown', reason: 'dispatch_ambiguous' })
+ expect(inject).toHaveBeenCalledTimes(1)
+ controller.forget('s1')
+ })
+
+ it('reports retry exhaustion as unknown after the body was pasted', async () => {
+ vi.useFakeTimers()
+ const { controller, onDelivery } = setup()
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.advanceTimersByTimeAsync(4_600)
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'unknown', reason: 'not_submitted' })
+ controller.forget('s1')
+ })
+
+ it('reports process loss after paste as unknown', async () => {
+ vi.useFakeTimers()
+ const validateRuntime = vi.fn().mockResolvedValueOnce(true).mockResolvedValue(false)
+ const { controller, onDelivery } = setup({ validateRuntime })
+ controller.submit('s1', 'hello', 'delivery-1')
+ await vi.advanceTimersByTimeAsync(1_600)
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-1', state: 'unknown', reason: 'runtime_gone_post_paste' })
+ controller.forget('s1')
+ })
+})
+
+describe('optional lamp delivery preserves legacy behavior', () => {
+ afterEach(() => vi.useRealTimers())
+
+ it('keeps concurrent untracked Claude submits out of the new lamp queue', async () => {
+ const validations: Array<(valid: boolean) => void> = []
+ const inject = vi.fn(async () => true)
+ const controller = new SessionInputController({
+ getSession: () => session('claude'),
+ validateRuntime: () => new Promise<boolean>(resolve => validations.push(resolve)),
+ inject, sendKey: async () => true, onError: vi.fn(),
+ })
+ controller.setTurnOpen('s1', true)
+ controller.submit('s1', 'first local prompt')
+ controller.submit('s1', 'second local prompt')
+ expect(validations).toHaveLength(2)
+ validations.forEach(resolve => resolve(true))
+ await vi.waitFor(() => expect(inject).toHaveBeenCalledTimes(2))
+ controller.forget('s1')
+ })
+
+ it('keeps native control available during untracked runtime validation', async () => {
+ let resolve!: (valid: boolean) => void
+ const controller = new SessionInputController({
+ getSession: () => session('claude'),
+ validateRuntime: () => new Promise<boolean>(done => { resolve = done }),
+ inject: async () => true, sendKey: async () => true, onError: vi.fn(),
+ })
+ controller.submit('s1', 'local prompt')
+ const release = controller.acquireControl('s1')
+ expect(release).not.toBeNull()
+ release?.()
+ resolve(false)
+ await Promise.resolve()
+ controller.forget('s1')
+ })
+
+ it('reports the original legacy cancellation error for a vanished process', async () => {
+ const onError = vi.fn()
+ const sendKey = vi.fn(async () => true)
+ const controller = new SessionInputController({
+ getSession: () => session(), validateRuntime: async () => false,
+ inject: async () => true, sendKey, onError,
+ })
+ controller.cancel('s1')
+ await vi.waitFor(() => expect(onError).toHaveBeenCalledWith('s1', 'This agent process is no longer running.'))
+ expect(sendKey).not.toHaveBeenCalled()
+ controller.forget('s1')
+ })
+
+ it('keeps accepted Command Code delivery until the delayed transcript identifies its start', async () => {
+ vi.useFakeTimers()
+ const onDelivery = vi.fn()
+ const sendKey = vi.fn(async () => true)
+ const controller = new SessionInputController({
+ getSession: () => session('commandcode'), validateRuntime: async () => true,
+ inject: async () => true, sendKey, capture: async () => 'Thinking… esc to interrupt',
+ onError: vi.fn(), onDelivery,
+ })
+ controller.submit('s1', 'long thinking task', 'delivery-commandcode')
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(onDelivery.mock.calls.map(([event]) => event.state)).toEqual(['queued', 'delivered'])
+ expect(sendKey).not.toHaveBeenCalled()
+ controller.onTurnStarted('s1', 'long thinking task')
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-commandcode', state: 'started' })
+ controller.forget('s1')
+ })
+
+ it('does not invent rejection when a turn begins during pre-paste validation', async () => {
+ let resolve!: (valid: boolean) => void
+ const onDelivery = vi.fn()
+ const controller = new SessionInputController({
+ getSession: () => session('claude'),
+ validateRuntime: () => new Promise<boolean>(done => { resolve = done }),
+ inject: async () => true, sendKey: async () => true, onError: vi.fn(), onDelivery,
+ })
+ controller.submit('s1', 'lamp followup', 'delivery-followup')
+ controller.onTurnStarted('s1', 'a different local turn')
+ resolve(true)
+ await vi.waitFor(() => expect(onDelivery.mock.calls.map(([event]) => event.state)).toEqual(['queued', 'delivered']))
+ controller.onTurnStarted('s1', 'lamp followup')
+ expect(onDelivery).toHaveBeenLastCalledWith({ sessionId: 's1', deliveryId: 'delivery-followup', state: 'started' })
+ controller.forget('s1')
+ })
+})
diff --git a/cli/src/lib/sessionInput.ts b/cli/src/lib/sessionInput.ts
index d2d3b558a..10dc82eb8 100644
--- a/cli/src/lib/sessionInput.ts
+++ b/cli/src/lib/sessionInput.ts
@@ -54,13 +54,27 @@ const SUBMIT_MAX_RETRIES = 2
// prompt is in flight. Bounded so a truly wedged session eventually reverts to the retry/error path.
const SUBMIT_MAX_OBSERVES = 5
+export interface SessionInputDelivery {
+ deliveryId: string
+ sessionId: string
+ state: 'queued' | 'delivered' | 'started' | 'rejected' | 'unknown'
+ reason?: string
+}
+
interface QueuedInput {
+ deliveryId?: string
content: string
bytes: number
expiresAt: number
}
interface InputState {
+ deliveryId?: string
+ deliveryFingerprint?: string
+ dispatching?: boolean
+ writing?: boolean
+ cancelled?: boolean
+ observedStart?: string
turnOpen: boolean
awaitingFingerprint: string | null
awaitingContent: string | null
@@ -75,6 +89,7 @@ interface InputState {
}
export interface SessionInputDeps {
+ onDelivery?: (event: SessionInputDelivery) => void
getSession: (sessionId: string) => RegisteredSession | undefined
validateRuntime: (session: RegisteredSession) => Promise<boolean>
/** Boolean is retained for direct controller tests and legacy embedders. Production returns dispatch evidence. */
@@ -130,18 +145,49 @@ export class SessionInputController {
this.state(sessionId).turnOpen = open
}
- submit(sessionId: string, content: string): void {
+ private delivery(sessionId: string, deliveryId: string | undefined, state: SessionInputDelivery['state'], reason?: string): void {
+ if (deliveryId) this.deps.onDelivery?.({ sessionId, deliveryId, state, ...(reason ? { reason } : {}) })
+ }
+
+ private finishDelivery(sessionId: string, state: InputState, outcome: SessionInputDelivery['state'], reason?: string): void {
+ const id = state.deliveryId
+ state.deliveryId = undefined
+ state.deliveryFingerprint = undefined
+ this.delivery(sessionId, id, outcome, reason)
+ }
+
+ /** Revoke queued work only; a paste already in progress cannot be recalled. */
+ cancelDelivery(deliveryId: string): boolean {
+ for (const [sessionId, state] of this.states) {
+ const index = state.queue.findIndex((item) => item.deliveryId === deliveryId)
+ if (index >= 0) {
+ state.queue.splice(index, 1)
+ this.delivery(sessionId, deliveryId, 'rejected', 'cancelled')
+ return true
+ }
+ if (state.deliveryId === deliveryId && !state.writing && !state.awaitingFingerprint && !state.deliveryFingerprint) {
+ state.cancelled = true
+ this.finishDelivery(sessionId, state, 'rejected', 'cancelled')
+ return true
+ }
+ }
+ return false
+ }
+
+ submit(sessionId: string, content: string, deliveryId?: string): void {
const session = this.controlSession(sessionId)
- if (!session) { this.deps.onError(sessionId, 'This agent is no longer available.'); return }
+ if (!session) { this.delivery(sessionId, deliveryId, 'rejected', 'agent_gone'); this.deps.onError(sessionId, 'This agent is no longer available.'); return }
const state = this.state(sessionId)
this.dropExpired(sessionId, state)
if (state.controlLocked
+ || (deliveryId && (state.deliveryId || state.dispatching || state.turnOpen || state.awaitingFingerprint || state.settling))
|| (session.engine !== 'claude' && (state.turnOpen || state.awaitingFingerprint || state.settling))) {
console.log(`[inject] ${sid(sessionId)} queued · engine=${session.engine} · depth=${state.queue.length + 1}`)
- this.enqueue(sessionId, state, content)
+ this.enqueue(sessionId, state, content, deliveryId)
return
}
- void this.inject(sessionId, session, content)
+ this.delivery(sessionId, deliveryId, 'queued')
+ void this.inject(sessionId, session, content, deliveryId)
}
/** Reserve this pane for a short native control interaction such as `/model`. */
@@ -178,6 +224,10 @@ export class SessionInputController {
onTurnStarted(sessionId: string, userMessage: string): void {
const state = this.state(sessionId)
+ if (state.deliveryId && state.writing) state.observedStart = userMessage
+ else if (state.deliveryId && state.deliveryFingerprint) this.finishDelivery(sessionId, state,
+ state.deliveryFingerprint === fingerprint(userMessage) ? 'started' : 'unknown',
+ state.deliveryFingerprint === fingerprint(userMessage) ? undefined : 'prompt_mismatch')
if (state.settleTimer) clearTimeout(state.settleTimer)
state.settleTimer = null
state.settling = false
@@ -223,6 +273,7 @@ export class SessionInputController {
onTurnEnded(sessionId: string): void {
const state = this.state(sessionId)
+ if (!state.dispatching) this.finishDelivery(sessionId, state, 'unknown', 'turn_ended_without_start')
state.turnOpen = false
state.awaitingFingerprint = null
state.awaitingContent = null
@@ -254,6 +305,7 @@ export class SessionInputController {
if (!valid) { this.deps.onError(sessionId, 'This agent process is no longer running.'); return }
await this.deps.sendKey(session.agentId, 'C-c')
const state = this.state(sessionId)
+ this.finishDelivery(sessionId, state, 'unknown', 'cancelled_after_paste')
state.turnOpen = false
state.awaitingFingerprint = null
state.awaitingContent = null
@@ -264,14 +316,36 @@ export class SessionInputController {
})
}
+ async cancelConfirmed(sessionId: string): Promise<boolean> {
+ const session = this.controlSession(sessionId)
+ if (!session || !await this.deps.validateRuntime(session)) return false
+ const result = await this.deps.sendKey(session.agentId, 'C-c')
+ const state = this.state(sessionId)
+ this.finishDelivery(sessionId, state, 'unknown', 'cancelled_after_paste')
+ state.turnOpen = false
+ state.awaitingFingerprint = null
+ state.awaitingContent = null
+ state.ambiguousDispatch = false
+ if (state.timer) clearTimeout(state.timer)
+ state.timer = null
+ setTimeout(() => this.drainOne(sessionId, state), 250)
+ return typeof result === 'boolean' ? result : result.dispatch === 'executed'
+ }
+
forget(sessionId: string): void {
const state = this.states.get(sessionId)
if (state?.timer) clearTimeout(state.timer)
if (state?.settleTimer) clearTimeout(state.settleTimer)
+ if (state) {
+ this.finishDelivery(sessionId, state, state.writing || state.awaitingFingerprint || state.deliveryFingerprint ? 'unknown' : 'rejected', 'agent_gone')
+ for (const item of state.queue) this.delivery(sessionId, item.deliveryId, 'rejected', 'agent_gone')
+ state.cancelled = true
+ }
this.states.delete(sessionId)
}
- private async inject(sessionId: string, session: RegisteredSession, content: string): Promise<void> {
+ /** Preserve the established injection path for every caller that opts out of receipts. */
+ private async injectLegacy(sessionId: string, session: RegisteredSession, content: string): Promise<void> {
const state = this.state(sessionId)
if (!(await this.deps.validateRuntime(session))) {
console.warn(`[inject] ${sid(sessionId)} abort · engine=${session.engine} · process not running`)
@@ -314,12 +388,91 @@ export class SessionInputController {
this.armSubmitCheck(sessionId, session, state)
}
+ private async inject(sessionId: string, session: RegisteredSession, content: string, deliveryId?: string): Promise<void> {
+ const state = this.state(sessionId)
+ if (!deliveryId) {
+ // A local submission keeps its original scheduling. Overlap removes our ability
+ // to attribute a later terminal turn to the lamp; it must not block local input.
+ this.finishDelivery(sessionId, state, 'unknown', 'prompt_mismatch')
+ return this.injectLegacy(sessionId, session, content)
+ }
+ state.deliveryId = deliveryId
+ state.deliveryFingerprint = undefined
+ state.dispatching = true
+ state.cancelled = false
+ try {
+ if (!(await this.deps.validateRuntime(session))) {
+ console.warn(`[inject] ${sid(sessionId)} abort · engine=${session.engine} · process not running`)
+ this.finishDelivery(sessionId, state, 'rejected', 'runtime_gone_pre_paste')
+ this.deps.onError(sessionId, 'This agent process is no longer running.')
+ return
+ }
+ if (state.cancelled || this.states.get(sessionId) !== state) return
+ if (session.engine === 'cursor') {
+ // Cursor leaves the previous prompt sitting in its composer after the turn completes — the text is
+ // still on the "→" line long after the answer and its recap have arrived. sendToTmux() types into
+ // whatever is already there, so the next message is APPENDED to the last one and the pair is
+ // submitted as a single run-on prompt:
+ // "…đầu tư dài hạn" + "Có nên mua thêm eth không…"
+ // The agent then answers a question nobody asked, and the device shows a recap for it.
+ //
+ // The adapter already NOTICED this — onTurnStarted logs "observed a different terminal prompt while
+ // awaiting submit" when the fingerprint of the started turn does not match what we sent — but it
+ // only warned and carried on. Clear the line first so the composer is ours alone.
+ //
+ // C-u (kill-to-start-of-line) is a no-op on an empty composer, so this costs nothing in the normal
+ // case. It does discard a draft a human was typing in the terminal — but pasting into that draft
+ // would corrupt it into a run-on prompt anyway, which is worse and harder to notice.
+ await this.deps.sendKey(session.agentId, 'C-u')
+ }
+ if (state.cancelled || this.states.get(sessionId) !== state) return
+ state.writing = true
+ const delivery = await this.deps.inject(session.agentId, content)
+ state.writing = false
+ if (state.cancelled || this.states.get(sessionId) !== state) return
+ const accepted = typeof delivery === 'boolean'
+ ? delivery
+ : delivery.state === 'succeeded' || delivery.dispatch === 'possibly_executed'
+ if (!accepted) {
+ console.warn(`[inject] ${sid(sessionId)} paste failed · engine=${session.engine} · target=${session.agentId}`)
+ this.finishDelivery(sessionId, state, 'rejected', 'paste_failed')
+ this.deps.onError(sessionId, 'The message could not be delivered to the agent.')
+ return
+ }
+ console.log(`[inject] ${sid(sessionId)} paste ok · engine=${session.engine} · target=${session.agentId} · len=${content.length}`)
+ state.awaitingFingerprint = fingerprint(content)
+ state.deliveryFingerprint = state.awaitingFingerprint
+ state.awaitingContent = content
+ state.retries = 0
+ state.observes = 0
+ state.ambiguousDispatch = typeof delivery !== 'boolean' && delivery.dispatch === 'possibly_executed'
+ state.dispatching = false
+ this.delivery(sessionId, state.deliveryId, 'delivered')
+ if (state.observedStart !== undefined) {
+ const observed = state.observedStart
+ state.observedStart = undefined
+ this.onTurnStarted(sessionId, observed)
+ }
+ this.deps.onSubmitted?.(sessionId, content)
+ this.armSubmitCheck(sessionId, session, state)
+ } catch {
+ this.finishDelivery(sessionId, state, state.writing || state.awaitingFingerprint ? 'unknown' : 'rejected', state.writing || state.awaitingFingerprint ? 'dispatch_ambiguous' : 'runtime_gone_pre_paste')
+ this.deps.onError(sessionId, 'The message delivery could not be confirmed. Check the agent before trying again.')
+ } finally {
+ state.writing = false
+ state.dispatching = false
+ if (!state.awaitingFingerprint && !state.turnOpen) this.drainOne(sessionId, state)
+ }
+ }
+
private armSubmitCheck(sessionId: string, session: RegisteredSession, state: InputState): void {
if (state.timer) clearTimeout(state.timer)
state.timer = setTimeout(() => {
state.timer = null
if (!state.awaitingFingerprint || state.turnOpen) return
- void this.retrySubmit(sessionId, session, state)
+ const retry = this.retrySubmit(sessionId, session, state)
+ if (state.deliveryId) void retry.catch(() => this.failAmbiguousSubmission(sessionId, state))
+ else void retry
}, session.engine === 'claude'
? CLAUDE_SUBMIT_VERIFY_MS
: session.engine === 'opencode'
@@ -357,6 +510,10 @@ export class SessionInputController {
return
}
if (capture && cursorSubmissionAccepted(capture, state.awaitingContent ?? '')) {
+ if (state.deliveryId && ++state.observes > SUBMIT_MAX_OBSERVES) {
+ this.failAmbiguousSubmission(sessionId, state)
+ return
+ }
// The transcript hook can trail the TUI by a moment. Observe again without pressing Enter:
// another Enter here would duplicate a running/queued follow-up.
this.armSubmitCheck(sessionId, session, state)
@@ -366,6 +523,7 @@ export class SessionInputController {
console.warn(`[inject] ${sid(sessionId)} not accepted · engine=cursor · composer clear of draft`)
state.awaitingFingerprint = null
state.awaitingContent = null
+ this.finishDelivery(sessionId, state, 'unknown', 'not_submitted')
this.deps.onError(sessionId, 'The agent did not accept the message. Please try again.')
return
}
@@ -391,6 +549,8 @@ export class SessionInputController {
// acceptance it is, rather than timing out into an error the user can see is false.
if (capture && session.engine === 'commandcode' && /esc to interrupt/i.test(visibleTerminal(capture))) {
console.log(`[inject] ${sid(sessionId)} accepted (agent working) · engine=commandcode`)
+ // Keep the optional delivery fingerprint for the real transcript start.
+ // Visible work confirms acceptance; it must not be timed out as a failed submit.
state.awaitingFingerprint = null
state.awaitingContent = null
state.observes = 0
@@ -426,6 +586,7 @@ export class SessionInputController {
state.awaitingFingerprint = null
state.awaitingContent = null
state.ambiguousDispatch = false
+ this.finishDelivery(sessionId, state, 'unknown', 'not_submitted')
this.deps.onError(sessionId, 'The agent did not accept the message. Please try again.')
return
}
@@ -433,12 +594,14 @@ export class SessionInputController {
console.log(`[inject] ${sid(sessionId)} resubmit Enter · engine=${session.engine} · retry=${state.retries}/${SUBMIT_MAX_RETRIES}`)
const valid = await this.deps.validateRuntime(session)
if (!valid) {
+ this.finishDelivery(sessionId, state, 'unknown', 'runtime_gone_post_paste')
state.awaitingFingerprint = null
state.awaitingContent = null
state.ambiguousDispatch = false
this.deps.onError(sessionId, 'This agent process is no longer running.')
return
}
+ if (state.deliveryId && (this.states.get(sessionId) !== state || !state.awaitingFingerprint || state.turnOpen)) return
// Only the submit key is retried. The prompt body is never pasted twice.
const delivery = await this.deps.sendKey(session.agentId, 'Enter')
state.ambiguousDispatch = typeof delivery === 'boolean'
@@ -448,6 +611,7 @@ export class SessionInputController {
}
private failAmbiguousSubmission(sessionId: string, state: InputState): void {
+ this.finishDelivery(sessionId, state, 'unknown', 'dispatch_ambiguous')
state.awaitingFingerprint = null
state.awaitingContent = null
state.ambiguousDispatch = false
@@ -457,26 +621,30 @@ export class SessionInputController {
private drainOne(sessionId: string, state: InputState): void {
this.dropExpired(sessionId, state)
if (state.controlLocked || state.turnOpen || state.awaitingFingerprint || state.settling) return
+ if (state.queue[0]?.deliveryId && (state.dispatching || state.deliveryId)) return
const next = state.queue.shift()
if (!next) return
const session = this.controlSession(sessionId)
- if (!session) { this.deps.onError(sessionId, 'This agent is no longer available.'); return }
- void this.inject(sessionId, session, next.content)
+ if (!session) { this.delivery(sessionId, next.deliveryId, 'rejected', 'agent_gone'); this.deps.onError(sessionId, 'This agent is no longer available.'); return }
+ void this.inject(sessionId, session, next.content, next.deliveryId)
}
- private enqueue(sessionId: string, state: InputState, content: string): void {
+ private enqueue(sessionId: string, state: InputState, content: string, deliveryId?: string): void {
const bytes = Buffer.byteLength(content, 'utf8')
const queuedBytes = state.queue.reduce((sum, item) => sum + item.bytes, 0)
if (state.queue.length >= MAX_QUEUE_ITEMS || queuedBytes + bytes > MAX_QUEUE_BYTES) {
+ this.delivery(sessionId, deliveryId, 'rejected', 'queue_full')
this.deps.onError(sessionId, 'This agent already has too many queued messages. Try again after the current operation finishes.')
return
}
- state.queue.push({ content, bytes, expiresAt: Date.now() + ITEM_TTL_MS })
+ state.queue.push({ content, bytes, expiresAt: Date.now() + ITEM_TTL_MS, deliveryId })
+ this.delivery(sessionId, deliveryId, 'queued')
}
private dropExpired(sessionId: string, state: InputState): void {
const before = state.queue.length
const now = Date.now()
+ for (const item of state.queue) if (item.expiresAt <= now) this.delivery(sessionId, item.deliveryId, 'rejected', 'queue_expired')
state.queue = state.queue.filter((item) => item.expiresAt > now)
if (state.queue.length < before) this.deps.onError(sessionId, 'A queued message expired before the agent became available.')
}
diff --git a/docs/autonomous-device-integration.md b/docs/autonomous-device-integration.md
new file mode 100644
index 000000000..0d7770582
--- /dev/null
+++ b/docs/autonomous-device-integration.md
@@ -0,0 +1,203 @@
+# Autonomous device ↔ Mac: direct discovery and original Harness E2EE
+
+The Mac discovers Autonomous OS on the local network and connects **directly to the device**.
+No manual IP address, device backend credentials, cloud device registration, or backend relay is
+involved in this path. The existing Harness Mac login/start behavior is unchanged; an already
+running daemon can pair and operate while its backend connection is offline. Buddy is untouched.
+
+## Discovery and pairing
+
+Autonomous OS already advertises `_autonomous._tcp` using Avahi. CLI uses `bonjour-service` to
+browse that existing service for three seconds. It returns stable DNS-SD instance IDs and the
+advertised host/port; no new Avahi service or script is needed. Metadata is untrusted discovery,
+not authorization. The user selects a discovered device and enters the code displayed by it.
+
+```sh
+harness autonomous-device discover --json
+harness autonomous-device pair --device '<discovery id>' --code-stdin
+harness autonomous-device status --json
+harness autonomous-device list --json
+harness autonomous-device revoke '<full fingerprint>'
+```
+
+Desktop writes the device code to stdin and closes stdin. Terminal users can use
+`pair <device-code> --device <discovery-id>`. No response echoes the code. No address entry, listen,
+replace or blanket revoke command exists. A stale discovery ID returns DEVICE_NOT_FOUND; if the
+selected device has not opened pairing, NO_INTENT. Wrong code fails the original PAKE and closes
+the attempted socket; a retry makes a fresh socket and requests a new device intent.
+
+CLI connects `ws://<discovered-host>:<SRV-port>/api/harness/ws`. The service may advertise port80;
+its existing nginx must forward WebSocket upgrade for that exact route to OS-server. Never hardcode
+OS port5000 or ask the user to type it. First message:
+
+```json
+{"type":"machine_select","payload":{"machineId":"stable-harness-machine-id","label":"Mac name"}}
+```
+
+OS responds machine_selected. During device pairing it sends original e2e_pair_intent role device;
+CLI accepts the human code and delegates to the existing E2eeManager. After original PAKE, OS
+sends original e2e_hello on the same direct socket. CLI waits for authentication as the exact newly
+paired device before reporting success. On reconnect, OS sends e2e_hello using its stored pin.
+
+The Mac retains only `{discoveryId,fingerprint}` association metadata in
+`${ADAPTER_DATA_DIR}/autonomous-device-connections.json`; keys and trust remain exclusively in
+original E2eeManager/paired.json. Every 15 seconds it rediscovers disconnected saved devices.
+Discovered reconnect identity must match the saved fingerprint, even if a different identity is
+already trusted elsewhere. Revocation deletes the association, closes its direct socket and stops
+reconnect. Browser/dial pairings retain their existing behavior and are never blanket-revoked.
+
+Direct connections enter the **same** daemon manager via isolated connIds and targeted sends.
+Inbound direct whitelist is original device PAKE/cancel/hello/status plus Autonomous device app
+RPC, never generic backend/terminal/admin handlers, setup claims or remote-password PAKE.
+Pair intent/PAKE is accepted only during an explicit direct pairing attempt. Backend disconnection
+drops relay sessions but preserves direct ones. Offline pairing availability is checked for the
+specific pending connection, so a direct socket cannot authorize pairing an offline browser slot.
+Only an authenticated application hello activates recap generation/notifications.
+
+## Local management facade
+
+All routes remain on the credential-checked loopback hook server. There is no new Mac LAN listener.
+
+| Route | Input/result |
+|---|---|
+| GET `/api/autonomous-device/discover` | `{devices:[{id,name,host,port}]}` discovered candidates |
+| POST `/api/autonomous-device/pair/start` | `{code,device:<discovery-id>}` → `{state:"paired",label,fingerprint}` |
+| GET `/api/autonomous-device/pair/status` | existing pending device status idle/waiting/running |
+| GET `/api/autonomous-device/status` | `{transport:"direct",connected,paired,sessions,proto:1}`; connected/sessions count authenticated application-ready direct sessions only |
+| GET `/api/autonomous-device/list` | `{devices:[{id:fingerprint,fingerprint,label,pairedAt,online,role,current}]}` existing trusted device-role identities |
+| POST `/api/autonomous-device/revoke` | `{id:<full fingerprint>}` → `{revoked:1}` |
+| GET `/api/autonomous-device/receipt?deviceId=…&idempotencyKey=…` | existing receipt; deviceId here is canonical public key |
+
+Discovery id and trusted fingerprint are distinct identifiers. A user chooses a discovery record
+for pairing; revoke targets the exact existing trusted fingerprint. Original `harness pair` and
+browser/dial UI behavior are unchanged. Direct pairing is initiated by the named facade above.
+
+## Existing encrypted wire, unchanged
+
+Client identity and session use `cli/src/lib/e2ee/core.ts` and `manager.ts` exactly:
+
+- `e2e_pair_intent`, `e2e_pair_intent_result`, `e2e_pair_cancel`, `e2e_pake` payload rounds 1–5;
+ CPace CI `autonomous-e2e-pair|agent:<machineId>|a:adapter|b:device`.
+- `e2e_hello` payload `{identityPub,ephPub,sig}` using existing `helloSig`.
+- `e2e_welcome` payload `{webEphPub,ephPub,sig,enc}` using existing `welcomeSig`. `enc` is AEAD
+ server counter 0, AAD `e2e-welcome`, plaintext `{groupKey,epoch,features}`.
+- Existing X25519 sessionKeys, pairwise counters/replay window and `e2e_rekey` behavior.
+- No custom canonical hello/welcome signature, challenge, `autonomous_device_finished`, or custom
+ identity file. The device needs its own existing E2EE identity/pin, separate from Buddy.
+
+After original E2EE session establishment on the direct socket, application RPC uses:
+
+```json
+{"type":"autonomous_device_request","machineId":"selected-machine","payload":{"__e2e":{"v":1,"k":"p","n":0,"ct":"..."}}}
+```
+
+AAD uses existing wrapPayload: `1|autonomous_device_request||p|`; no dbSessionId on this envelope.
+The encrypted payload is the full application request. CLI intercepts before frame logging,
+requires an authenticated role-device session and ciphertext, and derives receipt identity from
+that session, never from a client-supplied identifier. Results use outer `autonomous_device_result`
+and events use outer `autonomous_device_event`, encrypted via existing wrapTarget with the same
+empty dbSessionId AAD convention. Machine targeting is explicit in the inner application request. No cloud routing is involved.
+
+First encrypted application request:
+
+```json
+{"type":"hello","requestId":"uuid","proto":1,"resume":{"serverInstanceId":"previous","cursor":4}}
+```
+
+Result plaintext: `{type:"hello_result",requestId,proto:1,machineId,serverInstanceId,capabilities,
+resumed,cursor}`. Resume is optional. This is application capability/resume negotiation, not a new
+cryptographic handshake. Existing session proof is the encrypted request. Then replay/resync and
+normal requests below follow. Result plaintext retains the service's `<operation>_result` type.
+Events retain full `{type:"event",...}` inside their encrypted outer envelope. Old browsers and
+dials remain on their existing request/event protocol.
+
+## Application requests, results and events
+
+All requests have UUIDv4 `requestId`. Unknown fields are rejected. Responses use
+`{type:"<operation>_result",requestId,...}`. Application failures before acceptance have
+`error:{code,message}` without a receipt. Mutations successfully reserved have `status` and receipt;
+a duplicate may return any retained receipt state. Supported operations:
+
+| Operation | Additional request fields | Success fields |
+|---|---|---|
+| `agents.list` | none | `machineId,agents:[{machineId,agentId,name,engine,state}]` |
+| `status` | `machineId,agentId` | `machineId,agentId,state,openQuestion:null\|{requestId,questions}` |
+| `recap` | `machineId,agentId,n?` (default 3, integer 1–5) | `machineId,agentId,turns:[{kind,text,recap?}]` |
+| `turn.send` | `machineId,agentId,idempotencyKey,text` | `status,receipt` |
+| `turn.stop` | `machineId,agentId,idempotencyKey` | `status,receipt` |
+| `question.answer` | `machineId,agentId,idempotencyKey,questionRequestId,answers` | `status,receipt` |
+| `receipt.get` | `idempotencyKey` | `receipt:null\|Receipt` |
+
+`idempotencyKey` matches `[A-Za-z0-9_-]{1,64}`. Prompt must be nonblank and ≤16 KiB UTF-8;
+it is never truncated. Answers is a nonempty object mapping question keys to string answers.
+Question ID must still be open. Question answering cannot approve tool permissions.
+Agent state currently derives `running`/`idle` from the local registry/turn tracker.
+There is no CLI selection operation: OS retains a validated explicit target.
+
+Receipt:
+
+```json
+{"idempotencyKey":"device-1","deliveryId":"<uuid>","operation":"turn.send","state":"queued","machineId":"machine","agentId":"agent","serverInstanceId":"<uuid>","turnId":null,"error":null,"at":1757302040000}
+```
+
+States: `queued`, `delivered`, `started`, `completed`, `rejected`, `unknown`. `turnId` is local
+receipt correlation generated when start is observed, not an engine-native transcript ID.
+`status` is `accepted` or `duplicate`; accepted means a reservation was created, not delivery or
+completion. After reservation every result carries a receipt, including revoked or failed requests.
+A proven failure is `receipt.state:"rejected"`; failure details remain inside `receipt.error`.
+Successful stop/answer transitions its own receipt to completed; an unconfirmed outcome is unknown.
+Submit exceptions and ambiguous post-dispatch failures are unknown. Only proven no-delivery cases
+may be rejected. `receipt:null` means no information, never proof a request did not run.
+
+Dedupe is reserved synchronously before dispatch, keyed `(deviceId,idempotencyKey)`, comparing all
+validated request fields except correlation IDs (normalized to null before canonical SHA-256).
+Same key/different intent → `IDEMPOTENCY_CONFLICT`. Receipt capacity is 512 total. Completed and
+rejected entries age out after 30 minutes from their last transition. At capacity, the oldest
+completed/rejected receipt is evicted, even if younger than 30 minutes; retention is bounded by
+both capacity and TTL. Outstanding/unknown entries are never silently evicted: if all 512 are
+unresolved, new mutations receive `BACKPRESSURE`. Evicting these entries would permit a duplicate
+live prompt; this explicit exception takes precedence over unconditional oldest-entry eviction.
+A retired key may be treated as new, so never auto-resend after `receipt:null`. All receipts/events are
+RAM-only. Every daemon start has a new UUID `serverInstanceId`; no mutation auto-replay is safe
+across restart. Revoke clears the old device's receipts and event replay history.
+
+Events are encrypted full objects:
+
+```json
+{"type":"event","eventId":1,"serverInstanceId":"<uuid>","machineId":"machine","agentId":"agent","kind":"receipt.updated","payload":{"receipt":{},"idempotencyKey":"device-1"}}
+```
+
+Kinds include `receipt.updated`, `turn.started`, `turn.done`, `turn.error`, `turn.summary`,
+`turn.tool`, `agent.error`, `question.open`, `question.close`. Question-open payload is
+`{questionRequestId,questions}`. Status uses `openQuestion.requestId` for that same identifier.
+Only device-origin turns with known correlation include `idempotencyKey`/`turnId`.
+Ring capacity 500; cursor is `(serverInstanceId,eventId)`. Matching retained cursor replays newer
+events. Changed instance or stale cursor returns encrypted `{type:"resync",reason:
+"instance_changed"|"cursor_too_old",serverInstanceId,cursor}`. First connect also requests resync.
+OS re-reads agents/status and reconciles outstanding keys using receipt.get. Queued means wait;
+delivered/started/completed means adopt; rejected means report; unknown/null means inspect and ask
+before resending. Never automatically replay mutations on reconnect.
+
+Application errors include `INVALID_REQUEST`, `UNSUPPORTED_CAPABILITY`, `MISSING_TARGET`,
+`MACHINE_MISMATCH`, `AGENT_NOT_FOUND`, `PAYLOAD_TOO_LARGE`, `QUESTION_STALE`,
+`IDEMPOTENCY_CONFLICT`, `BACKPRESSURE`, `RATE_LIMITED`, `REVOKED`, `INTERNAL`.
+A per-relay-connection token bucket permits burst 20, refilling one request/second, with at most four async
+requests in flight; a new relay connection starts a new quota. Excess returns an error result.
+Direct transport uses an outbound WebSocket; reconnection rediscovers the saved service identity. There is
+currently no server-wide request timeout guarantee.
+
+## Implementation and validation
+
+`discovery.ts` browses existing mDNS with bonjour-service; `direct.ts` owns outbound sockets and
+non-secret reconnect associations. `relay.ts` is the retained application/E2EE adapter name, not a
+network backend dependency; it sends on the direct connId through existing manager wrapTarget.
+`service.ts` retains local agent dispatch and bounded receipt/dedupe logic.
+Focused CLI tests and typecheck pass, including discovered-target-only pairing, failed-attempt
+fresh retry, authentication before success and reconnect identity mismatch. Real mDNS discovery and direct Go OS ↔ CLI integration passed with the backend never connected:
+advertised SRV port, wrong-code/fresh retry, original PAKE/session, encrypted list/send/dedupe,
+restart/reconnect and revoke/unpair. This is a real local client/server test, not physical-device deployment.
+Full CLI regression passed: `npm test -- --maxWorkers=1 --testTimeout=30000 --hookTimeout=30000`
+(144 files / 1,871 tests passed; 5 files / 50 tests skipped), plus `npm run typecheck`.
+The default 5-second test deadline timed out in existing password/scrypt tests under local load;
+the serial run uses command-line deadlines only and does not change test files or configuration.
+No physical device deployment.
diff --git a/docs/vi/autonomous-device-integration_vi.md b/docs/vi/autonomous-device-integration_vi.md
new file mode 100644
index 000000000..035ec3b2f
--- /dev/null
+++ b/docs/vi/autonomous-device-integration_vi.md
@@ -0,0 +1,51 @@
+# Autonomous device ↔ Mac trực tiếp
+
+Mac tự tìm Autonomous OS qua service Avahi `_autonomous._tcp` đang có, dùng bonjour-service
+browse ba giây. Không nhập IP, không backend relay hoặc credential cloud trên thiết bị. Giữ
+login/start của Harness Mac như cũ; daemon đang chạy vẫn pair/điều khiển khi backend offline.
+Buddy không dùng và không sửa.
+
+```sh
+harness autonomous-device discover --json
+harness autonomous-device pair --device '<discovery-id>' --code-stdin
+harness autonomous-device status --json
+harness autonomous-device list --json
+harness autonomous-device revoke '<full fingerprint>'
+```
+
+Thiết bị sinh/hiển thị mã; Desktop chọn thiết bị tìm thấy rồi ghi mã vào stdin của CLI, không argv/log.
+Discovery trả `{devices:[{id,name,host,port}]}`. CLI dial trực tiếp
+`ws://<host>:<SRV-port>/api/harness/ws`, dùng đúng port quảng bá (có thể80), nginx chuyển Upgrade
+cho route đó. Không hardcode5000, không thêm Avahi/script. Frame đầu machine_select payload
+machineId/label; OS trả machine_selected và e2e_pair_intent nếu đang pair. Sau mã nhập đúng, chạy
+PAKE và e2e_hello/welcome gốc; CLI chờ session đúng identity trước báo paired.
+
+Không listener Mac mới, custom handshake/trust store, role mới hay backend onboarding. Inbound
+trực tiếp chỉ nhận PAKE/cancel/hello/status cần thiết và app RPC; không setup token/remote password,
+terminal/admin. Intent/PAKE chỉ được nhận trong lần pair chủ động. Backend offline không xóa
+direct session hoặc cho phép pair nhầm browser slot.
+
+Metadata `${ADAPTER_DATA_DIR}/autonomous-device-connections.json` chỉ lưu discoveryId/fingerprint;
+key/pin vẫn ở E2eeManager/paired.json gốc. Mỗi15giây tìm lại thiết bị đã lưu và reconnect. Publickey
+reconnect phải đúng fingerprint association; mDNS không cấp quyền. Revoke đóng socket và bỏ
+association, không ảnh hưởng browser/dial khác. Sai mã đóng attempt để lần sau có socket/intent mới.
+Chỉ app hello đã xác thực mới bật recap/notification.
+
+Facade loopback có credential: GET discover; POST pair/start `{code,device}`; GET pair/status;
+GET status (transport direct); GET list (id là fingerprint, khác discoveryId); POST revoke `{id}`;
+GET receipt query deviceId canonical publickey và idempotencyKey. Không listen/address/replace/all.
+
+Wire dùng nguyên e2e_* gốc role device, CI b:device. App outer autonomous_device_request/result/event
+vẫn pairwise encrypted với empty dbSessionId AAD; helper relay.ts chỉ là adapter ứng dụng dùng chung
+crypto, không kết nối backend. Request agents.list/status/recap/turn.send/turn.stop/question.answer/
+receipt.get giữ target rõ và receipt/dedupe. Không replay mutation khi mất kết nối; unknown không
+có nghĩa chưa gửi. Cache512/ring500 và schema đầy đủ ở [bản EN](../autonomous-device-integration.md).
+
+Typecheck/focused test đã đạt gồm chỉ chọn discovery, retry socket mới, chờ authenticated identity
+và từ chối reconnect giả mạo. Real mDNS/direct Go OS ↔ CLI đã đạt khi backend chưa từng kết nối: discovery SRV, sai mã/retry,
+PAKE/session, encrypted list/send/dedupe, restart/reconnect và revoke/unpair. Status chỉ đếm direct
+session đã xác thực và app-ready, không đếm socket thô. Full CLI đã đạt với
+`npm test -- --maxWorkers=1 --testTimeout=30000 --hookTimeout=30000`: 144 file / 1.871 test pass,
+5 file / 50 test skip; `npm run typecheck` đạt. Lần chạy deadline mặc định 5 giây bị timeout ở
+các test password/scrypt sẵn có khi máy chịu tải. Chỉ đổi deadline qua lệnh chạy serial, không
+sửa test hoặc cấu hình để né lỗi. Không deploy hoặc pair thiết bị thật.