agl 41.2.0 → 42.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/changelog.md +41 -0
  2. package/dist_serve/bundle.js +2625 -2278
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +3 -68
  5. package/dist_serve/bundle.js.third-party-notices.txt +4 -137
  6. package/dist_ts/00_commitinfo_data.js +1 -1
  7. package/dist_ts/aglapi/aglapisurface.document.js +4 -4
  8. package/dist_ts/classes.authmodels.d.ts +2 -8
  9. package/dist_ts/classes.authmodels.js +60 -23
  10. package/dist_ts/classes.authstore.d.ts +24 -0
  11. package/dist_ts/classes.authstore.js +185 -23
  12. package/dist_ts/classes.cli.d.ts +3 -6
  13. package/dist_ts/classes.cli.js +38 -51
  14. package/dist_ts/classes.config.d.ts +17 -3
  15. package/dist_ts/classes.config.js +55 -18
  16. package/dist_ts/classes.controller.d.ts +83 -14
  17. package/dist_ts/classes.controller.js +545 -229
  18. package/dist_ts/classes.controllerdevices.d.ts +128 -0
  19. package/dist_ts/classes.controllerdevices.js +472 -0
  20. package/dist_ts/classes.controllermanagement.d.ts +42 -9
  21. package/dist_ts/classes.controllermanagement.js +72 -23
  22. package/dist_ts/classes.controllerservice.d.ts +3 -31
  23. package/dist_ts/classes.controllerservice.js +3 -47
  24. package/dist_ts/classes.mcpcontrollerhost.js +9 -3
  25. package/dist_ts/classes.processinspection.d.ts +8 -1
  26. package/dist_ts/classes.processinspection.js +92 -2
  27. package/dist_ts/classes.proxycontrol.js +6 -1
  28. package/dist_ts/classes.proxydaemon.d.ts +2 -2
  29. package/dist_ts/classes.proxydaemon.js +1 -1
  30. package/dist_ts/classes.proxystore.d.ts +2 -11
  31. package/dist_ts/classes.proxystore.js +3 -25
  32. package/dist_ts/classes.sessionfeed.d.ts +10 -1
  33. package/dist_ts/classes.sessionfeed.js +12 -2
  34. package/dist_ts/classes.tpmsecretcodec.d.ts +13 -0
  35. package/dist_ts/classes.tpmsecretcodec.js +28 -0
  36. package/dist_ts/classes.trustedproxysecrets.d.ts +91 -0
  37. package/dist_ts/classes.trustedproxysecrets.js +338 -0
  38. package/dist_ts/classes.upgradecoordinator.d.ts +14 -1
  39. package/dist_ts/classes.upgradecoordinator.js +21 -3
  40. package/dist_ts/classes.upgradetransaction.d.ts +32 -0
  41. package/dist_ts/classes.upgradetransaction.js +101 -4
  42. package/dist_ts/classes.validation.d.ts +2 -0
  43. package/dist_ts/classes.validation.js +2 -2
  44. package/dist_ts/functions.controlleradmission.d.ts +67 -0
  45. package/dist_ts/functions.controlleradmission.js +127 -0
  46. package/dist_ts/functions.deviceapi.d.ts +28 -0
  47. package/dist_ts/functions.deviceapi.js +246 -0
  48. package/dist_ts/functions.deviceproof.d.ts +33 -0
  49. package/dist_ts/functions.deviceproof.js +93 -0
  50. package/dist_ts/functions.remotecli.d.ts +27 -0
  51. package/dist_ts/functions.remotecli.js +241 -0
  52. package/dist_ts/functions.retiredenvironment.d.ts +11 -2
  53. package/dist_ts/functions.retiredenvironment.js +22 -5
  54. package/dist_ts/index.d.ts +1 -0
  55. package/dist_ts/index.js +2 -1
  56. package/dist_ts/interfaces.auth.d.ts +29 -4
  57. package/dist_ts/interfaces.auth.js +10 -1
  58. package/dist_ts/interfaces.config.d.ts +14 -0
  59. package/dist_ts/interfaces.config.js +9 -2
  60. package/dist_ts/interfaces.lifecycle.d.ts +3 -0
  61. package/dist_ts_authswitch/classes.authoritydaemon.js +6 -1
  62. package/dist_ts_interfaces/devices.d.ts +331 -0
  63. package/dist_ts_interfaces/devices.js +34 -0
  64. package/dist_ts_interfaces/index.d.ts +2 -0
  65. package/dist_ts_interfaces/index.js +3 -1
  66. package/dist_ts_interfaces/interfaces.d.ts +5 -3
  67. package/dist_ts_interfaces/interfaces.js +3 -2
  68. package/dist_ts_interfaces/management.d.ts +2 -2
  69. package/dist_ts_interfaces/management.js +2 -2
  70. package/dist_ts_interfaces/mcprequests.d.ts +1 -1
  71. package/dist_ts_interfaces/requests.d.ts +2 -2
  72. package/dist_ts_interfaces/requests.devices.d.ts +89 -0
  73. package/dist_ts_interfaces/requests.devices.js +2 -0
  74. package/dist_ts_interfaces/requests.upgrade.d.ts +0 -12
  75. package/package.json +12 -11
  76. package/readme.md +116 -24
  77. package/ts/00_commitinfo_data.ts +1 -1
  78. package/ts/aglapi/aglapisurface.document.ts +3 -3
  79. package/ts/classes.authmodels.ts +68 -25
  80. package/ts/classes.authstore.ts +183 -24
  81. package/ts/classes.cli.ts +38 -61
  82. package/ts/classes.config.ts +70 -21
  83. package/ts/classes.controller.ts +746 -329
  84. package/ts/classes.controllerdevices.ts +469 -0
  85. package/ts/classes.controllermanagement.ts +123 -49
  86. package/ts/classes.controllerservice.ts +3 -56
  87. package/ts/classes.mcpcontrollerhost.ts +10 -5
  88. package/ts/classes.processinspection.ts +84 -3
  89. package/ts/classes.proxycontrol.ts +2 -0
  90. package/ts/classes.proxydaemon.ts +3 -2
  91. package/ts/classes.proxystore.ts +4 -25
  92. package/ts/classes.sessionfeed.ts +13 -1
  93. package/ts/classes.tpmsecretcodec.ts +26 -0
  94. package/ts/classes.trustedproxysecrets.ts +317 -0
  95. package/ts/classes.upgradecoordinator.ts +33 -3
  96. package/ts/classes.upgradetransaction.ts +130 -1
  97. package/ts/classes.validation.ts +1 -1
  98. package/ts/functions.controlleradmission.ts +168 -0
  99. package/ts/functions.deviceapi.ts +295 -0
  100. package/ts/functions.deviceproof.ts +118 -0
  101. package/ts/functions.remotecli.ts +270 -0
  102. package/ts/functions.retiredenvironment.ts +25 -3
  103. package/ts/index.ts +1 -0
  104. package/ts/interfaces.auth.ts +41 -3
  105. package/ts/interfaces.config.ts +15 -0
  106. package/ts/interfaces.lifecycle.ts +3 -0
  107. package/ts_authswitch/classes.authoritydaemon.ts +2 -0
  108. package/ts_interfaces/devices.schema.json +890 -0
  109. package/ts_interfaces/devices.ts +392 -0
  110. package/ts_interfaces/index.ts +2 -0
  111. package/ts_interfaces/interfaces.ts +5 -2
  112. package/ts_interfaces/management.ts +2 -2
  113. package/ts_interfaces/mcprequests.ts +1 -1
  114. package/ts_interfaces/requests.devices.ts +95 -0
  115. package/ts_interfaces/requests.ts +10 -10
  116. package/ts_interfaces/requests.upgrade.ts +0 -16
  117. package/ts_web/00_commitinfo_data.ts +1 -1
  118. package/ts_web/classes.controllersocketclient.ts +27 -0
  119. package/ts_web/elements.devices.ts +752 -0
  120. package/ts_web/elements.harnesscontrollerapp.ts +18 -1
@@ -0,0 +1,392 @@
1
+ /*
2
+ * The device protocol (AGL-824): what a paired phone or desktop app and AGL say to each other over the controller's
3
+ * socket. The file is a leaf on purpose: it imports nothing but typedrequest-interfaces' types, so an app generates its
4
+ * client from this file alone (`swiftsupport generate`), and `ts_interfaces/devices.schema.json` is the same contracts
5
+ * as JSON Schema for other generators (`pnpm exec tsrepo run scripts/devicesschema.ts` writes it;
6
+ * `test/test.devicecontracts.node.ts` fails while it differs).
7
+ *
8
+ * A device speaks one major of the protocol (`device.hello`); within a major, changes only add. Binary values are
9
+ * base64url without padding. The two signed messages are fields, each a 4-byte big-endian length and its bytes:
10
+ *
11
+ * - pairing: `"agl-device-pair"`, the controller id, the public origin, SHA-256 of the 32 code bytes, the public key;
12
+ * - authentication: `"agl-device-auth"`, the controller id, the public origin, the 32 nonce bytes, the public key.
13
+ *
14
+ * Strings are UTF-8; the origin is the controller's public origin exactly (`https://host`, a port only when it is not
15
+ * 443); the public key is a P-256 SubjectPublicKeyInfo in DER; a signature is ECDSA P-256 with SHA-256 in DER (X9.62).
16
+ */
17
+ import type { ITypedRequest, implementsTR } from '@api.global/typedrequest-interfaces';
18
+
19
+ /** The device protocol this controller speaks. */
20
+ export const deviceProtocolVersion = { major: 1, minor: 0 } as const;
21
+
22
+ /** The scheme of a pairing payload: `agl-pair:?origin=<https origin>&controller=<controller id>&code=<base64url>`. */
23
+ export const devicePairingScheme = 'agl-pair' as const;
24
+ /** The first field of the message a device signs to pair. */
25
+ export const devicePairingMessageLabel = 'agl-device-pair' as const;
26
+ /** The first field of the message a device signs to authenticate a connection. */
27
+ export const deviceAuthenticationMessageLabel = 'agl-device-auth' as const;
28
+ /** The size of a pairing code and of an authentication nonce. */
29
+ export const deviceSecretBytes = 32;
30
+ /** A pairing code is valid this long after it was made, and once. */
31
+ export const devicePairingLifetimeMs = 5 * 60 * 1000;
32
+ /** A nonce is valid this long after it was handed out, and once, on its own connection. */
33
+ export const deviceChallengeLifetimeMs = 60 * 1000;
34
+ /** At most this many pairing codes wait at once. */
35
+ export const maximumPendingDevicePairings = 4;
36
+ /** At most this many devices are paired with a controller. */
37
+ export const maximumDevices = 16;
38
+ /** The longest device name and hardware model, in characters. */
39
+ export const deviceLabelMaximumCharacters = 64;
40
+ /** The longest message a device sends, in UTF-8 bytes. */
41
+ export const deviceMessageMaximumBytes = 64 * 1024;
42
+ /** The close code of every live connection of a device the owner revoked. */
43
+ export const deviceRevokedCloseCode = 4403;
44
+
45
+ /**
46
+ * Why AGL refused a device request, as `error.data.code`:
47
+ * `device_unknown`: no such device is paired (any more): forget the pairing;
48
+ * `device_pairing_invalid`: the code is unknown, used or expired;
49
+ * `device_pairing_unavailable`: the controller has no public origin, so nothing can pair with it;
50
+ * `device_limit`: the controller holds its maximum of devices;
51
+ * `device_already_paired`: this key is paired already;
52
+ * `device_proof_invalid`: the signature does not verify;
53
+ * `device_challenge_invalid`: no live nonce of this connection for this device;
54
+ * `device_authentication_required`: the connection is not authenticated as a device;
55
+ * `session_not_found`: the session feed lists no such session;
56
+ * `session_read_only`: AGL does not write to the session (another process runs it, a fleet worker owns it);
57
+ * `rate_limited`, `invalid_request`, `controller_unavailable` and `operation_limit` as for any client.
58
+ * In this device protocol version (1.0) AGL sends no retry hint with a refusal (no `retry` beside the error, no retry
59
+ * timing in `error.data`), and `rate_limited` is final: a client never resends the refused request on its own; it shows
60
+ * the refusal, and the user may try again.
61
+ */
62
+ export type TDeviceRefusalCode =
63
+ | 'device_unknown'
64
+ | 'device_pairing_invalid'
65
+ | 'device_pairing_unavailable'
66
+ | 'device_limit'
67
+ | 'device_already_paired'
68
+ | 'device_proof_invalid'
69
+ | 'device_challenge_invalid'
70
+ | 'device_authentication_required'
71
+ | 'session_not_found'
72
+ | 'session_read_only';
73
+
74
+ /** The harness a session runs on. */
75
+ export type TDeviceHarness = 'claude' | 'codex' | 'flex' | 'opencode';
76
+
77
+ /** `needs_input`: a question or permission waits for the owner. */
78
+ export type TDeviceSessionState = 'needs_input' | 'working' | 'completed' | 'failed';
79
+
80
+ /** One session of the feed as a device sees it: the browser feed row without where it opens (no host paths, no tickets). */
81
+ export interface IDeviceSessionRow {
82
+ /** `${harness}:${nativeId}`, the feed's row id; the device names a session only by it. */
83
+ id: string;
84
+ harness: TDeviceHarness;
85
+ state: TDeviceSessionState;
86
+ name: string;
87
+ /** The tail of the newest assistant text. */
88
+ excerpt?: string;
89
+ /**
90
+ * Unix milliseconds of the session's last activity.
91
+ * @asType integer
92
+ */
93
+ updatedAt: number;
94
+ }
95
+
96
+ /** A feed change: apply it on the same epoch at the revision after the held one; on `reset` or any gap, list again. */
97
+ export interface IDeviceSessionFeedDelta {
98
+ epoch: string;
99
+ /** @asType integer */
100
+ revision: number;
101
+ reset: boolean;
102
+ upserts: IDeviceSessionRow[];
103
+ removed: string[];
104
+ }
105
+
106
+ export type TDeviceMessageRole = 'user' | 'assistant';
107
+
108
+ /** `stopped`: the turn ended before the call finished. */
109
+ export type TDeviceToolStatus = 'pending' | 'running' | 'completed' | 'error' | 'stopped';
110
+
111
+ export interface IDeviceTextPart {
112
+ type: 'text';
113
+ id: string;
114
+ text: string;
115
+ }
116
+
117
+ export interface IDeviceReasoningPart {
118
+ type: 'reasoning';
119
+ id: string;
120
+ text: string;
121
+ }
122
+
123
+ /** A tool call, reduced to its name, title and status: no input, no output. */
124
+ export interface IDeviceToolPart {
125
+ type: 'tool';
126
+ id: string;
127
+ tool: string;
128
+ title?: string;
129
+ status: TDeviceToolStatus;
130
+ }
131
+
132
+ export type TDeviceMessagePart = IDeviceTextPart | IDeviceReasoningPart | IDeviceToolPart;
133
+
134
+ export interface IDeviceMessage {
135
+ id: string;
136
+ role: TDeviceMessageRole;
137
+ /** @asType integer */
138
+ createdAt: number;
139
+ parts: TDeviceMessagePart[];
140
+ }
141
+
142
+ /** A permission the session waits for. */
143
+ export interface IDevicePermission {
144
+ id: string;
145
+ title: string;
146
+ type: string;
147
+ patterns: string[];
148
+ }
149
+
150
+ export interface IDeviceQuestionOption {
151
+ label: string;
152
+ description: string;
153
+ }
154
+
155
+ export interface IDeviceQuestionItem {
156
+ question: string;
157
+ header: string;
158
+ options: IDeviceQuestionOption[];
159
+ multiple?: boolean;
160
+ /** A free-text answer is accepted besides the options. */
161
+ custom?: boolean;
162
+ }
163
+
164
+ /** A question the session waits for; it is never answered automatically. */
165
+ export interface IDeviceQuestion {
166
+ id: string;
167
+ questions: IDeviceQuestionItem[];
168
+ }
169
+
170
+ /** A live snapshot of an assistant text part while it streams: it replaces the part's text. */
171
+ export interface IDeviceTextUpdate {
172
+ sessionId: string;
173
+ messageId: string;
174
+ partId: string;
175
+ text: string;
176
+ }
177
+
178
+ /**
179
+ * Text appended to an assistant text part while it streams. Apply it only when the part's text held now is
180
+ * `baseTextUtf8Bytes` long in UTF-8, which makes it `textUtf8Bytes` long; otherwise read the session again.
181
+ */
182
+ export interface IDeviceTextDelta {
183
+ sessionId: string;
184
+ messageId: string;
185
+ partId: string;
186
+ delta: string;
187
+ /** @asType integer */
188
+ baseTextUtf8Bytes: number;
189
+ /** @asType integer */
190
+ textUtf8Bytes: number;
191
+ }
192
+
193
+ export interface IDeviceSessionFeedChangedEvent {
194
+ type: 'sessionfeed.changed';
195
+ delta: IDeviceSessionFeedDelta;
196
+ }
197
+
198
+ /** The session's transcript, state or pending prompts changed: read it again. */
199
+ export interface IDeviceSessionChangedEvent {
200
+ type: 'session.changed';
201
+ sessionId: string;
202
+ }
203
+
204
+ export interface IDeviceSessionTextUpdatedEvent {
205
+ type: 'session.text.updated';
206
+ update: IDeviceTextUpdate;
207
+ }
208
+
209
+ export interface IDeviceSessionTextDeltaEvent {
210
+ type: 'session.text.delta';
211
+ delta: IDeviceTextDelta;
212
+ }
213
+
214
+ /** Changes reached this device only in part: list the feed and read the open session again. */
215
+ export interface IDeviceSessionsChangedEvent {
216
+ type: 'sessions.changed';
217
+ }
218
+
219
+ /** The events a device receives: an allowlist, each in a reduced shape. */
220
+ export type TDeviceEvent =
221
+ | IDeviceSessionFeedChangedEvent
222
+ | IDeviceSessionChangedEvent
223
+ | IDeviceSessionTextUpdatedEvent
224
+ | IDeviceSessionTextDeltaEvent
225
+ | IDeviceSessionsChangedEvent;
226
+
227
+ /**
228
+ * The device protocol of this controller. A device speaks one major; minors only add. Unauthenticated
229
+ * (scope `devicePairing`).
230
+ */
231
+ export interface IReq_DeviceHello extends implementsTR<ITypedRequest, IReq_DeviceHello> {
232
+ method: 'device.hello';
233
+ request: {};
234
+ response: {
235
+ /** @asType integer */
236
+ major: number;
237
+ /** @asType integer */
238
+ minor: number;
239
+ };
240
+ }
241
+
242
+ /**
243
+ * Pairs a device with the single-use code of the QR. `proof` is the device key's signature over the pairing message
244
+ * (label `agl-device-pair`, controller id, origin, SHA-256 of the code bytes, public key). Refused while the controller
245
+ * has no public origin. Unauthenticated (scope `devicePairing`).
246
+ */
247
+ export interface IReq_DevicePair extends implementsTR<ITypedRequest, IReq_DevicePair> {
248
+ method: 'device.pair';
249
+ request: {
250
+ /** The QR's code: base64url (no padding) of 32 bytes. */
251
+ code: string;
252
+ /** The device's name, at most 64 characters. */
253
+ name: string;
254
+ /** The hardware model, at most 64 characters. */
255
+ model: string;
256
+ /** The P-256 public key: SubjectPublicKeyInfo DER, base64url. */
257
+ publicKey: string;
258
+ /** ECDSA P-256 with SHA-256, DER (X9.62), base64url. */
259
+ proof: string;
260
+ };
261
+ response: {
262
+ deviceId: string;
263
+ /** The name AGL keeps for the device. */
264
+ name: string;
265
+ };
266
+ }
267
+
268
+ /**
269
+ * A fresh nonce bound to this connection, single use, valid 60 s; a newer one replaces it. A device that is not paired
270
+ * (any more) is refused with `device_unknown`. Unauthenticated (scope `devicePairing`).
271
+ */
272
+ export interface IReq_DeviceAuthChallenge extends implementsTR<ITypedRequest, IReq_DeviceAuthChallenge> {
273
+ method: 'device.auth.challenge';
274
+ request: { deviceId: string };
275
+ response: {
276
+ /** base64url (no padding) of 32 bytes. */
277
+ nonce: string;
278
+ };
279
+ }
280
+
281
+ /**
282
+ * Authenticates this connection as the device: `signature` is the device key's signature over the authentication
283
+ * message (label `agl-device-auth`, controller id, origin, nonce bytes, public key). Unauthenticated (scope
284
+ * `devicePairing`); a device that is not paired (any more) is refused with `device_unknown`.
285
+ */
286
+ export interface IReq_DeviceAuthProve extends implementsTR<ITypedRequest, IReq_DeviceAuthProve> {
287
+ method: 'device.auth.prove';
288
+ request: {
289
+ deviceId: string;
290
+ /** ECDSA P-256 with SHA-256, DER (X9.62), base64url. */
291
+ signature: string;
292
+ };
293
+ response: {
294
+ /** The name AGL keeps for the device. */
295
+ name: string;
296
+ };
297
+ }
298
+
299
+ /** The session feed, newest first, without terminal rows. Scope `device`. */
300
+ export interface IReq_DeviceSessionsList extends implementsTR<ITypedRequest, IReq_DeviceSessionsList> {
301
+ method: 'device.sessions.list';
302
+ request: {};
303
+ response: {
304
+ epoch: string;
305
+ /** @asType integer */
306
+ revision: number;
307
+ rows: IDeviceSessionRow[];
308
+ };
309
+ }
310
+
311
+ /**
312
+ * A bounded page of one session's transcript, oldest first, and what the session waits for now (on every page). Scope
313
+ * `device`. A read without `before` returns the newest page, sized by the controller's own bound whatever `limit`
314
+ * says; a read with `before` returns the next older page of `limit` messages.
315
+ */
316
+ export interface IReq_DeviceSessionRead extends implementsTR<ITypedRequest, IReq_DeviceSessionRead> {
317
+ method: 'device.session.read';
318
+ request: {
319
+ sessionId: string;
320
+ /** The `before` cursor of a newer page; absent for the newest page. */
321
+ before?: string;
322
+ /**
323
+ * Messages of an older page (a read with `before`), 1 to 50 (default 20). The newest page ignores it and holds what
324
+ * the controller's own bound allows; the value is still validated.
325
+ * @asType integer
326
+ */
327
+ limit?: number;
328
+ };
329
+ response: {
330
+ session: IDeviceSessionRow;
331
+ messages: IDeviceMessage[];
332
+ /** The cursor of the next older page; `null` at the first message. */
333
+ before: string | null;
334
+ permissions: IDevicePermission[];
335
+ questions: IDeviceQuestion[];
336
+ };
337
+ }
338
+
339
+ /**
340
+ * Sends text to a session as a direct message (never the browser's shared draft); it queues behind a running turn. A
341
+ * session AGL does not write to (another process runs it, a fleet worker owns it) refuses it. Scope `device`.
342
+ */
343
+ export interface IReq_DeviceSessionSend extends implementsTR<ITypedRequest, IReq_DeviceSessionSend> {
344
+ method: 'device.session.send';
345
+ request: {
346
+ sessionId: string;
347
+ /** At most 64 KiB of UTF-8, not blank. */
348
+ text: string;
349
+ };
350
+ response: { accepted: true };
351
+ }
352
+
353
+ /** Answers a permission. Scope `device`. */
354
+ export interface IReq_DevicePermissionReply extends implementsTR<ITypedRequest, IReq_DevicePermissionReply> {
355
+ method: 'device.permission.reply';
356
+ request: {
357
+ sessionId: string;
358
+ permissionId: string;
359
+ reply: 'once' | 'reject';
360
+ /** Sent along with the answer where the harness takes one (OpenCode). */
361
+ message?: string;
362
+ };
363
+ response: { success: boolean };
364
+ }
365
+
366
+ /** Answers a question: one answer list per question, in order; `null` rejects it. Scope `device`. */
367
+ export interface IReq_DeviceQuestionReply extends implementsTR<ITypedRequest, IReq_DeviceQuestionReply> {
368
+ method: 'device.question.reply';
369
+ request: {
370
+ sessionId: string;
371
+ questionId: string;
372
+ answers: string[][] | null;
373
+ };
374
+ response: { success: boolean };
375
+ }
376
+
377
+ /** An event, sent by the controller to an authenticated device connection. */
378
+ export interface IReq_DeviceEventPush extends implementsTR<ITypedRequest, IReq_DeviceEventPush> {
379
+ method: 'device.event';
380
+ request: { event: TDeviceEvent };
381
+ response: {};
382
+ }
383
+
384
+ /** Every device method, by the scope that admits it. */
385
+ export const devicePairingMethods = ['device.hello', 'device.pair', 'device.auth.challenge', 'device.auth.prove'] as const;
386
+ export const deviceMethods = [
387
+ 'device.sessions.list',
388
+ 'device.session.read',
389
+ 'device.session.send',
390
+ 'device.permission.reply',
391
+ 'device.question.reply',
392
+ ] as const;
@@ -31,3 +31,5 @@ export * from './requests.driver.js';
31
31
  export * from './sessionfeed.js';
32
32
  export * from './nativesessions.js';
33
33
  export * from './metrics.js';
34
+ export * from './devices.js';
35
+ export * from './requests.devices.js';
@@ -5,7 +5,7 @@ import type {
5
5
  TControllerBrowserPaintAvailability,
6
6
  TControllerBrowserPaintTermination,
7
7
  } from './browserpaint.js';
8
- export const controllerProtocolVersion = 47 as const;
8
+ export const controllerProtocolVersion = 49 as const;
9
9
  export const controllerUpgradeManagementVersion = 2 as const;
10
10
  export const controllerPackageName = 'agl' as const;
11
11
  /** The systemd user unit `agl service install` writes; a controller it runs reports it in its status. */
@@ -327,7 +327,7 @@ export interface IControllerStatus {
327
327
  upgradeManagementVersion: number;
328
328
  /**
329
329
  * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent
330
- * from a controller older than the endpoint, which is reached over its socket.
330
+ * from a controller older than the endpoint, which this release refuses to manage.
331
331
  */
332
332
  managementProtocolVersion?: number;
333
333
  controllerPid: number;
@@ -1778,6 +1778,7 @@ export const controllerEventTypes = [
1778
1778
  'directreports.changed',
1779
1779
  'sessionfeed.changed',
1780
1780
  'usage.changed',
1781
+ 'devices.changed',
1781
1782
  ] as const;
1782
1783
  export type TControllerEventType = (typeof controllerEventTypes)[number];
1783
1784
 
@@ -1820,5 +1821,7 @@ export interface IControllerEvent {
1820
1821
  sessionFeed?: import('./sessionfeed.js').TControllerSessionFeedDelta;
1821
1822
  /** Present only on a usage.changed event, sent only to the browser that watches the window. */
1822
1823
  usageDelta?: import('./metrics.js').TControllerUsageDelta;
1824
+ /** Present only on the devices.changed event of a pairing: the code the device used, and the device. */
1825
+ devicePairing?: import('./requests.devices.js').IControllerDevicePairingOutcome;
1823
1826
  timestamp: number;
1824
1827
  }
@@ -20,8 +20,8 @@ export const controllerManagementTypedRequestPath = '/management/typedrequest' a
20
20
  * shapes. 1 is the endpoint as its first release ships it; only an incompatible change to that contract raises it.
21
21
  * A release declares it twice: as `controllerManagementProtocolVersion` in its `package.json`, which a client reads
22
22
  * before the release's controller runs, and as `managementProtocolVersion` in that controller's status. A client
23
- * reaches a controller over this endpoint only when it declares 1 or more, and over the controller socket otherwise
24
- * (an older release has no endpoint).
23
+ * manages a controller over this endpoint only when it declares 1 or more; since AGL 42 a client refuses one that
24
+ * declares none (an older release has no endpoint, and its socket speaks TypedSocket 8).
25
25
  *
26
26
  * It is not `controllerUpgradeManagementVersion` (2), the upgrade contract: every upgrade worker requires exactly
27
27
  * that number in its target's `package.json` and status, and upgrade transactions record it, so it cannot move
@@ -66,7 +66,7 @@ export const controllerMcpMethods = [
66
66
  ] as const;
67
67
  export type TControllerMcpMethod = (typeof controllerMcpMethods)[number];
68
68
 
69
- export type TControllerOperationPrincipal = 'browser' | 'mcp';
69
+ export type TControllerOperationPrincipal = 'browser' | 'mcp' | 'device';
70
70
 
71
71
  /** JSON kind of one top-level field in a private MCP response. */
72
72
  export type TControllerMcpFieldKind = 'record' | 'array' | 'string' | 'number' | 'boolean' | 'record-or-false';
@@ -0,0 +1,95 @@
1
+ import type * as plugins from './plugins.js';
2
+
3
+ /**
4
+ * The owner's side of the paired devices (AGL-824): Settings → Devices lists them, makes the single-use pairing code a
5
+ * phone scans, and revokes a device. The device's own protocol is `devices.ts`.
6
+ */
7
+
8
+ /** A paired device as the owner sees it. */
9
+ export interface IControllerDevice {
10
+ id: string;
11
+ /** The name the device gave itself when it paired. */
12
+ name: string;
13
+ /** The hardware model the device named. */
14
+ model: string;
15
+ /**
16
+ * The device key's fingerprint, as the device shows it: SHA-256 of the public key, the first 16 bytes as eight groups
17
+ * of four uppercase hex digits.
18
+ */
19
+ fingerprint: string;
20
+ /** Unix milliseconds. */
21
+ pairedAt: number;
22
+ /** Unix milliseconds of the device's last authenticated connection, kept to about five minutes. */
23
+ lastSeenAt?: number;
24
+ /** A connection of the device is authenticated now. */
25
+ connected: boolean;
26
+ }
27
+
28
+ /**
29
+ * Whether a new device can pair now: `publicOriginRequired` while the controller is reachable only on this machine
30
+ * (local mode), since a phone reaches it only through its public HTTPS origin; `deviceLimit` while it holds its maximum
31
+ * of devices.
32
+ */
33
+ export type TControllerDevicePairingAvailability =
34
+ | { available: true }
35
+ | { available: false; reason: 'publicOriginRequired' | 'deviceLimit' };
36
+
37
+ export interface IReq_ControllerDevicesList extends plugins.typedrequestInterfaces.implementsTR<
38
+ plugins.typedrequestInterfaces.ITypedRequest,
39
+ IReq_ControllerDevicesList
40
+ > {
41
+ method: 'controller.devices.list';
42
+ request: Record<string, never>;
43
+ /** Devices newest paired first. */
44
+ response: { devices: IControllerDevice[]; pairing: TControllerDevicePairingAvailability };
45
+ }
46
+
47
+ /**
48
+ * Makes a single-use pairing code, valid five minutes. Refused in local mode (`device_pairing_unavailable`), at the
49
+ * device limit (`device_limit`) and while four codes wait already (`device_pairing_limit`). The payload is what the QR
50
+ * code carries.
51
+ */
52
+ export interface IReq_ControllerDevicesPairingBegin extends plugins.typedrequestInterfaces.implementsTR<
53
+ plugins.typedrequestInterfaces.ITypedRequest,
54
+ IReq_ControllerDevicesPairingBegin
55
+ > {
56
+ method: 'controller.devices.pairing.begin';
57
+ request: Record<string, never>;
58
+ response: {
59
+ /** Names this code in `devices.changed` once a device paired with it; it is no secret. */
60
+ pairingId: string;
61
+ /** `agl-pair:?origin=<https origin>&controller=<controller id>&code=<base64url>`: a secret until it is used. */
62
+ payload: string;
63
+ /** Unix milliseconds. */
64
+ expiresAt: number;
65
+ };
66
+ }
67
+
68
+ /** Withdraws a pairing code nobody used yet; one that is gone already changes nothing. */
69
+ export interface IReq_ControllerDevicesPairingCancel extends plugins.typedrequestInterfaces.implementsTR<
70
+ plugins.typedrequestInterfaces.ITypedRequest,
71
+ IReq_ControllerDevicesPairingCancel
72
+ > {
73
+ method: 'controller.devices.pairing.cancel';
74
+ request: { pairingId: string };
75
+ response: { cancelled: boolean };
76
+ }
77
+
78
+ /**
79
+ * Revokes a device: its record is deleted and every live connection of it is closed with 4403 at once. A device that is
80
+ * gone already answers `revoked: false`.
81
+ */
82
+ export interface IReq_ControllerDevicesRevoke extends plugins.typedrequestInterfaces.implementsTR<
83
+ plugins.typedrequestInterfaces.ITypedRequest,
84
+ IReq_ControllerDevicesRevoke
85
+ > {
86
+ method: 'controller.devices.revoke';
87
+ request: { deviceId: string };
88
+ response: { revoked: boolean };
89
+ }
90
+
91
+ /** Carried by the `devices.changed` a pairing causes: which code the device used, and the device. */
92
+ export interface IControllerDevicePairingOutcome {
93
+ pairingId: string;
94
+ device: IControllerDevice;
95
+ }
@@ -46,12 +46,6 @@ import type {
46
46
  IReq_ControllerAccountsCodexRelease,
47
47
  } from './requests.accounts.js';
48
48
  import type { IReq_ControllerOpenCodeRestart, IReq_ControllerProxyStatusGet, IReq_ControllerRestart, IReq_ControllerStatus } from './requests.status.js';
49
- import type {
50
- IReq_ControllerUpgradeLaunch,
51
- IReq_ControllerUpgradePrepare,
52
- IReq_ControllerUpgradePrepareBegin,
53
- IReq_ControllerUpgradeFinalize,
54
- } from './requests.upgrade.js';
55
49
  import type {
56
50
  IReq_ControllerDriverGet,
57
51
  IReq_ControllerDriverEnsure,
@@ -203,6 +197,12 @@ import type {
203
197
  IReq_ControllerWorkspaceUnwatch,
204
198
  IReq_ControllerWorkspaceBaseSet,
205
199
  } from './requests.workspace.js';
200
+ import type {
201
+ IReq_ControllerDevicesList,
202
+ IReq_ControllerDevicesPairingBegin,
203
+ IReq_ControllerDevicesPairingCancel,
204
+ IReq_ControllerDevicesRevoke,
205
+ } from './requests.devices.js';
206
206
  import type {
207
207
  IReq_ControllerTerminalOutput,
208
208
  IReq_ControllerTerminalDetached,
@@ -253,10 +253,6 @@ export type TControllerRequest =
253
253
  | IReq_ControllerProxyStatusGet
254
254
  | IReq_ControllerOpenCodeRestart
255
255
  | IReq_ControllerRestart
256
- | IReq_ControllerUpgradeLaunch
257
- | IReq_ControllerUpgradePrepare
258
- | IReq_ControllerUpgradePrepareBegin
259
- | IReq_ControllerUpgradeFinalize
260
256
  | IReq_ControllerDriverGet
261
257
  | IReq_ControllerDriverEnsure
262
258
  | IReq_ControllerDriverSeen
@@ -424,6 +420,10 @@ export type TControllerRequest =
424
420
  | IReq_ControllerCodexAccountUse
425
421
  | IReq_ControllerAccountsCodexRelease
426
422
  | IReq_ControllerAccountsCodexAdopt
423
+ | IReq_ControllerDevicesList
424
+ | IReq_ControllerDevicesPairingBegin
425
+ | IReq_ControllerDevicesPairingCancel
426
+ | IReq_ControllerDevicesRevoke
427
427
  | import('./requests.tickets.js').TControllerTicketTypedRequest
428
428
  | IReq_ControllerEvent
429
429
  | IReq_ControllerSessionChildEvent;
@@ -16,22 +16,6 @@ export interface IReq_ControllerUpgradeLaunch extends plugins.typedrequestInterf
16
16
  };
17
17
  }
18
18
 
19
- export interface IReq_ControllerUpgradePrepare extends plugins.typedrequestInterfaces.implementsTR<
20
- plugins.typedrequestInterfaces.ITypedRequest,
21
- IReq_ControllerUpgradePrepare
22
- > {
23
- method: 'controller.upgrade.prepare';
24
- request: {
25
- token: string;
26
- targetVersion: string;
27
- gracePeriodMs: number;
28
- };
29
- response: {
30
- prepared: true;
31
- sessionCount: number;
32
- };
33
- }
34
-
35
19
  export interface IReq_ControllerUpgradePrepareBegin extends plugins.typedrequestInterfaces.implementsTR<
36
20
  plugins.typedrequestInterfaces.ITypedRequest,
37
21
  IReq_ControllerUpgradePrepareBegin
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '41.2.0',
6
+ version: '42.1.0',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }
@@ -663,6 +663,30 @@ export const isControllerUsageWatch = (
663
663
  && candidate.buckets.every((bucketArg) => isControllerUsageBucket(bucketArg) && bucketArg.span === span);
664
664
  };
665
665
 
666
+ const deviceKeys: ReadonlySet<string> = new Set(['id', 'name', 'model', 'fingerprint', 'pairedAt', 'lastSeenAt', 'connected']);
667
+
668
+ /** A paired device as the controller lists it. */
669
+ export const isControllerDevice = (valueArg: unknown): valueArg is interfaces.IControllerDevice => {
670
+ if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
671
+ const candidate = valueArg as Partial<interfaces.IControllerDevice>;
672
+ return Object.keys(candidate).every((keyArg) => deviceKeys.has(keyArg))
673
+ && typeof candidate.id === 'string' && /^[A-Za-z0-9_-]{24}$/u.test(candidate.id)
674
+ && isNonEmptyString(candidate.name) && candidate.name.length <= 256
675
+ && isNonEmptyString(candidate.model) && candidate.model.length <= 256
676
+ && typeof candidate.fingerprint === 'string' && /^[0-9A-F]{4}( [0-9A-F]{4}){7}$/u.test(candidate.fingerprint)
677
+ && Number.isSafeInteger(candidate.pairedAt)
678
+ && (candidate.lastSeenAt === undefined || Number.isSafeInteger(candidate.lastSeenAt))
679
+ && typeof candidate.connected === 'boolean';
680
+ };
681
+
682
+ const isDevicePairingOutcome = (valueArg: unknown): valueArg is interfaces.IControllerDevicePairingOutcome => {
683
+ if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
684
+ const candidate = valueArg as Partial<interfaces.IControllerDevicePairingOutcome>;
685
+ return Object.keys(candidate).length === 2
686
+ && typeof candidate.pairingId === 'string' && /^[A-Za-z0-9_-]{22}$/u.test(candidate.pairingId)
687
+ && isControllerDevice(candidate.device);
688
+ };
689
+
666
690
  export const isControllerEvent = (valueArg: unknown): valueArg is interfaces.IControllerEvent => {
667
691
  if (!valueArg || typeof valueArg !== 'object') {
668
692
  return false;
@@ -857,6 +881,9 @@ export const isControllerEvent = (valueArg: unknown): valueArg is interfaces.ICo
857
881
  candidate.type === 'usage.changed' && isControllerUsageDelta(candidate.usageDelta)
858
882
  ))
859
883
  && (candidate.usageDelta !== undefined || candidate.type !== 'usage.changed')
884
+ && (candidate.devicePairing === undefined || (
885
+ candidate.type === 'devices.changed' && isDevicePairingOutcome(candidate.devicePairing)
886
+ ))
860
887
  );
861
888
  };
862
889