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 add-ons: a device publishes summaries, agents propose, the device decides (#1485)

daniel-auto3f3922e5268d
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 23db0ba3a..a9d97514a 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -202,7 +202,7 @@ ${apiUsage}
${connectionsUsage}
Browser end-to-end encryption:
- harness autonomous-device <command> pair/status/list/revoke an Autonomous device
+ harness autonomous-device <command> pair/status/list/revoke an Autonomous device; addon state/propose/proposal
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)
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index 5e7e755cd..d7c9b514d 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -1275,6 +1275,12 @@ export interface WifiResume {
/** A receipt the device asked for by `harness device receipt`, or the service is not there to say. */
export type WifiReceipt = { receipt: AutonomousDeviceReceipt | null } | { unavailable: true }
+/** `harness autonomous-device addon`: what devices published, a proposal sent, or one read back
+ * (lib/autonomous-device/addons.ts); refused with the add-on layer's own code, or the service is not there. */
+export const WIFI_ADDON_OPS = ['state', 'propose', 'proposal'] as const
+export type WifiAddonOp = typeof WIFI_ADDON_OPS[number]
+export type WifiAddon = { result: Record<string, unknown> } | { error: { code: string; message: string } } | { unavailable: true }
+
/** What the core lists for the Wi-Fi device, read in line while it answers a request: the agents as it
* shows them, the Store's evidence on each, and whether a window is attached to show one. */
export interface WifiView {
@@ -1319,6 +1325,8 @@ export interface WifiPort {
revealed(operationId: string, agentId: string): void
/** `harness device receipt`: what became of one of a device's requests. */
receipt(deviceId: string, idempotencyKey: string): Promise<WifiReceipt>
+ /** `harness autonomous-device addon`: an agent reads what devices published, or proposes to one. */
+ addon(op: WifiAddonOp, input: Record<string, unknown>): Promise<WifiAddon>
stop(): Promise<void>
}
@@ -1342,7 +1350,7 @@ export const WIFI_FALLBACKS: PortFallbacks<WifiPort> = {
session: undefined, request: later(undefined), dropped: undefined, revoked: undefined, resume: later(undefined), card: undefined,
turnStarted: undefined, turnEnded: undefined, stream: undefined, transcript: undefined, delivery: undefined,
dispatched: undefined, inputStatus: undefined, agentGone: undefined, appFocus: later(undefined), revealed: undefined,
- receipt: later({ unavailable: true }), stop: later(undefined),
+ receipt: later({ unavailable: true }), addon: later({ unavailable: true }), stop: later(undefined),
}
/*
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index e2e870445..e05db9de3 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -221,7 +221,7 @@ import { wakeGateway } from './gatewayWake.js'
import { createViewersWake, VIEWERS_ON_DEMAND, wakeViewers } from './viewersWake.js'
import { createWifiLink } from './wifiLink.js'
import { wifiDoors } from './wifiAgents.js'
-import { autonomousDeviceLocalRequest } from '../lib/deviceManagementHttp.js'
+import { autonomousDeviceLocalRequest, deviceAddonRoutes } from '../lib/deviceManagementHttp.js'
import { loadOrCreateHookCredential } from '../lib/hookAuth.js'
import { attachLocalWsServer, LOCAL_WS_PATH, LOCAL_WS_PROTOCOL_VERSION } from '../localWsServer.js'
import { TERMINAL_BINARY_VERSION } from '../lib/terminalBinary.js'
@@ -1967,6 +1967,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
if ('unavailable' in answer) throw Object.assign(new Error('The Wi-Fi device service is not running on this computer. See the daemon\'s log.'), { code: 'UNAVAILABLE' })
return { receipt: answer.receipt }
},
+ ...deviceAddonRoutes((op, input) => ports.wifi?.addon(op, input) ?? Promise.resolve({ unavailable: true as const })),
}, method, target, body)
},
resolveHookAgent: engineHooks.resolveHookAgent,
diff --git a/cli/src/core/wifi.spec.ts b/cli/src/core/wifi.spec.ts
index 5598097f1..d74c3ebc7 100644
--- a/cli/src/core/wifi.spec.ts
+++ b/cli/src/core/wifi.spec.ts
@@ -9,7 +9,7 @@ function harness() {
const port = {
session: vi.fn(), request: vi.fn(async () => {}), dropped: vi.fn(), revoked: vi.fn(), resume: vi.fn(async () => {}), card: vi.fn(),
turnStarted: vi.fn(), turnEnded: vi.fn(), stream: vi.fn(), transcript: vi.fn(), delivery: vi.fn(), dispatched: vi.fn(),
- inputStatus: vi.fn(), agentGone: vi.fn(), appFocus: vi.fn(async () => {}), revealed: vi.fn(), receipt: vi.fn(), stop: vi.fn(),
+ inputStatus: vi.fn(), agentGone: vi.fn(), appFocus: vi.fn(async () => {}), revealed: vi.fn(), receipt: vi.fn(), addon: vi.fn(), stop: vi.fn(),
} satisfies WifiPort
let on: WifiPort | null = port
const clients = new Map<string, RemoteClient>()
diff --git a/cli/src/core/wifiLink.spec.ts b/cli/src/core/wifiLink.spec.ts
index e54ab33de..b1e1ca8bf 100644
--- a/cli/src/core/wifiLink.spec.ts
+++ b/cli/src/core/wifiLink.spec.ts
@@ -54,6 +54,17 @@ describe('the Wi-Fi device in the devices\' process, as the core sees it', () =>
expect(await link({ error: 'SERVICE_UNAVAILABLE' }).wifi.port.receipt('dev', 'k')).toEqual({ unavailable: true })
})
+ it('asks it about device add-ons with a deadline, and passes the add-on layer\'s own refusal through', async () => {
+ const answered = link({ result: { devices: [] } })
+ expect(await answered.wifi.port.addon('state', { deviceId: 'lamp' })).toEqual({ result: { devices: [] } })
+ expect(answered.call).toHaveBeenCalledWith('addon', { op: 'state', input: { deviceId: 'lamp' } }, WIFI_WAIT_MS)
+ const refused = { error: { code: 'RATE_LIMITED', message: 'slow down' } }
+ expect(await link(refused).wifi.port.addon('propose', {})).toEqual(refused)
+ expect(await link({ error: 'SERVICE_UNAVAILABLE' }).wifi.port.addon('proposal', { proposalId: 'p' })).toEqual({ unavailable: true })
+ // A proposal with no answer in time may have been sent: unknown, retried with its key, never "not running".
+ expect(await link({ error: 'SERVICE_UNAVAILABLE' }).wifi.port.addon('propose', {})).toMatchObject({ error: { code: 'OUTCOME_UNKNOWN' } })
+ })
+
it('answers what it asks through the core\'s Wi-Fi doors', async () => {
const { wifi, core } = link()
expect(await wifi.answer('machine', {})).toEqual({ id: 'machine-1' })
diff --git a/cli/src/core/wifiLink.ts b/cli/src/core/wifiLink.ts
index f7c7f7fd7..f7752cf59 100644
--- a/cli/src/core/wifiLink.ts
+++ b/cli/src/core/wifiLink.ts
@@ -14,7 +14,7 @@
* and a recent turn, as queries; the rest as notices.
*/
import type { AutonomousDeviceReceipt } from '../lib/autonomous-device/service.js'
-import { WIFI_FALLBACKS, readFallback, type CoreApi, type WifiPort, type WifiReceipt } from './api.js'
+import { WIFI_FALLBACKS, readFallback, type CoreApi, type WifiAddon, type WifiPort, type WifiReceipt } from './api.js'
import type { ServiceFrame } from './serviceLinks.js'
export interface WifiLinkDeps {
@@ -61,6 +61,17 @@ export function createWifiLink(deps: WifiLinkDeps) {
if (typeof answer.error === 'string') return readFallback(WIFI_FALLBACKS.receipt).value as WifiReceipt
return { receipt: (answer.receipt ?? null) as AutonomousDeviceReceipt | null }
},
+ // A person's or an agent's, as `receipt` is: asked with a deadline. The link answers a service that is
+ // down and one that missed the deadline alike, so a proposal with no answer may still have been sent:
+ // said as unknown, to be retried with the same key, never as a stopped service.
+ addon: async (op, input) => {
+ const answer = await deps.call('addon', { op, input }, WIFI_WAIT_MS)
+ if (typeof answer.error !== 'string') return answer as WifiAddon
+ if (op === 'propose') {
+ return { error: { code: 'OUTCOME_UNKNOWN', message: 'No answer in time: the proposal may have been sent. Retry with the same key (--key) to send it at most once.' } }
+ }
+ return readFallback(WIFI_FALLBACKS.addon).value as WifiAddon
+ },
// Its own process: the master stops it.
stop: async () => {},
}
diff --git a/cli/src/lib/autonomous-device/addonCommand.spec.ts b/cli/src/lib/autonomous-device/addonCommand.spec.ts
new file mode 100644
index 000000000..14a502357
--- /dev/null
+++ b/cli/src/lib/autonomous-device/addonCommand.spec.ts
@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { runAutonomousDeviceCommand } from './command.js'
+vi.mock('../hookAuth.js', () => ({ readHookCredential: () => 'hook-test-credential' }))
+afterEach(() => vi.restoreAllMocks())
+
+const ok = (body: unknown) => vi.spyOn(globalThis, 'fetch').mockImplementation(async () => new Response(JSON.stringify(body)))
+const quiet = () => vi.spyOn(console, 'log').mockImplementation(() => {})
+
+describe('harness autonomous-device addon', () => {
+ it('reads what devices published, for one device when named', async () => {
+ const fetch = ok({ devices: [] }); quiet()
+ expect(await runAutonomousDeviceCommand(['addon', 'state'], '/unused', 18473)).toBe(0)
+ expect(String(fetch.mock.calls[0][0])).toBe('http://127.0.0.1:18473/api/autonomous-device/addon/state')
+ expect(await runAutonomousDeviceCommand(['addon', 'state', '--device', 'a b'], '/unused', 18473)).toBe(0)
+ expect(String(fetch.mock.calls[1][0])).toBe('http://127.0.0.1:18473/api/autonomous-device/addon/state?deviceId=a%20b')
+ expect(fetch.mock.calls[1][1]).toMatchObject({ method: 'GET', headers: { Authorization: 'Bearer hook-test-credential' } })
+ })
+
+ it('posts a proposal with what was given, a fresh key, and the add-on named by --addon', async () => {
+ const fetch = ok({ proposal: { proposalId: 'p' } }); quiet()
+ expect(await runAutonomousDeviceCommand(['addon', 'propose', '--act', 'light', '--holds-ms', '30000', '--why', 'evening', '--sure', '0.6',
+ '--params', '{"colour":"warm","level":2}', '--note', 'A warm evening light.', '--addon', 'evening-glow', '--device', 'lamp'], '/unused', 18473)).toBe(0)
+ expect(String(fetch.mock.calls[0][0])).toBe('http://127.0.0.1:18473/api/autonomous-device/addon/propose')
+ const body = JSON.parse(String(fetch.mock.calls[0][1]?.body))
+ expect(body).toEqual({ addon: 'evening-glow', act: 'light', holdsMs: 30000, idempotencyKey: expect.stringMatching(/^[0-9a-f]{32}$/),
+ why: 'evening', sure: 0.6, params: { colour: 'warm', level: 2 }, note: 'A warm evening light.', deviceId: 'lamp' })
+ })
+
+ it('names the add-on after the agent running the shell, and keeps a given key', async () => {
+ const fetch = ok({ proposal: {} }); quiet()
+ vi.stubEnv('CLAUDECODE', '1'); vi.stubEnv('CLAUDE_CODE_SESSION_ID', 'abc-123')
+ try {
+ expect(await runAutonomousDeviceCommand(['addon', 'propose', '--act', 'mood', '--holds-ms', '5000', '--key', 'once'], '/unused', 18473)).toBe(0)
+ } finally { vi.unstubAllEnvs() }
+ // The engine and a short hash: the session's own id never reaches the device.
+ const hash = createHash('sha256').update('claude-code:abc-123').digest('hex').slice(0, 12)
+ const sent = JSON.parse(String(fetch.mock.calls[0][1]?.body))
+ expect(sent).toMatchObject({ addon: `claude-${hash}`, idempotencyKey: 'once' })
+ expect(JSON.stringify(sent)).not.toContain('abc-123')
+ })
+
+ it('says the key a failed propose used, for a retry that sends it at most once', async () => {
+ vi.spyOn(globalThis, 'fetch').mockImplementation(async () => new Response(JSON.stringify({ error: { code: 'OUTCOME_UNKNOWN', message: 'maybe' } }), { status: 504 }))
+ const log = quiet()
+ expect(await runAutonomousDeviceCommand(['addon', 'propose', '--act', 'mood', '--holds-ms', '5000', '--addon', 'x', '--key', 'k7', '--json'], '/unused', 18473)).toBe(1)
+ expect(JSON.parse(String(log.mock.calls[0][0]))).toEqual({ error: { code: 'OUTCOME_UNKNOWN', message: 'maybe' }, idempotencyKey: 'k7' })
+ })
+
+ it('reads one proposal back', async () => {
+ const fetch = ok({ proposal: null }); quiet()
+ const id = '0b6c3c3e-8f3a-4f5a-9d2b-6f1e2a3b4c5d'
+ expect(await runAutonomousDeviceCommand(['addon', 'proposal', id, '--json'], '/unused', 18473)).toBe(0)
+ expect(String(fetch.mock.calls[0][0])).toBe(`http://127.0.0.1:18473/api/autonomous-device/addon/proposal?proposalId=${id}`)
+ })
+
+ it('refuses before asking the daemon: no act, bad JSON, unknown flag, no add-on name, a flag the verb does not take', async () => {
+ const fetch = vi.spyOn(globalThis, 'fetch'); quiet()
+ vi.stubEnv('CLAUDECODE', ''); vi.stubEnv('CLAUDE_CODE_SESSION_ID', ''); vi.stubEnv('CODEX_THREAD_ID', ''); vi.stubEnv('AI_AGENT', '')
+ try {
+ for (const argv of [
+ ['addon'], ['addon', 'propose', '--holds-ms', '5000', '--addon', 'x'],
+ ['addon', 'propose', '--act', 'light', '--holds-ms', '5000', '--addon', 'x', '--params', '{nope'],
+ ['addon', 'propose', '--act', 'light', '--holds-ms', '5000', '--addon', 'x', '--force'],
+ ['addon', 'propose', '--act', 'light', '--holds-ms', '5000'],
+ ['addon', 'state', '--act', 'light'], ['addon', 'proposal'], ['addon', 'state', 'extra'],
+ ...['', '0x1', '1e0', '1.5', '-0.1', 'nan'].map(sure => ['addon', 'propose', '--act', 'light', '--holds-ms', '5000', '--addon', 'x', '--sure', sure]),
+ ...['', '5e3', '5000.5', '-5000'].map(holds => ['addon', 'propose', '--act', 'light', '--holds-ms', holds, '--addon', 'x']),
+ ]) expect(await runAutonomousDeviceCommand(argv, '/unused', 18473)).toBe(1)
+ } finally { vi.unstubAllEnvs() }
+ expect(fetch).not.toHaveBeenCalled()
+ })
+})
diff --git a/cli/src/lib/autonomous-device/addonCommand.ts b/cli/src/lib/autonomous-device/addonCommand.ts
new file mode 100644
index 000000000..1a1311de6
--- /dev/null
+++ b/cli/src/lib/autonomous-device/addonCommand.ts
@@ -0,0 +1,90 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { readHookCredential } from '../hookAuth.js'
+import { outsideCaller } from '../../agentClient/model.js'
+
+const USAGE = 'Usage: harness autonomous-device addon state [--device <id>]'
+ + ' | addon propose --act <act> --holds-ms <ms> [--why <why>] [--sure <0..1>] [--params <json>] [--note <text>] [--addon <name>] [--key <key>] [--device <id>]'
+ + ' | addon proposal <proposalId> [--json]. To retry a propose that got no answer, pass the same --key, which it prints.'
+
+const VALUE_FLAGS = new Set(['--device', '--act', '--holds-ms', '--why', '--sure', '--params', '--note', '--addon', '--key'])
+
+/**
+ * The add-on's name a device is told: `--addon`, or the agent whose shell runs this, as its engine and a short
+ * hash of how Harness names the outside caller (agentClient/model.ts): one name per session, without the
+ * session's own id, which the device has no need of. Said by this computer, not proven to the device: the
+ * device rate-limits and judges every proposal whatever it is called (docs/autonomous-device-addons.md).
+ */
+function addonName(given: string | undefined, env: NodeJS.ProcessEnv): string | undefined {
+ if (given) return given
+ const caller = outsideCaller(env, '')
+ if (!caller) return undefined
+ const engine = caller.engine.replace(/[^A-Za-z0-9._-]/g, '-').slice(0, 40) || 'agent'
+ return `${engine}-${createHash('sha256').update(caller.agentId).digest('hex').slice(0, 12)}`
+}
+
+/** A confidence, 0 to 1, written plainly: no empty value, hex or exponent read as a number. */
+const SURE = /^(0(\.\d{1,6})?|1(\.0{1,6})?|\.\d{1,6})$/
+const WHOLE = /^\d{1,6}$/
+
+/** `harness autonomous-device addon …`: read what paired devices publish, or propose to one. */
+export async function runAddonCommand(argv: string[], dataDir: string, port: number, env: NodeJS.ProcessEnv = process.env): Promise<number> {
+ const json = argv.includes('--json'), args: string[] = [], flags = new Map<string, string>()
+ let invalid = false
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ if (a === '--json') continue
+ if (VALUE_FLAGS.has(a)) {
+ if (flags.has(a) || argv[i + 1] === undefined || argv[i + 1].startsWith('--')) invalid = true
+ else flags.set(a, argv[++i])
+ } else if (a.startsWith('--')) invalid = true
+ else args.push(a)
+ }
+ const print = (value: unknown) => console.log(JSON.stringify(value, null, json ? undefined : 2))
+ const usage = (message = USAGE) => { print({ error: { code: 'INVALID_ARGUMENT', message } }); return 1 }
+ const verb = args[0]
+ const allowed = verb === 'state' ? ['--device'] : verb === 'proposal' ? [] : verb === 'propose' ? [...VALUE_FLAGS] : null
+ if (invalid || !allowed || [...flags.keys()].some(f => !allowed.includes(f)) || args.length !== (verb === 'proposal' ? 2 : 1)) return usage()
+
+ let path: string, method = 'GET', body: Record<string, unknown> | undefined
+ if (verb === 'state') {
+ const device = flags.get('--device')
+ path = `addon/state${device ? `?deviceId=${encodeURIComponent(device)}` : ''}`
+ } else if (verb === 'proposal') {
+ path = `addon/proposal?proposalId=${encodeURIComponent(args[1])}`
+ } else {
+ const act = flags.get('--act'), holds = flags.get('--holds-ms')
+ if (!act || !holds) return usage('propose needs --act and --holds-ms')
+ if (!WHOLE.test(holds)) return usage('--holds-ms is a whole number of milliseconds')
+ if (flags.has('--sure') && !SURE.test(flags.get('--sure')!)) return usage('--sure is a number from 0 to 1')
+ const addon = addonName(flags.get('--addon'), env)
+ if (!addon) return usage('Name the add-on with --addon: no agent is running this shell')
+ let params: unknown
+ if (flags.has('--params')) {
+ try { params = JSON.parse(flags.get('--params')!) } catch { return usage('--params must be a JSON object') }
+ }
+ const sure = flags.has('--sure') ? Number(flags.get('--sure')) : undefined
+ body = { addon, act, holdsMs: Number(holds),
+ // A fresh key per invocation: a retry of the same shell command is a new proposal. Pass --key to make it one.
+ idempotencyKey: flags.get('--key') ?? randomUUID().replace(/-/g, ''),
+ ...(flags.has('--why') ? { why: flags.get('--why') } : {}), ...(sure !== undefined ? { sure } : {}),
+ ...(params !== undefined ? { params } : {}), ...(flags.has('--note') ? { note: flags.get('--note') } : {}),
+ ...(flags.has('--device') ? { deviceId: flags.get('--device') } : {}) }
+ path = 'addon/propose'; method = 'POST'
+ }
+ const credential = readHookCredential(dataDir)
+ if (!credential) { print({ error: { code: 'DAEMON_UNAVAILABLE', message: 'Start Harness with harness start first.' } }); return 1 }
+ try {
+ const result = await fetch(`http://127.0.0.1:${port}/api/autonomous-device/${path}`, {
+ method, redirect: 'error', signal: AbortSignal.timeout(15_000),
+ headers: { Authorization: `Bearer ${credential}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+ ...(body ? { body: JSON.stringify(body) } : {}),
+ })
+ const answer = await result.json() as Record<string, unknown>
+ // A propose that failed says the key it used, so a retry can send the same proposal at most once.
+ print(!result.ok && body ? { ...answer, idempotencyKey: body.idempotencyKey } : answer)
+ return result.ok ? 0 : 1
+ } catch {
+ print({ error: { code: 'DAEMON_UNAVAILABLE', message: 'Could not reach the Harness Autonomous device API. Start or update Harness CLI.' } })
+ return 1
+ }
+}
diff --git a/cli/src/lib/autonomous-device/addons.spec.ts b/cli/src/lib/autonomous-device/addons.spec.ts
new file mode 100644
index 000000000..96a4869a1
--- /dev/null
+++ b/cli/src/lib/autonomous-device/addons.spec.ts
@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'vitest'
+import { randomUUID } from 'node:crypto'
+import { DEVICE_PROPOSALS_PER_MINUTE, DeviceAddons, DeviceAddonError, HOLDS_MAX_MS, OPEN_PROPOSALS_MAX, PROPOSALS_PER_MINUTE, TOPICS_MAX, VALUE_MAX_BYTES } from './addons.js'
+import type { AutonomousDeviceFrame } from './service.js'
+
+function fixture() {
+ let clock = 1_000_000
+ const sent: Array<{ deviceId: string; frame: AutonomousDeviceFrame }> = []
+ const addons = new DeviceAddons({ machineId: 'machine', serverInstanceId: 'instance', now: () => clock, send: (deviceId, frame) => sent.push({ deviceId, frame }) })
+ const publish = (deviceId: string, values: Array<Record<string, unknown>>) => addons.request(deviceId, { type: 'addon.publish', requestId: randomUUID(), values })
+ const decide = (deviceId: string, proposalId: string, decision: string, reason?: string) =>
+ addons.request(deviceId, { type: 'addon.decision', requestId: randomUUID(), proposalId, decision, ...(reason ? { reason } : {}) })
+ let keys = 0
+ const propose = (fields: Record<string, unknown> = {}) => addons.propose({ addon: 'mood-addon', idempotencyKey: `k${++keys}`, act: 'mood', holdsMs: 10_000, ...fields })
+ const code = (run: () => unknown): string => { try { run() } catch (e) { return e instanceof DeviceAddonError ? e.code : `not an add-on error: ${String(e)}` } return 'no error' }
+ return { addons, sent, publish, decide, propose, code, tick: (ms: number) => { clock += ms }, now: () => clock }
+}
+
+describe('device add-ons: what a device publishes', () => {
+ it('keeps the newest value of each topic, and forgets a topic published as null', () => {
+ const f = fixture()
+ expect(f.publish('lamp', [{ topic: 'mood/state', value: { energy: 0.4 }, at: 5 }, { topic: 'voice/state', value: { state: 'resting' } }])).toEqual({ topics: 2 })
+ f.publish('lamp', [{ topic: 'mood/state', value: { energy: 0.6 } }, { topic: 'voice/state', value: null }])
+ expect(f.addons.state()).toEqual([{ deviceId: 'lamp', online: true,
+ topics: { 'mood/state': { value: { energy: 0.6 }, at: null, receivedAt: f.now() } } }])
+ })
+
+ it('refuses a malformed topic, an oversized value or too many topics, and keeps nothing of a refused batch', () => {
+ const f = fixture()
+ expect(f.code(() => f.publish('lamp', [{ topic: 'Mood State', value: {} }]))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.publish('lamp', [{ topic: 'mood/state', value: { x: 'a'.repeat(VALUE_MAX_BYTES) } }]))).toBe('PAYLOAD_TOO_LARGE')
+ expect(f.code(() => f.publish('lamp', [{ topic: 'mood/state', value: {}, extra: 1 }]))).toBe('INVALID_REQUEST')
+ const many = (from: number, n: number) => Array.from({ length: n }, (_, i) => ({ topic: `t/n${from + i}`, value: {} }))
+ for (let i = 0; i < TOPICS_MAX; i += 16) f.publish('lamp', many(i, 16))
+ expect(f.code(() => f.publish('lamp', [{ topic: 'room/state', value: {} }]))).toBe('BACKPRESSURE')
+ // Replacing one and adding one in the same batch stays within the bound.
+ expect(f.publish('lamp', [{ topic: 't/n0', value: null }, { topic: 'room/state', value: {} }])).toEqual({ topics: TOPICS_MAX })
+ })
+
+ it('clears what a device published at its hello, so a topic it withdrew is gone and counts for nothing', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'voice/state', value: { state: 'resting' } }, { topic: 'mood/state', value: {} }])
+ for (let i = 0; i < TOPICS_MAX - 2; i += 15) f.publish('lamp', Array.from({ length: Math.min(15, TOPICS_MAX - 2 - i) }, (_, n) => ({ topic: `t/n${i + n}`, value: {} })))
+ f.addons.hello('lamp')
+ expect(f.addons.state('lamp')).toEqual([])
+ // Its new set, without voice/state: nothing of the old one is left, and the bound is the new set's.
+ f.publish('lamp', [{ topic: 'mood/state', value: { energy: 0.5 } }, { topic: 'room/presence', value: { someone: true } }])
+ expect(Object.keys(f.addons.state('lamp')[0].topics)).toEqual(['mood/state', 'room/presence'])
+ })
+
+ it('asks a device to publish again, to that device alone', () => {
+ const f = fixture()
+ f.addons.republish('lamp')
+ expect(f.sent).toEqual([{ deviceId: 'lamp', frame: { type: 'event', serverInstanceId: 'instance', machineId: 'machine', kind: 'addon.republish', payload: {} } }])
+ })
+
+ it('marks a device offline when its link closes, and forgets it when it is unpaired', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ f.addons.offline('lamp')
+ expect(f.addons.state('lamp')[0].online).toBe(false)
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ expect(f.addons.state('lamp')[0].online).toBe(true)
+ f.addons.revoke('lamp')
+ expect(f.addons.state()).toEqual([])
+ })
+})
+
+describe('device add-ons: what an agent proposes', () => {
+ it('sends a proposal to the one connected device, without the key or the device id in it', () => {
+ const f = fixture()
+ expect(f.code(() => f.propose())).toBe('MISSING_TARGET')
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ const proposal = f.propose({ why: 'music', sure: 0.7, params: { energy: 0.1 }, note: 'Music is on.' })
+ expect(proposal).toMatchObject({ deviceId: 'lamp', addon: 'mood-addon', act: 'mood', state: 'sent', expiresAt: f.now() + 10_000 })
+ expect(f.sent).toEqual([{ deviceId: 'lamp', frame: { type: 'event', serverInstanceId: 'instance', machineId: 'machine', kind: 'addon.proposal',
+ payload: { proposalId: proposal.proposalId, addon: 'mood-addon', act: 'mood', why: 'music', sure: 0.7, holdsMs: 10_000,
+ params: { energy: 0.1 }, note: 'Music is on.', expiresAt: f.now() + 10_000 } } }])
+ })
+
+ it('needs a device named when several are connected, and refuses one offline or unknown', () => {
+ const f = fixture()
+ f.publish('a', [{ topic: 'mood/state', value: {} }]); f.publish('b', [{ topic: 'mood/state', value: {} }])
+ expect(f.code(() => f.propose())).toBe('MISSING_TARGET')
+ expect(f.propose({ deviceId: 'b' }).deviceId).toBe('b')
+ f.addons.offline('a')
+ expect(f.code(() => f.propose({ deviceId: 'a' }))).toBe('DEVICE_OFFLINE')
+ expect(f.code(() => f.propose({ deviceId: 'c' }))).toBe('DEVICE_NOT_FOUND')
+ // With a single device still connected, it is the target.
+ expect(f.propose().deviceId).toBe('b')
+ })
+
+ it('is one proposal per add-on and key, and refuses the key for a different intent', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ const first = f.addons.propose({ addon: 'x', idempotencyKey: 'same', act: 'light', holdsMs: 5000, params: { a: 1, b: 2 } })
+ const again = f.addons.propose({ addon: 'x', idempotencyKey: 'same', act: 'light', holdsMs: 5000, params: { b: 2, a: 1 } })
+ expect(again.proposalId).toBe(first.proposalId)
+ expect(f.sent).toHaveLength(1)
+ expect(f.code(() => f.addons.propose({ addon: 'x', idempotencyKey: 'same', act: 'say', holdsMs: 5000 }))).toBe('IDEMPOTENCY_CONFLICT')
+ // Another add-on may use the same key.
+ expect(f.addons.propose({ addon: 'y', idempotencyKey: 'same', act: 'light', holdsMs: 5000 }).proposalId).not.toBe(first.proposalId)
+ })
+
+ it('validates what a proposal carries', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ expect(f.code(() => f.propose({ holdsMs: HOLDS_MAX_MS + 1 }))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.propose({ holdsMs: 999 }))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.propose({ act: 'Mood!' }))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.propose({ sure: 1.5 }))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.propose({ addon: 'has space' }))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.propose({ note: 'a\u0007b' }))).toBe('INVALID_REQUEST')
+ expect(f.code(() => f.propose({ note: 'é'.repeat(151) }))).toBe('PAYLOAD_TOO_LARGE')
+ expect(f.code(() => f.propose({ params: { x: 'a'.repeat(2048) } }))).toBe('PAYLOAD_TOO_LARGE')
+ expect(f.code(() => f.propose({ extra: true }))).toBe('INVALID_REQUEST')
+ expect(f.sent).toHaveLength(0)
+ })
+
+ it('bounds a device per minute whatever the add-ons call themselves', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ for (let i = 0; i < DEVICE_PROPOSALS_PER_MINUTE; i++) {
+ const p = f.propose({ addon: `name-${i}` })
+ f.decide('lamp', p.proposalId, 'dropped')
+ }
+ expect(f.code(() => f.propose({ addon: 'yet-another-name' }))).toBe('RATE_LIMITED')
+ f.tick(60_000)
+ expect(f.propose({ addon: 'yet-another-name' }).state).toBe('sent')
+ })
+
+ it('never drops a proposal the limits still count to make room, and refuses instead', () => {
+ const f = fixture()
+ // 22 devices, each at its minute's bound: more proposals than are kept, all inside the window.
+ let made = 0
+ let refused = ''
+ for (let d = 0; d < 22 && !refused; d++) {
+ f.publish(`d${d}`, [{ topic: 'mood/state', value: {} }])
+ for (let i = 0; i < DEVICE_PROPOSALS_PER_MINUTE && !refused; i++) {
+ refused = f.code(() => {
+ const p = f.propose({ deviceId: `d${d}`, addon: `a${i}` })
+ f.decide(`d${d}`, p.proposalId, 'dropped')
+ made++
+ })
+ if (refused === 'no error') refused = ''
+ }
+ }
+ expect(refused).toBe('BACKPRESSURE')
+ expect(made).toBe(256)
+ // A minute on, the oldest settled ones make room.
+ f.tick(60_000)
+ expect(f.propose({ deviceId: 'd21', addon: 'later' }).state).toBe('sent')
+ })
+
+ it('limits each add-on per minute and each device to a few undecided proposals', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ for (let i = 0; i < OPEN_PROPOSALS_MAX; i++) f.propose({ addon: `a${i}` })
+ expect(f.code(() => f.propose({ addon: 'other' }))).toBe('BACKPRESSURE')
+ // Lapsed proposals free their places.
+ f.tick(10_000)
+ expect(f.addons.proposal((f.sent[0].frame.payload as { proposalId: string }).proposalId)?.state).toBe('expired')
+ const own = fixture()
+ own.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ for (let i = 0; i < PROPOSALS_PER_MINUTE; i++) {
+ const p = own.propose()
+ own.decide('lamp', p.proposalId, 'dropped')
+ }
+ expect(own.code(() => own.propose())).toBe('RATE_LIMITED')
+ own.tick(60_000)
+ expect(own.propose().state).toBe('sent')
+ })
+})
+
+describe('device add-ons: the device decides', () => {
+ it('records the decision of the device it was sent to, once', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }]); f.publish('other', [{ topic: 'mood/state', value: {} }])
+ const p = f.propose({ deviceId: 'lamp' })
+ expect(f.code(() => f.decide('other', p.proposalId, 'kept'))).toBe('PROPOSAL_UNKNOWN')
+ expect(f.decide('lamp', p.proposalId, 'kept', 'quiet room')).toEqual({ proposalId: p.proposalId, state: 'kept' })
+ expect(f.decide('lamp', p.proposalId, 'kept')).toEqual({ proposalId: p.proposalId, state: 'kept' })
+ expect(f.code(() => f.decide('lamp', p.proposalId, 'dropped'))).toBe('IDEMPOTENCY_CONFLICT')
+ expect(f.addons.proposal(p.proposalId)).toMatchObject({ state: 'kept', reason: 'quiet room', decidedAt: f.now() })
+ expect(f.code(() => f.decide('lamp', randomUUID(), 'kept'))).toBe('PROPOSAL_UNKNOWN')
+ expect(f.code(() => f.decide('lamp', p.proposalId, 'maybe'))).toBe('INVALID_REQUEST')
+ })
+
+ it('takes a decision that arrives after the proposal lapsed here, and forgets settled ones after ten minutes', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ const p = f.propose()
+ f.tick(11_000)
+ expect(f.addons.proposal(p.proposalId)?.state).toBe('expired')
+ expect(f.decide('lamp', p.proposalId, 'dropped')).toMatchObject({ state: 'dropped' })
+ f.tick(10 * 60_000 + 1)
+ expect(f.addons.proposal(p.proposalId)).toBeNull()
+ })
+
+ it('forgets the proposals of an unpaired device', () => {
+ const f = fixture()
+ f.publish('lamp', [{ topic: 'mood/state', value: {} }])
+ const p = f.propose()
+ f.addons.revoke('lamp')
+ expect(f.addons.proposal(p.proposalId)).toBeNull()
+ })
+})
diff --git a/cli/src/lib/autonomous-device/addons.ts b/cli/src/lib/autonomous-device/addons.ts
new file mode 100644
index 000000000..791a967d8
--- /dev/null
+++ b/cli/src/lib/autonomous-device/addons.ts
@@ -0,0 +1,253 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { z } from 'zod'
+import type { AutonomousDeviceFrame } from './service.js'
+
+/**
+ * Device add-ons v1 (docs/autonomous-device-addons.md): agents on this computer read what a paired device
+ * chose to publish about itself, and propose what it might do. The device stays the judge: a proposal is
+ * a suggestion it keeps or drops, never a command, and this computer never learns more than the device
+ * published.
+ *
+ * Device-agnostic on purpose. Which topics are safe to publish, which acts a device understands and what a
+ * proposal may change are the device's own policy; this layer bounds sizes, rates and lifetimes so that one
+ * agent cannot flood a device and one device cannot grow this daemon's memory.
+ *
+ * Nothing here is durable. Published values and proposals live in RAM. A hello clears what a device
+ * published, and the device publishes its whole set again after it, so a topic it no longer offers (a
+ * person withdrew consent) is gone, not left readable. When the service restarts under a session the
+ * gateway kept, there is no hello: the device is asked to publish again (`addon.republish`). A proposal
+ * lives at most `HOLDS_MAX_MS` before it lapses.
+ */
+export const DEVICE_ADDON_CAPABILITIES = ['addon.publish', 'addon.decision'] as const
+
+export const TOPICS_MAX = 32
+export const VALUE_MAX_BYTES = 4096
+export const PUBLISH_BATCH_MAX = 16
+export const HOLDS_MIN_MS = 1000
+export const HOLDS_MAX_MS = 30_000
+export const PARAMS_MAX_BYTES = 2048
+export const NOTE_MAX_BYTES = 300
+/** Per device and add-on, in any rolling minute. */
+export const PROPOSALS_PER_MINUTE = 6
+/** Per device, whatever the add-ons call themselves: the name is the caller's, so it cannot be the bound. */
+export const DEVICE_PROPOSALS_PER_MINUTE = 12
+/** Per device: proposals sent and not yet decided or lapsed. */
+export const OPEN_PROPOSALS_MAX = 4
+const PROPOSALS_RETAINED = 256
+const RATE_WINDOW_MS = 60_000
+/** How long a settled proposal stays readable by `addon proposal`. */
+const SETTLED_TTL_MS = 10 * 60_000
+
+const requestId = z.string().regex(/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/)
+/** `room/presence`, `mood/state`: two to four lowercase segments, as a device names its own state. */
+const topic = z.string().max(96).regex(/^[a-z][a-z0-9_]*(\/[a-z][a-z0-9_]*){1,3}$/)
+const word = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/)
+const reason = z.string().min(1).max(200).regex(/^[^\x00-\x1f\x7f]+$/)
+const bytes = (value: unknown): number => Buffer.byteLength(JSON.stringify(value))
+/** Key order does not change an intent: the same proposal written twice is one proposal. */
+function canonical(value: unknown): string {
+ if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+ if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical((value as Record<string, unknown>)[k])}`).join(',')}}`
+ return JSON.stringify(value)
+}
+
+export const DeviceAddonRequestSchema = z.discriminatedUnion('type', [
+ z.strictObject({ type: z.literal('addon.publish'), requestId,
+ values: z.array(z.strictObject({ topic,
+ // null: the device no longer offers this topic.
+ value: z.record(z.string(), z.unknown()).nullable(),
+ at: z.number().int().min(0).optional() })).min(1).max(PUBLISH_BATCH_MAX) }),
+ z.strictObject({ type: z.literal('addon.decision'), requestId, proposalId: z.uuid(),
+ decision: z.enum(['kept', 'dropped']), reason: reason.optional() }),
+])
+
+/** What an agent asks for through `harness autonomous-device addon propose`. */
+export const AddonProposeSchema = z.strictObject({
+ deviceId: z.string().min(1).max(64).optional(),
+ addon: z.string().regex(/^[A-Za-z0-9._:-]{1,64}$/),
+ idempotencyKey: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
+ act: word,
+ why: word.optional(),
+ sure: z.number().min(0).max(1).optional(),
+ holdsMs: z.number().int().min(HOLDS_MIN_MS).max(HOLDS_MAX_MS),
+ params: z.record(z.string(), z.unknown()).optional(),
+ note: z.string().min(1).regex(/^[^\x00-\x09\x0b-\x1f\x7f]+$/).optional(),
+})
+export type AddonPropose = z.infer<typeof AddonProposeSchema>
+
+export type ProposalState = 'sent' | 'kept' | 'dropped' | 'expired'
+export interface AddonProposal {
+ proposalId: string; deviceId: string; addon: string; idempotencyKey: string
+ act: string; why?: string; sure?: number; holdsMs: number; params?: Record<string, unknown>; note?: string
+ state: ProposalState; reason: string | null; sentAt: number; expiresAt: number; decidedAt: number | null
+}
+export interface AddonTopicValue { value: Record<string, unknown>; at: number | null; receivedAt: number }
+export interface AddonDeviceState { deviceId: string; online: boolean; topics: Record<string, AddonTopicValue> }
+
+export class DeviceAddonError extends Error {
+ constructor(readonly code: string, message: string) { super(message) }
+}
+const fail = (code: string, message: string): never => { throw new DeviceAddonError(code, message) }
+
+export interface DeviceAddonsOptions {
+ machineId: string
+ serverInstanceId: string
+ /** To that device's links alone. A proposal is never broadcast and never in the replay log. */
+ send: (deviceId: string, frame: AutonomousDeviceFrame) => void
+ now?: () => number
+}
+
+interface DeviceRecord { online: boolean; topics: Map<string, AddonTopicValue> }
+
+export class DeviceAddons {
+ private readonly devices = new Map<string, DeviceRecord>()
+ private readonly proposals = new Map<string, AddonProposal & { digest: string }>()
+ private readonly now: () => number
+ constructor(private readonly options: DeviceAddonsOptions) { this.now = options.now ?? Date.now }
+
+ /** A device's `addon.*` request, after the relay authenticated it as `deviceId`. */
+ request(deviceId: string, raw: Record<string, unknown>): Record<string, unknown> {
+ const parsed = DeviceAddonRequestSchema.safeParse(raw)
+ if (!parsed.success) fail('INVALID_REQUEST', parsed.error.issues[0]?.message ?? 'Invalid add-on request')
+ const req = parsed.data!
+ if (req.type === 'addon.publish') return this.publish(deviceId, req.values)
+ return this.decide(deviceId, req.proposalId, req.decision, req.reason)
+ }
+
+ private publish(deviceId: string, values: Array<{ topic: string; value: Record<string, unknown> | null; at?: number }>): Record<string, unknown> {
+ // Checked whole before anything is kept: a batch is taken or refused as one.
+ for (const item of values) if (item.value && bytes(item.value) > VALUE_MAX_BYTES) fail('PAYLOAD_TOO_LARGE', `${item.topic} exceeds ${VALUE_MAX_BYTES} bytes`)
+ const record = this.devices.get(deviceId) ?? { online: true, topics: new Map<string, AddonTopicValue>() }
+ const after = new Set(record.topics.keys())
+ for (const item of values) item.value ? after.add(item.topic) : after.delete(item.topic)
+ if (after.size > TOPICS_MAX) fail('BACKPRESSURE', `A device publishes at most ${TOPICS_MAX} topics`)
+ const receivedAt = this.now()
+ for (const item of values) {
+ if (item.value) record.topics.set(item.topic, { value: structuredClone(item.value), at: item.at ?? null, receivedAt })
+ else record.topics.delete(item.topic)
+ }
+ record.online = true
+ this.devices.set(deviceId, record)
+ return { topics: record.topics.size }
+ }
+
+ private decide(deviceId: string, proposalId: string, decision: 'kept' | 'dropped', why?: string): Record<string, unknown> {
+ this.prune()
+ const proposal = this.proposals.get(proposalId)
+ // Another device's proposal reads the same as one never sent: a device learns nothing of others.
+ if (!proposal || proposal.deviceId !== deviceId) fail('PROPOSAL_UNKNOWN', 'No such proposal for this device')
+ const p = proposal!
+ if (p.state === 'kept' || p.state === 'dropped') {
+ if (p.state !== decision) fail('IDEMPOTENCY_CONFLICT', `Proposal was already ${p.state}`)
+ return { proposalId, state: p.state }
+ }
+ // Late (lapsed here) is still recorded: the device's clock and its judge are what decided.
+ p.state = decision; p.reason = why ?? null; p.decidedAt = this.now()
+ return { proposalId, state: p.state }
+ }
+
+ /** An agent's proposal: validated, rate-limited, then sent to the device's links. */
+ propose(input: unknown): AddonProposal {
+ const parsed = AddonProposeSchema.safeParse(input)
+ if (!parsed.success) fail('INVALID_REQUEST', parsed.error.issues[0]?.message ?? 'Invalid proposal')
+ const req = parsed.data!
+ if (req.params && bytes(req.params) > PARAMS_MAX_BYTES) fail('PAYLOAD_TOO_LARGE', `params exceed ${PARAMS_MAX_BYTES} bytes`)
+ if (req.note && Buffer.byteLength(req.note) > NOTE_MAX_BYTES) fail('PAYLOAD_TOO_LARGE', `note exceeds ${NOTE_MAX_BYTES} bytes`)
+ this.prune()
+ const { deviceId: _target, idempotencyKey: _key, ...intent } = req
+ const digest = createHash('sha256').update(canonical(intent)).digest('hex')
+ for (const existing of this.proposals.values()) {
+ if (existing.addon !== req.addon || existing.idempotencyKey !== req.idempotencyKey) continue
+ if (existing.digest !== digest || (req.deviceId && req.deviceId !== existing.deviceId)) fail('IDEMPOTENCY_CONFLICT', 'Key already belongs to a different proposal')
+ return this.view(existing)
+ }
+ const deviceId = this.target(req.deviceId)
+ const now = this.now()
+ const recent = [...this.proposals.values()].filter(p => p.deviceId === deviceId && now - p.sentAt < RATE_WINDOW_MS)
+ if (recent.length >= DEVICE_PROPOSALS_PER_MINUTE) fail('RATE_LIMITED', `At most ${DEVICE_PROPOSALS_PER_MINUTE} proposals a minute to one device`)
+ if (recent.filter(p => p.addon === req.addon).length >= PROPOSALS_PER_MINUTE) fail('RATE_LIMITED', `At most ${PROPOSALS_PER_MINUTE} proposals a minute per add-on`)
+ const open = [...this.proposals.values()].filter(p => p.deviceId === deviceId && p.state === 'sent')
+ if (open.length >= OPEN_PROPOSALS_MAX) fail('BACKPRESSURE', 'The device has not answered earlier proposals yet')
+ // Room is made before anything is sent: a proposal the limits still count is never dropped for it.
+ if (this.proposals.size >= PROPOSALS_RETAINED && !this.evict(now)) fail('BACKPRESSURE', 'Too many recent proposals are kept; try again in a minute')
+ const proposal = { proposalId: randomUUID(), deviceId, addon: req.addon, idempotencyKey: req.idempotencyKey, act: req.act,
+ ...(req.why ? { why: req.why } : {}), ...(req.sure !== undefined ? { sure: req.sure } : {}), holdsMs: req.holdsMs,
+ ...(req.params ? { params: structuredClone(req.params) } : {}), ...(req.note ? { note: req.note } : {}),
+ state: 'sent' as ProposalState, reason: null, sentAt: now, expiresAt: now + req.holdsMs, decidedAt: null, digest }
+ this.proposals.set(proposal.proposalId, proposal)
+ const { deviceId: _d, idempotencyKey: _i, state: _s, reason: _r, sentAt: _t, decidedAt: _a, digest: _g, ...payload } = proposal
+ this.options.send(deviceId, { type: 'event', serverInstanceId: this.options.serverInstanceId, machineId: this.options.machineId,
+ kind: 'addon.proposal', payload })
+ return this.view(proposal)
+ }
+
+ /** A proposal an agent sent, or null once it aged out. */
+ proposal(proposalId: string): AddonProposal | null {
+ this.prune()
+ const found = this.proposals.get(proposalId)
+ return found ? this.view(found) : null
+ }
+
+ /** What the devices published, newest values only. */
+ state(deviceId?: string): AddonDeviceState[] {
+ return [...this.devices].filter(([id]) => !deviceId || id === deviceId).map(([id, record]) => ({
+ deviceId: id, online: record.online,
+ topics: Object.fromEntries([...record.topics].sort(([a], [b]) => a < b ? -1 : 1).map(([t, v]) => [t, structuredClone(v)])) }))
+ }
+
+ /** A hello: what it published before is cleared, and it publishes its whole set again (module doc). */
+ hello(deviceId: string): void {
+ this.devices.delete(deviceId)
+ }
+
+ /** Served again after the service restarted, without a hello: the device is asked to publish again. */
+ republish(deviceId: string): void {
+ this.options.send(deviceId, { type: 'event', serverInstanceId: this.options.serverInstanceId, machineId: this.options.machineId,
+ kind: 'addon.republish', payload: {} })
+ }
+
+ /** Its last link closed: its values stay readable, marked offline, and nothing is proposed to it. */
+ offline(deviceId: string): void {
+ const record = this.devices.get(deviceId)
+ if (record) record.online = false
+ }
+
+ /** Unpaired: everything it published and everything proposed to it is forgotten. */
+ revoke(deviceId: string): void {
+ this.devices.delete(deviceId)
+ for (const [id, p] of this.proposals) if (p.deviceId === deviceId) this.proposals.delete(id)
+ }
+
+ private target(deviceId: string | undefined): string {
+ if (deviceId) {
+ const record = this.devices.get(deviceId)
+ if (!record) fail('DEVICE_NOT_FOUND', 'That device has published no add-on state')
+ if (!record!.online) fail('DEVICE_OFFLINE', 'That device is not connected')
+ return deviceId
+ }
+ const online = [...this.devices].filter(([, r]) => r.online).map(([id]) => id)
+ if (online.length !== 1) fail('MISSING_TARGET', online.length ? 'Several devices are connected; name one with deviceId' : 'No connected device offers add-ons')
+ return online[0]
+ }
+
+ private view(p: AddonProposal & { digest?: string }): AddonProposal {
+ const { digest: _digest, ...rest } = p
+ return structuredClone(rest)
+ }
+
+ private prune(): void {
+ const now = this.now()
+ for (const [id, p] of this.proposals) {
+ if (p.state === 'sent' && now >= p.expiresAt) { p.state = 'expired'; p.decidedAt = p.expiresAt }
+ if (p.state !== 'sent' && now - (p.decidedAt ?? p.expiresAt) > SETTLED_TTL_MS) this.proposals.delete(id)
+ }
+ }
+
+ /** Over capacity: the oldest settled proposal outside the rate window goes, or none (false). */
+ private evict(now: number): boolean {
+ for (const [id, p] of this.proposals) {
+ if (p.state !== 'sent' && now - p.sentAt >= RATE_WINDOW_MS) { this.proposals.delete(id); return true }
+ }
+ return false
+ }
+}
diff --git a/cli/src/lib/autonomous-device/command.ts b/cli/src/lib/autonomous-device/command.ts
index 9c0abca6c..48d365981 100644
--- a/cli/src/lib/autonomous-device/command.ts
+++ b/cli/src/lib/autonomous-device/command.ts
@@ -1,4 +1,5 @@
import { readHookCredential } from '../hookAuth.js'
+import { runAddonCommand } from './addonCommand.js'
/** Native UI writes the displayed device code to stdin so it never appears in process arguments. */
async function stdinCode(): Promise<string> {
@@ -10,6 +11,7 @@ async function stdinCode(): Promise<string> {
return value.trim()
}
export async function runAutonomousDeviceCommand(argv: string[], dataDir: string, port: number): Promise<number> {
+ if (argv[0] === 'addon') return runAddonCommand(argv.slice(1), dataDir, port)
const json = argv.includes('--json'), args: string[] = []
let device: string | undefined
const flags = new Set<string>()
@@ -25,7 +27,7 @@ export async function runAutonomousDeviceCommand(argv: string[], dataDir: string
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]' } })
+ 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> | addon state|propose|proposal [--json]' } })
return 1
}
const credential = readHookCredential(dataDir)
diff --git a/cli/src/lib/autonomous-device/parts.spec.ts b/cli/src/lib/autonomous-device/parts.spec.ts
index 048c536de..c167ca1b5 100644
--- a/cli/src/lib/autonomous-device/parts.spec.ts
+++ b/cli/src/lib/autonomous-device/parts.spec.ts
@@ -52,6 +52,7 @@ describe('the Wi-Fi device pieces the core starts', () => {
discover: async () => ({ devices: await runningDevicePart(missing, 'Wi-Fi device link').discover() }),
pairStart: () => runningDevicePart(missing, 'Wi-Fi device link').pair('device', 'ABC234'),
pairStatus: () => ({}), list: () => ({}), status: () => ({}), revoke: () => ({}), receipt: () => ({}),
+ addonState: () => ({}), addonPropose: () => ({}), addonProposal: () => ({}),
}
expect(await autonomousDeviceLocalRequest(management, 'GET', '/api/autonomous-device/discover', undefined)).toEqual({
status: 503,
diff --git a/cli/src/lib/autonomous-device/relay.spec.ts b/cli/src/lib/autonomous-device/relay.spec.ts
index bd0d0faab..e30410755 100644
--- a/cli/src/lib/autonomous-device/relay.spec.ts
+++ b/cli/src/lib/autonomous-device/relay.spec.ts
@@ -143,3 +143,62 @@ describe('a session served on after the service restarted (services/wifi.ts)', (
expect(f.send).not.toHaveBeenCalled()
})
})
+
+describe('device add-ons over the E2EE relay', () => {
+ it('advertises add-ons, keeps what the device publishes, and seals a proposal to that device alone', async () => {
+ let crypto: { identity: string } = { identity: 'lamp' }
+ const send = vi.fn()
+ let relay: AutonomousDeviceRelay | undefined
+ const service = new AutonomousDeviceService({ now: () => 0, machineId: 'machine', agents: () => [], submit: vi.fn(), cancelDelivery: () => true,
+ stop: async () => true, answer: async () => true, recent: () => [], emit: (frame, deviceId) => relay?.emit(frame, deviceId) })
+ relay = new AutonomousDeviceRelay({ sessionRole: () => 'device', sessionIdentity: (connId) => connId === 'other' ? 'other-device' : crypto.identity,
+ unwrapDown: (_c, frame) => ({ ...frame, payload: (frame.payload as { __e2e: unknown }).__e2e }),
+ wrapTarget: (_c, type, payload) => ({ type, payload: { __e2e: payload } }) }, send, service, 'machine')
+ const request = (connId: string, payload: Record<string, unknown>) => relay!.handle(connId, { type: 'autonomous_device_request', payload: { __e2e: payload } })
+ const opened = (i: number) => (send.mock.calls[i][1] as { payload: { __e2e: Record<string, unknown> } }).payload.__e2e
+
+ await request('conn', { type: 'hello', proto: 1, requestId: randomUUID() })
+ expect(opened(0).capabilities).toEqual(expect.arrayContaining(['addon.publish', 'addon.decision']))
+ await request('other', { type: 'hello', proto: 1, requestId: randomUUID() })
+ send.mockClear()
+
+ await request('conn', { type: 'addon.publish', requestId: randomUUID(), values: [{ topic: 'room/presence', value: { someone: true } }] })
+ expect(opened(0)).toMatchObject({ type: 'addon.publish_result', topics: 1 })
+ expect(service.addons.state()).toMatchObject([{ deviceId: 'lamp', online: true, topics: { 'room/presence': { value: { someone: true } } } }])
+ send.mockClear()
+
+ const proposal = service.addons.propose({ addon: 'evening-glow', idempotencyKey: 'k1', act: 'light', holdsMs: 30_000, params: { colour: 'warm', level: 2 } })
+ expect(send).toHaveBeenCalledOnce()
+ expect(send.mock.calls[0][0]).toBe('conn')
+ expect(opened(0)).toEqual({ type: 'event', serverInstanceId: service.serverInstanceId, machineId: 'machine', kind: 'addon.proposal',
+ payload: { proposalId: proposal.proposalId, addon: 'evening-glow', act: 'light', holdsMs: 30_000, params: { colour: 'warm', level: 2 }, expiresAt: 30_000 } })
+ send.mockClear()
+
+ // Not in the replay log: a device that reconnects is not handed lapsed proposals.
+ await request('conn', { type: 'hello', proto: 1, requestId: randomUUID(), resume: { serverInstanceId: service.serverInstanceId, cursor: 0 } })
+ expect(send.mock.calls.map((_, i) => opened(i).kind).filter(Boolean)).not.toContain('addon.proposal')
+ send.mockClear()
+
+ await request('other', { type: 'addon.decision', requestId: randomUUID(), proposalId: proposal.proposalId, decision: 'kept' })
+ expect(opened(0)).toMatchObject({ type: 'addon.decision_result', error: { code: 'PROPOSAL_UNKNOWN' } })
+ await request('conn', { type: 'addon.decision', requestId: randomUUID(), proposalId: proposal.proposalId, decision: 'kept', reason: 'evening, someone here' })
+ expect(opened(1)).toMatchObject({ type: 'addon.decision_result', state: 'kept' })
+ expect(service.addons.proposal(proposal.proposalId)).toMatchObject({ state: 'kept', reason: 'evening, someone here' })
+
+ // A new hello clears what it published: it publishes its whole set again.
+ await request('conn', { type: 'hello', proto: 1, requestId: randomUUID() })
+ expect(service.addons.state('lamp')).toEqual([])
+ await request('conn', { type: 'addon.publish', requestId: randomUUID(), values: [{ topic: 'room/presence', value: { someone: false } }] })
+ send.mockClear()
+ // A restored session (the service restarted, no hello) is asked to publish again.
+ relay.drop('conn')
+ relay.restore('conn', 'lamp')
+ expect(send.mock.calls.map((_, i) => opened(i).kind)).toContain('addon.republish')
+ // The device's last link closing marks it offline; unpairing forgets it.
+ relay.drop('conn')
+ expect(service.addons.state('lamp')[0].online).toBe(false)
+ relay.revoke('lamp')
+ expect(service.addons.state('lamp')).toEqual([])
+ crypto = { identity: 'lamp' }
+ })
+})
diff --git a/cli/src/lib/autonomous-device/relay.ts b/cli/src/lib/autonomous-device/relay.ts
index b708d19df..b2646d711 100644
--- a/cli/src/lib/autonomous-device/relay.ts
+++ b/cli/src/lib/autonomous-device/relay.ts
@@ -36,6 +36,8 @@ export class AutonomousDeviceRelay {
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 })
+ // What it published before is cleared: it publishes its whole set again after a hello (addons.ts).
+ this.service.addons.hello(identity)
this.onClient?.(connId, identity)
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: this.service.capabilities, ...this.service.resume(resume) })
@@ -95,6 +97,8 @@ export class AutonomousDeviceRelay {
this.clients.set(connId, { identity, tokens: 20, at: Date.now(), active: 0 })
this.onClient?.(connId, identity)
this.service.replay(undefined, event => this.sendEvent(connId, identity, event))
+ // No hello comes after a restart, and this run holds nothing it published: it is asked again.
+ this.service.addons.republish(identity)
}
drop(connId: string): void {
const client = this.clients.get(connId)
diff --git a/cli/src/lib/autonomous-device/service.ts b/cli/src/lib/autonomous-device/service.ts
index 7861220a0..403fa860d 100644
--- a/cli/src/lib/autonomous-device/service.ts
+++ b/cli/src/lib/autonomous-device/service.ts
@@ -4,6 +4,7 @@ import type { DeviceResultJournal } from './resultJournal.js'
import type { DeviceInputStatus } from '../../core/deviceInput.js'
import type { AutonomousDeviceStore } from './store.js'
import { DEVICE_STORE_CAPABILITIES, DeviceStoreError } from './storeContract.js'
+import { DEVICE_ADDON_CAPABILITIES, DeviceAddonError, DeviceAddons } from './addons.js'
import { createHash, randomUUID } from 'node:crypto'
import type { LiveEvent } from '../normalize.js'
import { AgentStreams, STREAM_KINDS, STREAM_TTL_DEFAULT_SEC, STREAM_TTL_MAX_SEC, StreamRequestError, type StreamKind } from './stream.js'
@@ -318,6 +319,8 @@ export class AutonomousDeviceService {
this.now = options.now ?? Date.now
this.streams = new AgentStreams({ machineId: options.machineId, serverInstanceId: this.serverInstanceId,
send: (deviceId, frame) => this.options.emit?.(frame, deviceId) })
+ this.addons = new DeviceAddons({ machineId: options.machineId, serverInstanceId: this.serverInstanceId,
+ send: (deviceId, frame) => this.options.emit?.(frame, deviceId), now: this.now })
let snapshot = options.resultJournal?.load()
// Written on this computer under ANOTHER machine id: a sign-in to another account, a switch of
// backend, a machine re-registered. Its dedupe cannot apply here — every request naming that
@@ -356,12 +359,14 @@ export class AutonomousDeviceService {
}
}
private readonly streams: AgentStreams
+ /** What devices publish for this computer's agents, and the proposals the agents send back (addons.ts). */
+ readonly addons: DeviceAddons
/** Live events of one agent, for its subscribers only. Never recorded in the replay log. */
stream(agentId: string, events: readonly LiveEvent[]): void { this.streams.ingest(agentId, events) }
/** The agents a device subscribed to: the core sends their tools' events too (core/wifi.ts). */
streamedAgents(): string[] { return this.streams.agents() }
/** The device's last link closed: its subscriptions end with it, and a reconnect subscribes again. */
- deviceOffline(deviceId: string): void { this.streams.dropDevice(deviceId) }
+ deviceOffline(deviceId: string): void { this.streams.dropDevice(deviceId); this.addons.offline(deviceId) }
private subscription(deviceId: string, type: 'agent.subscribe' | 'agent.unsubscribe', req: Record<string, unknown>): Record<string, unknown> {
const fields = type === 'agent.subscribe' ? ['type', 'requestId', 'machineId', 'agentId', 'ttlSec', 'include'] : ['type', 'requestId', 'subscriptionId']
@@ -474,6 +479,7 @@ export class AutonomousDeviceService {
}
for (const [key, step] of this.steps) if (step.deviceId === deviceId) this.steps.delete(key)
this.streams.dropDevice(deviceId)
+ this.addons.revoke(deviceId)
for (const [key, result] of this.results) if (result.deviceId === deviceId) this.results.delete(key)
this.persist()
// A newly paired identity cannot replay the previous device's request receipts.
@@ -561,7 +567,7 @@ export class AutonomousDeviceService {
this.event(p.kind === 'summary' ? 'turn.summary' : p.kind === 'tool' ? 'turn.tool' : 'agent.error', agentId, full ? { ...p, fullText: full } : p)
}
}
- get capabilities(): string[] { return [...AUTONOMOUS_DEVICE_CAPABILITIES, 'input.status.v1', ...(this.options.store ? DEVICE_STORE_CAPABILITIES : [])] }
+ get capabilities(): string[] { return [...AUTONOMOUS_DEVICE_CAPABILITIES, 'input.status.v1', ...(this.options.store ? DEVICE_STORE_CAPABILITIES : []), ...DEVICE_ADDON_CAPABILITIES] }
async request(deviceId: string, req: Record<string, unknown>): Promise<AutonomousDeviceFrame> {
const type = typeof req.type === 'string' ? req.type : 'invalid'
const response = (data: Record<string, unknown>): AutonomousDeviceFrame => ({ type: `${type}_result`, requestId: req.requestId, ...data })
@@ -570,6 +576,7 @@ export class AutonomousDeviceService {
if (!UUID.test(String(req.requestId))) fail('INVALID_REQUEST', 'requestId must be a UUIDv4')
if (type === 'input.status.v1' || !this.capabilities.includes(type)) fail('UNSUPPORTED_CAPABILITY', 'Operation is not supported')
if ((DEVICE_STORE_CAPABILITIES as readonly string[]).includes(type)) return response(await this.options.store!.request(deviceId, req))
+ if ((DEVICE_ADDON_CAPABILITIES as readonly string[]).includes(type)) return response(this.addons.request(deviceId, req))
if (type === 'agent.subscribe' || type === 'agent.unsubscribe') return response(this.subscription(deviceId, type, req))
const allowed = ['type', 'requestId', ...(['agents.list', 'focus.get', 'focus.ensure'].includes(type) ? [] : type === 'receipt.get' ? ['idempotencyKey'] : type === 'focus.step' ? ['direction', 'idempotencyKey', 'focusRevision'] : type === 'scroll' ? ['phase', 'dy', 'velocity'] : ['machineId', 'agentId']),
...(MUTATIONS.has(type) ? ['idempotencyKey'] : []), ...(type === 'turn.send' ? ['text', 'focusRevision'] : type === 'question.answer' ? ['questionRequestId', 'answers', 'focusRevision'] : type === 'recap' ? ['n'] : [])]
@@ -647,7 +654,8 @@ export class AutonomousDeviceService {
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 instanceof DeviceStoreError ? e.code : 'INTERNAL', message: e instanceof RequestError || e instanceof DeviceStoreError ? e.message : 'Request failed' } })
+ const known = e instanceof RequestError || e instanceof DeviceStoreError || e instanceof DeviceAddonError
+ return response({ error: { code: known ? e.code : 'INTERNAL', message: known ? e.message : 'Request failed' } })
}
}
}
diff --git a/cli/src/lib/deviceManagementHttp.spec.ts b/cli/src/lib/deviceManagementHttp.spec.ts
index 783d8c184..f5b78755a 100644
--- a/cli/src/lib/deviceManagementHttp.spec.ts
+++ b/cli/src/lib/deviceManagementHttp.spec.ts
@@ -1,5 +1,5 @@
import { describe, expect, it, vi } from 'vitest'
-import { autonomousDeviceLocalRequest, type AutonomousDeviceManagement } from './deviceManagementHttp.js'
+import { autonomousDeviceLocalRequest, deviceAddonRoutes, type AutonomousDeviceManagement } from './deviceManagementHttp.js'
const id = Buffer.alloc(32, 255).toString('base64')
function fixture() {
@@ -11,6 +11,9 @@ function fixture() {
status: vi.fn().mockReturnValue({ proto: 1 }),
revoke: vi.fn().mockReturnValue({ revoked: 1 }),
receipt: vi.fn().mockReturnValue({ receipt: null }),
+ addonState: vi.fn().mockReturnValue({ devices: [] }),
+ addonPropose: vi.fn().mockReturnValue({ proposal: { proposalId: 'p' } }),
+ addonProposal: vi.fn().mockReturnValue({ proposal: null }),
} satisfies AutonomousDeviceManagement
}
@@ -106,3 +109,60 @@ describe('device local management validation', () => {
}
})
})
+
+describe('device add-on local routes', () => {
+ it('reads state with an optional device, a proposal by id, and posts a proposal as given', async () => {
+ const service = fixture()
+ expect(await autonomousDeviceLocalRequest(service, 'GET', '/api/autonomous-device/addon/state')).toEqual({ status: 200, body: { devices: [] } })
+ expect(service.addonState).toHaveBeenLastCalledWith({})
+ await autonomousDeviceLocalRequest(service, 'GET', '/api/autonomous-device/addon/state?deviceId=lamp')
+ expect(service.addonState).toHaveBeenLastCalledWith({ deviceId: 'lamp' })
+ const id = '0b6c3c3e-8f3a-4f5a-9d2b-6f1e2a3b4c5d'
+ expect((await autonomousDeviceLocalRequest(service, 'GET', `/api/autonomous-device/addon/proposal?proposalId=${id}`)).status).toBe(200)
+ expect(service.addonProposal).toHaveBeenCalledWith({ proposalId: id })
+ const body = { addon: 'x', idempotencyKey: 'k', act: 'light', holdsMs: 5000 }
+ expect(await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/addon/propose', body)).toEqual({ status: 200, body: { proposal: { proposalId: 'p' } } })
+ expect(service.addonPropose).toHaveBeenCalledWith(body)
+ })
+
+ it('refuses a wrong method, a stray or repeated parameter, and a missing or malformed proposal id', async () => {
+ const service = fixture()
+ for (const [method, target] of [
+ ['POST', '/api/autonomous-device/addon/state'],
+ ['GET', '/api/autonomous-device/addon/propose'],
+ ] as const) expect((await autonomousDeviceLocalRequest(service, method, target, method === 'POST' ? {} : undefined)).status).toBe(405)
+ for (const target of [
+ '/api/autonomous-device/addon/state?device=lamp',
+ '/api/autonomous-device/addon/state?deviceId=a&deviceId=b',
+ '/api/autonomous-device/addon/state?deviceId=',
+ '/api/autonomous-device/addon/proposal',
+ '/api/autonomous-device/addon/proposal?proposalId=nope',
+ ]) expect((await autonomousDeviceLocalRequest(service, 'GET', target)).status).toBe(400)
+ expect((await autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/addon/propose?x=1', {})).status).toBe(400)
+ expect(service.addonState).not.toHaveBeenCalled()
+ expect(service.addonPropose).not.toHaveBeenCalled()
+ expect(service.addonProposal).not.toHaveBeenCalled()
+ })
+
+ it('maps the add-on layer and the service being down to HTTP answers', async () => {
+ const answers = [
+ { error: { code: 'RATE_LIMITED', message: 'slow down' } },
+ { error: { code: 'MISSING_TARGET', message: 'name one' } },
+ { error: { code: 'PAYLOAD_TOO_LARGE', message: 'too big' } },
+ { unavailable: true as const },
+ { error: { code: 'OUTCOME_UNKNOWN', message: 'maybe sent' } },
+ { error: { code: 'PROPOSAL_UNKNOWN', message: 'aged out' } },
+ { result: { proposal: null } },
+ ]
+ const routes = deviceAddonRoutes(async () => answers.shift()!)
+ const service = { ...fixture(), ...routes }
+ const post = () => autonomousDeviceLocalRequest(service, 'POST', '/api/autonomous-device/addon/propose', {})
+ expect(await post()).toEqual({ status: 429, body: { error: { code: 'RATE_LIMITED', message: 'slow down' } } })
+ expect((await post()).status).toBe(409)
+ expect((await post()).status).toBe(413)
+ expect((await post()).body).toMatchObject({ error: { code: 'UNAVAILABLE' } })
+ expect((await post()).status).toBe(504)
+ expect((await post()).status).toBe(404)
+ expect(await post()).toEqual({ status: 200, body: { proposal: null } })
+ })
+})
diff --git a/cli/src/lib/deviceManagementHttp.ts b/cli/src/lib/deviceManagementHttp.ts
index fc4eccedd..927f8e71a 100644
--- a/cli/src/lib/deviceManagementHttp.ts
+++ b/cli/src/lib/deviceManagementHttp.ts
@@ -1,3 +1,5 @@
+import type { WifiAddon, WifiAddonOp } from '../core/api.js'
+
/** Local HTTP validation only. Pairing and device state stay behind the gateway and Wi-Fi ports. */
export interface AutonomousDeviceManagement {
discover(): unknown | Promise<unknown>
@@ -7,10 +9,30 @@ export interface AutonomousDeviceManagement {
status(): unknown | Promise<unknown>
revoke(target: { id: string }): unknown | Promise<unknown>
receipt(target: { deviceId: string; idempotencyKey: string }): unknown | Promise<unknown>
+ /** Device add-ons (lib/autonomous-device/addons.ts), which validates the proposal itself. */
+ addonState(target: { deviceId?: string }): unknown | Promise<unknown>
+ addonPropose(proposal: Record<string, unknown>): unknown | Promise<unknown>
+ addonProposal(target: { proposalId: string }): unknown | Promise<unknown>
}
export interface AutonomousDeviceLocalResponse { status: number; body: unknown }
+/** The add-on routes over the Wi-Fi device service's one `addon` door (core/api.ts `WifiPort.addon`). */
+export function deviceAddonRoutes(ask: (op: WifiAddonOp, input: Record<string, unknown>) => Promise<WifiAddon>):
+ Pick<AutonomousDeviceManagement, 'addonState' | 'addonPropose' | 'addonProposal'> {
+ const call = async (op: WifiAddonOp, input: Record<string, unknown>): Promise<Record<string, unknown>> => {
+ const answer = await ask(op, input)
+ if ('unavailable' in answer) throw Object.assign(new Error('The Wi-Fi device service is not running on this computer. See the daemon\'s log.'), { code: 'UNAVAILABLE' })
+ if ('error' in answer) throw Object.assign(new Error(answer.error.message), { code: answer.error.code })
+ return answer.result
+ }
+ return {
+ addonState: (target) => call('state', target),
+ addonPropose: (proposal) => call('propose', proposal),
+ addonProposal: (target) => call('proposal', target),
+ }
+}
+
const routes: Record<string, string> = {
'/api/autonomous-device/discover': 'GET',
'/api/autonomous-device/pair/start': 'POST',
@@ -19,12 +41,23 @@ const routes: Record<string, string> = {
'/api/autonomous-device/status': 'GET',
'/api/autonomous-device/revoke': 'POST',
'/api/autonomous-device/receipt': 'GET',
+ '/api/autonomous-device/addon/state': 'GET',
+ '/api/autonomous-device/addon/propose': 'POST',
+ '/api/autonomous-device/addon/proposal': 'GET',
+}
+
+/** The routes that take a query string, and the one parameter each may carry. */
+const queries: Record<string, { name: string; required: boolean; valid: (value: string) => boolean }> = {
+ '/api/autonomous-device/addon/state': { name: 'deviceId', required: false, valid: v => v.length > 0 && v.length <= 64 },
+ '/api/autonomous-device/addon/proposal': { name: 'proposalId', required: true, valid: v => /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(v) },
}
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,
LOCAL_NETWORK_BLOCKED: 503, UNAVAILABLE: 503,
+ INVALID_REQUEST: 400, PAYLOAD_TOO_LARGE: 413, MISSING_TARGET: 409, DEVICE_OFFLINE: 409, IDEMPOTENCY_CONFLICT: 409, BACKPRESSURE: 429,
+ PROPOSAL_UNKNOWN: 404, OUTCOME_UNKNOWN: 504,
}
function failure(status: number, code: string, message: string): AutonomousDeviceLocalResponse {
@@ -56,7 +89,7 @@ export async function autonomousDeviceLocalRequest(
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()
+ if (url.pathname !== '/api/autonomous-device/receipt' && !Object.hasOwn(queries, url.pathname) && url.search) return bad()
const input = body === undefined ? {} : body
if (!object(input)) return bad()
const keys = Object.keys(input)
@@ -81,6 +114,22 @@ export async function autonomousDeviceLocalRequest(
call = () => service.receipt({ deviceId: id, idempotencyKey: key })
break
}
+ case '/api/autonomous-device/addon/propose':
+ call = () => service.addonPropose(input)
+ break
+ case '/api/autonomous-device/addon/state':
+ case '/api/autonomous-device/addon/proposal': {
+ const rule = queries[url.pathname]
+ const query = url.searchParams
+ const values = query.getAll(rule.name)
+ if ([...query.keys()].some(key => key !== rule.name) || values.length > 1 || (rule.required && !values.length)
+ || (values.length && !rule.valid(values[0]))) return bad()
+ const value = values[0]
+ call = url.pathname === '/api/autonomous-device/addon/state'
+ ? () => service.addonState(value ? { deviceId: value } : {})
+ : () => service.addonProposal({ proposalId: value })
+ break
+ }
default:
if (keys.length) return bad()
switch (url.pathname) {
diff --git a/cli/src/services/wifi.spec.ts b/cli/src/services/wifi.spec.ts
index aba8ae048..b89de5620 100644
--- a/cli/src/services/wifi.spec.ts
+++ b/cli/src/services/wifi.spec.ts
@@ -184,6 +184,25 @@ describe('the Wi-Fi device, with the dials', () => {
expect(core.wifi.joined).not.toHaveBeenCalled()
})
+ it('carries device add-ons end to end: what the device publishes, an agent\'s proposal sealed to it, and its decision', async () => {
+ const { core, port, hello, ask } = started()
+ expect(await port.addon('propose', { addon: 'glow', idempotencyKey: 'k', act: 'light', holdsMs: 5000 }))
+ .toEqual({ error: { code: 'MISSING_TARGET', message: 'No connected device offers add-ons' } })
+ await hello()
+ expect(await ask({ type: 'addon.publish', values: [{ topic: 'room/presence', value: { someone: true } }] })).toMatchObject({ type: 'addon.publish_result', topics: 1 })
+ expect(await port.addon('state', {})).toMatchObject({ result: { devices: [{ deviceId: 'device-1', online: true, topics: { 'room/presence': { value: { someone: true } } } }] } })
+ vi.mocked(core.wifi.send).mockClear()
+ const proposed = await port.addon('propose', { addon: 'glow', idempotencyKey: 'k', act: 'light', holdsMs: 5000, params: { colour: 'warm' } })
+ const proposalId = ('result' in proposed ? (proposed.result.proposal as { proposalId: string }) : { proposalId: '' }).proposalId
+ expect(sent(core)).toEqual([expect.objectContaining({ connId: 'c1', identity: 'device-1', frame: 'autonomous_device_event', kind: 'addon.proposal',
+ payload: expect.objectContaining({ proposalId, addon: 'glow', act: 'light', params: { colour: 'warm' } }) })])
+ expect(await ask({ type: 'addon.decision', proposalId, decision: 'dropped', reason: 'someone is talking' })).toMatchObject({ state: 'dropped' })
+ expect(await port.addon('proposal', { proposalId })).toMatchObject({ result: { proposal: { proposalId, state: 'dropped', reason: 'someone is talking' } } })
+ port.revoked('device-1')
+ expect(await port.addon('state', {})).toEqual({ result: { devices: [] } })
+ await port.stop()
+ })
+
it('forgets a closed connection and an unpaired device, and answers a receipt', async () => {
const { core, port, hello, ask } = started()
await hello()
@@ -271,6 +290,21 @@ describe('the Wi-Fi device, with the dials', () => {
warn.mockRestore()
})
+ it('reads add-on state for one device, a proposal by a malformed id as none, and lets an unexpected failure through', async () => {
+ const { port, hello, ask } = started()
+ await hello()
+ await ask({ type: 'addon.publish', values: [{ topic: 'mood/state', value: { energy: 0.5 } }] })
+ expect(await port.addon('state', { deviceId: 'device-1' })).toMatchObject({ result: { devices: [{ deviceId: 'device-1' }] } })
+ expect(await port.addon('state', { deviceId: 'nobody' })).toEqual({ result: { devices: [] } })
+ expect(await port.addon('proposal', { proposalId: 42 })).toMatchObject({ error: { code: 'PROPOSAL_UNKNOWN' } })
+ await port.stop()
+ const ports = emptyPorts()
+ startWifi(fakeCore({ dataDir }), ports, {
+ service: () => ({ addons: { state: () => { throw new Error('broken') } } }) as unknown as AutonomousDeviceService,
+ })
+ await expect((ports.wifi as WifiPort).addon('state', {})).rejects.toThrow('broken')
+ })
+
it('says a focus change that carries no revision to nobody', () => {
const emits: Array<(frame: Record<string, unknown>) => void> = []
const core = fakeCore({ dataDir })
diff --git a/cli/src/services/wifi.ts b/cli/src/services/wifi.ts
index c8d10c8e6..92d869748 100644
--- a/cli/src/services/wifi.ts
+++ b/cli/src/services/wifi.ts
@@ -16,6 +16,7 @@ import { startDevicePart } from '../lib/autonomous-device/parts.js'
import { deviceRelayOverGateway } from '../lib/autonomous-device/overGateway.js'
import { DeviceResultJournal } from '../lib/autonomous-device/resultJournal.js'
import { AutonomousDeviceService, type AutonomousDeviceFrame } from '../lib/autonomous-device/service.js'
+import { DeviceAddonError } from '../lib/autonomous-device/addons.js'
import { createDeviceStore } from '../lib/autonomous-device/storeRuntime.js'
export { WIFI_FALLBACKS } from '../core/api.js'
@@ -179,6 +180,19 @@ export function startWifi(core: CoreApi, ports: CorePorts, deps: WifiDeps = {}):
},
revealed: (operationId, agentId) => store.acknowledgeReveal(operationId, agentId),
receipt: async (deviceId, idempotencyKey) => ({ receipt: service.receipt(deviceId, idempotencyKey) }),
+ addon: async (op, input) => {
+ try {
+ if (op === 'state') return { result: { devices: service.addons.state(typeof input.deviceId === 'string' ? input.deviceId : undefined) } }
+ if (op === 'propose') return { result: { proposal: service.addons.propose(input) } }
+ const proposal = service.addons.proposal(typeof input.proposalId === 'string' ? input.proposalId : '')
+ // Never sent, or aged out: said as such, so a script can tell it from a proposal.
+ if (!proposal) return { error: { code: 'PROPOSAL_UNKNOWN', message: 'No such proposal: never sent, or aged out after ten minutes' } }
+ return { result: { proposal } }
+ } catch (error) {
+ if (error instanceof DeviceAddonError) return { error: { code: error.code, message: error.message } }
+ throw error
+ }
+ },
stop: async () => store.stopUiDelivery(),
}
store.startUiDelivery()
diff --git a/cli/src/services/wifiProcess.spec.ts b/cli/src/services/wifiProcess.spec.ts
index 5a72943ac..bb707032e 100644
--- a/cli/src/services/wifiProcess.spec.ts
+++ b/cli/src/services/wifiProcess.spec.ts
@@ -24,6 +24,7 @@ function wifiPort(machineId: string, log: string[]) {
appFocus: vi.fn(async (...args: unknown[]) => { record('appFocus')(...args) }),
resume: vi.fn(async (...args: unknown[]) => { record('resume')(...args) }),
receipt: vi.fn(async () => ({ receipt: null })),
+ addon: vi.fn(async (...args: unknown[]) => { record('addon')(...args); return { result: { devices: [] } } }),
stop: vi.fn(async () => { log.push(`${machineId} stop`) }),
}
return port
@@ -242,6 +243,20 @@ describe('the Wi-Fi device in the devices\' process', () => {
expect(f.ports[0].receipt).toHaveBeenCalledWith('d', 'k')
})
+ it('answers the core\'s add-on questions once it is built, and refuses an operation it does not know', async () => {
+ const f = setup()
+ const addon = f.options().requests!.addon
+ expect(await addon({ op: 'state', input: {} }, { local: false, owner: false })).toEqual({ error: 'SERVICE_UNAVAILABLE' })
+ f.connect()
+ f.event({ kind: 'resume' })
+ expect(await addon({ op: 'state', input: { deviceId: 'lamp' } }, { local: false, owner: false })).toEqual({ result: { devices: [] } })
+ expect(f.ports[0].addon).toHaveBeenCalledWith('state', { deviceId: 'lamp' })
+ expect(await addon({ op: 'delete', input: {} }, { local: false, owner: false })).toEqual({ error: { code: 'INVALID_REQUEST', message: 'Unknown add-on operation' } })
+ // What is not an object reaches the port as no input at all.
+ await addon({ op: 'proposal', input: ['p'] }, { local: false, owner: false })
+ expect(f.ports[0].addon).toHaveBeenLastCalledWith('proposal', {})
+ })
+
it('leaves the Wi-Fi device off when its service does not start, and says why', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const f = setup({ startThrows: true })
diff --git a/cli/src/services/wifiProcess.ts b/cli/src/services/wifiProcess.ts
index da284813c..616ad131e 100644
--- a/cli/src/services/wifiProcess.ts
+++ b/cli/src/services/wifiProcess.ts
@@ -9,7 +9,7 @@
* whichever devices the new core's gateway brings.
*/
import type { RecentTurn } from '../cable/cableHost.js'
-import { emptyPorts, type CoreApi, type CorePorts, type ForkResult, type RemoteClient, type WifiPort, type WifiResume, type WifiView } from '../core/api.js'
+import { WIFI_ADDON_OPS, emptyPorts, type CoreApi, type CorePorts, type ForkResult, type RemoteClient, type WifiAddonOp, type WifiPort, type WifiResume, type WifiView } from '../core/api.js'
import type { AutonomousDeviceDelivery } from '../lib/autonomous-device/service.js'
import type { LiveEvent } from '../lib/normalize.js'
import { runServiceProcess, type CoreConnection, type ServiceProcess, type ServiceProcessOptions } from './process.js'
@@ -164,6 +164,13 @@ export function runWifiService(options: WifiServiceOptions): ServiceProcess {
if (!built) return { error: 'SERVICE_UNAVAILABLE' }
return { ...await built.port.receipt(text(deviceId), text(idempotencyKey)) }
},
+ // `harness autonomous-device addon`, asked by the core the same way.
+ addon: async ({ op, input }) => {
+ await heardSoFar
+ if (!built) return { error: 'SERVICE_UNAVAILABLE' }
+ if (!(WIFI_ADDON_OPS as readonly unknown[]).includes(op)) return { error: { code: 'INVALID_REQUEST', message: 'Unknown add-on operation' } }
+ return { ...await built.port.addon(op as WifiAddonOp, input && typeof input === 'object' && !Array.isArray(input) ? input as Record<string, unknown> : {}) }
+ },
},
onEvent: (payload) => {
const kind = text(payload.kind)
diff --git a/docs/autonomous-device-addons.md b/docs/autonomous-device-addons.md
new file mode 100644
index 000000000..50d50db21
--- /dev/null
+++ b/docs/autonomous-device-addons.md
@@ -0,0 +1,186 @@
+# Autonomous device add-ons, v1
+
+An **add-on** is an agent on the paired computer that reads what a device chose to publish about
+itself and proposes what the device might do. The first device is the Autonomous lamp (lampOS): a
+partner's add-on can read summaries such as "someone is at the desk" or the lamp's mood, and suggest a
+warm evening light or a small mood lift. The lamp decides whether to act on it, through its own
+judge, safety limits and output owners. The design on the lamp's side is lampOS
+[`docs/addons.md`](https://github.com/autonomous-ai/lampOS/blob/lamp-voice/lampOS/docs/addons.md).
+
+**Status:** implemented in this checkout (CLI only); not released or deployed. Do not assume a
+running CLI supports it until its hello advertises the capabilities below.
+
+## What Harness does and does not do
+
+- **Carries, bounds and forgets.** Harness keeps the newest value of each published topic in RAM,
+ forwards proposals to the one device they are for, and records the device's decision. It bounds
+ sizes, rates and lifetimes so that one agent cannot flood a device and one device cannot grow the
+ daemon's memory.
+- **Never judges.** Which topics are safe to publish, which acts a device understands and whether a
+ proposal is carried out are the device's policy. A proposal is a suggestion, never a command:
+ nothing here writes to a speaker, light or motor.
+- **Is device-agnostic.** No topic or act is named by Harness. Topic names and act names only have
+ to be well formed.
+- **Adds no transport.** Everything rides the existing direct, end-to-end encrypted device channel
+ of [the device integration](autonomous-device-integration.md): protocol `proto: 1`, the same
+ pairing, identity pins, PAKE and envelopes. No new listener, credential, or pairing flow.
+
+## Capabilities
+
+An authenticated role-device application `hello` advertises two more strings:
+
+```json
+["addon.publish", "addon.decision"]
+```
+
+An older CLI does not list them and answers `UNSUPPORTED_CAPABILITY`. A device offers add-ons by
+publishing after its hello. **A hello clears what the device published before**, and the device
+publishes its whole set again after every hello, so a topic it no longer offers (a person withdrew
+consent) is gone, not left readable. When the Wi-Fi device service restarts under a session the
+gateway kept, no hello comes: the computer sends the `addon.republish` event below, and the device
+publishes its whole set again.
+
+## Device → computer requests
+
+Both are ordinary encrypted application requests: a fresh UUIDv4 `requestId`, unknown fields
+rejected, answered with `<type>_result`. They count against the connection's existing token bucket
+(burst 20, one a second), so a device coalesces its changes into batches.
+
+### `addon.publish`
+
+```json
+{"type":"addon.publish","requestId":"<uuid>","values":[
+ {"topic":"room/presence","value":{"someone":true},"at":1761030000000},
+ {"topic":"mood/state","value":{"energy":0.6,"warmth":0.5}},
+ {"topic":"voice/state","value":null}
+]}
+```
+
+| Field | Rule |
+|---|---|
+| `values` | 1 to 16 entries, taken or refused as one batch |
+| `topic` | two to four lowercase segments, `[a-z][a-z0-9_]*` each, `/` between, at most 96 characters |
+| `value` | a JSON object of at most 4096 bytes serialized; `null` withdraws the topic |
+| `at` | optional, the device's own time of the value in Unix milliseconds, kept as given |
+
+At most 32 topics per device: a batch that would exceed it is refused `BACKPRESSURE`. An oversized
+value is `PAYLOAD_TOO_LARGE`. Success: `{"type":"addon.publish_result","requestId":…,"topics":<count>}`.
+
+Publish **summaries only**. The computer and every agent on it can read what is published; a device
+must never publish transcripts, pictures, audio, faces, names or memory it would not show the person.
+Even summaries say a lot about a person's routine (when someone is at the desk, when the room is
+loud), and here they leave the device. So a device publishes only with its person's yes, and v1
+gives the device no way to tell add-ons apart (below, "Not in v1"): what one agent may read, every
+agent on the computer may read. Per-add-on consent, seen and revoked per add-on, needs that
+identity first.
+
+### `addon.decision`
+
+```json
+{"type":"addon.decision","requestId":"<uuid>","proposalId":"<uuid>","decision":"kept","reason":"evening, someone here"}
+```
+
+`decision` is `kept` or `dropped`; `reason` is optional, 1 to 200 characters without control
+characters. Success: `{"type":"addon.decision_result","requestId":…,"proposalId":…,"state":"kept"}`.
+
+- A proposal sent to another device, unknown, or aged out answers `PROPOSAL_UNKNOWN`. A device
+ learns nothing about another device's proposals.
+- The same decision again answers the same result; a different one answers `IDEMPOTENCY_CONFLICT`.
+- A decision for a proposal that already lapsed here is still recorded: the device's judge decided.
+
+## Computer → device events
+
+`addon.republish`, with an empty payload, asks the device to publish its whole set again (above).
+
+A proposal reaches its device as an encrypted `autonomous_device_event`:
+
+```json
+{"type":"event","serverInstanceId":"<uuid>","machineId":"<machine>","kind":"addon.proposal",
+ "payload":{"proposalId":"<uuid>","addon":"evening-glow","act":"light","why":"evening","sure":0.6,
+ "holdsMs":30000,"params":{"colour":"warm","level":2},"note":"A warm evening light.","expiresAt":1761030030000}}
+```
+
+- It goes to that device's links alone, is **not** in the replay log, and has no `eventId`. A device
+ that is offline when a proposal is made never gets it; a lapsed proposal is never worth replaying.
+- `expiresAt` is the computer's clock (`sentAt + holdsMs`). A device judges with its own clock and
+ may drop a proposal it received late.
+- `addon` is the name the computer gives the agent (below). It is said by the computer, not proven:
+ the device rate-limits and judges every proposal whatever it is called.
+- `act`, `why`, `params` and `note` are the device's vocabulary. A device drops a proposal it does
+ not understand, with a reason.
+
+## Agents on the computer
+
+Agents use the CLI, which calls the credential-checked loopback hook server like the other
+`autonomous-device` commands.
+
+```sh
+harness autonomous-device addon state [--device <id>] [--json]
+harness autonomous-device addon propose --act light --holds-ms 30000 \
+ [--why evening] [--sure 0.6] [--params '{"colour":"warm","level":2}'] [--note '…'] \
+ [--addon evening-glow] [--key <idempotency key>] [--device <id>] [--json]
+harness autonomous-device addon proposal <proposalId> [--json]
+```
+
+| Route | Input / result |
+|---|---|
+| GET `/api/autonomous-device/addon/state[?deviceId=…]` | `{devices:[{deviceId,online,topics:{<topic>:{value,at,receivedAt}}}]}` |
+| POST `/api/autonomous-device/addon/propose` | `{addon,idempotencyKey,act,holdsMs,why?,sure?,params?,note?,deviceId?}` → `{proposal}` |
+| GET `/api/autonomous-device/addon/proposal?proposalId=…` | `{proposal}`; `PROPOSAL_UNKNOWN` (404) for one never sent or aged out |
+
+A proposal record is `{proposalId,deviceId,addon,idempotencyKey,act,why?,sure?,holdsMs,params?,note?,
+state,reason,sentAt,expiresAt,decidedAt}`, with `state` one of `sent`, `kept`, `dropped`, `expired`.
+
+**Proposal rules**
+
+| Field | Rule |
+|---|---|
+| `addon` | `[A-Za-z0-9._:-]{1,64}`. The CLI uses `--addon`, or else the engine of the agent running the shell and a 12-hex hash of how Harness names that outside caller (`claude-1a2b3c4d5e6f`): one name per session, never the session's own id |
+| `idempotencyKey` | `[A-Za-z0-9_-]{1,64}`; the same add-on and key is one proposal. The CLI makes a fresh key per call unless `--key` is given, and prints the key it used when a propose fails |
+| `act`, `why` | `[a-z][a-z0-9_]{0,31}` |
+| `sure` | 0 to 1 |
+| `holdsMs` | 1000 to 30000 |
+| `params` | a JSON object of at most 2048 bytes |
+| `note` | at most 300 bytes, no control characters but newline |
+| `deviceId` | optional when exactly one device that published is connected |
+
+**Limits:** six proposals a minute per add-on and device, and twelve a minute per device whatever the
+add-ons call themselves, since the name is the caller's (`RATE_LIMITED`); four undecided proposals per
+device (`BACKPRESSURE`). A proposal not decided within `holdsMs` becomes `expired`. Settled proposals
+stay readable ten minutes; at most 256 are kept, and a proposal still inside the rate window is never
+dropped to make room: a new one is refused `BACKPRESSURE` instead.
+
+**No answer in time.** The CLI waits 5 seconds for the Wi-Fi device service. A `propose` with no answer
+in time is `OUTCOME_UNKNOWN` (504): it may have been sent. Retry with the same `--key` and it is sent at
+most once. A read with no answer is `UNAVAILABLE` (503).
+
+**Errors** (HTTP status): `INVALID_REQUEST` 400, `PAYLOAD_TOO_LARGE` 413, `DEVICE_NOT_FOUND` 404,
+`PROPOSAL_UNKNOWN` 404, `MISSING_TARGET` 409, `DEVICE_OFFLINE` 409, `IDEMPOTENCY_CONFLICT` 409,
+`RATE_LIMITED` 429, `BACKPRESSURE` 429, `UNAVAILABLE` 503 when the Wi-Fi device service is not running,
+`OUTCOME_UNKNOWN` 504 for a propose with no answer in time.
+
+## Lifetime
+
+- A device's link closing marks it `online: false`: its values stay readable, and nothing is
+ proposed to it until it publishes again.
+- A hello clears what it published; a restored session is asked to publish again.
+- Unpairing (either side) forgets everything it published and every proposal made to it.
+- A daemon restart forgets everything: values, proposals and decisions.
+
+## Implementation and validation
+
+`cli/src/lib/autonomous-device/addons.ts` holds the contract and the bounded state;
+`service.ts` advertises and routes the two requests; `services/wifi.ts`, `core/wifiLink.ts` and
+`services/wifiProcess.ts` carry the agent-facing operation across the service process boundary as
+`harness device receipt` is carried; `lib/deviceManagementHttp.ts` validates the routes;
+`addonCommand.ts` is the CLI. Unit tests cover each layer; `services/wifi.spec.ts` runs the real
+service and relay end to end with a fake core (publish, state, a proposal sealed to that device, its
+decision, unpairing). Not shown: a physical device. No device implements it yet.
+
+## Not in v1
+
+- An MCP tool for agents (`harness mcp`), and a Desktop view of published state.
+- Per-add-on identity proven to the device (for example from a Store package), and revoking one
+ add-on without unpairing.
+- Pushing published changes to agents as they happen; v1 agents read on demand.
+- Reading device memory or context beyond what the device publishes as topics.
diff --git a/docs/autonomous-device-integration.md b/docs/autonomous-device-integration.md
index a61ed8a46..813e5a26e 100644
--- a/docs/autonomous-device-integration.md
+++ b/docs/autonomous-device-integration.md
@@ -4,6 +4,10 @@
Paired robots can negotiate Store discovery and durable agent preparation separately from task delivery. See the [shared OS contract](autonomous-device-store.md), including JSON schemas, recovery rules and the Blender walkthrough. Older clients keep the operations below unchanged.
+## Add-ons (v1)
+
+A paired device can publish summaries of its own state for agents on this computer, and receive their proposals to judge. See [device add-ons](autonomous-device-addons.md). Older clients keep the operations below unchanged.
+
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
diff --git a/docs/cli.md b/docs/cli.md
index 0173cb50f..8350386a0 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -28,6 +28,7 @@ works the same on a headless Linux server; the app is not required on a machine,
| `harness grid env <grid>` | `<grid>`'s relay address and key as shell exports, through the harness's own `grid`: `eval "$(harness grid env <grid>)"` before pointing an OpenAI-compatible client at `$OPENAI_BASE_URL`. |
| `harness flash [flags]` | Re-flash a plugged-in Harness device over USB. Flags pass straight to the flasher. |
| `harness autonomous-device discover\|status\|list\|pair\|revoke` | Pair Autonomous OS devices found on the LAN, directly, with no relay. |
+| `harness autonomous-device addon state\|propose\|proposal` | Read what a paired device publishes, and propose what it might do ([device add-ons](autonomous-device-addons.md)). |
Interactive prompts read one line from stdin with `--stdin`; `--json` switches any of them to NDJSON.