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
package/ts/classes.cli.ts CHANGED
@@ -9,6 +9,7 @@ import {
9
9
  controllerManagementProtocolVersion,
10
10
  configurationOwnerTokenEnvironmentVariable,
11
11
  describeBrowserPaintAvailability,
12
+ type IControllerManagementStatus,
12
13
  type IControllerStatus,
13
14
  } from '../ts_interfaces/index.js';
14
15
  import { defaultControllerPort } from './classes.config.js';
@@ -143,6 +144,7 @@ Usage:
143
144
  ${currentCliName} foreground [options]
144
145
  ${currentCliName} temp-password [--port 4097] [--ttl-hours 24]
145
146
  ${currentCliName} remote set|unset|secret import [--port 4097] [options]
147
+ ${currentCliName} remote gateway enrol|status|sync|remove [--port 4097] [options]
146
148
  ${currentCliName} feed list [--state failed] [--json] | acknowledge <row-id> --updated-at <ms> [--json]
147
149
  ${currentCliName} deploy status [TARGET] | history TARGET | probe TARGET [--json]
148
150
  ${currentCliName} release status [REPO] [--json]
@@ -167,7 +169,8 @@ Commands:
167
169
  foreground Run ${currentRuntimeName} attached to this terminal
168
170
  temp-password Mint a temporary browser login password (max 24 hours)
169
171
  remote Move a stopped controller between localhost and a public origin behind a TLS
170
- reverse proxy, or import the proxy's secret (remote --help)
172
+ reverse proxy, or import the proxy's secret (remote --help); keep the
173
+ controller's own route on a dcrouter gateway (remote gateway --help)
171
174
  help Show this help
172
175
 
173
176
  Startup options:
@@ -432,13 +435,14 @@ const assertStatus = (statusArg: unknown): IControllerStatus => assertController
432
435
  export const queryControllerStatus = async (
433
436
  portArg: number,
434
437
  timeoutMsArg = 2_500,
435
- ): Promise<IControllerStatus> => queryManagedControllerStatus(
438
+ ): Promise<IControllerManagementStatus> => queryManagedControllerStatus(
436
439
  portArg,
437
440
  currentStatusExpectation,
438
441
  timeoutMsArg,
439
442
  );
440
443
 
441
- const tryQueryControllerStatus = async (portArg: number): Promise<IControllerStatus | undefined> => {
444
+ /** The status of this release's controller on `portArg`, with its management sections, or `undefined` when none answers. */
445
+ export const tryQueryControllerStatus = async (portArg: number): Promise<IControllerManagementStatus | undefined> => {
442
446
  return tryQueryManagedControllerStatus(portArg, currentStatusExpectation);
443
447
  };
444
448
 
@@ -8,7 +8,7 @@ import { ControllerWorkerCallers, type IWorkerCodexCallerOrigin } from './classe
8
8
  import { WorkerCallerBindingStore } from './classes.workercallerbindings.js';
9
9
  import { FleetWorkerLaunches } from './fleet/classes.workerlaunches.js';
10
10
  import { workerCallerEnrollmentToolName } from './classes.mcpworkercaller.js';
11
- import { readWorkerProcessSnapshot, readWorkerUnixSocketOwner, workerSnapshotsEqual, isWorkerCallerProofRefusal, type IWorkerCallerConnection } from './functions.workerprocessproof.js';
11
+ import { proveConnectionProcessAncestry, readWorkerProcessSnapshot, readWorkerUnixSocketOwner, workerSnapshotsEqual, isWorkerCallerProofRefusal, type IWorkerCallerConnection } from './functions.workerprocessproof.js';
12
12
  import { proveCliCallerClaudeSession } from './functions.cliticketsession.js';
13
13
  import type { IFleetWorkerCallerHooks, TFleetWorkerCallerLaunch } from '../ts_interfaces/workercallers.js';
14
14
  import { awaitWithAbortSignal } from './functions.abort.js';
@@ -52,7 +52,7 @@ import { AccountsActions } from './classes.accountsactions.js';
52
52
  import { AglProxyMonitor } from './classes.proxymonitor.js';
53
53
  import type { TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
54
54
  import { AglProxyLeaseHolder } from './classes.proxyleaseholder.js';
55
- import { AglProxyRefusedError } from './classes.proxycontrolclient.js';
55
+ import { AglProxyOutdatedError, AglProxyRefusedError, AglProxyUnavailableError } from './classes.proxycontrolclient.js';
56
56
  import { inferenceHarnessLaunch } from './functions.inferencelaunch.js';
57
57
  import type { IControllerTerminalAgentInferenceSession } from './classes.terminalmanager.js';
58
58
  import type { TConfigurationHostClaudeLogin } from './configuration/classes.inferencereview.js';
@@ -337,6 +337,9 @@ import {
337
337
  type IReq_ControllerSetupBegin,
338
338
  type IReq_ControllerSetupFinish,
339
339
  type IReq_ControllerStatus,
340
+ type IReq_ControllerManagementStatus,
341
+ type IReq_ControllerGatewaySync,
342
+ type IControllerGatewayStatus,
340
343
  type IReq_ControllerUpgradeLaunch,
341
344
  type IReq_ControllerUpgradePrepareBegin,
342
345
  type IReq_ControllerUpgradeFinalize,
@@ -394,6 +397,11 @@ import {
394
397
  import { controllerListenerOptions } from './functions.controlleradmission.js';
395
398
  import { ControllerTrustedProxySecrets } from './classes.trustedproxysecrets.js';
396
399
  import { TpmSecretCodec } from './classes.tpmsecretcodec.js';
400
+ import { ControllerGatewayClient } from './classes.gatewayclient.js';
401
+ import { ControllerGatewayClientStore } from './classes.gatewayclientstore.js';
402
+ import { gatewayRouteKey } from './functions.gatewayroute.js';
403
+ import { readManagementPeerConnection } from './functions.controllermanagementsurface.js';
404
+ import { assertConfigurationLocalCliActor } from './functions.configurationactor.js';
397
405
  import { resolveAGLHomePaths } from './classes.aglhome.js';
398
406
  import { selectControllerBrowserPaint } from './functions.browserpaintartifact.js';
399
407
  import { ControllerBrowserViewerAssets } from './functions.browserpaintassets.js';
@@ -3452,6 +3460,8 @@ export class OpenCodeController {
3452
3460
  private passkeyManager?: PasskeyManager;
3453
3461
  /** TLS-proxy mode only: the secret admission accepts from the reverse proxy, and its rotation. */
3454
3462
  private trustedProxySecrets?: ControllerTrustedProxySecrets;
3463
+ /** The controller's own route on its gateway (`agl remote gateway`), synced in the background once it is ready. */
3464
+ private gatewayClient?: ControllerGatewayClient;
3455
3465
  private openCodeSupervisor?: OpenCodeSupervisor;
3456
3466
  private openCodeClient?: OpenCodeClientAdapter;
3457
3467
  private flexSupervisor?: FlexSupervisor;
@@ -9867,6 +9877,21 @@ export class OpenCodeController {
9867
9877
  throw errorArg;
9868
9878
  }
9869
9879
  }),
9880
+ // A read for every caller (AGL-1097): the answer names accounts by id alone.
9881
+ proxyCapacity: (requestArg, signalArg) => run(signalArg, async (operationSignalArg) => {
9882
+ const monitor = this.proxyMonitor;
9883
+ if (!monitor) throw new plugins.typedrequest.TypedResponseError('The AGL proxy is not running.', { code: 'proxy_unavailable' });
9884
+ try {
9885
+ return await monitor.capacity(requestArg, operationSignalArg);
9886
+ } catch (errorArg) {
9887
+ const code = errorArg instanceof AglProxyUnavailableError ? 'proxy_unavailable'
9888
+ : errorArg instanceof AglProxyOutdatedError ? 'proxy_outdated'
9889
+ : errorArg instanceof AglProxyRefusedError && errorArg.code === 'authority_unavailable' ? 'proxy_accounts_unavailable'
9890
+ : undefined;
9891
+ if (code && errorArg instanceof Error) throw new plugins.typedrequest.TypedResponseError(errorArg.message, { code });
9892
+ throw errorArg;
9893
+ }
9894
+ }),
9870
9895
  status: async (principalArg, signalArg) => run(signalArg, async () => ({
9871
9896
  status: this.statusForPrincipal(principalArg),
9872
9897
  controllerPort: controllerPortArg,
@@ -10239,6 +10264,19 @@ export class OpenCodeController {
10239
10264
  this.assertStartActive();
10240
10265
  }
10241
10266
  const trustedProxySecrets = this.trustedProxySecrets;
10267
+ // Its enrolment is read now; its first sync runs once the controller is ready, never holding up the start.
10268
+ const gatewayClient = new ControllerGatewayClient({
10269
+ store: new ControllerGatewayClientStore({
10270
+ controllerId: authDocument.id,
10271
+ issuerId: issuerIdentity.issuerId,
10272
+ codec: this.options.trustedProxySecretCodec ?? new TpmSecretCodec(),
10273
+ }),
10274
+ runtimeConfig: () => this.requireRuntimeConfig(),
10275
+ secrets: () => this.trustedProxySecrets,
10276
+ });
10277
+ this.gatewayClient = gatewayClient;
10278
+ await gatewayClient.load();
10279
+ this.assertStartActive();
10242
10280
  const publicHostname = new URL(runtimeConfig.publicOrigin).hostname;
10243
10281
  const hostnames = [...new Set([publicHostname, 'localhost', '127.0.0.1'])];
10244
10282
  const serveDirectory = plugins.path.resolve(
@@ -10797,6 +10835,7 @@ export class OpenCodeController {
10797
10835
  startupOpenCodeExitSignal,
10798
10836
  );
10799
10837
  this.lifecycleState = 'ready';
10838
+ this.gatewayClient?.start();
10800
10839
  this.requireFleetWorkers();
10801
10840
  // New Claude Code releases an earlier run recorded but did not announce are announced now, once.
10802
10841
  const harnessReleases = this.harnessReleases;
@@ -13181,6 +13220,7 @@ export class OpenCodeController {
13181
13220
  await stopPart(async () => { await this.fleetService?.close(); this.fleetService = undefined; });
13182
13221
  await stopPart(async () => { await this.boardPump?.close(); this.boardPump = undefined; });
13183
13222
  await stopPart(async () => { await this.deployMonitor?.close(); this.deployMonitor = undefined; });
13223
+ await stopPart(async () => { await this.gatewayClient?.close(); this.gatewayClient = undefined; });
13184
13224
  await stopPart(async () => { await this.ticketNotifier?.close(); this.ticketNotifier = undefined; });
13185
13225
  await stopPart(async () => { await this.sessionFeed?.close(); this.sessionFeed = undefined; });
13186
13226
  await stopPart(async () => { await this.usageFeed?.stop(); this.usageFeed = undefined; });
@@ -14093,13 +14133,104 @@ export class OpenCodeController {
14093
14133
  */
14094
14134
  private createManagementRouter(): plugins.typedrequest.TypedRouter {
14095
14135
  const router = new plugins.typedrequest.TypedRouter();
14096
- router.addTypedHandler(this.createStatusHandler());
14136
+ router.addTypedHandler(this.createManagementStatusHandler());
14097
14137
  router.addTypedHandler(this.createUpgradeLaunchHandler());
14098
14138
  router.addTypedHandler(this.createUpgradePrepareBeginHandler());
14099
14139
  router.addTypedHandler(this.createUpgradeFinalizeHandler());
14140
+ router.addTypedHandler(this.createGatewaySyncHandler());
14100
14141
  return router;
14101
14142
  }
14102
14143
 
14144
+ /** The browser's status and, on the management endpoint only, the gateway client's (AGL-828). */
14145
+ private createManagementStatusHandler(): plugins.typedrequest.TypedHandler<IReq_ControllerManagementStatus> {
14146
+ return new plugins.typedrequest.TypedHandler<IReq_ControllerManagementStatus>(
14147
+ 'controller.status',
14148
+ async (requestArg) => {
14149
+ validateRequest(() => assertEmptyRequest(requestArg));
14150
+ return { ...this.statusForPrincipal('browser'), gateway: this.gatewayClient?.status() ?? { state: 'not_enrolled' } };
14151
+ },
14152
+ );
14153
+ }
14154
+
14155
+ /**
14156
+ * `agl remote gateway sync [--rotate]`: only a process of the controller's own OS user that holds the request's
14157
+ * loopback connection (the `localCli` it names, proved from the kernel) syncs the route now, rotating the
14158
+ * trusted-proxy secret first when asked; audited as `remote.gateway.sync`.
14159
+ */
14160
+ private createGatewaySyncHandler(): plugins.typedrequest.TypedHandler<IReq_ControllerGatewaySync> {
14161
+ return new plugins.typedrequest.TypedHandler<IReq_ControllerGatewaySync>(
14162
+ 'controller.gateway.sync',
14163
+ async (requestArg, toolsArg) => {
14164
+ const peer = peerFromLocalData(toolsArg?.localData);
14165
+ this.recordUnauthenticatedPreflightOperation(peer.id);
14166
+ const invalid = () => new plugins.typedrequest.TypedResponseError(
14167
+ 'The gateway sync request is invalid.',
14168
+ { code: 'invalid_request' },
14169
+ );
14170
+ if (
14171
+ !requestArg
14172
+ || typeof requestArg !== 'object'
14173
+ || Array.isArray(requestArg)
14174
+ || Object.keys(requestArg).length !== 2
14175
+ || typeof requestArg.rotate !== 'boolean'
14176
+ ) throw invalid();
14177
+ try {
14178
+ assertConfigurationLocalCliActor(requestArg.localCli);
14179
+ } catch {
14180
+ throw invalid();
14181
+ }
14182
+ const localCli = requestArg.localCli;
14183
+ try {
14184
+ const [caller] = await proveConnectionProcessAncestry(readManagementPeerConnection(toolsArg?.localData), localCli.pid, 1);
14185
+ if (!caller || caller.parentPid !== localCli.parentPid) throw new Error('The caller is not the process it names.');
14186
+ } catch (errorArg) {
14187
+ if (!(errorArg instanceof Error)) throw errorArg;
14188
+ throw new plugins.typedrequest.TypedResponseError(
14189
+ 'Only a process of the controller\'s own OS user that holds its connection syncs the gateway route.',
14190
+ { code: 'unauthorized' },
14191
+ );
14192
+ }
14193
+ const gatewayClient = this.gatewayClient;
14194
+ const authStore = this.requireAuthStore();
14195
+ if (!gatewayClient || this.lifecycleState !== 'ready') {
14196
+ throw new plugins.typedrequest.TypedResponseError('The controller is not ready.', { code: 'not_ready' });
14197
+ }
14198
+ const before = gatewayClient.status();
14199
+ const enrolment = before.enrolment;
14200
+ if (!enrolment) {
14201
+ throw new plugins.typedrequest.TypedResponseError(
14202
+ `controller:${this.requireRuntimeConfig().controllerPort} is not enrolled with a gateway: run \`agl remote gateway enrol\` first.`,
14203
+ { code: 'not_enrolled' },
14204
+ );
14205
+ }
14206
+ const details = { gateway: {
14207
+ gatewayUrl: enrolment.gatewayUrl,
14208
+ gatewayClientId: enrolment.gatewayClientId,
14209
+ appId: enrolment.appId,
14210
+ hostname: enrolment.hostname,
14211
+ targetHost: enrolment.target.host,
14212
+ targetPort: enrolment.target.port,
14213
+ routeKey: gatewayRouteKey({ gatewayClientId: enrolment.gatewayClientId, appId: enrolment.appId, hostname: enrolment.hostname }),
14214
+ rotate: requestArg.rotate,
14215
+ } };
14216
+ const audit = { type: 'remote.gateway.sync' as const, peerId: peer.id, localCli, details };
14217
+ await authStore.recordAuditEvent({ ...audit, outcome: 'attempted' });
14218
+ let gateway: IControllerGatewayStatus;
14219
+ try {
14220
+ gateway = await gatewayClient.sync({ rotate: requestArg.rotate });
14221
+ } catch (errorArg) {
14222
+ await authStore.recordAuditEvent({ ...audit, outcome: 'failed' });
14223
+ throw new plugins.typedrequest.TypedResponseError(
14224
+ errorArg instanceof Error ? errorArg.message : 'The gateway sync failed.',
14225
+ { code: 'gateway_sync_failed' },
14226
+ );
14227
+ }
14228
+ await authStore.recordAuditEvent({ ...audit, outcome: gateway.state === 'synced' ? 'succeeded' : 'failed' });
14229
+ return { gateway };
14230
+ },
14231
+ );
14232
+ }
14233
+
14103
14234
  private createStatusHandler(): plugins.typedrequest.TypedHandler<IReq_ControllerStatus> {
14104
14235
  return new plugins.typedrequest.TypedHandler<IReq_ControllerStatus>(
14105
14236
  'controller.status',
@@ -6,8 +6,13 @@ import {
6
6
  controllerPackageName,
7
7
  controllerProtocolVersion,
8
8
  controllerServiceUnitName,
9
+ readControllerGatewayStatus,
10
+ type IConfigurationLocalCliActor,
11
+ type IControllerGatewayStatus,
12
+ type IControllerManagementStatus,
9
13
  type IControllerStatus,
10
- type IReq_ControllerStatus,
14
+ type IReq_ControllerGatewaySync,
15
+ type IReq_ControllerManagementStatus,
11
16
  type IReq_ControllerUpgradeLaunch,
12
17
  type IReq_ControllerUpgradePrepareBegin,
13
18
  type IReq_ControllerUpgradeFinalize,
@@ -238,7 +243,7 @@ export const assertControllerStatus = (
238
243
  statusArg: unknown,
239
244
  expectationArg: IControllerStatusExpectation,
240
245
  knownProtocolVersionArg: number = controllerProtocolVersion,
241
- ): IControllerStatus => {
246
+ ): IControllerManagementStatus => {
242
247
  if (typeof statusArg !== 'object' || statusArg === null) {
243
248
  throw new Error(`The service on the management port is not an ${currentRuntimeName} endpoint.`);
244
249
  }
@@ -276,10 +281,13 @@ export const assertControllerStatus = (
276
281
  throw new Error('The service on the management port has an incompatible controller identity.');
277
282
  }
278
283
  // A section a newer controller reports in a form this release cannot read is left out.
279
- const readableStatus: Partial<IControllerStatus> = { ...status, harnesses };
284
+ const readableStatus: Partial<IControllerManagementStatus> = { ...status, harnesses };
280
285
  if (!isControllerUpgradeStatus(status.upgrade, exactShape)) delete readableStatus.upgrade;
281
286
  if (!isControllerProxyStatus(status.proxy, exactShape)) delete readableStatus.proxy;
282
- return readableStatus as IControllerStatus;
287
+ // The gateway section only the management endpoint reports (AGL-828); a controller before it reports none.
288
+ const gateway = (statusArg as Partial<IControllerManagementStatus>).gateway;
289
+ if (gateway === undefined || !readControllerGatewayStatus(gateway)) delete readableStatus.gateway;
290
+ return readableStatus as IControllerManagementStatus;
283
291
  };
284
292
 
285
293
  /** A management request the controller answered with an error, or whose answer this build cannot read. */
@@ -532,9 +540,9 @@ export const queryControllerStatus = async (
532
540
  portArg: number,
533
541
  queryArg: IControllerStatusQuery,
534
542
  timeoutMsArg = 2_500,
535
- ): Promise<IControllerStatus> => {
543
+ ): Promise<IControllerManagementStatus> => {
536
544
  const status = assertControllerStatus(
537
- await requestManagedController<IReq_ControllerStatus>(
545
+ await requestManagedController<IReq_ControllerManagementStatus>(
538
546
  portArg,
539
547
  queryArg,
540
548
  'controller.status',
@@ -561,7 +569,7 @@ export const isUnmanagedControllerError = (errorArg: unknown): errorArg is Contr
561
569
  export const tryQueryControllerStatus = async (
562
570
  portArg: number,
563
571
  queryArg: IControllerStatusQuery,
564
- ): Promise<IControllerStatus | undefined> => {
572
+ ): Promise<IControllerManagementStatus | undefined> => {
565
573
  try {
566
574
  return await queryControllerStatus(portArg, queryArg);
567
575
  } catch (errorArg) {
@@ -570,6 +578,31 @@ export const tryQueryControllerStatus = async (
570
578
  }
571
579
  };
572
580
 
581
+ /**
582
+ * Syncs the gateway route of the controller `controllerArg` names now, rotating its trusted-proxy secret first when
583
+ * `rotateArg` is set (`agl remote gateway sync`). `localCliArg` is this process: the controller proves that it holds
584
+ * the request's loopback connection and runs as the controller's user before it acts, and audits it as the actor.
585
+ * The sync talks to the gateway, so it may take as long as the gateway's DNS reconciliation.
586
+ */
587
+ export const requestControllerGatewaySync = async (
588
+ portArg: number,
589
+ controllerArg: IControllerManagementTarget,
590
+ optionsArg: { rotate: boolean; localCli: IConfigurationLocalCliActor },
591
+ timeoutMsArg = 180_000,
592
+ ): Promise<IControllerGatewayStatus> => {
593
+ const response = await requestManagedController<IReq_ControllerGatewaySync>(
594
+ portArg,
595
+ controllerArg,
596
+ 'controller.gateway.sync',
597
+ { rotate: optionsArg.rotate, localCli: optionsArg.localCli },
598
+ { timeoutMs: timeoutMsArg },
599
+ );
600
+ const gateway = isPlainRecord(response) && Object.keys(response).length === 1
601
+ ? readControllerGatewayStatus(response.gateway) : undefined;
602
+ if (!gateway) throw new Error('The controller returned an invalid gateway sync response.');
603
+ return gateway;
604
+ };
605
+
573
606
  export const isLoopbackPortListening = async (
574
607
  portArg: number,
575
608
  timeoutMsArg = 500,