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
@@ -17,7 +17,7 @@
17
17
  import type { ITypedRequest, implementsTR } from '@api.global/typedrequest-interfaces';
18
18
 
19
19
  /** The device protocol this controller speaks. */
20
- export const deviceProtocolVersion = { major: 1, minor: 3 } as const;
20
+ export const deviceProtocolVersion = { major: 1, minor: 4 } as const;
21
21
 
22
22
  /** The scheme of a pairing payload: `agl-pair:?origin=<https origin>&controller=<controller id>&code=<base64url>`. */
23
23
  export const devicePairingScheme = 'agl-pair' as const;
@@ -809,8 +809,177 @@ export interface IDeviceHostDevice {
809
809
  * @asType integer
810
810
  */
811
811
  lastSeenAt?: number;
812
+ /** Its notifications, while it is registered for them; absent while it is not. Since protocol 1.4. */
813
+ push?: IDeviceHostPush;
814
+ }
815
+
816
+ /** The push service a device registers its token with: Apple's (APNs) or Firebase Cloud Messaging. Since protocol 1.4. */
817
+ export type TDevicePushPlatform = 'apns' | 'fcm';
818
+
819
+ /** The APNs environment a device token belongs to: `sandbox` for a development build, else `production`. Since protocol 1.4. */
820
+ export type TDevicePushEnvironment = 'sandbox' | 'production';
821
+
822
+ /**
823
+ * Why a notification to a device did not go out: `credential_refused`, Apple or Google refused the host's credential
824
+ * for the platform, and the host sends nothing on it until the owner sets the credential again; `refused`, the push
825
+ * service refused the notification itself; `rate_limited`, it asked the host to send less; `service_failed`, it failed
826
+ * the request; `unreachable`, the host could not reach it. A later minor may add a reason: an app shows one it does not
827
+ * know as a failure without a named cause. Since protocol 1.4.
828
+ */
829
+ export type TDevicePushFailureReason = 'credential_refused' | 'refused' | 'rate_limited' | 'service_failed' | 'unreachable';
830
+
831
+ /** A notification to the device that did not go out. Since protocol 1.4. */
832
+ export interface IDevicePushFailure {
833
+ /**
834
+ * Unix milliseconds of the failed send.
835
+ * @asType integer
836
+ */
837
+ at: number;
838
+ reason: TDevicePushFailureReason;
839
+ }
840
+
841
+ /**
842
+ * The notifications a device registered for, as the host sends them: never its token. Since protocol 1.4.
843
+ */
844
+ export interface IDeviceHostPush {
845
+ /** Whether the device asked for direct report results too, besides what waits in the Inbox. */
846
+ reports: boolean;
847
+ /**
848
+ * Whether notifications carry previews: where an item lives, what it asks and its id (`IDevicePushInboxData`). One
849
+ * setting for every device of the host, which only the owner changes on the host; off unless the owner turns it on.
850
+ */
851
+ previews: boolean;
852
+ /**
853
+ * Whether the host can send the device notifications now: it holds a credential for the device's platform that Apple
854
+ * or Google did not refuse. While it does not, the registration stays and nothing is sent until the owner sets the
855
+ * credential on the host.
856
+ */
857
+ available: boolean;
858
+ /** The last notification to the device that did not go out, while none went out after it. */
859
+ lastFailure?: IDevicePushFailure;
860
+ }
861
+
862
+ /**
863
+ * A notification's text with previews off for an item of each kind: one fixed sentence that says only the kind.
864
+ * Since protocol 1.4.
865
+ */
866
+ export const devicePushSentences: Readonly<Record<TDeviceInboxKind, string>> = {
867
+ permission: 'A session waits for your permission.',
868
+ question: 'A session asks you a question.',
869
+ elicitation: 'A session asks you to fill in a form.',
870
+ native_wait: 'A session waits for you on the host.',
871
+ driver: 'The driver needs your input.',
872
+ deploy_go: 'A deploy waits for your go.',
873
+ window_go: 'A maintenance window waits for your go.',
874
+ ticket_question: 'A ticket asks you a question.',
875
+ };
876
+
877
+ /** A summary notification's text. Since protocol 1.4. */
878
+ export const devicePushSummarySentence = 'New items wait for you in the Inbox.';
879
+
880
+ /** A direct report's notification text with previews off. Since protocol 1.4. */
881
+ export const devicePushReportSentence = 'A direct report has a new result.';
882
+
883
+ /** The text of the owner's test notification. Since protocol 1.4. */
884
+ export const devicePushTestSentence = 'Push from AGL works.';
885
+
886
+ /**
887
+ * One Inbox item that came: an alert (iOS: thread `inbox`, interruption level `active`; Android: channel Inbox). With
888
+ * previews off it says only the kind's fixed sentence; with previews on also where the item lives, what it asks and
889
+ * its id. Tapping it opens the Inbox. Since protocol 1.4.
890
+ */
891
+ export interface IDevicePushInboxData {
892
+ type: 'inbox';
893
+ /**
894
+ * The notification's key: base64url of HMAC-SHA256 under the registration's own random salt over the item's id. It
895
+ * names nothing, and the same item has the same key for as long as the registration stands, across restarts of the
896
+ * host, so a notification sent again replaces the one shown (iOS: `apns-collapse-id`; Android: the notification's
897
+ * tag), and a `clear` removes it.
898
+ */
899
+ key: string;
900
+ kind: TDeviceInboxKind;
901
+ /** The number of items in the Inbox after this one came, in decimal: the app's badge (iOS: also `aps.badge`). */
902
+ badge: string;
903
+ /** Previews off: `devicePushSentences` for the kind. Previews on: the item's title, one line of at most 280 characters. */
904
+ body: string;
905
+ /** Previews on only: where the item lives, such as the session's name, `Driver` or the ticket's key and title. */
906
+ title?: string;
907
+ /** Previews on only: the item's id, as `device.inbox.list` names it. */
908
+ itemId?: string;
909
+ }
910
+
911
+ /**
912
+ * More than four items came at once: one notification says so (iOS: thread `inbox`, level `active`; Android: channel
913
+ * Inbox) instead of one per item, with no item's kind, place or id. Since protocol 1.4.
914
+ */
915
+ export interface IDevicePushSummaryData {
916
+ type: 'summary';
917
+ /** The registration's one summary key, the same for every summary, so a later summary replaces an earlier one. */
918
+ key: string;
919
+ /** The number of items that came, in decimal. */
920
+ count: string;
921
+ /** The number of items in the Inbox, in decimal: the app's badge. */
922
+ badge: string;
923
+ /** `devicePushSummarySentence`. */
924
+ body: string;
925
+ }
926
+
927
+ /**
928
+ * A direct report's new `result:` line, sent only to a registration with `reports` (iOS: thread `reports`,
929
+ * interruption level `passive`; Android: channel Reports, low importance). It leaves the badge alone: a result waits
930
+ * for nobody. Since protocol 1.4.
931
+ */
932
+ export interface IDevicePushReportData {
933
+ type: 'report';
934
+ /** As an item's key, over the report's name: a newer result of the same report replaces the older one. */
935
+ key: string;
936
+ /** Previews off: `devicePushReportSentence`. Previews on: the `result:` line. */
937
+ body: string;
938
+ /** Previews on only: the report's name. */
939
+ title?: string;
940
+ }
941
+
942
+ /**
943
+ * The owner's test notification, which the owner sends on the host to see that notifications reach the device (iOS:
944
+ * thread `inbox`, interruption level `active`; Android: channel Inbox). It names no item and leaves the badge alone;
945
+ * tapping it opens the Inbox. Since protocol 1.4.
946
+ */
947
+ export interface IDevicePushTestData {
948
+ type: 'test';
949
+ /** The registration's one test key, the same for every test, so a later test replaces an earlier one. */
950
+ key: string;
951
+ /** `devicePushTestSentence`. */
952
+ body: string;
953
+ }
954
+
955
+ /**
956
+ * Items left the Inbox: remove their notifications (Android cancels them by tag; on iOS it is a background push, which
957
+ * the system may hold back, so an app also matches its notifications against `device.inbox.list` on every connect).
958
+ * Since protocol 1.4.
959
+ */
960
+ export interface IDevicePushClearData {
961
+ type: 'clear';
962
+ /** The keys of the notifications to remove, separated by single spaces. */
963
+ keys: string;
964
+ /** The number of items in the Inbox now, in decimal: the app's badge. */
965
+ badge: string;
812
966
  }
813
967
 
968
+ /**
969
+ * What a notification from the host carries, the same for both platforms, each value a string because FCM data carries
970
+ * only strings: FCM sends it as a data-only message's `data` (the Android app builds the notification itself), APNs as
971
+ * the payload's `agl` object beside `aps` (an alert push for `inbox`, `summary`, `report` and `test`, a background push
972
+ * for `clear`). No notification carries a session's or a ticket's id with previews off. A later minor may add keys and
973
+ * types: an app ignores keys it does not know, and a notification whose `type` it does not know, except an iOS alert
974
+ * push, which the system presents from `aps` without running the app. Since protocol 1.4.
975
+ */
976
+ export type TDevicePushData =
977
+ | IDevicePushInboxData
978
+ | IDevicePushSummaryData
979
+ | IDevicePushReportData
980
+ | IDevicePushTestData
981
+ | IDevicePushClearData;
982
+
814
983
  /**
815
984
  * Why a section was not read: `not_running`, what answers it does not run now (the configuration service the deploy
816
985
  * monitor reads, the inference proxy or the accounts service; it may be starting); `outdated`, it runs a release this
@@ -1493,6 +1662,40 @@ export interface IReq_DeviceHostGet extends implementsTR<ITypedRequest, IReq_Dev
1493
1662
  };
1494
1663
  }
1495
1664
 
1665
+ /**
1666
+ * Registers this device for notifications of what comes into the Inbox, and with `reports` of the direct reports'
1667
+ * results too: one registration per device, which the next one replaces, so an app registers again with its current
1668
+ * token on every connect. Taken also while the host holds no credential to send with (the answer's `available` says
1669
+ * so). The token stays on the host: no answer, event or log repeats it. Scope `device`. Since protocol 1.4.
1670
+ */
1671
+ export interface IReq_DevicePushRegister extends implementsTR<ITypedRequest, IReq_DevicePushRegister> {
1672
+ method: 'device.push.register';
1673
+ request: {
1674
+ platform: TDevicePushPlatform;
1675
+ /**
1676
+ * APNs: the device token as lowercase hex, 32 to 100 bytes. FCM: the registration token as the Firebase SDK hands
1677
+ * it, 1 to 1024 characters of letters, digits, `_`, `-` and `:`.
1678
+ */
1679
+ token: string;
1680
+ /** APNs only, and required there: the environment the token belongs to. */
1681
+ environment?: TDevicePushEnvironment;
1682
+ /** Whether to notify the direct reports' results too. */
1683
+ reports: boolean;
1684
+ };
1685
+ /** The registration as `device.host.get` shows it. */
1686
+ response: { push: IDeviceHostPush };
1687
+ }
1688
+
1689
+ /**
1690
+ * Ends this device's registration: the host sends it no notification from then on. `removed` says whether it held one.
1691
+ * Scope `device`. Since protocol 1.4.
1692
+ */
1693
+ export interface IReq_DevicePushUnregister extends implementsTR<ITypedRequest, IReq_DevicePushUnregister> {
1694
+ method: 'device.push.unregister';
1695
+ request: {};
1696
+ response: { removed: boolean };
1697
+ }
1698
+
1496
1699
  /**
1497
1700
  * One column of the shared board, as the browser's board shows its cards: the tasks (an epic and its subtasks show on
1498
1701
  * their task's card in the browser; a device opens them with `device.ticket.get`), in the column's order, `limit` from
@@ -1634,6 +1837,8 @@ export const deviceMethods = [
1634
1837
  'device.directreports.list',
1635
1838
  'device.directreport.message',
1636
1839
  'device.host.get',
1840
+ 'device.push.register',
1841
+ 'device.push.unregister',
1637
1842
  'device.board.list',
1638
1843
  'device.ticket.get',
1639
1844
  'device.ticket.comment',
@@ -38,3 +38,4 @@ export * from './metrics.js';
38
38
  export * from './proxycapacity.js';
39
39
  export * from './devices.js';
40
40
  export * from './requests.devices.js';
41
+ export * from './push.js';
@@ -5,6 +5,7 @@ import { controllerMcpTicketMethods, type TControllerMcpTicketTypedRequest } fro
5
5
  import { controllerMcpFleetMethods, type TControllerMcpFleetTypedRequest } from './requests.fleet.js';
6
6
  import { controllerMcpSessionFeedMethods, type TControllerMcpSessionFeedTypedRequest } from './sessionfeed.js';
7
7
  import { controllerMcpDeployMethods, type TControllerMcpDeployTypedRequest } from './deployments.js';
8
+ import { controllerMcpPushMethods, type TControllerMcpPushTypedRequest } from './push.js';
8
9
  import * as plugins from './plugins.js';
9
10
  import type { IProxyCapacityAnswer, IProxyCapacityRequest } from './proxycapacity.js';
10
11
  import type { IReq_ControllerMcpWorkerEnroll, IWorkerCallerSubject } from './workercallers.js';
@@ -68,6 +69,7 @@ export const controllerMcpMethods = [
68
69
  ...controllerMcpFleetWorkerMethods,
69
70
  ...controllerMcpSessionFeedMethods,
70
71
  ...controllerMcpDeployMethods,
72
+ ...controllerMcpPushMethods,
71
73
  'agl.mcp.worker.enroll',
72
74
  ] as const;
73
75
  export type TControllerMcpMethod = (typeof controllerMcpMethods)[number];
@@ -492,6 +494,7 @@ export type TControllerMcpTypedRequest =
492
494
  | TControllerMcpFleetWorkerTypedRequest
493
495
  | TControllerMcpSessionFeedTypedRequest
494
496
  | TControllerMcpDeployTypedRequest
497
+ | TControllerMcpPushTypedRequest
495
498
  | IReq_ControllerMcpSettingsGet
496
499
  | IReq_ControllerMcpSettingsUpdate
497
500
  | TControllerMcpWorkspaceTypedRequest
@@ -0,0 +1,162 @@
1
+ import type * as plugins from './plugins.js';
2
+ import type { TDevicePushEnvironment, TDevicePushFailureReason, TDevicePushPlatform } from './devices.js';
3
+
4
+ /**
5
+ * Notifications from the host (AGL-1639): the push settings the owner sets with `agl push` against the running
6
+ * controller, through its private channel with the local owner capability. The answers name what the host holds for
7
+ * each push service (key id, team id, topic, Firebase project, service account address), never a key, a token or a
8
+ * device's push token.
9
+ */
10
+
11
+ /**
12
+ * What the host holds for one push service: `unset`, no credential; `ready`, a credential it sends with;
13
+ * `refused`, Apple or Google refused it, and nothing is sent on the platform until the owner sets it again;
14
+ * `unreadable`, the stored credential cannot be read or unsealed on this machine, so the owner sets it again.
15
+ */
16
+ export type TPushCredentialState = 'unset' | 'ready' | 'refused' | 'unreadable';
17
+
18
+ /** A send that failed, as `agl push status` shows it: the reason and, when the push service named one, its code. */
19
+ export interface IPushFailureStatus {
20
+ /** Unix milliseconds. */
21
+ at: number;
22
+ reason: TDevicePushFailureReason;
23
+ /** The push service's own code (an APNs `reason`, an FCM `errorCode` or an OAuth `error`), never its message. */
24
+ vendorReason?: string;
25
+ /**
26
+ * Set when the push service refused while its clock and the host's were apart (Google's `invalid_grant` with its
27
+ * `Date` more than 60 s off the host's clock): the service's clock minus the host's, in milliseconds, so a positive
28
+ * value is a host clock behind. The send is `service_failed` and tried again, the credential kept.
29
+ */
30
+ clockSkewMs?: number;
31
+ }
32
+
33
+ /** A clock skew as `agl push status` and the failure journal name it: how far apart, and which clock is behind. */
34
+ export const pushClockSkewText = (clockSkewMsArg: number): string => (
35
+ `${Math.round(Math.abs(clockSkewMsArg) / 1000)} s apart, the host's clock ${clockSkewMsArg > 0 ? 'behind' : 'ahead'}`
36
+ );
37
+
38
+ /** What the host holds for Apple's push service. */
39
+ export interface IPushApnsStatus {
40
+ state: TPushCredentialState;
41
+ /** The key's 10-character id; absent while unset. */
42
+ keyId?: string;
43
+ /** The 10-character Apple team id; absent while unset. */
44
+ teamId?: string;
45
+ /** The app's bundle id, the topic every notification names; absent while unset. */
46
+ topic?: string;
47
+ /** Unix milliseconds the credential was set. */
48
+ setAt?: number;
49
+ /** While `refused`: when and why Apple refused the credential. */
50
+ refused?: IPushFailureStatus;
51
+ /** The paired devices registered for APNs notifications. */
52
+ registrations: number;
53
+ /** The last send on the platform that failed since the controller started. */
54
+ lastFailure?: IPushFailureStatus;
55
+ }
56
+
57
+ /** What the host holds for Firebase Cloud Messaging. */
58
+ export interface IPushFcmStatus {
59
+ state: TPushCredentialState;
60
+ /** The Firebase project id; absent while unset. */
61
+ projectId?: string;
62
+ /** The service account's address; absent while unset. */
63
+ clientEmail?: string;
64
+ /** Unix milliseconds the credential was set. */
65
+ setAt?: number;
66
+ /** While `refused`: when and why Google refused the credential. */
67
+ refused?: IPushFailureStatus;
68
+ /** The paired devices registered for FCM notifications. */
69
+ registrations: number;
70
+ /** The last send on the platform that failed since the controller started. */
71
+ lastFailure?: IPushFailureStatus;
72
+ }
73
+
74
+ /** The host's push settings: one for every device of the host. */
75
+ export interface IPushStatus {
76
+ /** Whether notifications carry previews (`IDevicePushInboxData`); off unless the owner turns it on. */
77
+ previews: boolean;
78
+ apns: IPushApnsStatus;
79
+ fcm: IPushFcmStatus;
80
+ }
81
+
82
+ /** A change to the push settings: the settings after it, and whether it changed anything. */
83
+ export interface IPushChange {
84
+ changed: boolean;
85
+ status: IPushStatus;
86
+ }
87
+
88
+ /**
89
+ * What the owner's test notification came to on one device: `delivered`; `unregistered`, the push service no longer
90
+ * knows the device's token (the registration was removed, and the app registers again on its next connect);
91
+ * `unavailable`, the host holds no usable credential for the device's platform, so nothing was sent; `no_answer`, the
92
+ * push service did not answer within `pushTestAnswerWaitMs`, and the notification may still arrive; or why it did not go out.
93
+ */
94
+ export type TPushTestOutcome = 'delivered' | 'unregistered' | 'unavailable' | 'no_answer' | TDevicePushFailureReason;
95
+
96
+ /**
97
+ * How long `agl push test` waits for each device's answer: under the CLI's 30 s request timeout, although one attempt may
98
+ * take a token request, a send, a token asked anew and a send again, at 15 s each.
99
+ */
100
+ export const pushTestAnswerWaitMs = 20_000;
101
+
102
+ /** One registered device's answer to `agl push test`: never its token. */
103
+ export interface IPushTestResult {
104
+ deviceId: string;
105
+ name: string;
106
+ platform: TDevicePushPlatform;
107
+ environment?: TDevicePushEnvironment;
108
+ outcome: TPushTestOutcome;
109
+ /** The push service's own code, when it named one. */
110
+ vendorReason?: string;
111
+ }
112
+
113
+ /** Every `agl push` request: the request without the owner capability, and its answer. */
114
+ export interface IPushOperations {
115
+ status: { request: Record<never, never>; response: IPushStatus };
116
+ 'apns.set': {
117
+ /** `signingKey` is the AuthKey .p8 file's text, which the controller seals and never repeats. */
118
+ request: { keyId: string; teamId: string; topic?: string; signingKey: string };
119
+ response: IPushChange;
120
+ };
121
+ 'apns.unset': { request: Record<never, never>; response: IPushChange };
122
+ 'fcm.set': {
123
+ /** `serviceAccount` is the service account key file's JSON text, which the controller seals and never repeats. */
124
+ request: { serviceAccount: string };
125
+ response: IPushChange;
126
+ };
127
+ 'fcm.unset': { request: Record<never, never>; response: IPushChange };
128
+ previews: { request: { previews: boolean }; response: IPushChange };
129
+ /** Sends the test notification (`IDevicePushTestData`) to every registered device, or to the one `deviceId` names. */
130
+ test: { request: { deviceId?: string }; response: { results: IPushTestResult[] } };
131
+ }
132
+ export type TPushOperation = keyof IPushOperations;
133
+ export const pushOperations = ['status', 'apns.set', 'apns.unset', 'fcm.set', 'fcm.unset', 'previews', 'test'] as const satisfies readonly TPushOperation[];
134
+
135
+ /** The request fields that carry a secret: no answer, log or error repeats them, and the request's echo redacts them. */
136
+ export const pushSecretRequestFields = ['signingKey', 'serviceAccount'] as const;
137
+
138
+ /** Why the controller refused an `agl push` request; its sentence names the cause, never the input. */
139
+ export const pushErrorCodes = ['push_credential_invalid', 'push_device_unknown', 'push_unavailable'] as const;
140
+ export type TPushErrorCode = (typeof pushErrorCodes)[number];
141
+
142
+ export const controllerMcpPushMethods = [
143
+ 'agl.mcp.push.status',
144
+ 'agl.mcp.push.apns.set',
145
+ 'agl.mcp.push.apns.unset',
146
+ 'agl.mcp.push.fcm.set',
147
+ 'agl.mcp.push.fcm.unset',
148
+ 'agl.mcp.push.previews',
149
+ 'agl.mcp.push.test',
150
+ ] as const satisfies readonly `agl.mcp.push.${TPushOperation}`[];
151
+ export type TControllerMcpPushMethod = (typeof controllerMcpPushMethods)[number];
152
+ export type TControllerMcpPushRequest<TOperation extends TPushOperation> = {
153
+ method: `agl.mcp.push.${TOperation}`;
154
+ request: IPushOperations[TOperation]['request'] & { ownerToken: string };
155
+ response: IPushOperations[TOperation]['response'];
156
+ } & plugins.typedrequestInterfaces.ITypedRequest;
157
+ export type TControllerMcpPushTypedRequest = { [TOperation in TPushOperation]: TControllerMcpPushRequest<TOperation> }[TPushOperation];
158
+
159
+ /** The operation a private push method names. */
160
+ export const pushOperationOf = (methodArg: TControllerMcpPushMethod): TPushOperation => (
161
+ methodArg.slice('agl.mcp.push.'.length) as TPushOperation
162
+ );
@@ -60,12 +60,18 @@ export interface IFleetWorkerCallerHooks {
60
60
  }>;
61
61
  getWorkerCallerStatus(launchId: string): IWorkerCallerReadiness;
62
62
  /**
63
- * Revokes one launch, or the current launch of a worker, also one the controller kept from before a restart. Every
64
- * reason but `generation_change` revokes it for good: its kept binding is deleted with it.
63
+ * Revokes one launch, or the current launch of a worker, also one the controller kept from before a restart or
64
+ * recorded for a bridge it identified by its process. Every reason but `generation_change` revokes it for good: its
65
+ * kept binding is deleted with it.
65
66
  */
66
67
  revokeWorkerCaller(request: ({ launchId: string } | { workerId: string }) & {
67
68
  reason: 'failure' | 'stop' | 'replacement' | 'generation_change' | 'cancelled';
68
69
  }): Promise<void>;
70
+ /**
71
+ * The fleet adopted or re-bound a worker: every process whose bridge the controller refused to identify is
72
+ * identified afresh at its bridge's next call.
73
+ */
74
+ clearCallerRefusals(): void;
69
75
  }
70
76
 
71
77
  /** The background job a Claude worker's launch is bound to, as the controller asks the fleet about it. */
@@ -87,6 +93,27 @@ export type TWorkerClaudeJobObservation =
87
93
  | { state: 'ended'; reason: string }
88
94
  | { state: 'unproven'; reason: string };
89
95
 
96
+ /**
97
+ * The process an MCP bridge runs under (its direct parent), which the controller proved to run an installed Claude Code
98
+ * release, and that process's own parent, as the controller asks the fleet whose job it is.
99
+ */
100
+ export interface IWorkerClaudeProcessRequest {
101
+ pid: number;
102
+ parentPid: number;
103
+ }
104
+
105
+ /**
106
+ * What the fleet names a process for: `identified` when a fresh inventory of the fleet's Claude homes lists it exactly
107
+ * once, as the process of a background job with an agent id whose session it lists once, and exactly one stored worker
108
+ * of any owner, a live Claude worker without a dispatch in flight or a lost one, binds that session under the home that
109
+ * lists it. Otherwise `refused` by the check that failed: `parent` when the process is not the job's but its own parent
110
+ * is (the bridge runs one level too deep), `inventory` or `worker`; with the worker when one is named, and whether the
111
+ * refusal holds while the process runs (`forGood`) or may pass soon.
112
+ */
113
+ export type TWorkerClaudeProcessIdentification =
114
+ | { state: 'identified'; workerId: string; projectId: string; nativeSessionId: string; jobId: string }
115
+ | { state: 'refused'; check: 'parent' | 'inventory' | 'worker'; reason: string; forGood: boolean; workerId?: string; nativeSessionId?: string };
116
+
90
117
  export interface IWorkerCallerSubject {
91
118
  kind: 'worker_launch';
92
119
  launchId: string;
@@ -101,10 +128,15 @@ export interface IWorkerCallerSubject {
101
128
  workerName: string;
102
129
  }
103
130
 
131
+ /**
132
+ * A bridge enrolls with the launch its MCP configuration gave it, a Codex challenge or thread, or, holding none, its
133
+ * process id alone: the controller then identifies it by its process chain.
134
+ */
104
135
  export type TWorkerCallerEnrollment = { bridgePid: number } & (
105
136
  | { launchId: string; launchGeneration: string }
106
137
  | { challenge: string; nativeThreadId: string }
107
138
  | { nativeThreadId: string }
139
+ | Record<never, never>
108
140
  );
109
141
 
110
142
  export interface IWorkerCallerEnrollmentResponse extends IWorkerCallerReadiness {
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '43.7.0',
6
+ version: '43.8.0',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }