The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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/proposalharness pair <code> pair a BROWSER (code shown on the machine page)harness pairings list paired clientsharness unpair <#|fp> unpair one browser (by list number or fingerprint)diff --git a/cli/src/core/api.ts b/cli/src/core/api.tsindex 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.tsindex 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.tsindex 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 WifiPortlet on: WifiPort | null = portconst clients = new Map<string, RemoteClient>()diff --git a/cli/src/core/wifiLink.spec.ts b/cli/src/core/wifiLink.spec.tsindex 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.tsindex 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 WifiReceiptreturn { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 | undefinedconst flags = new Set<string>()@@ -25,7 +27,7 @@ export async function runAutonomousDeviceCommand(argv: string[], dataDir: stringconst 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.tsindex 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.tsindex 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.tsindex 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 } | undefinedreply({ 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.tsindex 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.nowthis.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.tsindex 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.tsindex 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 ? {} : bodyif (!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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdnew file mode 100644index 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.mdindex 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 isdiff --git a/docs/cli.md b/docs/cli.mdindex 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.