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
@@ -12,7 +12,9 @@ import { assertSessionFeedWireRequest, assertSessionFeedWireResponse } from './f
12
12
  import { assertFleetDeployResponse, assertFleetDeployWireRequest } from './fleet/functions.deployvalidation.js';
13
13
  import type { IFleetDeployOperations, TFleetDeployOperation } from '../ts_interfaces/deployments.js';
14
14
  import type { IReq_ControllerMcpSessionFeedAcknowledge, IReq_ControllerMcpSessionFeedList } from '../ts_interfaces/sessionfeed.js';
15
+ import { isProxyCapacityAnswer, type IProxyCapacityAnswer, type IProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
15
16
  import {
17
+ controllerMcpNativeDeliveries,
16
18
  controllerMcpSessionDetailFields,
17
19
  controllerMcpTypedResponseMaximumBytes,
18
20
  controllerPackageName,
@@ -66,6 +68,7 @@ import { compareUpgradeSemver } from './classes.upgradecoordinator.js';
66
68
  import {
67
69
  assertControllerMcpExactKeys,
68
70
  assertControllerMcpModelChoice,
71
+ assertControllerMcpNativeSession,
69
72
  assertControllerMcpResponseFields,
70
73
  assertControllerMcpRuntimeId,
71
74
  controllerMcpValueIsRecord,
@@ -97,6 +100,7 @@ export type TControllerMcpClientErrorCode =
97
100
  | 'CONCURRENT_CHANGE'
98
101
  | 'PROJECT_NOT_FOUND'
99
102
  | 'SESSION_NOT_FOUND'
103
+ | 'SESSION_READ_ONLY'
100
104
  | 'AMBIGUOUS_SESSION'
101
105
  | 'MODEL_NOT_FOUND'
102
106
  | 'JOB_NOT_FOUND'
@@ -111,6 +115,9 @@ export type TControllerMcpClientErrorCode =
111
115
  | 'DELIVERY_UNSUPPORTED'
112
116
  | 'REQUEST_FAILED'
113
117
  | 'OUTCOME_UNKNOWN'
118
+ | 'PROXY_UNAVAILABLE'
119
+ | 'PROXY_OUTDATED'
120
+ | 'PROXY_ACCOUNTS_UNAVAILABLE'
114
121
  | Uppercase<TFleetWorkerErrorCode>;
115
122
 
116
123
  export class ControllerMcpClientError extends Error {
@@ -280,6 +287,10 @@ const assertResponsePayload = (
280
287
  if (new Set(models.map(model => model.harnessId)).size !== models.length) throw new Error('invalid');
281
288
  return;
282
289
  }
290
+ if (methodArg === 'agl.mcp.proxy.capacity') {
291
+ if (!isProxyCapacityAnswer(valueArg)) throw new Error('invalid');
292
+ return;
293
+ }
283
294
  if (methodArg === 'agl.mcp.configuration.state') {
284
295
  assertControllerMcpExactKeys(valueArg, ['resource', 'projectionRun', 'harnesses', 'history'], ['master', 'projection']);
285
296
  if (!controllerMcpValueIsRecord(valueArg.resource) || !controllerMcpValueIsRecord(valueArg.projectionRun)
@@ -368,8 +379,12 @@ const assertResponsePayload = (
368
379
  return;
369
380
  }
370
381
  if (methodArg === 'agl.mcp.sessions.list') {
371
- assertControllerMcpExactKeys(valueArg, ['sessions']);
372
- if (!Array.isArray(valueArg.sessions)) throw new Error('invalid');
382
+ assertControllerMcpExactKeys(valueArg, ['sessions', 'nativeSessions'], ['nativeSessionsTruncated', 'nativeSessionsError']);
383
+ if (!Array.isArray(valueArg.sessions) || !Array.isArray(valueArg.nativeSessions)
384
+ || (valueArg.nativeSessionsTruncated !== undefined && valueArg.nativeSessionsTruncated !== true)
385
+ || (valueArg.nativeSessionsError !== undefined && (typeof valueArg.nativeSessionsError !== 'string'
386
+ || valueArg.nativeSessions.length > 0 || valueArg.nativeSessionsTruncated !== undefined))) throw new Error('invalid');
387
+ valueArg.nativeSessions.forEach(assertControllerMcpNativeSession);
373
388
  return;
374
389
  }
375
390
  if (methodArg === 'agl.mcp.session.send') {
@@ -378,10 +393,15 @@ const assertResponsePayload = (
378
393
  return;
379
394
  }
380
395
  if (methodArg === 'agl.mcp.session.message') {
381
- assertControllerMcpExactKeys(valueArg, ['accepted', 'delivery'], ['turnId']);
396
+ assertControllerMcpExactKeys(valueArg, ['accepted', 'delivery'], ['turnId', 'native']);
382
397
  if (
383
398
  valueArg.accepted !== true
384
399
  || !['steer', 'next-turn', 'queue'].includes(valueArg.delivery as string)
400
+ || (valueArg.native !== undefined && (
401
+ (valueArg.native !== 'wake' && valueArg.native !== 'inbox')
402
+ || valueArg.delivery !== controllerMcpNativeDeliveries[valueArg.native]
403
+ || valueArg.turnId !== undefined
404
+ ))
385
405
  || (valueArg.turnId !== undefined && (
386
406
  typeof valueArg.turnId !== 'string'
387
407
  || valueArg.turnId.length === 0
@@ -398,6 +418,14 @@ const assertResponsePayload = (
398
418
  assertScratchpadResponse(valueArg.scratchpad);
399
419
  return;
400
420
  }
421
+ if (valueArg.kind === 'native') {
422
+ // A Claude Code session outside AGL: the session, its transcript page and its scratchpad.
423
+ assertControllerMcpExactKeys(valueArg, ['kind', 'session', 'messagePage', 'scratchpad']);
424
+ assertControllerMcpNativeSession(valueArg.session);
425
+ if (!controllerMcpValueIsRecord(valueArg.messagePage) || !Array.isArray(valueArg.messagePage.bundles)) throw new Error('invalid');
426
+ assertScratchpadResponse(valueArg.scratchpad);
427
+ return;
428
+ }
401
429
  assertControllerMcpResponseFields(valueArg, controllerMcpSessionDetailFields);
402
430
  if (!controllerMcpValueIsRecord(valueArg.session)) throw new Error('invalid');
403
431
  const sessionId = assertControllerMcpRuntimeId(valueArg.session.id);
@@ -446,6 +474,11 @@ export class ControllerMcpClient {
446
474
  this.requestTimeoutMs = timeout;
447
475
  }
448
476
 
477
+ /** A pool's room for new work in AGL's inference proxy, or both pools', as the controller asks the proxy for it. */
478
+ public async proxyCapacity(requestArg: IProxyCapacityRequest, signalArg?: AbortSignal): Promise<IProxyCapacityAnswer> {
479
+ return this.dispatchAfterHandshake('agl.mcp.proxy.capacity', requestArg, signalArg, false);
480
+ }
481
+
449
482
  public async status(signalArg?: AbortSignal): Promise<IReq_ControllerMcpStatus['response']> {
450
483
  const descriptor = await this.readCompatibleDescriptor();
451
484
  const status = await this.dispatch(
@@ -973,6 +1006,7 @@ export class ControllerMcpClient {
973
1006
  if (serverCode === 'concurrent_change') code = 'CONCURRENT_CHANGE';
974
1007
  if (serverCode === 'project_not_found') code = 'PROJECT_NOT_FOUND';
975
1008
  if (serverCode === 'session_not_found') code = 'SESSION_NOT_FOUND';
1009
+ if (serverCode === 'session_read_only') code = 'SESSION_READ_ONLY';
976
1010
  if (serverCode === 'ambiguous_session') code = 'AMBIGUOUS_SESSION';
977
1011
  if (serverCode === 'model_not_found') code = 'MODEL_NOT_FOUND';
978
1012
  if (serverCode === 'outcome_unknown') code = 'OUTCOME_UNKNOWN';
@@ -987,6 +1021,11 @@ export class ControllerMcpClient {
987
1021
  if (serverCode === 'agent_messages_disabled') code = 'AGENT_MESSAGES_DISABLED';
988
1022
  if (serverCode === 'message_rate_limited') code = 'MESSAGE_RATE_LIMITED';
989
1023
  if (serverCode === 'delivery_unsupported') code = 'DELIVERY_UNSUPPORTED';
1024
+ if (methodArg === 'agl.mcp.proxy.capacity') {
1025
+ if (serverCode === 'proxy_unavailable') code = 'PROXY_UNAVAILABLE';
1026
+ if (serverCode === 'proxy_outdated') code = 'PROXY_OUTDATED';
1027
+ if (serverCode === 'proxy_accounts_unavailable') code = 'PROXY_ACCOUNTS_UNAVAILABLE';
1028
+ }
990
1029
  if (methodArg.startsWith('agl.mcp.fleet.worker.') && (fleetWorkerErrorCodes as readonly unknown[]).includes(serverCode)) {
991
1030
  code = (serverCode as TFleetWorkerErrorCode).toUpperCase() as Uppercase<TFleetWorkerErrorCode>;
992
1031
  }
@@ -51,6 +51,7 @@ import {
51
51
  type IReq_ControllerMcpSessionMessage,
52
52
  type IReq_ControllerMcpSessionsList,
53
53
  type IReq_ControllerMcpStatus,
54
+ type IReq_ControllerMcpProxyCapacity,
54
55
  type IReq_ControllerMcpSettingsGet,
55
56
  type IReq_ControllerMcpSettingsUpdate,
56
57
  type IReq_ControllerMcpConfigurationState,
@@ -93,6 +94,9 @@ export interface IControllerMcpPrivateApi {
93
94
  fleet?: (method: string, request: Record<string, unknown>, signal: AbortSignal) => Promise<IFleetOperation>;
94
95
  /** Deploy status, history, a probe now and release state for the local owner (`agl deploy`, `agl release status`). */
95
96
  deploy?: (method: TControllerMcpDeployMethod, request: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
97
+ /** A pool's room for new work in AGL's inference proxy, asked of the proxy (AGL-1097); open to every caller. */
98
+ proxyCapacity?: (request: IReq_ControllerMcpProxyCapacity['request'], signal: AbortSignal)
99
+ => Promise<IReq_ControllerMcpProxyCapacity['response']>;
96
100
  /** The session feed for the local owner; each call verifies the owner capability it carries. */
97
101
  sessionFeed?: {
98
102
  list(request: IReq_ControllerMcpSessionFeedList['request'], signal: AbortSignal): Promise<IReq_ControllerMcpSessionFeedList['response']>;
@@ -311,6 +315,8 @@ const safeTypedResponseError = (
311
315
  rate_limited: 'The authenticated operation rate limit was reached.',
312
316
  project_not_found: 'The requested project is unavailable.',
313
317
  session_not_found: 'The requested session is unavailable.',
318
+ session_read_only: 'The session takes no message now; session_read names why.',
319
+ native_session_failed: 'The Claude Code session could not be reached, and nothing was sent; read the session before acting again.',
314
320
  ambiguous_session: 'The native ID exists on multiple connections; select its qualified AGL ID.',
315
321
  model_not_found: 'The selected model is unavailable.',
316
322
  browser_image_limit: 'The screenshot exceeds 512 KiB; request JPEG with lower quality.',
@@ -331,6 +337,9 @@ const safeTypedResponseError = (
331
337
  sessionfeed_row_not_found: 'The session feed lists no such row; list the feed again.',
332
338
  sessionfeed_row_not_failed: 'Only a failed row can be acknowledged.',
333
339
  sessionfeed_row_stale: 'The session changed since it was listed; list the feed again.',
340
+ proxy_unavailable: 'The AGL proxy is not running.',
341
+ proxy_outdated: 'The AGL proxy runs an older AGL release and does not answer capacity; restart it onto the installed AGL.',
342
+ proxy_accounts_unavailable: 'The AGL proxy cannot reach its account service, so it cannot judge its pools.',
334
343
  };
335
344
  const conflict = readTicketRevisionConflict(errorArg.errorData);
336
345
  return new plugins.typedrequest.TypedResponseError(
@@ -684,6 +693,12 @@ export class ControllerMcpHost {
684
693
  return this.options.api.deploy(method, request as unknown as Record<string, unknown>, tools?.abortSignal ?? new AbortController().signal) as never;
685
694
  })));
686
695
  }
696
+ routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_ControllerMcpProxyCapacity>(
697
+ 'agl.mcp.proxy.capacity', async (requestArg, toolsArg) => run('agl.mcp.proxy.capacity', async () => {
698
+ if (!this.options.api.proxyCapacity) throw new Error('Proxy capacity API is unavailable.');
699
+ return this.options.api.proxyCapacity(requestArg, toolsArg?.abortSignal ?? new AbortController().signal);
700
+ }),
701
+ ));
687
702
  routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_ControllerMcpSessionFeedList>(
688
703
  'agl.mcp.sessionfeed.list', async (requestArg, toolsArg) => run('agl.mcp.sessionfeed.list', async () => {
689
704
  if (!this.options.api.sessionFeed) throw new Error('Session feed API is unavailable.');
@@ -33,6 +33,7 @@ import { assertControllerMcpJobRequest } from './functions.jobvalidation.js';
33
33
  export const aglMcpToolNames = [
34
34
  workerCallerEnrollmentToolName,
35
35
  'controller_status',
36
+ 'proxy_capacity',
36
37
  'projects_list',
37
38
  'sessions_list',
38
39
  'session_read',
@@ -132,7 +133,7 @@ export interface IAglMcpToolsOptions {
132
133
  | 'messageSession'
133
134
  | 'readSessionScratchpad'
134
135
  | 'updateSessionScratchpad'
135
- > & Partial<Pick<ControllerMcpClient, 'ticket' | 'fleet' | 'fleetStart' | 'fleetStatus' | 'fleetWorker' | 'deploy'>>;
136
+ > & Partial<Pick<ControllerMcpClient, 'ticket' | 'fleet' | 'fleetStart' | 'fleetStatus' | 'fleetWorker' | 'deploy' | 'proxyCapacity'>>;
136
137
  }
137
138
 
138
139
  const maximumIdentifierBytes = 1024;
@@ -229,7 +230,7 @@ const workspaceToolDefinitions: IWorkspaceToolDefinition[] = [
229
230
  path: plugins.z.string().max(controllerWorkspaceMaximumPathBytes) }).strict(),
230
231
  readOnly: false, destructive: false },
231
232
  { name: 'context_resolve', method: 'agl.mcp.context.resolve',
232
- description: "Resolve an absolute project directory and optionally an existing native task. Accepts a raw Codex thread ID only when it uniquely resolves; returns the qualified AGL session ID. Does not take over a running task.",
233
+ description: "Resolve an absolute project directory and optionally an existing native task. Accepts a raw Codex thread ID only when it uniquely resolves; returns the qualified AGL session ID. A Claude Code session outside AGL in the project folder answers as nativeSession and is recorded nowhere. Does not take over a running task.",
233
234
  inputSchema: plugins.z.object({ directory: boundedNonblankString(4096, 'directory'), sessionId: runtimeIdSchema.optional() }).strict(), readOnly: false, destructive: false },
234
235
  { name: 'project_add', method: 'agl.mcp.project.create',
235
236
  description: "Register an existing project directory. Does not create directories.",
@@ -289,6 +290,7 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
289
290
  CONCURRENT_CHANGE: 'The task, resource or scratchpad changed; read its current state before acting again.',
290
291
  PROJECT_NOT_FOUND: 'The project is unavailable. Use projects_list or register its directory with project_add.',
291
292
  SESSION_NOT_FOUND: 'The task is unavailable in this project. Use sessions_list to select an active task.',
293
+ SESSION_READ_ONLY: 'The Claude Code session takes no message now; session_read names why (readOnly). Nothing was sent.',
292
294
  AMBIGUOUS_SESSION: 'The native ID exists on multiple connections. Use sessions_list and select its qualified AGL ID.',
293
295
  MODEL_NOT_FOUND: 'The selected model is unavailable. Use models_list for this task.',
294
296
  JOB_NOT_FOUND: 'The job is unavailable. Use jobs_list for this project.',
@@ -306,8 +308,11 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
306
308
  TURN_ENDED: 'The turn the message was to steer has ended; nothing was sent. Read the task before sending again.',
307
309
  AGENT_MESSAGES_DISABLED: 'The owner does not accept agent messages for this project.',
308
310
  MESSAGE_RATE_LIMITED: 'Too many messages to this task; wait at least a minute before sending another.',
309
- DELIVERY_UNSUPPORTED: 'The task cannot take this delivery: OpenCode cannot be steered, expectedTurnId applies only to a Codex steer, and steering a turn another Codex client runs requires expectedTurnId.',
311
+ DELIVERY_UNSUPPORTED: 'The task cannot take this delivery: OpenCode cannot be steered, expectedTurnId applies only to a Codex steer (never to a Claude Code session outside AGL), and steering a turn another Codex client runs requires expectedTurnId.',
310
312
  OUTCOME_UNKNOWN: 'The operation outcome is unknown; inspect current state before acting again.',
313
+ PROXY_UNAVAILABLE: 'The AGL inference proxy is not running; its owner starts it with agl proxy service start.',
314
+ PROXY_OUTDATED: 'The AGL inference proxy runs an older AGL release and does not answer capacity; its owner restarts it onto the installed AGL with agl proxy service stop, then agl proxy service start.',
315
+ PROXY_ACCOUNTS_UNAVAILABLE: 'The AGL inference proxy cannot reach its account service, so it cannot judge its pools now.',
311
316
  };
312
317
 
313
318
  const serializeToolResult = (
@@ -370,7 +375,7 @@ export class AglMcpTools {
370
375
  | 'messageSession'
371
376
  | 'readSessionScratchpad'
372
377
  | 'updateSessionScratchpad'
373
- > & Partial<Pick<ControllerMcpClient, 'ticket' | 'fleet' | 'fleetStart' | 'fleetStatus' | 'fleetWorker' | 'deploy'>>;
378
+ > & Partial<Pick<ControllerMcpClient, 'ticket' | 'fleet' | 'fleetStart' | 'fleetStatus' | 'fleetWorker' | 'deploy' | 'proxyCapacity'>>;
374
379
  private readonly withFleetOwner: <T>(operation: (token: string) => Promise<T>) => Promise<T>;
375
380
  private readonly onControllerUpgraded?: IAglMcpToolsOptions['onControllerUpgraded'];
376
381
  private readonly workerCaller?: McpWorkerCaller;
@@ -423,6 +428,30 @@ export class AglMcpTools {
423
428
  async () => this.client.status(extra.signal),
424
429
  ),
425
430
  ));
431
+ registeredTools.push(serverArg.registerTool(
432
+ 'proxy_capacity',
433
+ {
434
+ title: 'Read the inference proxy capacity',
435
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
436
+ description: "Read a pool's room for new work in AGL's inference proxy, as agl proxy capacity --json answers it: "
437
+ + 'provider anthropic (Claude accounts) or openai (ChatGPT accounts), both when omitted. Its members are its '
438
+ + 'subscription sign-ins that have not lapsed on a counted plan (Claude: max; ChatGPT: every plan but free); '
439
+ + "room is the headroom they add now, summed (0 for one that takes no work now). Each member, by account id, names "
440
+ + 'its plan, state, binding window and growsAt, when its headroom next grows. verdict is open when room reaches '
441
+ + 'minHeadroom (15 unless given) and no provider 429 hit a member within five minutes; otherwise wait with '
442
+ + 'reason room, provider-429 or quiet-unobserved and until/seconds, both null when no moment is foreseen. It '
443
+ + 'does not wait: ask again after verdict.seconds.',
444
+ inputSchema: plugins.z.object({
445
+ provider: plugins.z.enum(['anthropic', 'openai']).optional(),
446
+ minHeadroom: plugins.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
447
+ }).strict(),
448
+ },
449
+ async (args, extra) => this.runToolCall(extra, async () => {
450
+ if (!this.client.proxyCapacity) throw new Error('Proxy capacity API is unavailable.');
451
+ return this.client.proxyCapacity({ ...(args.provider === undefined ? {} : { provider: args.provider }),
452
+ ...(args.minHeadroom === undefined ? {} : { minHeadroom: args.minHeadroom }) }, extra.signal);
453
+ }),
454
+ ));
426
455
  registeredTools.push(serverArg.registerTool(
427
456
  'projects_list',
428
457
  {
@@ -440,7 +469,7 @@ export class AglMcpTools {
440
469
  {
441
470
  title: 'List project sessions',
442
471
  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
443
- description: 'Discover OpenCode, Flex and Codex tasks from the project folder and configured connections, including tasks created outside AGL.',
472
+ description: 'Discover OpenCode, Flex and Codex tasks and AGL\'s own Claude Code conversations from the project folder and configured connections, including tasks created outside AGL (sessions), and the Claude Code sessions of the host\'s own Claude Code home that run in the project folder itself (nativeSessions: running ones first, all of them, then at most 50 settled ones, nativeSessionsTruncated when more may exist; nativeSessionsError when the Claude Code inventory could not be read). A native session names why it takes no message (readOnly) or how a background job takes one (jobDelivery: wake or inbox). Read or message it with sessionId { harnessId: claude, nativeId }.',
444
473
  inputSchema: plugins.z.object({
445
474
  projectId: boundedNonblankString(maximumIdentifierBytes, 'projectId'),
446
475
  }).strict(),
@@ -454,7 +483,7 @@ export class AglMcpTools {
454
483
  {
455
484
  title: 'Read an AGL session',
456
485
  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
457
- description: 'Read the bounded current detail for one qualified AGL session.',
486
+ description: 'Read the bounded current detail for one qualified AGL session. A Claude Code session outside AGL (sessions_list nativeSessions) answers with kind native: the session with readOnly or jobDelivery, its newest transcript page and its scratchpad.',
458
487
  inputSchema: plugins.z.object({
459
488
  projectId: boundedNonblankString(maximumIdentifierBytes, 'projectId'),
460
489
  sessionId: runtimeIdSchema,
@@ -512,9 +541,13 @@ export class AglMcpTools {
512
541
  + 'next-turn makes it the next turn\'s input, queue runs it after every earlier message; each '
513
542
  + 'starts a turn when nothing runs. OpenCode cannot be steered. To steer a Codex turn, pass '
514
543
  + 'expectedTurnId from session_read codexActivity.turnId; steering a turn another Codex '
515
- + 'client runs requires it, and such a turn takes steers only. The result says how the '
516
- + 'message was delivered. The owner can refuse agent messages for a project, and sending '
517
- + 'is rate-limited. An OUTCOME_UNKNOWN result must not be retried automatically.',
544
+ + 'client runs requires it, and such a turn takes steers only. A Claude Code background '
545
+ + 'job outside AGL (sessions_list nativeSessions) takes it through Claude Code itself, '
546
+ + 'whatever the delivery: a settled job is woken with it (native wake, delivery next-turn), '
547
+ + 'a running one gets it in its inbox, accepted and queued, not yet read (native inbox, '
548
+ + 'delivery queue); a session with readOnly is refused with SESSION_READ_ONLY. The result '
549
+ + 'says how the message was delivered. The owner can refuse agent messages for a project, '
550
+ + 'and sending is rate-limited. An OUTCOME_UNKNOWN result must not be retried automatically.',
518
551
  inputSchema: plugins.z.object({
519
552
  projectId: boundedNonblankString(maximumIdentifierBytes, 'projectId'),
520
553
  sessionId: runtimeIdSchema,
@@ -28,6 +28,7 @@ import { assertMcpTicketRequest } from './functions.ticketvalidation.js';
28
28
  import { assertFleetWireRequest } from './fleet/functions.validation.js';
29
29
  import { assertSessionFeedWireRequest } from './functions.sessionfeedvalidation.js';
30
30
  import { assertFleetDeployWireRequest } from './fleet/functions.deployvalidation.js';
31
+ import { isProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
31
32
 
32
33
  const maximumIdBytes = 1024;
33
34
  const maximumModelPartBytes = 512;
@@ -144,6 +145,10 @@ const assertMethodRequest = (
144
145
  return assertSessionFeedWireRequest(methodArg, requestArg);
145
146
  }
146
147
  if (methodArg.startsWith('agl.mcp.deploy.')) return assertFleetDeployWireRequest(methodArg, requestArg);
148
+ if (methodArg === 'agl.mcp.proxy.capacity') {
149
+ if (!isProxyCapacityRequest(requestArg)) throw new Error('Invalid private controller request.');
150
+ return requestArg;
151
+ }
147
152
  if (methodArg.startsWith('agl.mcp.configuration.')) {
148
153
  // The authority validates the master document itself; this admits the request's shape.
149
154
  const required: Partial<Record<TControllerMcpMethod, string[]>> = {
@@ -349,6 +354,30 @@ export const assertControllerMcpWireCaller = (
349
354
 
350
355
  export const controllerMcpValueIsRecord = isRecord;
351
356
 
357
+ const nativeReadOnlyReasons = new Set(['running', 'unaddressable', 'notBackgroundJob', 'profileHome', 'directoryMissing',
358
+ 'projectConversation', 'fleetWorker', 'jobFailed', 'jobHeld']);
359
+ /**
360
+ * Holds a Claude Code session outside AGL as the MCP routes answer it (`IControllerNativeSession`): a host session, no
361
+ * profile, its directory, title and status, and either why it takes no message or how a background job takes one.
362
+ */
363
+ export const assertControllerMcpNativeSession = (valueArg: unknown): void => {
364
+ if (!isRecord(valueArg)) throw new Error('Invalid native session.');
365
+ assertExactKeys(valueArg, ['harness', 'nativeId', 'cwd', 'title', 'status'],
366
+ ['updatedAt', 'workerName', 'model', 'effort', 'readOnly', 'jobDelivery']);
367
+ if (valueArg.harness !== 'claude' || typeof valueArg.nativeId !== 'string' || valueArg.nativeId.length === 0
368
+ || typeof valueArg.cwd !== 'string' || typeof valueArg.title !== 'string'
369
+ || !['busy', 'idle', 'error'].includes(valueArg.status as string)
370
+ || (valueArg.updatedAt !== undefined && (typeof valueArg.updatedAt !== 'number' || !Number.isFinite(valueArg.updatedAt)))
371
+ || [valueArg.workerName, valueArg.model, valueArg.effort].some((field) => field !== undefined && typeof field !== 'string')
372
+ || (valueArg.jobDelivery !== undefined && valueArg.jobDelivery !== 'wake' && valueArg.jobDelivery !== 'inbox')
373
+ || (valueArg.readOnly !== undefined && valueArg.jobDelivery !== undefined)) throw new Error('Invalid native session.');
374
+ if (valueArg.readOnly !== undefined) {
375
+ if (!isRecord(valueArg.readOnly)) throw new Error('Invalid native session.');
376
+ assertExactKeys(valueArg.readOnly, ['reason', 'message']);
377
+ if (!nativeReadOnlyReasons.has(valueArg.readOnly.reason as string) || typeof valueArg.readOnly.message !== 'string') throw new Error('Invalid native session.');
378
+ }
379
+ };
380
+
352
381
  export const assertControllerMcpExactKeys = assertExactKeys;
353
382
 
354
383
  const fieldKindMatchers: Record<TControllerMcpFieldKind, (valueArg: unknown) => boolean> = {
@@ -492,13 +521,15 @@ export const assertControllerMcpWorkspaceResponse = (
492
521
  plugins.browserRuntime.validateAgentActionResult(valueArg.result);
493
522
  }
494
523
  } else if (methodArg === 'agl.mcp.context.resolve' || methodArg === 'agl.mcp.project.create') {
495
- assertExactKeys(valueArg, ['project'], methodArg === 'agl.mcp.context.resolve' ? ['session'] : []);
524
+ assertExactKeys(valueArg, ['project'], methodArg === 'agl.mcp.context.resolve' ? ['session', 'nativeSession'] : []);
496
525
  if (!isRecord(valueArg.project) || typeof valueArg.project.id !== 'string'
497
526
  || typeof valueArg.project.directory !== 'string') throw new Error('Invalid project response.');
527
+ if (valueArg.session !== undefined && valueArg.nativeSession !== undefined) throw new Error('Invalid session response.');
498
528
  if (valueArg.session !== undefined) {
499
529
  if (!isRecord(valueArg.session)) throw new Error('Invalid session response.');
500
530
  assertControllerMcpRuntimeId(valueArg.session.id);
501
531
  }
532
+ if (valueArg.nativeSession !== undefined) assertControllerMcpNativeSession(valueArg.nativeSession);
502
533
  } else if (methodArg === 'agl.mcp.model.list') {
503
534
  assertExactKeys(valueArg, ['models', 'defaults', 'flexAccountPlacement'], ['codexContext']);
504
535
  if (!Array.isArray(valueArg.models) || !Array.isArray(valueArg.defaults)
@@ -3,6 +3,7 @@ import type { IFleetWorker } from '../ts_interfaces/fleetworkers.js';
3
3
  import type {
4
4
  IControllerNativeSession,
5
5
  IControllerNativeSessionRef,
6
+ TControllerNativeJobDelivery,
6
7
  TControllerNativeSessionReadOnlyReason,
7
8
  } from '../ts_interfaces/index.js';
8
9
  import type { IFleetNativeAgent, IFleetNativeSession, IFleetNativeThread } from './fleet/interfaces.workers.js';
@@ -34,14 +35,21 @@ export interface IResolvedNativeSession {
34
35
  scope: { profileId: string | null };
35
36
  worker?: IFleetWorker;
36
37
  /**
37
- * A Claude Code background job holds the session: a send wakes the job through Claude Code itself, never AGL's own
38
- * Claude Code, so the job stays its owner.
38
+ * A Claude Code background job holds the session: a send reaches the job through Claude Code itself, never AGL's own
39
+ * Claude Code, so the job stays its owner. It wakes a settled job, and goes into a running job's inbox.
39
40
  */
40
- claudeJob?: true;
41
+ claudeJob?: TControllerNativeJobDelivery;
42
+ /**
43
+ * For a running job's inbox: the fleet profile homes apart from the host's own, whose running sessions SendMessage
44
+ * reaches by name too; the send checks the job's name against them again at dispatch (`IFleetNativeSession.peerHomes`).
45
+ */
46
+ peerHomes?: string[];
41
47
  }
42
48
 
43
- const readOnlyMessages: Record<TControllerNativeSessionReadOnlyReason, string> = {
49
+ export const nativeSessionReadOnlyMessages: Record<TControllerNativeSessionReadOnlyReason, string> = {
44
50
  running: 'Another Claude Code process runs this session. AGL never becomes its second writer; the composer unlocks once it settles.',
51
+ unaddressable: 'This Claude Code background job runs, and Claude Code\'s SendMessage reaches a running job only by a session name no other running session shares; this one has no name or shares it. The composer unlocks once it settles.',
52
+ notBackgroundJob: 'This Claude Code session is no background job (`claude --bg`): agents reach only background jobs. The owner sends to it from its native session view in AGL.',
45
53
  profileHome: 'This session lives in a fleet profile\'s Claude Code home, which AGL\'s own Claude Code does not resume. It stays read-only here.',
46
54
  directoryMissing: 'The session\'s directory is missing, so nothing can resume it. It stays read-only.',
47
55
  projectConversation: 'An AGL project conversation holds this Claude Code session. Send to it from its project.',
@@ -124,11 +132,16 @@ export class NativeSessions {
124
132
  const cwd = agent?.cwd ?? boundWorker!.cwd;
125
133
  const own = home === undefined || samePath(home, this.sources.ownClaudeHome());
126
134
  const held = this.sources.claudeHeld(refArg.nativeId);
127
- const running = held === undefined && agent !== undefined
128
- && (agent.pid !== undefined || agent.state === 'working' || agent.status === 'busy');
129
135
  const job = agent?.kind === 'background';
130
- // A failed job is not woken unverified; one AGL's own Claude Code holds would be woken as a copy.
131
- const jobReason = !job ? undefined : agent.state === 'failed' ? 'jobFailed' as const : held ? 'jobHeld' as const : undefined;
136
+ // A running background job takes a message in its inbox, through Claude Code's own SendMessage: no second writer.
137
+ const inbox = job && held === undefined && agent.pid !== undefined && agent.status !== undefined
138
+ && agent.state !== 'failed' && agent.state !== 'stopped';
139
+ const running = held === undefined && agent !== undefined && !inbox
140
+ && (agent.pid !== undefined || agent.state === 'working' || agent.status === 'busy');
141
+ // A failed job is not woken unverified; one AGL's own Claude Code holds would be woken as a copy; SendMessage
142
+ // addresses a running job by a name no other running session of any listed home shares, never by a guess.
143
+ const jobReason = !job ? undefined : agent.state === 'failed' ? 'jobFailed' as const : held ? 'jobHeld' as const
144
+ : inbox && !await this.uniquelyNamed(agent, profiles) ? 'unaddressable' as const : undefined;
132
145
  const reason = await this.readOnlyReason(cwd, boundWorker, !own, running,
133
146
  own && await this.sources.claudeProjectConversation(refArg.nativeId), jobReason);
134
147
  const status: IControllerNativeSession['status'] = held
@@ -146,15 +159,40 @@ export class NativeSessions {
146
159
  status,
147
160
  ...(agent?.startedAt === undefined ? {} : { updatedAt: agent.startedAt }),
148
161
  ...this.workerFields(boundWorker),
149
- ...(reason === undefined ? {} : { readOnly: { reason, message: readOnlyMessages[reason] } }),
162
+ ...(reason === undefined ? {} : { readOnly: { reason, message: nativeSessionReadOnlyMessages[reason] } }),
163
+ ...(job && reason === undefined ? { jobDelivery: inbox ? 'inbox' as const : 'wake' as const } : {}),
150
164
  },
151
165
  native: { nativeId: refArg.nativeId, cwd, ...(own ? {} : { home }) },
152
166
  scope: { profileId: own ? null : scopeProfile ?? null },
153
167
  ...(boundWorker ? { worker: boundWorker } : {}),
154
- ...(job ? { claudeJob: true as const } : {}),
168
+ ...(job ? { claudeJob: inbox ? 'inbox' as const : 'wake' as const } : {}),
169
+ // A profile home's job is read-only (`profileHome`), so only an inbox of the host's own home is ever addressed.
170
+ ...(own && inbox ? { peerHomes: this.peerHomes(profiles) } : {}),
155
171
  };
156
172
  }
157
173
 
174
+ /**
175
+ * Whether the running session `agentArg` is the only running session of that name in the host's inventory and every
176
+ * fleet profile home's: Claude Code's SendMessage resolves a recipient by its name among the sessions it can reach.
177
+ */
178
+ private async uniquelyNamed(agentArg: IFleetNativeAgent, profilesArg: Array<{ profileId: string; home: string }>): Promise<boolean> {
179
+ if (!agentArg.name) return false;
180
+ let named = 0;
181
+ for (const home of [undefined, ...this.peerHomes(profilesArg)]) {
182
+ named += (await this.sources.claudeAgents(home)).filter((entry) => entry.pid !== undefined && entry.name === agentArg.name).length;
183
+ }
184
+ return named === 1;
185
+ }
186
+
187
+ /** The fleet profile homes apart from the host's own, each once. */
188
+ private peerHomes(profilesArg: Array<{ profileId: string; home: string }>): string[] {
189
+ const own = this.sources.ownClaudeHome(), homes: string[] = [];
190
+ for (const { home } of profilesArg) {
191
+ if (!samePath(home, own) && !homes.some((entry) => samePath(entry, home))) homes.push(home);
192
+ }
193
+ return homes;
194
+ }
195
+
158
196
  private async resolveCodex(refArg: IControllerNativeSessionRef): Promise<IResolvedNativeSession> {
159
197
  if (refArg.profileId !== undefined) throw nativeSessionNotFound();
160
198
  const [threads, worker] = await Promise.all([
@@ -174,7 +212,7 @@ export class NativeSessions {
174
212
  status: thread === undefined ? 'idle' : thread.status === 'busy' || thread.status === 'waiting' ? 'busy' : thread.status,
175
213
  ...(thread === undefined ? {} : { updatedAt: thread.updatedAt }),
176
214
  ...this.workerFields(worker),
177
- ...(reason === undefined ? {} : { readOnly: { reason, message: readOnlyMessages[reason] } }),
215
+ ...(reason === undefined ? {} : { readOnly: { reason, message: nativeSessionReadOnlyMessages[reason] } }),
178
216
  },
179
217
  native: { nativeId: refArg.nativeId, cwd },
180
218
  scope: { profileId: null },
@@ -193,7 +231,7 @@ export class NativeSessions {
193
231
  profileHomeArg: boolean,
194
232
  runningArg: boolean,
195
233
  projectConversationArg: boolean,
196
- jobArg?: 'jobFailed' | 'jobHeld',
234
+ jobArg?: 'jobFailed' | 'jobHeld' | 'unaddressable',
197
235
  ): Promise<TControllerNativeSessionReadOnlyReason | undefined> {
198
236
  if (!await this.sources.directoryExists(cwdArg)) return 'directoryMissing';
199
237
  if (projectConversationArg) return 'projectConversation';
@@ -1286,7 +1286,11 @@ export const createBoundedOpenCodeSelectedMessageSlice = (
1286
1286
  throw new Error('Selected OpenCode message shells exceeded the aggregate output budget.');
1287
1287
  };
1288
1288
 
1289
- export const normalizeOpenCodePermissions = (value: unknown): IControllerPermission[] => {
1289
+ /** A pending request as OpenCode lists it, which carries no time: the adapter adds when it entered (`createdAt`). */
1290
+ export type TOpenCodePendingPermission = Omit<IControllerPermission, 'createdAt'>;
1291
+ export type TOpenCodePendingQuestion = Omit<IControllerQuestion, 'createdAt'>;
1292
+
1293
+ export const normalizeOpenCodePermissions = (value: unknown): TOpenCodePendingPermission[] => {
1290
1294
  if (!Array.isArray(value) || value.length > maxCollectionEntries) {
1291
1295
  throw new Error('OpenCode returned an invalid permission list.');
1292
1296
  }
@@ -1337,7 +1341,7 @@ export const normalizeOpenCodePermissions = (value: unknown): IControllerPermiss
1337
1341
  return result;
1338
1342
  };
1339
1343
 
1340
- export const normalizeOpenCodeQuestions = (value: unknown): IControllerQuestion[] => {
1344
+ export const normalizeOpenCodeQuestions = (value: unknown): TOpenCodePendingQuestion[] => {
1341
1345
  if (!Array.isArray(value) || value.length > maxCollectionEntries) {
1342
1346
  throw new Error('OpenCode returned an invalid question list.');
1343
1347
  }
@@ -1626,6 +1630,20 @@ const openCodeTurnRefusalText = (errorArg: unknown): string | undefined => {
1626
1630
  return Buffer.byteLength(text, 'utf8') <= maxTurnRefusalBytes ? text : `${truncateUtf8(text, maxTurnRefusalBytes)}…`;
1627
1631
  };
1628
1632
 
1633
+ /** At most this many pending requests keep the time they entered. */
1634
+ const maxPendingSinceEntries = 4096;
1635
+
1636
+ /** The permission or question an `asked` event announces: the time it entered OpenCode's pending requests is now. */
1637
+ export const openCodeAskedRequest = (valueArg: unknown): { directory: string; kind: 'permission' | 'question'; id: string } | undefined => {
1638
+ if (!isRecord(valueArg) || typeof valueArg.directory !== 'string' || !isRecord(valueArg.payload)) return undefined;
1639
+ const { type, properties } = valueArg.payload;
1640
+ const kind = type === 'permission.asked' || type === 'permission.v2.asked' ? 'permission'
1641
+ : type === 'question.asked' || type === 'question.v2.asked' ? 'question' : undefined;
1642
+ if (!kind || !isRecord(properties) || typeof properties.id !== 'string' || properties.id.length === 0
1643
+ || Buffer.byteLength(properties.id, 'utf8') > maxIdentifierBytes) return undefined;
1644
+ return { directory: valueArg.directory, kind, id: properties.id };
1645
+ };
1646
+
1629
1647
  const normalizeEvent = (
1630
1648
  value: unknown,
1631
1649
  ): TNormalizedOpenCodeEvent | undefined => {
@@ -1863,6 +1881,11 @@ export class OpenCodeClientAdapter implements IOpenCodeSessionIdentitySnapshotCa
1863
1881
  private eventTask?: Promise<void>;
1864
1882
  private readonly runtimeRequestAbortController = new AbortController();
1865
1883
  private readonly temporarySessionIds = new Set<string>();
1884
+ /**
1885
+ * When each pending permission and question entered OpenCode's pending requests, as this adapter first heard of it
1886
+ * (its `asked` event, or the first list that held it): OpenCode's requests carry no time of their own.
1887
+ */
1888
+ private readonly pendingSince = new Map<string, { at: number; directory: string }>();
1866
1889
  /** The message AGL last sent each session, by session ID: a refusal that follows is that message's. */
1867
1890
  private readonly lastSentMessageIds = new Map<string, string>();
1868
1891
  /** Why OpenCode refused a message AGL sent, by session ID and message ID (`openCodeTurnRefusalText`). */
@@ -3192,6 +3215,32 @@ export class OpenCodeClientAdapter implements IOpenCodeSessionIdentitySnapshotCa
3192
3215
  }
3193
3216
  }
3194
3217
 
3218
+ /** Records that the request `idArg` of `kindArg` entered OpenCode's pending requests now, unless it was seen before. */
3219
+ private notePendingRequest(directoryArg: string, kindArg: 'permission' | 'question', idArg: string): number {
3220
+ const key = `${kindArg}:${idArg}`;
3221
+ const seen = this.pendingSince.get(key);
3222
+ if (seen) return seen.at;
3223
+ const at = Date.now();
3224
+ rememberNewest(this.pendingSince, key, { at, directory: directoryArg }, maxPendingSinceEntries);
3225
+ return at;
3226
+ }
3227
+
3228
+ /**
3229
+ * The directory's whole pending list of `kindArg` with the time each request entered it. The requests of the
3230
+ * directory that the list no longer holds are forgotten.
3231
+ */
3232
+ private withPendingSince<TRequest extends { id: IControllerRuntimeId }>(
3233
+ directoryArg: string,
3234
+ kindArg: 'permission' | 'question',
3235
+ requestsArg: TRequest[],
3236
+ ): Array<TRequest & { createdAt: number }> {
3237
+ const listed = new Set(requestsArg.map((requestArg) => `${kindArg}:${requestArg.id.nativeId}`));
3238
+ for (const [key, entry] of this.pendingSince) {
3239
+ if (entry.directory === directoryArg && key.startsWith(`${kindArg}:`) && !listed.has(key)) this.pendingSince.delete(key);
3240
+ }
3241
+ return requestsArg.map((requestArg) => ({ ...requestArg, createdAt: this.notePendingRequest(directoryArg, kindArg, requestArg.id.nativeId) }));
3242
+ }
3243
+
3195
3244
  public async listPermissions(
3196
3245
  directoryArg: string,
3197
3246
  sessionId?: string,
@@ -3208,7 +3257,7 @@ export class OpenCodeClientAdapter implements IOpenCodeSessionIdentitySnapshotCa
3208
3257
  { signal: requestSignal }
3209
3258
  )
3210
3259
  );
3211
- const permissions = normalizeOpenCodePermissions(response);
3260
+ const permissions = this.withPendingSince(directory, 'permission', normalizeOpenCodePermissions(response));
3212
3261
  return validatedSessionId
3213
3262
  ? permissions.filter((permission) => permission.sessionId.nativeId === validatedSessionId)
3214
3263
  : permissions;
@@ -3230,7 +3279,7 @@ export class OpenCodeClientAdapter implements IOpenCodeSessionIdentitySnapshotCa
3230
3279
  { signal: requestSignal }
3231
3280
  )
3232
3281
  );
3233
- const questions = normalizeOpenCodeQuestions(response);
3282
+ const questions = this.withPendingSince(directory, 'question', normalizeOpenCodeQuestions(response));
3234
3283
  return validatedSessionId
3235
3284
  ? questions.filter((question) => question.sessionId.nativeId === validatedSessionId)
3236
3285
  : questions;
@@ -4356,6 +4405,8 @@ export class OpenCodeClientAdapter implements IOpenCodeSessionIdentitySnapshotCa
4356
4405
  }
4357
4406
  }
4358
4407
 
4408
+ const asked = openCodeAskedRequest(event);
4409
+ if (asked) this.notePendingRequest(asked.directory, asked.kind, asked.id);
4359
4410
  const normalized = normalizeEvent(event);
4360
4411
  if (!normalized) continue;
4361
4412
  if ('toolStreamGap' in normalized) {
@@ -17,6 +17,7 @@ import {
17
17
  type TProxyCredentialDelivery,
18
18
  } from './functions.proxycontract.js';
19
19
  import { isAuthorityAccountId } from '../ts_interfaces/functions.authorityscope.js';
20
+ import { isProxyCapacityRequest, type IProxyCapacityAnswer, type IProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
20
21
  import { proxyControlMaximumFrameBytes, readProxyControlLine } from './classes.proxycontrolclient.js';
21
22
  import { claimProxySocketPath } from './functions.proxysocket.js';
22
23
 
@@ -116,6 +117,16 @@ export interface IReq_AglProxyStatus extends ITypedRequest {
116
117
  response: { status: IAglProxyStatus };
117
118
  }
118
119
 
120
+ /**
121
+ * A pool's room for new work, or both pools' when `provider` is absent (AGL-1097): see `IProxyCapacityAnswer` and
122
+ * `proxyPoolCapacity`. Refused while the account service is unavailable. A proxy before AGL-1097 refuses the method.
123
+ */
124
+ export interface IReq_AglProxyCapacity extends ITypedRequest {
125
+ method: 'agl.proxy.capacity';
126
+ request: IProxyCapacityRequest;
127
+ response: IProxyCapacityAnswer;
128
+ }
129
+
119
130
  /**
120
131
  * A credential that lives as long as the connection that asked for it. A proxy that restarts keeps the leases its
121
132
  * holders have not ended, and serves them for a bounded window in which each holder takes its lease back on a new
@@ -228,6 +239,7 @@ export interface IAglProxyConnection {
228
239
  export interface IAglProxyControlHandlers {
229
240
  credential(requestArg: IReq_AglProxyCredential['request']): Promise<IReq_AglProxyCredential['response']>;
230
241
  status(): Promise<IReq_AglProxyStatus['response']>;
242
+ capacity(requestArg: IReq_AglProxyCapacity['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyCapacity['response']>;
231
243
  catalog(requestArg: IReq_AglProxyCatalog['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyCatalog['response']>;
232
244
  lease(requestArg: IReq_AglProxyLease['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyLease['response']>;
233
245
  reclaim(requestArg: IReq_AglProxyReclaim['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyReclaim['response']>;
@@ -301,6 +313,10 @@ export class AglProxyControlServer {
301
313
  return this.handlers!.credential(requestArg);
302
314
  }));
303
315
  this.router.addTypedHandler(handler<IReq_AglProxyStatus>('agl.proxy.status', () => this.handlers!.status()));
316
+ this.router.addTypedHandler(handler<IReq_AglProxyCapacity>('agl.proxy.capacity', (requestArg, connectionArg) => {
317
+ if (!isProxyCapacityRequest(requestArg)) throw new AglProxyControlRefusal('Invalid proxy capacity request.');
318
+ return this.handlers!.capacity(requestArg, connectionArg);
319
+ }));
304
320
  this.router.addTypedHandler(handler<IReq_AglProxyCatalog>('agl.proxy.catalog', (requestArg, connectionArg) => {
305
321
  if (!isRecord(requestArg)
306
322
  || Object.keys(requestArg).some((keyArg) => !['provider', 'credential', 'accountId'].includes(keyArg))