agl 43.1.0 → 43.3.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 (259) hide show
  1. package/changelog.md +32 -0
  2. package/dist_serve/bundle.js +5950 -5530
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +31 -31
  5. package/dist_serve/bundle.js.third-party-notices.txt +31 -31
  6. package/dist_ts/00_commitinfo_data.js +1 -1
  7. package/dist_ts/aglapi/aglapisurface.document.js +521 -17
  8. package/dist_ts/aglapi/interfaces.d.ts +3 -0
  9. package/dist_ts/aglapi/interfaces.js +2 -1
  10. package/dist_ts/classes.accountsactions.d.ts +3 -1
  11. package/dist_ts/classes.accountsactions.js +21 -3
  12. package/dist_ts/classes.authmodels.js +17 -4
  13. package/dist_ts/classes.authstore.js +16 -2
  14. package/dist_ts/classes.claudeharness.d.ts +16 -0
  15. package/dist_ts/classes.claudeharness.js +24 -2
  16. package/dist_ts/classes.cli.d.ts +4 -2
  17. package/dist_ts/classes.cli.js +6 -3
  18. package/dist_ts/classes.codexclientadapter.d.ts +11 -0
  19. package/dist_ts/classes.codexclientadapter.js +14 -2
  20. package/dist_ts/classes.controller.d.ts +175 -11
  21. package/dist_ts/classes.controller.js +1213 -173
  22. package/dist_ts/classes.controllerdevices.d.ts +2 -0
  23. package/dist_ts/classes.controllerdevices.js +6 -1
  24. package/dist_ts/classes.controllermanagement.d.ts +14 -4
  25. package/dist_ts/classes.controllermanagement.js +20 -2
  26. package/dist_ts/classes.gatewayclient.d.ts +115 -0
  27. package/dist_ts/classes.gatewayclient.js +336 -0
  28. package/dist_ts/classes.gatewayclientstore.d.ts +97 -0
  29. package/dist_ts/classes.gatewayclientstore.js +261 -0
  30. package/dist_ts/classes.inbox.d.ts +72 -0
  31. package/dist_ts/classes.inbox.js +231 -0
  32. package/dist_ts/classes.inferencerouter.d.ts +19 -0
  33. package/dist_ts/classes.inferencerouter.js +15 -3
  34. package/dist_ts/classes.inferenceservice.d.ts +9 -0
  35. package/dist_ts/classes.inferenceservice.js +28 -2
  36. package/dist_ts/classes.mcpclient.d.ts +4 -1
  37. package/dist_ts/classes.mcpclient.js +42 -6
  38. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -1
  39. package/dist_ts/classes.mcpcontrollerhost.js +11 -1
  40. package/dist_ts/classes.mcptools.d.ts +3 -3
  41. package/dist_ts/classes.mcptools.js +38 -8
  42. package/dist_ts/classes.mcpvalidation.d.ts +5 -0
  43. package/dist_ts/classes.mcpvalidation.js +38 -2
  44. package/dist_ts/classes.nativesessions.d.ts +17 -4
  45. package/dist_ts/classes.nativesessions.js +41 -9
  46. package/dist_ts/classes.opencodeclient.d.ts +23 -2
  47. package/dist_ts/classes.opencodeclient.js +47 -3
  48. package/dist_ts/classes.proxycontrol.d.ts +11 -0
  49. package/dist_ts/classes.proxycontrol.js +7 -1
  50. package/dist_ts/classes.proxycontrolclient.d.ts +17 -0
  51. package/dist_ts/classes.proxycontrolclient.js +35 -1
  52. package/dist_ts/classes.proxydaemon.js +8 -1
  53. package/dist_ts/classes.proxymonitor.d.ts +7 -0
  54. package/dist_ts/classes.proxymonitor.js +13 -1
  55. package/dist_ts/classes.publishedset.d.ts +38 -0
  56. package/dist_ts/classes.publishedset.js +50 -0
  57. package/dist_ts/classes.sessionfeed.d.ts +3 -3
  58. package/dist_ts/classes.sessionfeed.js +18 -26
  59. package/dist_ts/classes.systemmetricssampler.d.ts +6 -0
  60. package/dist_ts/classes.systemmetricssampler.js +15 -3
  61. package/dist_ts/classes.ticketstore.d.ts +50 -3
  62. package/dist_ts/classes.ticketstore.js +45 -8
  63. package/dist_ts/classes.trustedproxysecrets.d.ts +2 -0
  64. package/dist_ts/classes.trustedproxysecrets.js +5 -1
  65. package/dist_ts/driver/classes.directreports.d.ts +14 -4
  66. package/dist_ts/driver/classes.directreports.js +25 -6
  67. package/dist_ts/driver/classes.driverservice.d.ts +44 -3
  68. package/dist_ts/driver/classes.driverservice.js +50 -16
  69. package/dist_ts/fleet/classes.claudeworkers.d.ts +21 -5
  70. package/dist_ts/fleet/classes.claudeworkers.js +142 -46
  71. package/dist_ts/fleet/classes.codexworkers.d.ts +16 -4
  72. package/dist_ts/fleet/classes.codexworkers.js +22 -5
  73. package/dist_ts/fleet/classes.workercommand.d.ts +6 -1
  74. package/dist_ts/fleet/classes.workercommand.js +15 -4
  75. package/dist_ts/fleet/classes.workers.d.ts +5 -1
  76. package/dist_ts/fleet/classes.workers.js +8 -2
  77. package/dist_ts/fleet/functions.unbounddrivers.js +2 -2
  78. package/dist_ts/fleet/functions.workervalidation.js +2 -2
  79. package/dist_ts/fleet/interfaces.workers.d.ts +21 -3
  80. package/dist_ts/fleet/interfaces.workers.js +1 -1
  81. package/dist_ts/functions.agentmessage.d.ts +3 -0
  82. package/dist_ts/functions.agentmessage.js +4 -1
  83. package/dist_ts/functions.controllermanagementsurface.d.ts +4 -0
  84. package/dist_ts/functions.controllermanagementsurface.js +15 -1
  85. package/dist_ts/functions.deviceapi.d.ts +151 -4
  86. package/dist_ts/functions.deviceapi.js +893 -38
  87. package/dist_ts/functions.fleetworkercli.d.ts +1 -1
  88. package/dist_ts/functions.fleetworkercli.js +11 -8
  89. package/dist_ts/functions.gatewaycli.d.ts +24 -0
  90. package/dist_ts/functions.gatewaycli.js +395 -0
  91. package/dist_ts/functions.gatewayroute.d.ts +135 -0
  92. package/dist_ts/functions.gatewayroute.js +366 -0
  93. package/dist_ts/functions.inferencecli.js +32 -1
  94. package/dist_ts/functions.inferencecliarguments.d.ts +8 -2
  95. package/dist_ts/functions.inferencecliarguments.js +31 -3
  96. package/dist_ts/functions.mcpfleetworkertools.js +2 -2
  97. package/dist_ts/functions.proxycapacity.d.ts +50 -0
  98. package/dist_ts/functions.proxycapacity.js +142 -0
  99. package/dist_ts/functions.proxycapacitycli.d.ts +30 -0
  100. package/dist_ts/functions.proxycapacitycli.js +65 -0
  101. package/dist_ts/functions.remotecli.d.ts +30 -3
  102. package/dist_ts/functions.remotecli.js +44 -18
  103. package/dist_ts/functions.ticketvalidation.js +11 -2
  104. package/dist_ts/interfaces.auth.d.ts +25 -4
  105. package/dist_ts/interfaces.auth.js +15 -1
  106. package/dist_ts/plugins.d.ts +5 -1
  107. package/dist_ts/plugins.js +10 -2
  108. package/dist_ts_authswitch/authority-contract.d.ts +25 -0
  109. package/dist_ts_authswitch/authority-contract.js +1 -1
  110. package/dist_ts_authswitch/authority-overview.d.ts +8 -0
  111. package/dist_ts_authswitch/authority-overview.js +17 -6
  112. package/dist_ts_authswitch/authority-placement.d.ts +20 -16
  113. package/dist_ts_authswitch/authority-placement.js +19 -26
  114. package/dist_ts_authswitch/authority-renewal.d.ts +34 -0
  115. package/dist_ts_authswitch/authority-renewal.js +56 -0
  116. package/dist_ts_authswitch/authority-usagelimit.d.ts +29 -0
  117. package/dist_ts_authswitch/authority-usagelimit.js +66 -2
  118. package/dist_ts_authswitch/authority-usagewindows.d.ts +6 -0
  119. package/dist_ts_authswitch/authority-usagewindows.js +15 -1
  120. package/dist_ts_authswitch/classes.authoritybroker.d.ts +8 -0
  121. package/dist_ts_authswitch/classes.authoritybroker.js +35 -2
  122. package/dist_ts_authswitch/classes.authoritycli.d.ts +1 -0
  123. package/dist_ts_authswitch/classes.authoritycli.js +44 -3
  124. package/dist_ts_authswitch/classes.authorityclient.d.ts +6 -1
  125. package/dist_ts_authswitch/classes.authorityclient.js +12 -4
  126. package/dist_ts_authswitch/classes.authoritydaemon.js +8 -1
  127. package/dist_ts_authswitch/classes.authoritydatabase.js +6 -2
  128. package/dist_ts_authswitch/classes.authoritymodels.d.ts +7 -0
  129. package/dist_ts_authswitch/classes.authoritymodels.js +21 -5
  130. package/dist_ts_interfaces/devices.d.ts +1012 -5
  131. package/dist_ts_interfaces/devices.js +68 -2
  132. package/dist_ts_interfaces/fleetworkers.d.ts +5 -3
  133. package/dist_ts_interfaces/gateway.d.ts +151 -0
  134. package/dist_ts_interfaces/gateway.js +66 -0
  135. package/dist_ts_interfaces/inbox.d.ts +234 -0
  136. package/dist_ts_interfaces/inbox.js +101 -0
  137. package/dist_ts_interfaces/index.d.ts +3 -0
  138. package/dist_ts_interfaces/index.js +4 -1
  139. package/dist_ts_interfaces/interfaces.d.ts +10 -3
  140. package/dist_ts_interfaces/interfaces.js +4 -2
  141. package/dist_ts_interfaces/management.d.ts +4 -4
  142. package/dist_ts_interfaces/management.js +3 -2
  143. package/dist_ts_interfaces/mcprequests.d.ts +48 -6
  144. package/dist_ts_interfaces/mcprequests.js +12 -1
  145. package/dist_ts_interfaces/mcpworkspacerequests.d.ts +4 -1
  146. package/dist_ts_interfaces/mcpworkspacerequests.js +1 -1
  147. package/dist_ts_interfaces/nativesessions.d.ts +16 -3
  148. package/dist_ts_interfaces/plugins.d.ts +2 -1
  149. package/dist_ts_interfaces/plugins.js +4 -2
  150. package/dist_ts_interfaces/proxycapacity.d.ts +99 -0
  151. package/dist_ts_interfaces/proxycapacity.js +74 -0
  152. package/dist_ts_interfaces/requests.accounts.d.ts +21 -0
  153. package/dist_ts_interfaces/requests.accounts.js +3 -1
  154. package/dist_ts_interfaces/requests.d.ts +3 -2
  155. package/dist_ts_interfaces/requests.js +1 -1
  156. package/docs/authswitch.md +20 -1
  157. package/package.json +6 -5
  158. package/readme.md +191 -31
  159. package/ts/00_commitinfo_data.ts +1 -1
  160. package/ts/aglapi/aglapisurface.document.ts +520 -16
  161. package/ts/aglapi/interfaces.ts +1 -0
  162. package/ts/classes.accountsactions.ts +30 -3
  163. package/ts/classes.authmodels.ts +22 -3
  164. package/ts/classes.authstore.ts +15 -1
  165. package/ts/classes.claudeharness.ts +27 -1
  166. package/ts/classes.cli.ts +7 -3
  167. package/ts/classes.codexclientadapter.ts +14 -1
  168. package/ts/classes.controller.ts +1428 -249
  169. package/ts/classes.controllerdevices.ts +6 -0
  170. package/ts/classes.controllermanagement.ts +40 -7
  171. package/ts/classes.gatewayclient.ts +401 -0
  172. package/ts/classes.gatewayclientstore.ts +272 -0
  173. package/ts/classes.inbox.ts +239 -0
  174. package/ts/classes.inferencerouter.ts +27 -2
  175. package/ts/classes.inferenceservice.ts +28 -1
  176. package/ts/classes.mcpclient.ts +42 -3
  177. package/ts/classes.mcpcontrollerhost.ts +15 -0
  178. package/ts/classes.mcptools.ts +42 -9
  179. package/ts/classes.mcpvalidation.ts +32 -1
  180. package/ts/classes.nativesessions.ts +50 -12
  181. package/ts/classes.opencodeclient.ts +55 -4
  182. package/ts/classes.proxycontrol.ts +16 -0
  183. package/ts/classes.proxycontrolclient.ts +30 -0
  184. package/ts/classes.proxydaemon.ts +8 -0
  185. package/ts/classes.proxymonitor.ts +12 -0
  186. package/ts/classes.publishedset.ts +56 -0
  187. package/ts/classes.sessionfeed.ts +17 -20
  188. package/ts/classes.systemmetricssampler.ts +13 -2
  189. package/ts/classes.ticketstore.ts +73 -12
  190. package/ts/classes.trustedproxysecrets.ts +5 -0
  191. package/ts/driver/classes.directreports.ts +25 -6
  192. package/ts/driver/classes.driverservice.ts +75 -14
  193. package/ts/fleet/classes.claudeworkers.ts +112 -39
  194. package/ts/fleet/classes.codexworkers.ts +21 -6
  195. package/ts/fleet/classes.workercommand.ts +14 -4
  196. package/ts/fleet/classes.workers.ts +9 -2
  197. package/ts/fleet/functions.unbounddrivers.ts +1 -1
  198. package/ts/fleet/functions.workervalidation.ts +1 -1
  199. package/ts/fleet/interfaces.workers.ts +20 -5
  200. package/ts/functions.agentmessage.ts +3 -0
  201. package/ts/functions.controllermanagementsurface.ts +15 -0
  202. package/ts/functions.deviceapi.ts +1071 -34
  203. package/ts/functions.fleetworkercli.ts +10 -7
  204. package/ts/functions.gatewaycli.ts +436 -0
  205. package/ts/functions.gatewayroute.ts +429 -0
  206. package/ts/functions.inferencecli.ts +26 -0
  207. package/ts/functions.inferencecliarguments.ts +30 -4
  208. package/ts/functions.mcpfleetworkertools.ts +1 -1
  209. package/ts/functions.proxycapacity.ts +191 -0
  210. package/ts/functions.proxycapacitycli.ts +104 -0
  211. package/ts/functions.remotecli.ts +56 -20
  212. package/ts/functions.ticketvalidation.ts +11 -1
  213. package/ts/interfaces.auth.ts +36 -4
  214. package/ts/plugins.ts +12 -0
  215. package/ts_authswitch/authority-contract.ts +20 -0
  216. package/ts_authswitch/authority-overview.ts +28 -6
  217. package/ts_authswitch/authority-placement.ts +27 -32
  218. package/ts_authswitch/authority-renewal.ts +64 -0
  219. package/ts_authswitch/authority-usagelimit.ts +84 -1
  220. package/ts_authswitch/authority-usagewindows.ts +13 -0
  221. package/ts_authswitch/classes.authoritybroker.ts +34 -1
  222. package/ts_authswitch/classes.authoritycli.ts +49 -2
  223. package/ts_authswitch/classes.authorityclient.ts +14 -4
  224. package/ts_authswitch/classes.authoritydaemon.ts +9 -1
  225. package/ts_authswitch/classes.authoritydatabase.ts +5 -1
  226. package/ts_authswitch/classes.authoritymodels.ts +23 -3
  227. package/ts_authswitch/native-contracts.md +21 -0
  228. package/ts_authswitch/readme.md +1 -1
  229. package/ts_interfaces/devices.schema.json +3573 -603
  230. package/ts_interfaces/devices.ts +1093 -4
  231. package/ts_interfaces/fleetworkers.ts +5 -3
  232. package/ts_interfaces/gateway.ts +242 -0
  233. package/ts_interfaces/inbox.ts +287 -0
  234. package/ts_interfaces/index.ts +3 -0
  235. package/ts_interfaces/interfaces.ts +9 -2
  236. package/ts_interfaces/management.ts +6 -4
  237. package/ts_interfaces/mcprequests.ts +61 -4
  238. package/ts_interfaces/mcpworkspacerequests.ts +4 -2
  239. package/ts_interfaces/nativesessions.ts +17 -3
  240. package/ts_interfaces/plugins.ts +3 -1
  241. package/ts_interfaces/proxycapacity.ts +162 -0
  242. package/ts_interfaces/requests.accounts.ts +20 -0
  243. package/ts_interfaces/requests.ts +4 -0
  244. package/ts_web/00_commitinfo_data.ts +1 -1
  245. package/ts_web/accounts.plugins.ts +4 -2
  246. package/ts_web/classes.accountsreadmodel.ts +33 -0
  247. package/ts_web/classes.browserpresentation.ts +19 -6
  248. package/ts_web/classes.inboxfeed.ts +329 -0
  249. package/ts_web/classes.nativesessionstate.ts +9 -23
  250. package/ts_web/elements.accounts.ts +121 -113
  251. package/ts_web/elements.configurationpane.ts +24 -37
  252. package/ts_web/elements.deployments.ts +66 -2
  253. package/ts_web/elements.devices.ts +4 -17
  254. package/ts_web/elements.flexlimitstrip.ts +21 -70
  255. package/ts_web/elements.harnesscontrollerapp.ts +198 -222
  256. package/ts_web/elements.inbox.ts +808 -0
  257. package/ts_web/functions.inbox.ts +95 -0
  258. package/ts_web/functions.sessioncards.ts +40 -0
  259. package/ts_web/plugins.ts +2 -0
@@ -0,0 +1,272 @@
1
+ import * as plugins from './plugins.js';
2
+ import type { ITpmSecretCodec } from './classes.tpmsecretcodec.js';
3
+ import {
4
+ controllerGatewayProblemCodes,
5
+ type IControllerGatewayDns,
6
+ type IControllerGatewayEnrolment,
7
+ type IControllerGatewayProblem,
8
+ type TControllerGatewayProblemCode,
9
+ } from '../ts_interfaces/index.js';
10
+
11
+ /**
12
+ * One gateway-client credential of a controller with everything it was issued for: the gateway, the client, the
13
+ * route it may write and the token, TPM2-sealed (`TpmSecretCodec`) under a name bound to the controller and the
14
+ * token id. The token's plaintext exists only in the process that uses it, never in a log, a file or the output.
15
+ */
16
+ export interface IControllerGatewayCredential {
17
+ /** The gateway's API base URL; requests go to `<gatewayUrl>/typedrequest`. */
18
+ gatewayUrl: string;
19
+ /** `agl-<installation>-<port>`, type `custom`. */
20
+ gatewayClientId: string;
21
+ /** `controller-<port>`. */
22
+ appId: string;
23
+ hostname: string;
24
+ targetHost: string;
25
+ /** The gateway's id of the token; the seal name binds it. */
26
+ tokenId: string;
27
+ ciphertext: string;
28
+ /** Unix epoch milliseconds: when the gateway issued it (a candidate) or confirmed it (the active credential). */
29
+ at: number;
30
+ }
31
+
32
+ /** What the last sync of a running controller left for `agl remote gateway status` to show while it is stopped. */
33
+ export interface IControllerGatewaySyncRecord {
34
+ /** Unix epoch milliseconds of the last sync that wrote the route. */
35
+ syncedAt?: number;
36
+ dns?: IControllerGatewayDns;
37
+ /** Whether the gateway named the route's source profile as `LOCAL NETWORK` after that sync; false when it named none. */
38
+ sourceProfileVerified?: boolean;
39
+ /** Why the last sync failed; absent when it wrote the route. */
40
+ problem?: IControllerGatewayProblem;
41
+ }
42
+
43
+ export interface IControllerGatewayClientDocument {
44
+ /** `controller:<port>`. */
45
+ id: string;
46
+ /** The credential the controller syncs with, once the gateway confirmed it (`finalizeGatewayClientCredential`). */
47
+ active?: IControllerGatewayCredential;
48
+ /**
49
+ * A credential the gateway issued that is not confirmed yet: sealed and stored before the confirmation is asked for,
50
+ * so a confirmation whose answer is lost is asked for again with the same credential.
51
+ */
52
+ candidate?: IControllerGatewayCredential;
53
+ lastSync?: IControllerGatewaySyncRecord;
54
+ }
55
+
56
+ const isText = (valueArg: unknown, maximumArg: number): valueArg is string => (
57
+ typeof valueArg === 'string' && valueArg.length > 0 && valueArg.length <= maximumArg
58
+ );
59
+
60
+ const isRecordOf = (valueArg: unknown, requiredArg: readonly string[], optionalArg: readonly string[] = []): valueArg is Record<string, unknown> => (
61
+ !!valueArg && typeof valueArg === 'object' && !Array.isArray(valueArg)
62
+ && requiredArg.every((keyArg) => Object.hasOwn(valueArg, keyArg))
63
+ && Object.keys(valueArg).every((keyArg) => requiredArg.includes(keyArg) || optionalArg.includes(keyArg))
64
+ );
65
+
66
+ const isTime = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
67
+
68
+ /** A gateway token id as it may appear in a seal name. */
69
+ const gatewayTokenIdPattern = /^[A-Za-z0-9_.-]{1,64}$/u;
70
+
71
+ const isCredential = (valueArg: unknown): valueArg is IControllerGatewayCredential => (
72
+ isRecordOf(valueArg, ['gatewayUrl', 'gatewayClientId', 'appId', 'hostname', 'targetHost', 'tokenId', 'ciphertext', 'at'])
73
+ && isText(valueArg.gatewayUrl, 2048) && isText(valueArg.gatewayClientId, 128) && isText(valueArg.appId, 128)
74
+ && isText(valueArg.hostname, 253) && isText(valueArg.targetHost, 253)
75
+ && typeof valueArg.tokenId === 'string' && gatewayTokenIdPattern.test(valueArg.tokenId)
76
+ && typeof valueArg.ciphertext === 'string' && /^[A-Za-z0-9_-]{1,131072}$/u.test(valueArg.ciphertext)
77
+ && isTime(valueArg.at)
78
+ );
79
+
80
+ const isSyncRecord = (valueArg: unknown): valueArg is IControllerGatewaySyncRecord => {
81
+ if (!isRecordOf(valueArg, [], ['syncedAt', 'dns', 'sourceProfileVerified', 'problem'])) return false;
82
+ const { syncedAt, dns, sourceProfileVerified, problem } = valueArg;
83
+ return (syncedAt === undefined || isTime(syncedAt))
84
+ && (sourceProfileVerified === undefined || typeof sourceProfileVerified === 'boolean')
85
+ && (dns === undefined || (isRecordOf(dns, ['status', 'owned']) && isText(dns.status, 64) && typeof dns.owned === 'boolean'))
86
+ && (problem === undefined || (isRecordOf(problem, ['code', 'message'])
87
+ && controllerGatewayProblemCodes.includes(problem.code as TControllerGatewayProblemCode)
88
+ && isText(problem.message, 4096)));
89
+ };
90
+
91
+ const assertDocument: (valueArg: unknown) => asserts valueArg is IControllerGatewayClientDocument = (valueArg) => {
92
+ if (!isRecordOf(valueArg, ['id'], ['active', 'candidate', 'lastSync'])
93
+ || typeof valueArg.id !== 'string' || !/^controller:[1-9][0-9]{0,4}$/u.test(valueArg.id)
94
+ || (valueArg.active === undefined && valueArg.candidate === undefined)
95
+ || (valueArg.active !== undefined && !isCredential(valueArg.active))
96
+ || (valueArg.candidate !== undefined && !isCredential(valueArg.candidate))
97
+ || (valueArg.lastSync !== undefined && !isSyncRecord(valueArg.lastSync))) {
98
+ throw new Error('Invalid gateway client record.');
99
+ }
100
+ };
101
+
102
+ @plugins.nosqldb.managed({ collectionName: 'agl_controller_gateway_clients' })
103
+ @plugins.nosqldb.exactPersistence({ assertDocument })
104
+ export class ControllerGatewayClientModel
105
+ extends plugins.nosqldb.SmartDataDbDoc<ControllerGatewayClientModel, IControllerGatewayClientDocument> {
106
+ declare static exact: plugins.nosqldb.TExact<ControllerGatewayClientModel>;
107
+ @plugins.nosqldb.unI() public id!: string;
108
+ @plugins.nosqldb.svDb() public active?: IControllerGatewayCredential;
109
+ @plugins.nosqldb.svDb() public candidate?: IControllerGatewayCredential;
110
+ @plugins.nosqldb.svDb() public lastSync?: IControllerGatewaySyncRecord;
111
+ }
112
+
113
+ const readStored = (controllerIdArg: string) => ControllerGatewayClientModel.exact.findStoredOne({ id: controllerIdArg });
114
+
115
+ type TStoredRecord = NonNullable<Awaited<ReturnType<typeof readStored>>>;
116
+
117
+ export interface IControllerGatewayClientStoreOptions {
118
+ /** `controller:<port>`. */
119
+ controllerId: string;
120
+ /** The controller database's issuer id: a credential is sealed under a name bound to it. */
121
+ issuerId: string;
122
+ codec: ITpmSecretCodec;
123
+ }
124
+
125
+ /** The fields of a credential that say what it was issued for, without the token. */
126
+ export type TControllerGatewayCredentialSpec = Pick<IControllerGatewayCredential,
127
+ 'gatewayUrl' | 'gatewayClientId' | 'appId' | 'hostname' | 'targetHost'>;
128
+
129
+ /** What `agl remote gateway status` and the management status report of an enrolment, without its token. */
130
+ export const controllerGatewayEnrolment = (
131
+ credentialArg: IControllerGatewayCredential,
132
+ portArg: number,
133
+ ): IControllerGatewayEnrolment => ({
134
+ gatewayUrl: credentialArg.gatewayUrl,
135
+ gatewayClientId: credentialArg.gatewayClientId,
136
+ appId: credentialArg.appId,
137
+ hostname: credentialArg.hostname,
138
+ target: { host: credentialArg.targetHost, port: portArg },
139
+ enrolledAt: credentialArg.at,
140
+ });
141
+
142
+ /**
143
+ * A controller's gateway-client record in its database (`agl_controller_gateway_clients`): the active credential, a
144
+ * candidate awaiting the gateway's confirmation, and what the last sync left. Only `agl remote gateway` writes the
145
+ * credentials, against a stopped controller; the running controller writes only `lastSync`.
146
+ */
147
+ export class ControllerGatewayClientStore {
148
+ constructor(private readonly options: IControllerGatewayClientStoreOptions) {}
149
+
150
+ public get controllerId(): string {
151
+ return this.options.controllerId;
152
+ }
153
+
154
+ public async read(): Promise<IControllerGatewayClientDocument | undefined> {
155
+ const stored = await readStored(this.options.controllerId);
156
+ return stored ? ControllerGatewayClientModel.exact.toPersisted(stored) : undefined;
157
+ }
158
+
159
+ /** The token of `credentialArg`, unsealed; the caller wipes nothing, the string is the gateway's own text. */
160
+ public async unseal(credentialArg: IControllerGatewayCredential): Promise<string> {
161
+ let bytes: Uint8Array;
162
+ try {
163
+ bytes = await this.options.codec.unseal(this.sealName(credentialArg.tokenId), credentialArg.ciphertext);
164
+ } catch (errorArg) {
165
+ throw new Error(`The gateway credential of ${this.options.controllerId} cannot be unsealed on this machine. `
166
+ + 'Enrol again with `agl remote gateway enrol`.', { cause: errorArg });
167
+ }
168
+ try {
169
+ return Buffer.from(bytes).toString('utf8');
170
+ } finally {
171
+ bytes.fill(0);
172
+ }
173
+ }
174
+
175
+ /**
176
+ * Seals a credential the gateway just issued and stores it as the candidate, before its confirmation is asked
177
+ * for. A candidate stored before is replaced: the gateway superseded it by issuing this one.
178
+ */
179
+ public async storeCandidate(specArg: TControllerGatewayCredentialSpec, tokenIdArg: string, tokenArg: string): Promise<IControllerGatewayCredential> {
180
+ if (!gatewayTokenIdPattern.test(tokenIdArg)) throw new Error('The gateway issued a credential with an invalid id.');
181
+ const bytes = Buffer.from(tokenArg, 'utf8');
182
+ let ciphertext: string;
183
+ try {
184
+ ciphertext = await this.options.codec.seal(this.sealName(tokenIdArg), bytes);
185
+ } finally {
186
+ bytes.fill(0);
187
+ }
188
+ const candidate: IControllerGatewayCredential = { ...specArg, tokenId: tokenIdArg, ciphertext, at: Date.now() };
189
+ const stored = await readStored(this.options.controllerId);
190
+ if (!stored) {
191
+ const inserted = await ControllerGatewayClientModel.exact.insert({ id: this.options.controllerId, candidate });
192
+ if (inserted.status !== 'inserted') throw new Error('The gateway client record changed concurrently.');
193
+ return candidate;
194
+ }
195
+ await this.transition(stored, (modelArg) => { modelArg.candidate = candidate; });
196
+ return candidate;
197
+ }
198
+
199
+ /** Makes the confirmed candidate `tokenIdArg` the active credential; the previous one is gone from the gateway. */
200
+ public async promoteCandidate(tokenIdArg: string): Promise<IControllerGatewayCredential> {
201
+ const stored = await this.requireStored();
202
+ const record = ControllerGatewayClientModel.exact.toPersisted(stored);
203
+ if (record.candidate?.tokenId !== tokenIdArg) throw new Error('The gateway client record changed concurrently.');
204
+ const active: IControllerGatewayCredential = { ...record.candidate, at: Date.now() };
205
+ await this.transition(stored, (modelArg) => {
206
+ modelArg.active = active;
207
+ delete modelArg.candidate;
208
+ // A new credential starts without the previous one's outcome.
209
+ delete modelArg.lastSync;
210
+ });
211
+ return active;
212
+ }
213
+
214
+ /** Drops a candidate the gateway refuses to confirm; the record goes when it holds nothing else. */
215
+ public async dropCandidate(tokenIdArg: string): Promise<void> {
216
+ const stored = await this.requireStored();
217
+ const record = ControllerGatewayClientModel.exact.toPersisted(stored);
218
+ if (record.candidate?.tokenId !== tokenIdArg) throw new Error('The gateway client record changed concurrently.');
219
+ if (!record.active) {
220
+ await this.forget();
221
+ return;
222
+ }
223
+ await this.transition(stored, (modelArg) => { delete modelArg.candidate; });
224
+ }
225
+
226
+ /** Records what a sync of the running controller found; the record must still hold `tokenIdArg` as active. */
227
+ public async recordSync(tokenIdArg: string, syncArg: IControllerGatewaySyncRecord): Promise<void> {
228
+ const stored = await this.requireStored();
229
+ if (ControllerGatewayClientModel.exact.toPersisted(stored).active?.tokenId !== tokenIdArg) {
230
+ throw new Error('The gateway client record changed outside this controller.');
231
+ }
232
+ await this.transition(stored, (modelArg) => { modelArg.lastSync = structuredClone(syncArg); });
233
+ }
234
+
235
+ /** Removes the record; whether there was one. */
236
+ public async forget(): Promise<boolean> {
237
+ const stored = await readStored(this.options.controllerId);
238
+ if (!stored) return false;
239
+ const deleted = await ControllerGatewayClientModel.exact.delete({ current: stored });
240
+ if (deleted.status !== 'deleted' && await readStored(this.options.controllerId)) {
241
+ throw new Error('The gateway client record could not be removed.');
242
+ }
243
+ return true;
244
+ }
245
+
246
+ private sealName(tokenIdArg: string): string {
247
+ return `agl-controller.${this.options.issuerId.slice(0, 22)}.${this.options.controllerId.replace(':', '-')}.gateway.${tokenIdArg}`;
248
+ }
249
+
250
+ private async requireStored(): Promise<TStoredRecord> {
251
+ const stored = await readStored(this.options.controllerId);
252
+ if (!stored) throw new Error(`${this.options.controllerId} is not enrolled with a gateway.`);
253
+ return stored;
254
+ }
255
+
256
+ private async transition(storedArg: TStoredRecord, changeArg: (modelArg: ControllerGatewayClientModel) => void): Promise<void> {
257
+ const result = await ControllerGatewayClientModel.exact.transition({ current: storedArg, change: changeArg });
258
+ if (result.status !== 'transitioned') throw new Error('The gateway client record changed concurrently.');
259
+ }
260
+ }
261
+
262
+ /**
263
+ * The hostnames the gateway enrolment of `controllerIdArg` holds a route for, finished or not (its active and its
264
+ * candidate credential's); empty when it has none.
265
+ */
266
+ export const controllerGatewayEnrolledHostnames = async (controllerIdArg: string): Promise<string[]> => {
267
+ const stored = await readStored(controllerIdArg);
268
+ if (!stored) return [];
269
+ const record = ControllerGatewayClientModel.exact.toPersisted(stored);
270
+ return [...new Set([record.active?.hostname, record.candidate?.hostname]
271
+ .filter((hostnameArg): hostnameArg is string => hostnameArg !== undefined))];
272
+ };
@@ -0,0 +1,239 @@
1
+ import {
2
+ compareControllerInboxItems,
3
+ controllerInboxLimits,
4
+ type IControllerEvent,
5
+ type IControllerInboxSnapshot,
6
+ type TControllerInboxDelta,
7
+ type TControllerInboxItem,
8
+ } from '../ts_interfaces/index.js';
9
+ import { PublishedSet } from './classes.publishedset.js';
10
+
11
+ /**
12
+ * Where the Inbox's items come from, each read as a unit: the requests the Claude Code and Codex harnesses hold (their
13
+ * conversations' and the native sessions' AGL runs turns in), the OpenCode and Flex conversations' requests, the waits
14
+ * harnesses show in their own clients, the driver's `needs input:` turn, and the board's open questions.
15
+ */
16
+ export type TInboxSource = 'claude' | 'codex' | 'opencode' | 'flex' | 'native_waits' | 'driver' | 'tickets';
17
+ export const inboxSources: readonly TInboxSource[] = ['claude', 'codex', 'opencode', 'flex', 'native_waits', 'driver', 'tickets'];
18
+ const sessionSources: readonly TInboxSource[] = ['claude', 'codex', 'opencode', 'flex', 'native_waits'];
19
+
20
+ /** The reads the Inbox merges; the controller binds them to its harnesses, session feed, driver and board. */
21
+ export interface IInboxSources {
22
+ /**
23
+ * The items `sourceArg` holds now. `previousArg` are the source's items of the last read, for a source that keeps
24
+ * the part of them a failed partial read could not renew. A read that fails keeps the source's previous items.
25
+ */
26
+ read(sourceArg: TInboxSource, previousArg: readonly TControllerInboxItem[], signalArg: AbortSignal): Promise<TControllerInboxItem[]>;
27
+ /** Whether a browser or a device receives controller events; without one the Inbox only marks its sources stale. */
28
+ hasViewers(): Promise<boolean>;
29
+ publish(deltaArg: TControllerInboxDelta): void;
30
+ reportError(messageArg: string, errorArg: unknown): void;
31
+ }
32
+
33
+ export interface IInboxOptions {
34
+ /** Event bursts coalesce: a pass reads `debounceMs` after the newest event, at most `maxDebounceMs` after the first. */
35
+ debounceMs?: number;
36
+ maxDebounceMs?: number;
37
+ }
38
+
39
+ /** One line of at most `controllerInboxLimits.titleChars` characters, its end marked when it was cut. */
40
+ export const inboxTitle = (textArg: string): string => {
41
+ const line = textArg.replace(/\s+/gu, ' ').trim();
42
+ const characters = [...line];
43
+ return characters.length <= controllerInboxLimits.titleChars
44
+ ? line
45
+ : `${characters.slice(0, controllerInboxLimits.titleChars - 1).join('').trimEnd()}…`;
46
+ };
47
+
48
+ const itemBytes = (itemArg: TControllerInboxItem): number => Buffer.byteLength(JSON.stringify(itemArg), 'utf8');
49
+
50
+ /**
51
+ * An item within `controllerInboxLimits.itemBytes`: one over it keeps its place, kind, title and where it lives, and
52
+ * leaves its payload out with the marker `omitted`; it is then answered only where it lives. Nothing is cut short.
53
+ */
54
+ export const boundInboxItem = (itemArg: TControllerInboxItem): TControllerInboxItem => {
55
+ const bytes = itemBytes(itemArg);
56
+ if (bytes <= controllerInboxLimits.itemBytes) return itemArg;
57
+ const omitted = { reason: 'oversize' as const, bytes };
58
+ switch (itemArg.kind) {
59
+ case 'permission': { const { permission: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
60
+ case 'question': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
61
+ case 'elicitation': { const { elicitation: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
62
+ case 'driver': { const { line: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
63
+ case 'deploy_go': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
64
+ case 'window_go': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
65
+ case 'ticket_question': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
66
+ case 'native_wait': return { ...itemArg, omitted };
67
+ }
68
+ };
69
+
70
+ /**
71
+ * The Inbox (AGL-1635): one list of what waits for the owner, kept in memory and published to browsers and devices as
72
+ * deltas. Nothing is stored: every item is read from the component that owns it, so an answer anywhere removes it.
73
+ *
74
+ * Events mark the sources they concern stale; a pass reads only the stale ones, coalesced, and only while a browser
75
+ * or a device is connected. `list()` reads every stale source first.
76
+ */
77
+ export class ControllerInbox {
78
+ private readonly abort = new AbortController();
79
+ private readonly published = new PublishedSet<TControllerInboxItem>(controllerInboxLimits.deltaItems);
80
+ private readonly items = new Map<TInboxSource, TControllerInboxItem[]>();
81
+ private readonly stale = new Set<TInboxSource>(inboxSources);
82
+ private readonly debounceMs: number;
83
+ private readonly maxDebounceMs: number;
84
+ private total = 0;
85
+ private limited = false;
86
+ /** The last failure each source reported, so a lasting one is reported once. */
87
+ private readonly errors = new Map<TInboxSource, string>();
88
+ private timer?: ReturnType<typeof setTimeout>;
89
+ private firstPendingAt?: number;
90
+ /** Passes run one at a time, in order; a pass reads the sources stale when it starts. */
91
+ private tail: Promise<void> = Promise.resolve();
92
+
93
+ constructor(private readonly sources: IInboxSources, optionsArg: IInboxOptions = {}) {
94
+ this.debounceMs = optionsArg.debounceMs ?? 100;
95
+ this.maxDebounceMs = optionsArg.maxDebounceMs ?? 1_000;
96
+ }
97
+
98
+ /** The Inbox after reading every stale source. */
99
+ public async list(): Promise<IControllerInboxSnapshot> {
100
+ this.abort.signal.throwIfAborted();
101
+ await this.enqueuePass();
102
+ return { epoch: this.published.epoch, revision: this.published.revision, items: this.published.values(), total: this.total, limited: this.limited };
103
+ }
104
+
105
+ /** Called for every controller event: the ones that change what waits mark their sources stale. */
106
+ public observe(eventArg: IControllerEvent): void {
107
+ if (this.abort.signal.aborted) return;
108
+ switch (eventArg.type) {
109
+ case 'permissions.changed': {
110
+ const harness = eventArg.harnessId;
111
+ this.markStale(...(harness === 'claude' || harness === 'codex' || harness === 'opencode' || harness === 'flex' ? [harness] : sessionSources));
112
+ return;
113
+ }
114
+ case 'sessions.changed':
115
+ case 'harness.changed':
116
+ case 'projects.changed':
117
+ this.markStale(...sessionSources);
118
+ return;
119
+ // A feed row's group and name are what session items name and where they wait: the rows' harnesses read again.
120
+ case 'sessionfeed.changed': {
121
+ const delta = eventArg.sessionFeed;
122
+ if (!delta || 'reset' in delta) {
123
+ this.markStale(...sessionSources);
124
+ return;
125
+ }
126
+ const harnesses = new Set<string>([...delta.upserts.map((rowArg) => rowArg.harness),
127
+ ...delta.removed.map((rowIdArg) => rowIdArg.slice(0, rowIdArg.indexOf(':')))]);
128
+ this.markStale('native_waits', ...sessionSources.filter((sourceArg) => harnesses.has(sourceArg)));
129
+ return;
130
+ }
131
+ case 'driver.changed':
132
+ // The driver's own prompts are Flex permissions.
133
+ this.markStale('driver', 'flex');
134
+ return;
135
+ case 'tickets.changed':
136
+ case 'deployments.changed':
137
+ this.markStale('tickets');
138
+ return;
139
+ default:
140
+ return;
141
+ }
142
+ }
143
+
144
+ /** The requests a harness holds for a native session came or went (no controller event names those sessions). */
145
+ public nativeAttentionChanged(harnessArg: 'claude' | 'codex'): void {
146
+ this.markStale(harnessArg);
147
+ }
148
+
149
+ public markStale(...sourcesArg: TInboxSource[]): void {
150
+ if (this.abort.signal.aborted) return;
151
+ for (const source of sourcesArg) this.stale.add(source);
152
+ this.schedule();
153
+ }
154
+
155
+ /** Stops the timer and waits for the pass in flight, which sees the abort. */
156
+ public async close(): Promise<void> {
157
+ this.abort.abort();
158
+ if (this.timer) clearTimeout(this.timer);
159
+ this.timer = undefined;
160
+ await this.tail;
161
+ }
162
+
163
+ private schedule(): void {
164
+ const now = Date.now();
165
+ this.firstPendingAt ??= now;
166
+ const due = Math.min(now + this.debounceMs, this.firstPendingAt + this.maxDebounceMs);
167
+ if (this.timer) clearTimeout(this.timer);
168
+ this.timer = setTimeout(() => {
169
+ this.timer = undefined;
170
+ this.firstPendingAt = undefined;
171
+ void this.passIfViewed();
172
+ }, Math.max(0, due - now));
173
+ this.timer.unref?.();
174
+ }
175
+
176
+ /** A scheduled pass runs only while someone receives its changes; otherwise its sources stay stale for `list()`. */
177
+ private async passIfViewed(): Promise<void> {
178
+ let viewed: boolean;
179
+ try {
180
+ viewed = await this.sources.hasViewers();
181
+ } catch (errorArg) {
182
+ this.sources.reportError('Checking for Inbox viewers failed.', errorArg);
183
+ return;
184
+ }
185
+ if (viewed && !this.abort.signal.aborted) await this.enqueuePass();
186
+ }
187
+
188
+ private enqueuePass(): Promise<void> {
189
+ const pass = this.tail.then(() => this.pass());
190
+ this.tail = pass.catch((errorArg) => {
191
+ if (!this.abort.signal.aborted) this.sources.reportError('An Inbox pass failed.', errorArg);
192
+ });
193
+ return pass;
194
+ }
195
+
196
+ private async pass(): Promise<void> {
197
+ const signal = this.abort.signal;
198
+ signal.throwIfAborted();
199
+ const sources = inboxSources.filter((sourceArg) => this.stale.has(sourceArg));
200
+ for (const source of sources) this.stale.delete(source);
201
+ await Promise.all(sources.map(async (sourceArg) => {
202
+ try {
203
+ this.items.set(sourceArg, await this.sources.read(sourceArg, this.items.get(sourceArg) ?? [], signal));
204
+ this.errors.delete(sourceArg);
205
+ } catch (errorArg) {
206
+ signal.throwIfAborted();
207
+ // The source keeps what it held; its next change reads it again.
208
+ const message = errorArg instanceof Error ? errorArg.message : String(errorArg);
209
+ if (this.errors.get(sourceArg) === message) return;
210
+ this.errors.set(sourceArg, message);
211
+ this.sources.reportError(`Inbox: reading ${sourceArg} failed.`, errorArg);
212
+ }
213
+ }));
214
+ signal.throwIfAborted();
215
+ this.publish();
216
+ }
217
+
218
+ private publish(): void {
219
+ const unique = new Map<string, TControllerInboxItem>();
220
+ for (const item of [...this.items.values()].flat()) if (!unique.has(item.id)) unique.set(item.id, boundInboxItem(item));
221
+ const all = [...unique.values()].sort(compareControllerInboxItems);
222
+ const shown: TControllerInboxItem[] = [];
223
+ let bytes = 0;
224
+ for (const item of all) {
225
+ const size = itemBytes(item);
226
+ if (shown.length >= controllerInboxLimits.items || bytes + size > controllerInboxLimits.listBytes) break;
227
+ shown.push(item);
228
+ bytes += size;
229
+ }
230
+ const total = all.length;
231
+ const limited = shown.length < total;
232
+ const countsChanged = total !== this.total || limited !== this.limited;
233
+ this.total = total;
234
+ this.limited = limited;
235
+ const delta = this.published.publish(shown, countsChanged);
236
+ if (!delta) return;
237
+ this.sources.publish('reset' in delta ? delta : { ...delta, order: shown.map((itemArg) => itemArg.id), total, limited });
238
+ }
239
+ }
@@ -78,6 +78,11 @@ export interface IInferenceAccount {
78
78
  reserveLiftUntil: string | null;
79
79
  /** When the account's subscription ends (`IAuthSwitchAccount.lapsesAt`); `null` while it renews. */
80
80
  lapsesAt: string | null;
81
+ /**
82
+ * The anchor of a Claude sign-in's monthly renewal as its owner set it (`IAuthSwitchAccount.renewsAt`); `null`
83
+ * without one. Placement only: a window's usage counts as spent by the next renewal (`authSwitchPlacement`).
84
+ */
85
+ renewsAt: string | null;
81
86
  /**
82
87
  * An API key's monthly spend limit in micro-dollars (`IAuthSwitchAccount.spendLimitMicroUsd`); `null` without one,
83
88
  * and for a sign-in. It decides only whether a key whose spend the proxy holds no reading of may take work: one with
@@ -702,6 +707,11 @@ export interface IInferenceAccountStatus {
702
707
  lifecycle: plugins.authswitchPlacement.TAuthSwitchAccountLifecycle;
703
708
  /** When the account's subscription ends, or `null` while it renews. */
704
709
  lapsesAt: string | null;
710
+ /**
711
+ * The account's next renewal (`IInferenceAccount.renewsAt` rolled forward to the first one after now), or `null`
712
+ * without one. Placement ignores it while the account has a lapse date. A proxy of an earlier AGL reports none.
713
+ */
714
+ renewal?: plugins.authswitchRenewal.IAuthSwitchRenewal | null;
705
715
  /** The account's placement score in percent per hour (`IAuthSwitchPlacement.score`); `null` without a counted window. */
706
716
  placementScore: number | null;
707
717
  /**
@@ -933,7 +943,8 @@ const emptySelection = (accountsArg: number, pinnedArg: boolean): ISelectionStat
933
943
  /** An account's placement by the shared rule, on the reading the router holds for it. */
934
944
  const accountPlacement = (readingArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot['reading'],
935
945
  accountArg: IInferenceAccount, nowArg: number): plugins.authswitchPlacement.IAuthSwitchPlacement =>
936
- plugins.authswitchPlacement.authSwitchPlacement(readingArg, accountArg.maxUsagePercent, accountArg.lapsesAt, nowArg, accountArg.reserveLiftUntil);
946
+ plugins.authswitchPlacement.authSwitchPlacement(readingArg, accountArg.maxUsagePercent, accountArg.lapsesAt,
947
+ accountArg.renewsAt, nowArg, accountArg.reserveLiftUntil);
937
948
 
938
949
  /** Model-preserving account selection. Refresh grants and native sign-ins remain the authority's. */
939
950
  export class InferenceRouter {
@@ -1954,7 +1965,9 @@ export class InferenceRouter {
1954
1965
  const placement = accountPlacement(limits?.limit ? held!.reading : null, account, now);
1955
1966
  const base = { id: account.id, label: account.label, provider: account.providerId, credential: account.credential,
1956
1967
  maxUsagePercent: account.maxUsagePercent, reserveLiftUntil: account.reserveLiftUntil, inFlight: this.active.get(account.id) ?? 0,
1957
- lifecycle: placement.lifecycle, lapsesAt: account.lapsesAt, placementScore: placement.score, placementRank: null,
1968
+ lifecycle: placement.lifecycle, lapsesAt: account.lapsesAt,
1969
+ renewal: plugins.authswitchRenewal.authSwitchRenewal(account.renewsAt, now),
1970
+ placementScore: placement.score, placementRank: null,
1958
1971
  lastResort: placement.eligibility === 'last_resort', claudeCode: account.claudeCode,
1959
1972
  readingSource: held?.observation ? 'headers' as const : held?.reading ? 'poll' as const : null,
1960
1973
  readingObservedAt: held?.reading ? held.observedAt : null,
@@ -2005,6 +2018,18 @@ export class InferenceRouter {
2005
2018
  return statuses;
2006
2019
  }
2007
2020
 
2021
+ /**
2022
+ * The newest provider 429 this router saw on the account since it started (epoch milliseconds), or `null`, and until
2023
+ * when the account rests after it as routing judges it on `usageArg` (`cooldownUntil`; 0 when it does not rest): the
2024
+ * proxy's capacity reads both (`proxyPoolCapacity`). Held in memory only, so a restarted proxy starts with none.
2025
+ */
2026
+ public quotaOf(accountArg: IInferenceAccount,
2027
+ usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): { lastAt: number | null; restUntil: number } {
2028
+ const cooldown = this.cooldowns.get(accountArg.id);
2029
+ const until = cooldownUntil(cooldown, accountArg.credential === 'api_key' ? undefined : usageArg);
2030
+ return { lastAt: cooldown?.at ?? null, restUntil: until > this.now() ? until : 0 };
2031
+ }
2032
+
2008
2033
  /** Counts one request on an account until its release, which may be called more than once. */
2009
2034
  private reserve(idArg: string): () => void {
2010
2035
  this.active.set(idArg, (this.active.get(idArg) ?? 0) + 1);
@@ -15,6 +15,9 @@ import type { IInferenceUsageLedger } from './classes.inferenceusage.js';
15
15
  import type { TInferenceProvider } from './functions.proxycontract.js';
16
16
  import { findAuthorityApiKeyLogin, findAuthorityGatewayLogin, findInferencePool, isAuthorityInstallationId,
17
17
  parseAuthorityScope } from '../ts_interfaces/index.js';
18
+ import { proxyCapacityDefaultMinimumHeadroom, proxyCapacityProviders, type IProxyCapacityAnswer,
19
+ type IProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
20
+ import { proxyPoolCapacity } from './functions.proxycapacity.js';
18
21
 
19
22
  export interface IInferenceServiceOptions {
20
23
  authorityPaths: IAuthoritySocketPaths;
@@ -64,6 +67,8 @@ export class InferenceService {
64
67
  private started = false;
65
68
  private baseUrl?: string;
66
69
  private stopTask?: Promise<void>;
70
+ /** Since when the router sees this service's requests and their provider 429s (epoch milliseconds): its start. */
71
+ private observingSince = Date.now();
67
72
 
68
73
  constructor(private readonly options: IInferenceServiceOptions) {
69
74
  if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
@@ -154,7 +159,7 @@ export class InferenceService {
154
159
  const login = findAuthorityGatewayLogin(projection, account.id);
155
160
  return pool ? [{ id: account.id, label: account.label, revision: String(account.revision), providerId: pool.provider,
156
161
  credential: pool.credential, maxUsagePercent: account.maxUsagePercent, reserveLiftUntil: account.reserveLiftUntil, lapsesAt: account.lapsesAt,
157
- spendLimitMicroUsd: account.spendLimitMicroUsd, claudeCode: account.claudeCode, loginId: typeof login === 'string' ? null : login.id }] : [];
162
+ renewsAt: account.renewsAt, spendLimitMicroUsd: account.spendLimitMicroUsd, claudeCode: account.claudeCode, loginId: typeof login === 'string' ? null : login.id }] : [];
158
163
  });
159
164
  }
160
165
 
@@ -167,6 +172,7 @@ export class InferenceService {
167
172
  this.started = true;
168
173
  try {
169
174
  signalArg?.throwIfAborted();
175
+ this.observingSince = Date.now();
170
176
  this.baseUrl = await this.gateway.listen();
171
177
  signalArg?.throwIfAborted();
172
178
  this.authority.start();
@@ -231,6 +237,27 @@ export class InferenceService {
231
237
  recentPlacements: recent.map((placementArg) => ({ ...placementArg, at: placementArg.at.toISOString() })) };
232
238
  }
233
239
 
240
+ /**
241
+ * Each asked pool's room for new work (`proxyPoolCapacity`): its accounts judged on the readings a request would route
242
+ * on now, as `status` reads them, with the provider 429s the router saw since this service started. `undefined` while
243
+ * the account service is unavailable, as nothing can be judged then.
244
+ */
245
+ public async capacity(requestArg: IProxyCapacityRequest, signalArg: AbortSignal): Promise<IProxyCapacityAnswer | undefined> {
246
+ const pool = this.poolAccounts();
247
+ if (!pool) return undefined;
248
+ const readings = new Map(await Promise.all(pool
249
+ .map(async (accountArg) => [accountArg.id, await this.usage.current(accountArg.id, signalArg)] as const)));
250
+ const statuses = this.router.accountStatus(pool, (accountIdArg) => readings.get(accountIdArg));
251
+ const now = Date.now();
252
+ const accounts = pool.map((accountArg, indexArg) => ({ status: statuses[indexArg], usage: readings.get(accountArg.id),
253
+ quota: this.router.quotaOf(accountArg, readings.get(accountArg.id)) }));
254
+ const options = { minHeadroom: requestArg.minHeadroom ?? proxyCapacityDefaultMinimumHeadroom,
255
+ observedSince: this.observingSince, now };
256
+ return { at: new Date(now).toISOString(), observedSince: new Date(this.observingSince).toISOString(),
257
+ pools: (requestArg.provider ? [requestArg.provider] : proxyCapacityProviders)
258
+ .map((providerArg) => proxyPoolCapacity(providerArg, accounts, options)) };
259
+ }
260
+
234
261
  public stop(): Promise<void> {
235
262
  return this.stopTask ??= (async () => {
236
263
  this.ready = false;