agl 43.1.0 → 43.2.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 (123) hide show
  1. package/changelog.md +12 -0
  2. package/dist_serve/bundle.js +5329 -5116
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +30 -30
  5. package/dist_serve/bundle.js.third-party-notices.txt +30 -30
  6. package/dist_ts/00_commitinfo_data.js +1 -1
  7. package/dist_ts/aglapi/aglapisurface.document.js +325 -1
  8. package/dist_ts/aglapi/interfaces.d.ts +3 -0
  9. package/dist_ts/aglapi/interfaces.js +2 -1
  10. package/dist_ts/classes.authmodels.js +17 -4
  11. package/dist_ts/classes.authstore.js +16 -2
  12. package/dist_ts/classes.cli.d.ts +4 -2
  13. package/dist_ts/classes.cli.js +6 -3
  14. package/dist_ts/classes.controller.d.ts +10 -0
  15. package/dist_ts/classes.controller.js +119 -4
  16. package/dist_ts/classes.controllermanagement.d.ts +14 -4
  17. package/dist_ts/classes.controllermanagement.js +20 -2
  18. package/dist_ts/classes.gatewayclient.d.ts +115 -0
  19. package/dist_ts/classes.gatewayclient.js +336 -0
  20. package/dist_ts/classes.gatewayclientstore.d.ts +97 -0
  21. package/dist_ts/classes.gatewayclientstore.js +261 -0
  22. package/dist_ts/classes.inferencerouter.d.ts +9 -0
  23. package/dist_ts/classes.inferencerouter.js +11 -1
  24. package/dist_ts/classes.inferenceservice.d.ts +9 -0
  25. package/dist_ts/classes.inferenceservice.js +27 -1
  26. package/dist_ts/classes.mcpclient.d.ts +4 -1
  27. package/dist_ts/classes.mcpclient.js +19 -1
  28. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -1
  29. package/dist_ts/classes.mcpcontrollerhost.js +9 -1
  30. package/dist_ts/classes.mcptools.d.ts +3 -3
  31. package/dist_ts/classes.mcptools.js +26 -1
  32. package/dist_ts/classes.mcpvalidation.js +7 -1
  33. package/dist_ts/classes.proxycontrol.d.ts +11 -0
  34. package/dist_ts/classes.proxycontrol.js +7 -1
  35. package/dist_ts/classes.proxycontrolclient.d.ts +17 -0
  36. package/dist_ts/classes.proxycontrolclient.js +35 -1
  37. package/dist_ts/classes.proxydaemon.js +8 -1
  38. package/dist_ts/classes.proxymonitor.d.ts +7 -0
  39. package/dist_ts/classes.proxymonitor.js +13 -1
  40. package/dist_ts/classes.trustedproxysecrets.d.ts +2 -0
  41. package/dist_ts/classes.trustedproxysecrets.js +5 -1
  42. package/dist_ts/functions.controllermanagementsurface.d.ts +4 -0
  43. package/dist_ts/functions.controllermanagementsurface.js +15 -1
  44. package/dist_ts/functions.gatewaycli.d.ts +24 -0
  45. package/dist_ts/functions.gatewaycli.js +395 -0
  46. package/dist_ts/functions.gatewayroute.d.ts +135 -0
  47. package/dist_ts/functions.gatewayroute.js +366 -0
  48. package/dist_ts/functions.inferencecli.js +30 -1
  49. package/dist_ts/functions.inferencecliarguments.d.ts +8 -2
  50. package/dist_ts/functions.inferencecliarguments.js +31 -3
  51. package/dist_ts/functions.proxycapacity.d.ts +50 -0
  52. package/dist_ts/functions.proxycapacity.js +142 -0
  53. package/dist_ts/functions.proxycapacitycli.d.ts +30 -0
  54. package/dist_ts/functions.proxycapacitycli.js +65 -0
  55. package/dist_ts/functions.remotecli.d.ts +30 -3
  56. package/dist_ts/functions.remotecli.js +44 -18
  57. package/dist_ts/interfaces.auth.d.ts +25 -4
  58. package/dist_ts/interfaces.auth.js +7 -1
  59. package/dist_ts/plugins.d.ts +2 -0
  60. package/dist_ts/plugins.js +4 -1
  61. package/dist_ts_authswitch/authority-placement.js +3 -17
  62. package/dist_ts_authswitch/authority-usagelimit.d.ts +29 -0
  63. package/dist_ts_authswitch/authority-usagelimit.js +66 -2
  64. package/dist_ts_authswitch/authority-usagewindows.d.ts +6 -0
  65. package/dist_ts_authswitch/authority-usagewindows.js +15 -1
  66. package/dist_ts_interfaces/gateway.d.ts +151 -0
  67. package/dist_ts_interfaces/gateway.js +66 -0
  68. package/dist_ts_interfaces/index.d.ts +2 -0
  69. package/dist_ts_interfaces/index.js +3 -1
  70. package/dist_ts_interfaces/management.d.ts +4 -4
  71. package/dist_ts_interfaces/management.js +3 -2
  72. package/dist_ts_interfaces/mcprequests.d.ts +14 -2
  73. package/dist_ts_interfaces/mcprequests.js +2 -1
  74. package/dist_ts_interfaces/proxycapacity.d.ts +99 -0
  75. package/dist_ts_interfaces/proxycapacity.js +74 -0
  76. package/package.json +4 -3
  77. package/readme.md +79 -5
  78. package/ts/00_commitinfo_data.ts +1 -1
  79. package/ts/aglapi/aglapisurface.document.ts +324 -0
  80. package/ts/aglapi/interfaces.ts +1 -0
  81. package/ts/classes.authmodels.ts +22 -3
  82. package/ts/classes.authstore.ts +15 -1
  83. package/ts/classes.cli.ts +7 -3
  84. package/ts/classes.controller.ts +134 -3
  85. package/ts/classes.controllermanagement.ts +40 -7
  86. package/ts/classes.gatewayclient.ts +401 -0
  87. package/ts/classes.gatewayclientstore.ts +272 -0
  88. package/ts/classes.inferencerouter.ts +12 -0
  89. package/ts/classes.inferenceservice.ts +27 -0
  90. package/ts/classes.mcpclient.ts +18 -0
  91. package/ts/classes.mcpcontrollerhost.ts +13 -0
  92. package/ts/classes.mcptools.ts +30 -2
  93. package/ts/classes.mcpvalidation.ts +5 -0
  94. package/ts/classes.proxycontrol.ts +16 -0
  95. package/ts/classes.proxycontrolclient.ts +30 -0
  96. package/ts/classes.proxydaemon.ts +8 -0
  97. package/ts/classes.proxymonitor.ts +12 -0
  98. package/ts/classes.trustedproxysecrets.ts +5 -0
  99. package/ts/functions.controllermanagementsurface.ts +15 -0
  100. package/ts/functions.gatewaycli.ts +436 -0
  101. package/ts/functions.gatewayroute.ts +429 -0
  102. package/ts/functions.inferencecli.ts +24 -0
  103. package/ts/functions.inferencecliarguments.ts +30 -4
  104. package/ts/functions.proxycapacity.ts +191 -0
  105. package/ts/functions.proxycapacitycli.ts +104 -0
  106. package/ts/functions.remotecli.ts +56 -20
  107. package/ts/interfaces.auth.ts +28 -4
  108. package/ts/plugins.ts +5 -0
  109. package/ts_authswitch/authority-placement.ts +2 -15
  110. package/ts_authswitch/authority-usagelimit.ts +84 -1
  111. package/ts_authswitch/authority-usagewindows.ts +13 -0
  112. package/ts_interfaces/gateway.ts +242 -0
  113. package/ts_interfaces/index.ts +2 -0
  114. package/ts_interfaces/management.ts +6 -4
  115. package/ts_interfaces/mcprequests.ts +18 -0
  116. package/ts_interfaces/proxycapacity.ts +162 -0
  117. package/ts_web/00_commitinfo_data.ts +1 -1
  118. package/ts_web/classes.browserpresentation.ts +13 -5
  119. package/ts_web/elements.accounts.ts +40 -113
  120. package/ts_web/elements.configurationpane.ts +24 -37
  121. package/ts_web/elements.devices.ts +4 -17
  122. package/ts_web/elements.flexlimitstrip.ts +21 -70
  123. package/ts_web/elements.harnesscontrollerapp.ts +91 -185
@@ -2005,6 +2005,18 @@ export class InferenceRouter {
2005
2005
  return statuses;
2006
2006
  }
2007
2007
 
2008
+ /**
2009
+ * The newest provider 429 this router saw on the account since it started (epoch milliseconds), or `null`, and until
2010
+ * when the account rests after it as routing judges it on `usageArg` (`cooldownUntil`; 0 when it does not rest): the
2011
+ * proxy's capacity reads both (`proxyPoolCapacity`). Held in memory only, so a restarted proxy starts with none.
2012
+ */
2013
+ public quotaOf(accountArg: IInferenceAccount,
2014
+ usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): { lastAt: number | null; restUntil: number } {
2015
+ const cooldown = this.cooldowns.get(accountArg.id);
2016
+ const until = cooldownUntil(cooldown, accountArg.credential === 'api_key' ? undefined : usageArg);
2017
+ return { lastAt: cooldown?.at ?? null, restUntil: until > this.now() ? until : 0 };
2018
+ }
2019
+
2008
2020
  /** Counts one request on an account until its release, which may be called more than once. */
2009
2021
  private reserve(idArg: string): () => void {
2010
2022
  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) {
@@ -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;
@@ -12,6 +12,7 @@ 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 {
16
17
  controllerMcpSessionDetailFields,
17
18
  controllerMcpTypedResponseMaximumBytes,
@@ -111,6 +112,9 @@ export type TControllerMcpClientErrorCode =
111
112
  | 'DELIVERY_UNSUPPORTED'
112
113
  | 'REQUEST_FAILED'
113
114
  | 'OUTCOME_UNKNOWN'
115
+ | 'PROXY_UNAVAILABLE'
116
+ | 'PROXY_OUTDATED'
117
+ | 'PROXY_ACCOUNTS_UNAVAILABLE'
114
118
  | Uppercase<TFleetWorkerErrorCode>;
115
119
 
116
120
  export class ControllerMcpClientError extends Error {
@@ -280,6 +284,10 @@ const assertResponsePayload = (
280
284
  if (new Set(models.map(model => model.harnessId)).size !== models.length) throw new Error('invalid');
281
285
  return;
282
286
  }
287
+ if (methodArg === 'agl.mcp.proxy.capacity') {
288
+ if (!isProxyCapacityAnswer(valueArg)) throw new Error('invalid');
289
+ return;
290
+ }
283
291
  if (methodArg === 'agl.mcp.configuration.state') {
284
292
  assertControllerMcpExactKeys(valueArg, ['resource', 'projectionRun', 'harnesses', 'history'], ['master', 'projection']);
285
293
  if (!controllerMcpValueIsRecord(valueArg.resource) || !controllerMcpValueIsRecord(valueArg.projectionRun)
@@ -446,6 +454,11 @@ export class ControllerMcpClient {
446
454
  this.requestTimeoutMs = timeout;
447
455
  }
448
456
 
457
+ /** A pool's room for new work in AGL's inference proxy, or both pools', as the controller asks the proxy for it. */
458
+ public async proxyCapacity(requestArg: IProxyCapacityRequest, signalArg?: AbortSignal): Promise<IProxyCapacityAnswer> {
459
+ return this.dispatchAfterHandshake('agl.mcp.proxy.capacity', requestArg, signalArg, false);
460
+ }
461
+
449
462
  public async status(signalArg?: AbortSignal): Promise<IReq_ControllerMcpStatus['response']> {
450
463
  const descriptor = await this.readCompatibleDescriptor();
451
464
  const status = await this.dispatch(
@@ -987,6 +1000,11 @@ export class ControllerMcpClient {
987
1000
  if (serverCode === 'agent_messages_disabled') code = 'AGENT_MESSAGES_DISABLED';
988
1001
  if (serverCode === 'message_rate_limited') code = 'MESSAGE_RATE_LIMITED';
989
1002
  if (serverCode === 'delivery_unsupported') code = 'DELIVERY_UNSUPPORTED';
1003
+ if (methodArg === 'agl.mcp.proxy.capacity') {
1004
+ if (serverCode === 'proxy_unavailable') code = 'PROXY_UNAVAILABLE';
1005
+ if (serverCode === 'proxy_outdated') code = 'PROXY_OUTDATED';
1006
+ if (serverCode === 'proxy_accounts_unavailable') code = 'PROXY_ACCOUNTS_UNAVAILABLE';
1007
+ }
990
1008
  if (methodArg.startsWith('agl.mcp.fleet.worker.') && (fleetWorkerErrorCodes as readonly unknown[]).includes(serverCode)) {
991
1009
  code = (serverCode as TFleetWorkerErrorCode).toUpperCase() as Uppercase<TFleetWorkerErrorCode>;
992
1010
  }
@@ -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']>;
@@ -331,6 +335,9 @@ const safeTypedResponseError = (
331
335
  sessionfeed_row_not_found: 'The session feed lists no such row; list the feed again.',
332
336
  sessionfeed_row_not_failed: 'Only a failed row can be acknowledged.',
333
337
  sessionfeed_row_stale: 'The session changed since it was listed; list the feed again.',
338
+ proxy_unavailable: 'The AGL proxy is not running.',
339
+ proxy_outdated: 'The AGL proxy runs an older AGL release and does not answer capacity; restart it onto the installed AGL.',
340
+ proxy_accounts_unavailable: 'The AGL proxy cannot reach its account service, so it cannot judge its pools.',
334
341
  };
335
342
  const conflict = readTicketRevisionConflict(errorArg.errorData);
336
343
  return new plugins.typedrequest.TypedResponseError(
@@ -684,6 +691,12 @@ export class ControllerMcpHost {
684
691
  return this.options.api.deploy(method, request as unknown as Record<string, unknown>, tools?.abortSignal ?? new AbortController().signal) as never;
685
692
  })));
686
693
  }
694
+ routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_ControllerMcpProxyCapacity>(
695
+ 'agl.mcp.proxy.capacity', async (requestArg, toolsArg) => run('agl.mcp.proxy.capacity', async () => {
696
+ if (!this.options.api.proxyCapacity) throw new Error('Proxy capacity API is unavailable.');
697
+ return this.options.api.proxyCapacity(requestArg, toolsArg?.abortSignal ?? new AbortController().signal);
698
+ }),
699
+ ));
687
700
  routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_ControllerMcpSessionFeedList>(
688
701
  'agl.mcp.sessionfeed.list', async (requestArg, toolsArg) => run('agl.mcp.sessionfeed.list', async () => {
689
702
  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;
@@ -308,6 +309,9 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
308
309
  MESSAGE_RATE_LIMITED: 'Too many messages to this task; wait at least a minute before sending another.',
309
310
  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.',
310
311
  OUTCOME_UNKNOWN: 'The operation outcome is unknown; inspect current state before acting again.',
312
+ PROXY_UNAVAILABLE: 'The AGL inference proxy is not running; its owner starts it with agl proxy service start.',
313
+ 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.',
314
+ PROXY_ACCOUNTS_UNAVAILABLE: 'The AGL inference proxy cannot reach its account service, so it cannot judge its pools now.',
311
315
  };
312
316
 
313
317
  const serializeToolResult = (
@@ -370,7 +374,7 @@ export class AglMcpTools {
370
374
  | 'messageSession'
371
375
  | 'readSessionScratchpad'
372
376
  | 'updateSessionScratchpad'
373
- > & Partial<Pick<ControllerMcpClient, 'ticket' | 'fleet' | 'fleetStart' | 'fleetStatus' | 'fleetWorker' | 'deploy'>>;
377
+ > & Partial<Pick<ControllerMcpClient, 'ticket' | 'fleet' | 'fleetStart' | 'fleetStatus' | 'fleetWorker' | 'deploy' | 'proxyCapacity'>>;
374
378
  private readonly withFleetOwner: <T>(operation: (token: string) => Promise<T>) => Promise<T>;
375
379
  private readonly onControllerUpgraded?: IAglMcpToolsOptions['onControllerUpgraded'];
376
380
  private readonly workerCaller?: McpWorkerCaller;
@@ -423,6 +427,30 @@ export class AglMcpTools {
423
427
  async () => this.client.status(extra.signal),
424
428
  ),
425
429
  ));
430
+ registeredTools.push(serverArg.registerTool(
431
+ 'proxy_capacity',
432
+ {
433
+ title: 'Read the inference proxy capacity',
434
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
435
+ description: "Read a pool's room for new work in AGL's inference proxy, as agl proxy capacity --json answers it: "
436
+ + 'provider anthropic (Claude accounts) or openai (ChatGPT accounts), both when omitted. Its members are its '
437
+ + 'subscription sign-ins that have not lapsed on a counted plan (Claude: max; ChatGPT: every plan but free); '
438
+ + "room is the headroom they add now, summed (0 for one that takes no work now). Each member, by account id, names "
439
+ + 'its plan, state, binding window and growsAt, when its headroom next grows. verdict is open when room reaches '
440
+ + 'minHeadroom (15 unless given) and no provider 429 hit a member within five minutes; otherwise wait with '
441
+ + 'reason room, provider-429 or quiet-unobserved and until/seconds, both null when no moment is foreseen. It '
442
+ + 'does not wait: ask again after verdict.seconds.',
443
+ inputSchema: plugins.z.object({
444
+ provider: plugins.z.enum(['anthropic', 'openai']).optional(),
445
+ minHeadroom: plugins.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
446
+ }).strict(),
447
+ },
448
+ async (args, extra) => this.runToolCall(extra, async () => {
449
+ if (!this.client.proxyCapacity) throw new Error('Proxy capacity API is unavailable.');
450
+ return this.client.proxyCapacity({ ...(args.provider === undefined ? {} : { provider: args.provider }),
451
+ ...(args.minHeadroom === undefined ? {} : { minHeadroom: args.minHeadroom }) }, extra.signal);
452
+ }),
453
+ ));
426
454
  registeredTools.push(serverArg.registerTool(
427
455
  'projects_list',
428
456
  {
@@ -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[]>> = {
@@ -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))
@@ -18,6 +18,7 @@ import type { IInferenceUsageChangesRequest, IInferenceUsageSnapshotPage, IInfer
18
18
  TInferenceUsageChanges } from './classes.inferenceusage.js';
19
19
  import type { TAglProxyConfinedRun, TInferenceCredential, TInferenceProvider,
20
20
  TProxyCredentialDelivery } from './functions.proxycontract.js';
21
+ import type { IProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
21
22
 
22
23
  /**
23
24
  * The client of the proxy's private control socket. It needs nothing but Node's own modules, so the command a harness
@@ -70,6 +71,18 @@ export class AglProxyRefusedError extends Error {
70
71
  }
71
72
  }
72
73
 
74
+ /**
75
+ * A proxy of another AGL release refused a request it does not know: it runs the AGL it was started from, as after an
76
+ * upgrade it was not restarted by.
77
+ */
78
+ export class AglProxyOutdatedError extends Error {
79
+ constructor(public readonly proxyVersion: string, public readonly ownVersion: string) {
80
+ super(`The AGL proxy runs AGL ${proxyVersion}, not ${ownVersion}, and does not answer this request. `
81
+ + 'Restart it onto the installed AGL with `agl proxy service stop`, then `agl proxy service start`.');
82
+ this.name = 'AglProxyOutdatedError';
83
+ }
84
+ }
85
+
73
86
  interface IWireAnswer {
74
87
  method?: unknown;
75
88
  response?: unknown;
@@ -167,6 +180,23 @@ export class AglProxyControlClient {
167
180
  return (await exchange<IReq_AglProxyStatus['response']>(this.socketPath, 'agl.proxy.status', {}, signalArg)).status;
168
181
  }
169
182
 
183
+ /**
184
+ * The room for new work of the pool `requestArg` names, or of both (`IReq_AglProxyCapacity`), as the proxy answers it:
185
+ * a caller that may meet another release checks it (`isProxyCapacityAnswer`). A refusal from a proxy of another AGL
186
+ * release than `ownVersionArg` is that proxy not knowing the request (`AglProxyOutdatedError`); any other refusal is the
187
+ * proxy's own (`AglProxyRefusedError`).
188
+ */
189
+ public async capacity(requestArg: IProxyCapacityRequest, signalArg: AbortSignal, ownVersionArg: string): Promise<unknown> {
190
+ try {
191
+ return await exchange<unknown>(this.socketPath, 'agl.proxy.capacity', requestArg, signalArg);
192
+ } catch (errorArg) {
193
+ if (!(errorArg instanceof AglProxyRefusedError)) throw errorArg;
194
+ const version = (await this.status(signalArg)).version;
195
+ if (version !== ownVersionArg) throw new AglProxyOutdatedError(version, ownVersionArg);
196
+ throw errorArg;
197
+ }
198
+ }
199
+
170
200
  /**
171
201
  * A private credential and endpoint for one child, continuing the sessions of the proxy client `clientArg`; closing
172
202
  * the lease ends the credential.
@@ -169,6 +169,14 @@ export class AglProxyDaemon {
169
169
  credential: (requestArg) => this.heldCredential(requestArg.client, requestArg.rotate === true, requestArg.provider, requestArg.delivery)
170
170
  ?? this.serialized(() => this.credential(requestArg.client, requestArg.rotate === true, requestArg.provider, requestArg.delivery)),
171
171
  status: async () => ({ status: await this.status() }),
172
+ capacity: async (requestArg, connectionArg) => {
173
+ const answer = await this.service!.capacity(requestArg, AbortSignal.any([this.abort.signal, connectionArg.signal]));
174
+ if (!answer) {
175
+ throw new AglProxyControlRefusal('The account service is unavailable, so the proxy cannot judge its pools.',
176
+ 'authority_unavailable');
177
+ }
178
+ return answer;
179
+ },
172
180
  catalog: (requestArg, connectionArg) => this.catalog(requestArg, connectionArg),
173
181
  lease: (requestArg, connectionArg) => this.lease(requestArg.policy, requestArg.client, connectionArg),
174
182
  reclaim: async (requestArg, connectionArg) => this.reclaim(requestArg.token, connectionArg),
@@ -9,6 +9,7 @@ import { aglProxyDefaultPort, type TInferenceCredential, type TInferenceProvider
9
9
  type TProxyCredentialDelivery } from './functions.proxycontract.js';
10
10
  import type { IConfigurationInferenceProxy } from './configuration/classes.inferencereview.js';
11
11
  import type { IControllerProxyUnit, TControllerProxyState } from '../ts_interfaces/index.js';
12
+ import { isProxyCapacityAnswer, type IProxyCapacityAnswer, type IProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
12
13
 
13
14
  export interface IAglProxyMonitorOptions {
14
15
  /** The proxy's private control socket. */
@@ -158,6 +159,17 @@ export class AglProxyMonitor implements IConfigurationInferenceProxy {
158
159
  return (await this.unitState()) ?? undefined;
159
160
  }
160
161
 
162
+ /**
163
+ * A pool's room for new work as the proxy judges it (`agl.proxy.capacity`), read only by the contract. A proxy of an
164
+ * older release that does not know the request rejects with `AglProxyOutdatedError`, one that is not running with
165
+ * `AglProxyUnavailableError`.
166
+ */
167
+ public async capacity(requestArg: IProxyCapacityRequest, signalArg: AbortSignal): Promise<IProxyCapacityAnswer> {
168
+ const answer = await this.client.capacity(requestArg, signalArg, commitinfo.version);
169
+ if (!isProxyCapacityAnswer(answer)) throw new Error('The AGL proxy answered a capacity this AGL cannot read.');
170
+ return answer;
171
+ }
172
+
161
173
  /** The token usage the proxy counted, as the metrics board's usage feed reads it. */
162
174
  public usage(requestArg: IReq_AglProxyUsage['request'], signalArg: AbortSignal): Promise<IReq_AglProxyUsage['response']> {
163
175
  return this.client.usage(requestArg, signalArg);
@@ -180,6 +180,11 @@ export class ControllerTrustedProxySecrets {
180
180
  return { secret: secret.text.toString('utf8'), generation: secret.generation };
181
181
  }
182
182
 
183
+ /** Whether a rotation waits for the route to carry its secret: the next secret is accepted beside the active one. */
184
+ public rotating(): boolean {
185
+ return !this.closed && this.next !== undefined;
186
+ }
187
+
183
188
  /**
184
189
  * Starts a rotation: a new secret, accepted beside the active one from now on, which the route must carry next.
185
190
  * A rotation already in progress is returned again, so a sync that failed is retried with the same secret.
@@ -33,6 +33,8 @@ export interface IControllerManagementPeer {
33
33
  headers: Headers;
34
34
  state: Record<string, unknown>;
35
35
  };
36
+ /** The request's loopback connection, from which a local CLI caller's process is proved (`agl remote gateway sync`). */
37
+ connection?: plugins.smartserve.IConnectionInfo;
36
38
  }
37
39
 
38
40
  export const isLoopbackPeerAddress = (addressArg: string | undefined): boolean => (
@@ -113,11 +115,24 @@ export const admitControllerManagementTypedRequest = (
113
115
  peer: {
114
116
  id: `management:${plugins.crypto.randomUUID()}`,
115
117
  context: { headers: contextArg.headers, state: {} },
118
+ ...(contextArg.connectionInfo === undefined ? {} : { connection: { ...contextArg.connectionInfo } }),
116
119
  },
117
120
  },
118
121
  };
119
122
  };
120
123
 
124
+ /** The loopback connection a management request's peer carries, or `undefined` when it carries none. */
125
+ export const readManagementPeerConnection = (localDataArg: unknown): plugins.smartserve.IConnectionInfo | undefined => {
126
+ const peer = typeof localDataArg === 'object' && localDataArg !== null
127
+ ? (localDataArg as { peer?: unknown }).peer : undefined;
128
+ const connection = typeof peer === 'object' && peer !== null ? (peer as { connection?: unknown }).connection : undefined;
129
+ if (typeof connection !== 'object' || connection === null) return undefined;
130
+ const { remoteAddr, remotePort, localAddr, localPort, encrypted } = connection as Record<string, unknown>;
131
+ if (typeof remoteAddr !== 'string' || typeof localAddr !== 'string' || typeof encrypted !== 'boolean'
132
+ || !Number.isSafeInteger(remotePort) || !Number.isSafeInteger(localPort)) return undefined;
133
+ return { remoteAddr, remotePort: remotePort as number, localAddr, localPort: localPort as number, encrypted };
134
+ };
135
+
121
136
  /**
122
137
  * The management endpoint as a surface of the controller's listener: it matches only the exact host and path, so
123
138
  * every other request on the port keeps reaching the browser surface.