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.
- package/changelog.md +41 -0
- package/dist_serve/bundle.js +2625 -2278
- package/dist_serve/bundle.js.map +2 -2
- package/dist_serve/bundle.js.third-party-notices.json +3 -68
- package/dist_serve/bundle.js.third-party-notices.txt +4 -137
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/aglapi/aglapisurface.document.js +4 -4
- package/dist_ts/classes.authmodels.d.ts +2 -8
- package/dist_ts/classes.authmodels.js +60 -23
- package/dist_ts/classes.authstore.d.ts +24 -0
- package/dist_ts/classes.authstore.js +185 -23
- package/dist_ts/classes.cli.d.ts +3 -6
- package/dist_ts/classes.cli.js +38 -51
- package/dist_ts/classes.config.d.ts +17 -3
- package/dist_ts/classes.config.js +55 -18
- package/dist_ts/classes.controller.d.ts +83 -14
- package/dist_ts/classes.controller.js +545 -229
- package/dist_ts/classes.controllerdevices.d.ts +128 -0
- package/dist_ts/classes.controllerdevices.js +472 -0
- package/dist_ts/classes.controllermanagement.d.ts +42 -9
- package/dist_ts/classes.controllermanagement.js +72 -23
- package/dist_ts/classes.controllerservice.d.ts +3 -31
- package/dist_ts/classes.controllerservice.js +3 -47
- package/dist_ts/classes.mcpcontrollerhost.js +9 -3
- package/dist_ts/classes.processinspection.d.ts +8 -1
- package/dist_ts/classes.processinspection.js +92 -2
- package/dist_ts/classes.proxycontrol.js +6 -1
- package/dist_ts/classes.proxydaemon.d.ts +2 -2
- package/dist_ts/classes.proxydaemon.js +1 -1
- package/dist_ts/classes.proxystore.d.ts +2 -11
- package/dist_ts/classes.proxystore.js +3 -25
- package/dist_ts/classes.sessionfeed.d.ts +10 -1
- package/dist_ts/classes.sessionfeed.js +12 -2
- package/dist_ts/classes.tpmsecretcodec.d.ts +13 -0
- package/dist_ts/classes.tpmsecretcodec.js +28 -0
- package/dist_ts/classes.trustedproxysecrets.d.ts +91 -0
- package/dist_ts/classes.trustedproxysecrets.js +338 -0
- package/dist_ts/classes.upgradecoordinator.d.ts +14 -1
- package/dist_ts/classes.upgradecoordinator.js +21 -3
- package/dist_ts/classes.upgradetransaction.d.ts +32 -0
- package/dist_ts/classes.upgradetransaction.js +101 -4
- package/dist_ts/classes.validation.d.ts +2 -0
- package/dist_ts/classes.validation.js +2 -2
- package/dist_ts/functions.controlleradmission.d.ts +67 -0
- package/dist_ts/functions.controlleradmission.js +127 -0
- package/dist_ts/functions.deviceapi.d.ts +28 -0
- package/dist_ts/functions.deviceapi.js +246 -0
- package/dist_ts/functions.deviceproof.d.ts +33 -0
- package/dist_ts/functions.deviceproof.js +93 -0
- package/dist_ts/functions.remotecli.d.ts +27 -0
- package/dist_ts/functions.remotecli.js +241 -0
- package/dist_ts/functions.retiredenvironment.d.ts +11 -2
- package/dist_ts/functions.retiredenvironment.js +22 -5
- package/dist_ts/index.d.ts +1 -0
- package/dist_ts/index.js +2 -1
- package/dist_ts/interfaces.auth.d.ts +29 -4
- package/dist_ts/interfaces.auth.js +10 -1
- package/dist_ts/interfaces.config.d.ts +14 -0
- package/dist_ts/interfaces.config.js +9 -2
- package/dist_ts/interfaces.lifecycle.d.ts +3 -0
- package/dist_ts_authswitch/classes.authoritydaemon.js +6 -1
- package/dist_ts_interfaces/devices.d.ts +331 -0
- package/dist_ts_interfaces/devices.js +34 -0
- package/dist_ts_interfaces/index.d.ts +2 -0
- package/dist_ts_interfaces/index.js +3 -1
- package/dist_ts_interfaces/interfaces.d.ts +5 -3
- package/dist_ts_interfaces/interfaces.js +3 -2
- package/dist_ts_interfaces/management.d.ts +2 -2
- package/dist_ts_interfaces/management.js +2 -2
- package/dist_ts_interfaces/mcprequests.d.ts +1 -1
- package/dist_ts_interfaces/requests.d.ts +2 -2
- package/dist_ts_interfaces/requests.devices.d.ts +89 -0
- package/dist_ts_interfaces/requests.devices.js +2 -0
- package/dist_ts_interfaces/requests.upgrade.d.ts +0 -12
- package/package.json +12 -11
- package/readme.md +116 -24
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/aglapi/aglapisurface.document.ts +3 -3
- package/ts/classes.authmodels.ts +68 -25
- package/ts/classes.authstore.ts +183 -24
- package/ts/classes.cli.ts +38 -61
- package/ts/classes.config.ts +70 -21
- package/ts/classes.controller.ts +746 -329
- package/ts/classes.controllerdevices.ts +469 -0
- package/ts/classes.controllermanagement.ts +123 -49
- package/ts/classes.controllerservice.ts +3 -56
- package/ts/classes.mcpcontrollerhost.ts +10 -5
- package/ts/classes.processinspection.ts +84 -3
- package/ts/classes.proxycontrol.ts +2 -0
- package/ts/classes.proxydaemon.ts +3 -2
- package/ts/classes.proxystore.ts +4 -25
- package/ts/classes.sessionfeed.ts +13 -1
- package/ts/classes.tpmsecretcodec.ts +26 -0
- package/ts/classes.trustedproxysecrets.ts +317 -0
- package/ts/classes.upgradecoordinator.ts +33 -3
- package/ts/classes.upgradetransaction.ts +130 -1
- package/ts/classes.validation.ts +1 -1
- package/ts/functions.controlleradmission.ts +168 -0
- package/ts/functions.deviceapi.ts +295 -0
- package/ts/functions.deviceproof.ts +118 -0
- package/ts/functions.remotecli.ts +270 -0
- package/ts/functions.retiredenvironment.ts +25 -3
- package/ts/index.ts +1 -0
- package/ts/interfaces.auth.ts +41 -3
- package/ts/interfaces.config.ts +15 -0
- package/ts/interfaces.lifecycle.ts +3 -0
- package/ts_authswitch/classes.authoritydaemon.ts +2 -0
- package/ts_interfaces/devices.schema.json +890 -0
- package/ts_interfaces/devices.ts +392 -0
- package/ts_interfaces/index.ts +2 -0
- package/ts_interfaces/interfaces.ts +5 -2
- package/ts_interfaces/management.ts +2 -2
- package/ts_interfaces/mcprequests.ts +1 -1
- package/ts_interfaces/requests.devices.ts +95 -0
- package/ts_interfaces/requests.ts +10 -10
- package/ts_interfaces/requests.upgrade.ts +0 -16
- package/ts_web/00_commitinfo_data.ts +1 -1
- package/ts_web/classes.controllersocketclient.ts +27 -0
- package/ts_web/elements.devices.ts +752 -0
- 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;
|
package/ts_interfaces/index.ts
CHANGED
|
@@ -5,7 +5,7 @@ import type {
|
|
|
5
5
|
TControllerBrowserPaintAvailability,
|
|
6
6
|
TControllerBrowserPaintTermination,
|
|
7
7
|
} from './browserpaint.js';
|
|
8
|
-
export const controllerProtocolVersion =
|
|
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
|
|
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
|
-
*
|
|
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
|
|
@@ -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
|
|