agl 43.7.0 → 43.8.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 (116) hide show
  1. package/changelog.md +17 -0
  2. package/dist_serve/bundle.js +786 -786
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_ts/00_commitinfo_data.js +1 -1
  5. package/dist_ts/aglapi/interfaces.d.ts +35 -0
  6. package/dist_ts/aglapi/interfaces.js +9 -1
  7. package/dist_ts/classes.apnsclient.d.ts +97 -0
  8. package/dist_ts/classes.apnsclient.js +363 -0
  9. package/dist_ts/classes.authmodels.js +19 -6
  10. package/dist_ts/classes.authstore.js +15 -2
  11. package/dist_ts/classes.cli.js +8 -1
  12. package/dist_ts/classes.controller.d.ts +30 -3
  13. package/dist_ts/classes.controller.js +250 -9
  14. package/dist_ts/classes.controllerdevices.d.ts +35 -7
  15. package/dist_ts/classes.controllerdevices.js +86 -13
  16. package/dist_ts/classes.controllerpush.d.ts +111 -0
  17. package/dist_ts/classes.controllerpush.js +299 -0
  18. package/dist_ts/classes.fcmclient.d.ts +78 -0
  19. package/dist_ts/classes.fcmclient.js +278 -0
  20. package/dist_ts/classes.inbox.d.ts +10 -2
  21. package/dist_ts/classes.inbox.js +9 -2
  22. package/dist_ts/classes.mcpclient.d.ts +5 -0
  23. package/dist_ts/classes.mcpclient.js +18 -6
  24. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -0
  25. package/dist_ts/classes.mcpcontrollerhost.js +19 -1
  26. package/dist_ts/classes.mcpvalidation.js +4 -1
  27. package/dist_ts/classes.mcpworkercaller.d.ts +6 -0
  28. package/dist_ts/classes.mcpworkercaller.js +26 -4
  29. package/dist_ts/classes.pushdelivery.d.ts +115 -0
  30. package/dist_ts/classes.pushdelivery.js +311 -0
  31. package/dist_ts/classes.pushhandover.d.ts +46 -0
  32. package/dist_ts/classes.pushhandover.js +131 -0
  33. package/dist_ts/classes.pushregistrations.d.ts +96 -0
  34. package/dist_ts/classes.pushregistrations.js +263 -0
  35. package/dist_ts/classes.pushsettings.d.ts +125 -0
  36. package/dist_ts/classes.pushsettings.js +377 -0
  37. package/dist_ts/classes.workercallers.d.ts +73 -2
  38. package/dist_ts/classes.workercallers.js +354 -43
  39. package/dist_ts/driver/classes.directreports.d.ts +5 -0
  40. package/dist_ts/driver/classes.directreports.js +3 -2
  41. package/dist_ts/fleet/classes.workerlaunches.d.ts +6 -4
  42. package/dist_ts/fleet/classes.workerlaunches.js +10 -9
  43. package/dist_ts/fleet/classes.workers.d.ts +12 -2
  44. package/dist_ts/fleet/classes.workers.js +82 -2
  45. package/dist_ts/functions.deviceapi.d.ts +23 -3
  46. package/dist_ts/functions.deviceapi.js +41 -3
  47. package/dist_ts/functions.pushcli.d.ts +43 -0
  48. package/dist_ts/functions.pushcli.js +201 -0
  49. package/dist_ts/functions.pushcredentials.d.ts +53 -0
  50. package/dist_ts/functions.pushcredentials.js +111 -0
  51. package/dist_ts/functions.pushwire.d.ts +8 -0
  52. package/dist_ts/functions.pushwire.js +83 -0
  53. package/dist_ts/functions.remotecli.d.ts +2 -2
  54. package/dist_ts/functions.remotecli.js +4 -4
  55. package/dist_ts/functions.workercallervalidation.js +3 -2
  56. package/dist_ts/functions.workerprocessproof.d.ts +12 -0
  57. package/dist_ts/functions.workerprocessproof.js +32 -1
  58. package/dist_ts/interfaces.auth.d.ts +27 -3
  59. package/dist_ts/interfaces.auth.js +9 -1
  60. package/dist_ts/interfaces.lifecycle.d.ts +7 -1
  61. package/dist_ts/interfaces.push.d.ts +69 -0
  62. package/dist_ts/interfaces.push.js +25 -0
  63. package/dist_ts/plugins.d.ts +3 -1
  64. package/dist_ts/plugins.js +4 -2
  65. package/dist_ts_interfaces/devices.d.ts +178 -2
  66. package/dist_ts_interfaces/devices.js +24 -2
  67. package/dist_ts_interfaces/index.d.ts +1 -0
  68. package/dist_ts_interfaces/index.js +2 -1
  69. package/dist_ts_interfaces/mcprequests.d.ts +3 -2
  70. package/dist_ts_interfaces/mcprequests.js +3 -1
  71. package/dist_ts_interfaces/push.d.ts +166 -0
  72. package/dist_ts_interfaces/push.js +24 -0
  73. package/dist_ts_interfaces/workercallers.d.ts +43 -3
  74. package/package.json +1 -1
  75. package/readme.md +64 -11
  76. package/ts/00_commitinfo_data.ts +1 -1
  77. package/ts/aglapi/interfaces.ts +8 -0
  78. package/ts/classes.apnsclient.ts +389 -0
  79. package/ts/classes.authmodels.ts +21 -5
  80. package/ts/classes.authstore.ts +14 -1
  81. package/ts/classes.cli.ts +7 -0
  82. package/ts/classes.controller.ts +273 -7
  83. package/ts/classes.controllerdevices.ts +94 -12
  84. package/ts/classes.controllerpush.ts +351 -0
  85. package/ts/classes.fcmclient.ts +292 -0
  86. package/ts/classes.inbox.ts +13 -2
  87. package/ts/classes.mcpclient.ts +20 -5
  88. package/ts/classes.mcpcontrollerhost.ts +20 -0
  89. package/ts/classes.mcpvalidation.ts +2 -0
  90. package/ts/classes.mcpworkercaller.ts +24 -2
  91. package/ts/classes.pushdelivery.ts +378 -0
  92. package/ts/classes.pushhandover.ts +98 -0
  93. package/ts/classes.pushregistrations.ts +244 -0
  94. package/ts/classes.pushsettings.ts +428 -0
  95. package/ts/classes.workercallers.ts +329 -37
  96. package/ts/driver/classes.directreports.ts +7 -1
  97. package/ts/fleet/classes.workerlaunches.ts +9 -7
  98. package/ts/fleet/classes.workers.ts +65 -2
  99. package/ts/functions.deviceapi.ts +52 -2
  100. package/ts/functions.pushcli.ts +212 -0
  101. package/ts/functions.pushcredentials.ts +129 -0
  102. package/ts/functions.pushwire.ts +106 -0
  103. package/ts/functions.remotecli.ts +3 -2
  104. package/ts/functions.workercallervalidation.ts +2 -1
  105. package/ts/functions.workerprocessproof.ts +34 -0
  106. package/ts/interfaces.auth.ts +26 -3
  107. package/ts/interfaces.lifecycle.ts +7 -1
  108. package/ts/interfaces.push.ts +78 -0
  109. package/ts/plugins.ts +3 -1
  110. package/ts_interfaces/devices.schema.json +327 -0
  111. package/ts_interfaces/devices.ts +206 -1
  112. package/ts_interfaces/index.ts +1 -0
  113. package/ts_interfaces/mcprequests.ts +3 -0
  114. package/ts_interfaces/push.ts +162 -0
  115. package/ts_interfaces/workercallers.ts +34 -2
  116. package/ts_web/00_commitinfo_data.ts +1 -1
@@ -95,12 +95,13 @@ const maximumSecretInputBytes = 4_096;
95
95
 
96
96
  /**
97
97
  * Reads a secret from standard input, a pipe or a file, never a terminal (`refusalArg` names the right way), and
98
- * returns it trimmed; nothing of it is echoed or kept past the read.
98
+ * returns it trimmed; nothing of it is echoed or kept past the read. `maximumBytesArg` bounds it (4 KiB by default).
99
99
  */
100
100
  export const readStandardInputSecret = async (
101
101
  inputArg: NodeJS.ReadableStream & { isTTY?: boolean },
102
102
  refusalArg: string,
103
103
  whatArg: string,
104
+ maximumBytesArg = maximumSecretInputBytes,
104
105
  ): Promise<string> => {
105
106
  if (inputArg.isTTY) throw new Error(refusalArg);
106
107
  const chunks: Buffer[] = [];
@@ -110,7 +111,7 @@ export const readStandardInputSecret = async (
110
111
  const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk as Uint8Array);
111
112
  chunks.push(buffer);
112
113
  bytes += buffer.byteLength;
113
- if (bytes > maximumSecretInputBytes) throw new Error(`The standard input is longer than ${whatArg}.`);
114
+ if (bytes > maximumBytesArg) throw new Error(`The standard input is longer than ${whatArg}.`);
114
115
  }
115
116
  return Buffer.concat(chunks).toString('utf8').trim();
116
117
  } finally {
@@ -9,7 +9,8 @@ export const assertWorkerCallerEnrollment = (valueArg: unknown): TWorkerCallerEn
9
9
  throw new Error('Invalid worker enrollment request.');
10
10
  }
11
11
  const keys = Object.hasOwn(valueArg, 'launchId') ? ['bridgePid', 'launchId', 'launchGeneration']
12
- : Object.hasOwn(valueArg, 'challenge') ? ['bridgePid', 'challenge', 'nativeThreadId'] : ['bridgePid', 'nativeThreadId'];
12
+ : Object.hasOwn(valueArg, 'challenge') ? ['bridgePid', 'challenge', 'nativeThreadId']
13
+ : Object.hasOwn(valueArg, 'nativeThreadId') ? ['bridgePid', 'nativeThreadId'] : ['bridgePid'];
13
14
  if (Object.keys(valueArg).length !== keys.length || keys.some(key => !Object.hasOwn(valueArg, key))) {
14
15
  throw new Error('Invalid worker enrollment request.');
15
16
  }
@@ -3,6 +3,8 @@ import type { IConfigurationMcpStdioServer, IFleetClaudeProcess } from '../ts_in
3
3
  import { resolveControllerTerminalAgentExecutable } from './functions.terminalagents.js';
4
4
 
5
5
  export class WorkerCallerProofError extends Error {}
6
+ /** A proof refused because the process changed while it was read: unlike the other refusals, it may pass at the next read. */
7
+ export class WorkerProcessChangedError extends WorkerCallerProofError {}
6
8
 
7
9
  export const isWorkerCallerProofRefusal = (errorArg: unknown): boolean => (
8
10
  errorArg instanceof WorkerCallerProofError
@@ -213,6 +215,38 @@ export const verifyClaudeWorkerProcess = async (
213
215
  return snapshot;
214
216
  };
215
217
 
218
+ /**
219
+ * The process `processArg` (PID and start), proved to run an installed Claude Code release: its executable is a
220
+ * regular file of the controller's user in the directory of `releaseArg`, the release `claude` resolves to now, and is
221
+ * the very file the process runs. Claude Code installs every release as a file of its own there (`versions/<release>`)
222
+ * and moves its launcher to the newest, while a running job keeps the release it started on; a release file that was
223
+ * removed or replaced since the process started is refused. A local read of the process and two file stats: the
224
+ * controller proves it before it asks the fleet's inventory which job the process runs.
225
+ */
226
+ export const verifyClaudeReleaseProcess = async (
227
+ processArg: Pick<IFleetClaudeProcess, 'pid' | 'startTicks'>,
228
+ releaseArg: string,
229
+ ): Promise<IWorkerProcessSnapshot> => {
230
+ if (!/^\d+$/u.test(processArg.startTicks) || !plugins.path.isAbsolute(releaseArg)) {
231
+ throw new WorkerCallerProofError('Invalid Claude launch observation.');
232
+ }
233
+ const snapshot = await readWorkerProcessSnapshot(processArg.pid);
234
+ if (snapshot.startTicks !== processArg.startTicks || !plugins.path.isAbsolute(snapshot.executable)
235
+ || plugins.path.dirname(snapshot.executable) !== plugins.path.dirname(releaseArg)) {
236
+ throw new WorkerCallerProofError('The Claude process does not run an installed Claude Code release.');
237
+ }
238
+ const [installed, running] = await Promise.all([plugins.fs.promises.lstat(snapshot.executable, { bigint: true }),
239
+ plugins.fs.promises.stat(`/proc/${processArg.pid}/exe`, { bigint: true })]);
240
+ if (!installed.isFile() || installed.uid !== BigInt(process.getuid?.() ?? -1)
241
+ || installed.dev !== running.dev || installed.ino !== running.ino) {
242
+ throw new WorkerCallerProofError('The Claude process does not run an installed Claude Code release.');
243
+ }
244
+ if (!workerSnapshotsEqual(snapshot, await readWorkerProcessSnapshot(processArg.pid))) {
245
+ throw new WorkerProcessChangedError('The Claude launch observation no longer matches its process.');
246
+ }
247
+ return snapshot;
248
+ };
249
+
216
250
  export const readWorkerUnixSocketOwner = async (socketPathArg: string): Promise<IWorkerProcessSnapshot> => {
217
251
  const table = await plugins.fs.promises.readFile('/proc/net/unix', 'utf8');
218
252
  const rows = table.split('\n').slice(1).map(line => line.trim().split(/\s+/u))
@@ -167,6 +167,14 @@ export const controllerAuditEventTypes = [
167
167
  'device.pair',
168
168
  'device.auth',
169
169
  'device.revoke',
170
+ // The host's push settings (AGL-1639): `agl push` against the running controller, as the local owner; what a change
171
+ // sets rides in `details.push`, never a key.
172
+ 'push.apns.set',
173
+ 'push.apns.unset',
174
+ 'push.fcm.set',
175
+ 'push.fcm.unset',
176
+ 'push.previews',
177
+ 'push.test',
170
178
  ] as const;
171
179
  export type TControllerAuditEventType = (typeof controllerAuditEventTypes)[number];
172
180
  export type TControllerAuditOutcome = 'attempted' | 'succeeded' | 'denied' | 'failed';
@@ -302,16 +310,29 @@ export interface IControllerAuditGateway {
302
310
  rotate?: boolean;
303
311
  }
304
312
 
313
+ /**
314
+ * What a `push.*` event records of the change (AGL-1639), never a key or a token: `push.apns.set` the key id, team id
315
+ * and topic, `push.fcm.set` the Firebase project and the service account's address, `push.previews` the setting,
316
+ * `push.test` how many devices it went to and how many got it.
317
+ */
318
+ export type IControllerAuditPush =
319
+ | { keyId: string; teamId: string; topic: string }
320
+ | { projectId: string; clientEmail: string }
321
+ | { previews: boolean }
322
+ | { devices: number; delivered: number };
323
+
305
324
  /**
306
325
  * What an audit event records beyond its envelope (bounded plain JSON). This release records `remoteMove` on
307
- * `remote.set` and `remote.unset` and `gateway` on `remote.gateway.*`; any other key is a later release's, kept and
308
- * pruned as it wrote it.
326
+ * `remote.set` and `remote.unset`, `gateway` on `remote.gateway.*` and `push` on `push.apns.set`, `push.fcm.set` and
327
+ * `push.previews`; any other key is a later release's, kept and pruned as it wrote it.
309
328
  */
310
329
  export interface IControllerAuditEventDetails {
311
330
  /** `remote.set` and `remote.unset` only: where the move goes from and to. */
312
331
  remoteMove?: IControllerAuditRemoteMove;
313
332
  /** `remote.gateway.*` only: the gateway route the command acted on. */
314
333
  gateway?: IControllerAuditGateway;
334
+ /** `push.apns.set`, `push.fcm.set`, `push.previews` and `push.test` only: what the change set or sent. */
335
+ push?: IControllerAuditPush;
315
336
  [key: string]: unknown;
316
337
  }
317
338
 
@@ -320,7 +341,9 @@ export type IRecordAuditEventDetails =
320
341
  /** `remote.set` and `remote.unset` only: where the move goes from and to. */
321
342
  | { remoteMove: IControllerAuditRemoteMove }
322
343
  /** `remote.gateway.*` only: the gateway route the command acted on. */
323
- | { gateway: IControllerAuditGateway };
344
+ | { gateway: IControllerAuditGateway }
345
+ /** `push.apns.set`, `push.fcm.set`, `push.previews` and `push.test` only: what the change set or sent. */
346
+ | { push: IControllerAuditPush };
324
347
 
325
348
  /**
326
349
  * A stored audit event. The audit log is shared with later releases, so a stored `type` is any audit type, also one
@@ -3,6 +3,7 @@ import type { IAuthoritySocketPaths } from './classes.authorityclient.js';
3
3
  import type { IControllerRuntimeOverrides } from './interfaces.config.js';
4
4
  import type * as plugins from './plugins.js';
5
5
  import type { ITpmSecretCodec } from './classes.tpmsecretcodec.js';
6
+ import type { IPushEndpoints } from './interfaces.push.js';
6
7
 
7
8
  export interface IControllerStartOptions {
8
9
  processMode: TControllerProcessMode;
@@ -25,8 +26,13 @@ export interface IControllerStartOptions {
25
26
  codexAppServerScope?: plugins.authswitch.ICodexAppServerScopeOptions;
26
27
  /** Operator-provided first-start setup code; a random code is minted when absent. */
27
28
  setupCode?: string;
28
- /** Seals the trusted-proxy secret in TLS-proxy mode; TPM2 (`TpmSecretCodec`) when absent. For tests. */
29
+ /**
30
+ * Seals the trusted-proxy secret in TLS-proxy mode, the gateway credential and the push keys; TPM2 (`TpmSecretCodec`)
31
+ * when absent. For tests.
32
+ */
29
33
  trustedProxySecretCodec?: ITpmSecretCodec;
34
+ /** Where the push senders connect; Apple's and Google's hosts when absent. For tests: production never sets it. */
35
+ pushEndpoints?: IPushEndpoints;
30
36
  /** Private upgrade transaction token received over parent IPC. */
31
37
  upgradeToken?: string;
32
38
  upgradeGlobalRoot?: string;
@@ -0,0 +1,78 @@
1
+ import type { TDevicePushData, TDevicePushEnvironment, TDevicePushFailureReason } from '../ts_interfaces/devices.js';
2
+
3
+ /**
4
+ * What the APNs and FCM senders share (AGL-1639): the hosts they talk to, pinned here and nowhere configurable, and
5
+ * what one send came to.
6
+ */
7
+
8
+ /** Apple's push service: one host per environment of a device token. */
9
+ export const apnsHosts = { production: 'api.push.apple.com', sandbox: 'api.sandbox.push.apple.com' } as const satisfies Record<TDevicePushEnvironment, string>;
10
+ export type TApnsHost = (typeof apnsHosts)[TDevicePushEnvironment];
11
+
12
+ /** Google's token endpoint and Firebase Cloud Messaging; a service account file's `token_uri` is never asked. */
13
+ export const googleHosts = { token: 'oauth2.googleapis.com', fcm: 'fcm.googleapis.com' } as const;
14
+ export type TGoogleHost = (typeof googleHosts)[keyof typeof googleHosts];
15
+
16
+ /** Where an HTTPS request to a pinned Google host goes. */
17
+ export interface IPushHttpEndpoint {
18
+ protocol: 'https:' | 'http:';
19
+ hostname: string;
20
+ port: number;
21
+ }
22
+
23
+ /**
24
+ * Where the senders' connections go. Production code never sets it: the senders connect to the pinned hosts on 443
25
+ * with TLS. A test hands its own fake servers' addresses here, and the requests still name the pinned hosts.
26
+ */
27
+ export interface IPushEndpoints {
28
+ /** The authority URL an HTTP/2 session to an APNs host connects to. */
29
+ apns(hostArg: TApnsHost): string;
30
+ /** Where a request to a Google host connects. */
31
+ google(hostArg: TGoogleHost): IPushHttpEndpoint;
32
+ }
33
+
34
+ export const pushServiceEndpoints: IPushEndpoints = {
35
+ apns: (hostArg) => `https://${hostArg}:443`,
36
+ google: (hostArg) => ({ protocol: 'https:', hostname: hostArg, port: 443 }),
37
+ };
38
+
39
+ /** A device's registration as a sender needs it: the push token, and for APNs the token's environment. */
40
+ export interface IPushSendTarget {
41
+ token: string;
42
+ environment?: TDevicePushEnvironment;
43
+ }
44
+
45
+ /**
46
+ * What one send came to: `delivered`; `unregistered`, the push service says the token is gone (the registration is
47
+ * deleted if it still holds that token); or why it did not go out (`TDevicePushFailureReason`), with the push service's
48
+ * own code when it named one (never its message) and how long it asked the host to wait. `clockSkewMs` is set when the
49
+ * refusal came while the service's clock and the host's were apart (`googleTokenClockSkewLimitMs`): the service's `Date`
50
+ * minus the host's clock, so a positive value is a host clock behind.
51
+ */
52
+ export type TPushSendResult =
53
+ | { outcome: 'delivered' }
54
+ | { outcome: 'unregistered'; vendorReason?: string }
55
+ | { outcome: TDevicePushFailureReason; vendorReason?: string; retryAfterMs?: number; clockSkewMs?: number };
56
+
57
+ /** One send to a push service, for the delivery service. */
58
+ export interface IPushSender {
59
+ send(targetArg: IPushSendTarget, payloadArg: TDevicePushData, expiresAtArg: number, signalArg: AbortSignal): Promise<TPushSendResult>;
60
+ /** Ends every connection; a send still running ends as `unreachable`. */
61
+ close(): Promise<void>;
62
+ }
63
+
64
+ /** How long one request to a push service may take, from connecting to the last byte of its answer. */
65
+ export const pushRequestTimeoutMs = 15_000;
66
+
67
+ /** A push service's code as the host keeps it: an identifier of letters, digits and `_`, never its message. */
68
+ export const isPushVendorReason = (valueArg: unknown): valueArg is string => (
69
+ typeof valueArg === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,63}$/u.test(valueArg)
70
+ );
71
+
72
+ /** A `Retry-After` header in milliseconds: seconds, or an HTTP date; at most a day. */
73
+ export const retryAfterMs = (valueArg: string | string[] | undefined, nowArg: number): number | undefined => {
74
+ const value = Array.isArray(valueArg) ? valueArg[0] : valueArg;
75
+ if (value === undefined) return undefined;
76
+ const seconds = /^\d{1,6}$/u.test(value.trim()) ? Number(value.trim()) * 1000 : Date.parse(value) - nowArg;
77
+ return Number.isFinite(seconds) && seconds >= 0 ? Math.min(seconds, 24 * 60 * 60 * 1000) : undefined;
78
+ };
package/ts/plugins.ts CHANGED
@@ -5,6 +5,8 @@ import * as nodeConsole from 'node:console';
5
5
  import * as crypto from 'node:crypto';
6
6
  import * as fs from 'node:fs';
7
7
  import * as http from 'node:http';
8
+ import * as http2 from 'node:http2';
9
+ import * as https from 'node:https';
8
10
  import { createRequire } from 'node:module';
9
11
  import * as net from 'node:net';
10
12
  import * as os from 'node:os';
@@ -14,7 +16,7 @@ import * as url from 'node:url';
14
16
  import * as util from 'node:util';
15
17
  import * as timersPromises from 'node:timers/promises';
16
18
 
17
- export { asyncHooks, childProcess, nodeConsole, createRequire, crypto, fs, http, net, os, path, stream, url, util, timersPromises };
19
+ export { asyncHooks, childProcess, nodeConsole, createRequire, crypto, fs, http, http2, https, net, os, path, stream, url, util, timersPromises };
18
20
 
19
21
  // foss.global modules
20
22
  import * as docker from '@apiclient.xyz/docker';
@@ -634,6 +634,71 @@
634
634
  "additionalProperties": false
635
635
  }
636
636
  },
637
+ {
638
+ "name": "IReq_DevicePushRegister",
639
+ "method": "device.push.register",
640
+ "description": "Registers this device for notifications of what comes into the Inbox, and with `reports` of the direct reports' results too: one registration per device, which the next one replaces, so an app registers again with its current token on every connect. Taken also while the host holds no credential to send with (the answer's `available` says so). The token stays on the host: no answer, event or log repeats it. Scope `device`. Since protocol 1.4.",
641
+ "request": {
642
+ "type": "object",
643
+ "properties": {
644
+ "platform": {
645
+ "$ref": "#/components/schemas/TDevicePushPlatform"
646
+ },
647
+ "token": {
648
+ "type": "string",
649
+ "description": "APNs: the device token as lowercase hex, 32 to 100 bytes. FCM: the registration token as the Firebase SDK hands it, 1 to 1024 characters of letters, digits, `_`, `-` and `:`."
650
+ },
651
+ "environment": {
652
+ "$ref": "#/components/schemas/TDevicePushEnvironment",
653
+ "description": "APNs only, and required there: the environment the token belongs to."
654
+ },
655
+ "reports": {
656
+ "type": "boolean",
657
+ "description": "Whether to notify the direct reports' results too."
658
+ }
659
+ },
660
+ "required": [
661
+ "platform",
662
+ "token",
663
+ "reports"
664
+ ],
665
+ "additionalProperties": false
666
+ },
667
+ "response": {
668
+ "type": "object",
669
+ "properties": {
670
+ "push": {
671
+ "$ref": "#/components/schemas/IDeviceHostPush"
672
+ }
673
+ },
674
+ "required": [
675
+ "push"
676
+ ],
677
+ "additionalProperties": false,
678
+ "description": "The registration as `device.host.get` shows it."
679
+ }
680
+ },
681
+ {
682
+ "name": "IReq_DevicePushUnregister",
683
+ "method": "device.push.unregister",
684
+ "description": "Ends this device's registration: the host sends it no notification from then on. `removed` says whether it held one. Scope `device`. Since protocol 1.4.",
685
+ "request": {
686
+ "type": "object",
687
+ "additionalProperties": false
688
+ },
689
+ "response": {
690
+ "type": "object",
691
+ "properties": {
692
+ "removed": {
693
+ "type": "boolean"
694
+ }
695
+ },
696
+ "required": [
697
+ "removed"
698
+ ],
699
+ "additionalProperties": false
700
+ }
701
+ },
637
702
  {
638
703
  "name": "IReq_DeviceQuestionReply",
639
704
  "method": "device.question.reply",
@@ -1908,6 +1973,10 @@
1908
1973
  "lastSeenAt": {
1909
1974
  "type": "integer",
1910
1975
  "description": "Unix milliseconds of its last authenticated connection, kept to about five minutes."
1976
+ },
1977
+ "push": {
1978
+ "$ref": "#/components/schemas/IDeviceHostPush",
1979
+ "description": "Its notifications, while it is registered for them; absent while it is not. Since protocol 1.4."
1911
1980
  }
1912
1981
  },
1913
1982
  "required": [
@@ -1971,6 +2040,34 @@
1971
2040
  "additionalProperties": false,
1972
2041
  "description": "The host reached through a TLS reverse proxy the owner runs. Since protocol 1.3."
1973
2042
  },
2043
+ "IDeviceHostPush": {
2044
+ "type": "object",
2045
+ "properties": {
2046
+ "reports": {
2047
+ "type": "boolean",
2048
+ "description": "Whether the device asked for direct report results too, besides what waits in the Inbox."
2049
+ },
2050
+ "previews": {
2051
+ "type": "boolean",
2052
+ "description": "Whether notifications carry previews: where an item lives, what it asks and its id (`IDevicePushInboxData`). One setting for every device of the host, which only the owner changes on the host; off unless the owner turns it on."
2053
+ },
2054
+ "available": {
2055
+ "type": "boolean",
2056
+ "description": "Whether the host can send the device notifications now: it holds a credential for the device's platform that Apple or Google did not refuse. While it does not, the registration stays and nothing is sent until the owner sets the credential on the host."
2057
+ },
2058
+ "lastFailure": {
2059
+ "$ref": "#/components/schemas/IDevicePushFailure",
2060
+ "description": "The last notification to the device that did not go out, while none went out after it."
2061
+ }
2062
+ },
2063
+ "required": [
2064
+ "reports",
2065
+ "previews",
2066
+ "available"
2067
+ ],
2068
+ "additionalProperties": false,
2069
+ "description": "The notifications a device registered for, as the host sends them: never its token. Since protocol 1.4."
2070
+ },
1974
2071
  "IDeviceHostUnavailable": {
1975
2072
  "type": "object",
1976
2073
  "properties": {
@@ -2624,6 +2721,175 @@
2624
2721
  "additionalProperties": false,
2625
2722
  "description": "The usage window an account's room is bound by, as its last reading states it. Since protocol 1.3."
2626
2723
  },
2724
+ "IDevicePushClearData": {
2725
+ "type": "object",
2726
+ "properties": {
2727
+ "type": {
2728
+ "type": "string",
2729
+ "const": "clear"
2730
+ },
2731
+ "keys": {
2732
+ "type": "string",
2733
+ "description": "The keys of the notifications to remove, separated by single spaces."
2734
+ },
2735
+ "badge": {
2736
+ "type": "string",
2737
+ "description": "The number of items in the Inbox now, in decimal: the app's badge."
2738
+ }
2739
+ },
2740
+ "required": [
2741
+ "type",
2742
+ "keys",
2743
+ "badge"
2744
+ ],
2745
+ "additionalProperties": false,
2746
+ "description": "Items left the Inbox: remove their notifications (Android cancels them by tag; on iOS it is a background push, which the system may hold back, so an app also matches its notifications against `device.inbox.list` on every connect). Since protocol 1.4."
2747
+ },
2748
+ "IDevicePushFailure": {
2749
+ "type": "object",
2750
+ "properties": {
2751
+ "at": {
2752
+ "type": "integer",
2753
+ "description": "Unix milliseconds of the failed send."
2754
+ },
2755
+ "reason": {
2756
+ "$ref": "#/components/schemas/TDevicePushFailureReason"
2757
+ }
2758
+ },
2759
+ "required": [
2760
+ "at",
2761
+ "reason"
2762
+ ],
2763
+ "additionalProperties": false,
2764
+ "description": "A notification to the device that did not go out. Since protocol 1.4."
2765
+ },
2766
+ "IDevicePushInboxData": {
2767
+ "type": "object",
2768
+ "properties": {
2769
+ "type": {
2770
+ "type": "string",
2771
+ "const": "inbox"
2772
+ },
2773
+ "key": {
2774
+ "type": "string",
2775
+ "description": "The notification's key: base64url of HMAC-SHA256 under the registration's own random salt over the item's id. It names nothing, and the same item has the same key for as long as the registration stands, across restarts of the host, so a notification sent again replaces the one shown (iOS: `apns-collapse-id`; Android: the notification's tag), and a `clear` removes it."
2776
+ },
2777
+ "kind": {
2778
+ "$ref": "#/components/schemas/TDeviceInboxKind"
2779
+ },
2780
+ "badge": {
2781
+ "type": "string",
2782
+ "description": "The number of items in the Inbox after this one came, in decimal: the app's badge (iOS: also `aps.badge`)."
2783
+ },
2784
+ "body": {
2785
+ "type": "string",
2786
+ "description": "Previews off: `devicePushSentences` for the kind. Previews on: the item's title, one line of at most 280 characters."
2787
+ },
2788
+ "title": {
2789
+ "type": "string",
2790
+ "description": "Previews on only: where the item lives, such as the session's name, `Driver` or the ticket's key and title."
2791
+ },
2792
+ "itemId": {
2793
+ "type": "string",
2794
+ "description": "Previews on only: the item's id, as `device.inbox.list` names it."
2795
+ }
2796
+ },
2797
+ "required": [
2798
+ "type",
2799
+ "key",
2800
+ "kind",
2801
+ "badge",
2802
+ "body"
2803
+ ],
2804
+ "additionalProperties": false,
2805
+ "description": "One Inbox item that came: an alert (iOS: thread `inbox`, interruption level `active`; Android: channel Inbox). With previews off it says only the kind's fixed sentence; with previews on also where the item lives, what it asks and its id. Tapping it opens the Inbox. Since protocol 1.4."
2806
+ },
2807
+ "IDevicePushReportData": {
2808
+ "type": "object",
2809
+ "properties": {
2810
+ "type": {
2811
+ "type": "string",
2812
+ "const": "report"
2813
+ },
2814
+ "key": {
2815
+ "type": "string",
2816
+ "description": "As an item's key, over the report's name: a newer result of the same report replaces the older one."
2817
+ },
2818
+ "body": {
2819
+ "type": "string",
2820
+ "description": "Previews off: `devicePushReportSentence`. Previews on: the `result:` line."
2821
+ },
2822
+ "title": {
2823
+ "type": "string",
2824
+ "description": "Previews on only: the report's name."
2825
+ }
2826
+ },
2827
+ "required": [
2828
+ "type",
2829
+ "key",
2830
+ "body"
2831
+ ],
2832
+ "additionalProperties": false,
2833
+ "description": "A direct report's new `result:` line, sent only to a registration with `reports` (iOS: thread `reports`, interruption level `passive`; Android: channel Reports, low importance). It leaves the badge alone: a result waits for nobody. Since protocol 1.4."
2834
+ },
2835
+ "IDevicePushSummaryData": {
2836
+ "type": "object",
2837
+ "properties": {
2838
+ "type": {
2839
+ "type": "string",
2840
+ "const": "summary"
2841
+ },
2842
+ "key": {
2843
+ "type": "string",
2844
+ "description": "The registration's one summary key, the same for every summary, so a later summary replaces an earlier one."
2845
+ },
2846
+ "count": {
2847
+ "type": "string",
2848
+ "description": "The number of items that came, in decimal."
2849
+ },
2850
+ "badge": {
2851
+ "type": "string",
2852
+ "description": "The number of items in the Inbox, in decimal: the app's badge."
2853
+ },
2854
+ "body": {
2855
+ "type": "string",
2856
+ "description": "`devicePushSummarySentence`."
2857
+ }
2858
+ },
2859
+ "required": [
2860
+ "type",
2861
+ "key",
2862
+ "count",
2863
+ "badge",
2864
+ "body"
2865
+ ],
2866
+ "additionalProperties": false,
2867
+ "description": "More than four items came at once: one notification says so (iOS: thread `inbox`, level `active`; Android: channel Inbox) instead of one per item, with no item's kind, place or id. Since protocol 1.4."
2868
+ },
2869
+ "IDevicePushTestData": {
2870
+ "type": "object",
2871
+ "properties": {
2872
+ "type": {
2873
+ "type": "string",
2874
+ "const": "test"
2875
+ },
2876
+ "key": {
2877
+ "type": "string",
2878
+ "description": "The registration's one test key, the same for every test, so a later test replaces an earlier one."
2879
+ },
2880
+ "body": {
2881
+ "type": "string",
2882
+ "description": "`devicePushTestSentence`."
2883
+ }
2884
+ },
2885
+ "required": [
2886
+ "type",
2887
+ "key",
2888
+ "body"
2889
+ ],
2890
+ "additionalProperties": false,
2891
+ "description": "The owner's test notification, which the owner sends on the host to see that notifications reach the device (iOS: thread `inbox`, interruption level `active`; Android: channel Inbox). It names no item and leaves the badge alone; tapping it opens the Inbox. Since protocol 1.4."
2892
+ },
2627
2893
  "IDeviceQuestion": {
2628
2894
  "type": "object",
2629
2895
  "properties": {
@@ -3937,6 +4203,20 @@
3937
4203
  ],
3938
4204
  "description": "One thing that waits for the owner. Since protocol 1.2."
3939
4205
  },
4206
+ "TDeviceInboxKind": {
4207
+ "type": "string",
4208
+ "enum": [
4209
+ "permission",
4210
+ "question",
4211
+ "elicitation",
4212
+ "native_wait",
4213
+ "driver",
4214
+ "deploy_go",
4215
+ "window_go",
4216
+ "ticket_question"
4217
+ ],
4218
+ "description": "What an Inbox item is, in the order the Inbox lists the kinds: a permission, a question, an MCP form, a wait the harness shows in its own client, the driver's `needs input:` turn, a deploy plan's go, a maintenance window's go, a ticket question. Since protocol 1.2."
4219
+ },
3940
4220
  "TDeviceInboxWhere": {
3941
4221
  "anyOf": [
3942
4222
  {
@@ -4044,6 +4324,53 @@
4044
4324
  ],
4045
4325
  "description": "Whether a pool's account takes new work now, or why not. Since protocol 1.3."
4046
4326
  },
4327
+ "TDevicePushData": {
4328
+ "anyOf": [
4329
+ {
4330
+ "$ref": "#/components/schemas/IDevicePushInboxData"
4331
+ },
4332
+ {
4333
+ "$ref": "#/components/schemas/IDevicePushSummaryData"
4334
+ },
4335
+ {
4336
+ "$ref": "#/components/schemas/IDevicePushReportData"
4337
+ },
4338
+ {
4339
+ "$ref": "#/components/schemas/IDevicePushTestData"
4340
+ },
4341
+ {
4342
+ "$ref": "#/components/schemas/IDevicePushClearData"
4343
+ }
4344
+ ],
4345
+ "description": "What a notification from the host carries, the same for both platforms, each value a string because FCM data carries only strings: FCM sends it as a data-only message's `data` (the Android app builds the notification itself), APNs as the payload's `agl` object beside `aps` (an alert push for `inbox`, `summary`, `report` and `test`, a background push for `clear`). No notification carries a session's or a ticket's id with previews off. A later minor may add keys and types: an app ignores keys it does not know, and a notification whose `type` it does not know, except an iOS alert push, which the system presents from `aps` without running the app. Since protocol 1.4."
4346
+ },
4347
+ "TDevicePushEnvironment": {
4348
+ "type": "string",
4349
+ "enum": [
4350
+ "sandbox",
4351
+ "production"
4352
+ ],
4353
+ "description": "The APNs environment a device token belongs to: `sandbox` for a development build, else `production`. Since protocol 1.4."
4354
+ },
4355
+ "TDevicePushFailureReason": {
4356
+ "type": "string",
4357
+ "enum": [
4358
+ "credential_refused",
4359
+ "refused",
4360
+ "rate_limited",
4361
+ "service_failed",
4362
+ "unreachable"
4363
+ ],
4364
+ "description": "Why a notification to a device did not go out: `credential_refused`, Apple or Google refused the host's credential for the platform, and the host sends nothing on it until the owner sets the credential again; `refused`, the push service refused the notification itself; `rate_limited`, it asked the host to send less; `service_failed`, it failed the request; `unreachable`, the host could not reach it. A later minor may add a reason: an app shows one it does not know as a failure without a named cause. Since protocol 1.4."
4365
+ },
4366
+ "TDevicePushPlatform": {
4367
+ "type": "string",
4368
+ "enum": [
4369
+ "apns",
4370
+ "fcm"
4371
+ ],
4372
+ "description": "The push service a device registers its token with: Apple's (APNs) or Firebase Cloud Messaging. Since protocol 1.4."
4373
+ },
4047
4374
  "TDeviceRefusalCode": {
4048
4375
  "type": "string",
4049
4376
  "enum": [