agl 43.0.5 → 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 (216) hide show
  1. package/changelog.md +30 -0
  2. package/dist_serve/bundle.js +5996 -5280
  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_serve/third-party-notices.md +1 -1
  7. package/dist_ts/00_commitinfo_data.js +1 -1
  8. package/dist_ts/aglapi/aglapisurface.document.js +805 -10
  9. package/dist_ts/aglapi/interfaces.d.ts +13 -0
  10. package/dist_ts/aglapi/interfaces.js +4 -1
  11. package/dist_ts/classes.authmodels.js +17 -4
  12. package/dist_ts/classes.authstore.js +16 -2
  13. package/dist_ts/classes.claudeharness.d.ts +14 -5
  14. package/dist_ts/classes.claudeharness.js +62 -2
  15. package/dist_ts/classes.cli.d.ts +4 -2
  16. package/dist_ts/classes.cli.js +6 -3
  17. package/dist_ts/classes.codexclientadapter.d.ts +7 -5
  18. package/dist_ts/classes.codexclientadapter.js +38 -3
  19. package/dist_ts/classes.controller.d.ts +19 -2
  20. package/dist_ts/classes.controller.js +234 -27
  21. package/dist_ts/classes.controllermanagement.d.ts +14 -4
  22. package/dist_ts/classes.controllermanagement.js +20 -2
  23. package/dist_ts/classes.gatewayclient.d.ts +115 -0
  24. package/dist_ts/classes.gatewayclient.js +336 -0
  25. package/dist_ts/classes.gatewayclientstore.d.ts +97 -0
  26. package/dist_ts/classes.gatewayclientstore.js +261 -0
  27. package/dist_ts/classes.inferencegateway.d.ts +8 -5
  28. package/dist_ts/classes.inferencegateway.js +62 -19
  29. package/dist_ts/classes.inferencerouter.d.ts +9 -0
  30. package/dist_ts/classes.inferencerouter.js +11 -1
  31. package/dist_ts/classes.inferenceservice.d.ts +9 -0
  32. package/dist_ts/classes.inferenceservice.js +27 -1
  33. package/dist_ts/classes.inferencespend.d.ts +9 -3
  34. package/dist_ts/classes.inferencespend.js +44 -16
  35. package/dist_ts/classes.mcpclient.d.ts +9 -4
  36. package/dist_ts/classes.mcpclient.js +24 -2
  37. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -1
  38. package/dist_ts/classes.mcpcontrollerhost.js +13 -1
  39. package/dist_ts/classes.mcptools.d.ts +3 -3
  40. package/dist_ts/classes.mcptools.js +42 -4
  41. package/dist_ts/classes.mcpvalidation.js +7 -1
  42. package/dist_ts/classes.opencodeclient.js +3 -1
  43. package/dist_ts/classes.proxycontrol.d.ts +33 -11
  44. package/dist_ts/classes.proxycontrol.js +12 -3
  45. package/dist_ts/classes.proxycontrolclient.d.ts +23 -5
  46. package/dist_ts/classes.proxycontrolclient.js +42 -6
  47. package/dist_ts/classes.proxydaemon.d.ts +8 -6
  48. package/dist_ts/classes.proxydaemon.js +42 -21
  49. package/dist_ts/classes.proxyleaseholder.d.ts +12 -4
  50. package/dist_ts/classes.proxyleaseholder.js +39 -9
  51. package/dist_ts/classes.proxymonitor.d.ts +7 -0
  52. package/dist_ts/classes.proxymonitor.js +13 -1
  53. package/dist_ts/classes.proxystore.d.ts +4 -3
  54. package/dist_ts/classes.proxystore.js +17 -7
  55. package/dist_ts/classes.sessionfeed.d.ts +1 -1
  56. package/dist_ts/classes.trustedproxysecrets.d.ts +2 -0
  57. package/dist_ts/classes.trustedproxysecrets.js +5 -1
  58. package/dist_ts/classes.validation.d.ts +7 -0
  59. package/dist_ts/classes.validation.js +49 -2
  60. package/dist_ts/driver/functions.drivertools.js +2 -2
  61. package/dist_ts/fleet/classes.codexworkers.d.ts +4 -11
  62. package/dist_ts/fleet/classes.codexworkers.js +6 -3
  63. package/dist_ts/fleet/classes.workers.d.ts +25 -13
  64. package/dist_ts/fleet/classes.workers.js +105 -9
  65. package/dist_ts/fleet/functions.workervalidation.d.ts +26 -1
  66. package/dist_ts/fleet/functions.workervalidation.js +40 -11
  67. package/dist_ts/fleet/interfaces.workers.d.ts +17 -11
  68. package/dist_ts/fleet/interfaces.workers.js +10 -1
  69. package/dist_ts/functions.confinedrelay.d.ts +21 -0
  70. package/dist_ts/functions.confinedrelay.js +65 -0
  71. package/dist_ts/functions.controllermanagementsurface.d.ts +4 -0
  72. package/dist_ts/functions.controllermanagementsurface.js +15 -1
  73. package/dist_ts/functions.deviceapi.d.ts +4 -2
  74. package/dist_ts/functions.deviceapi.js +20 -2
  75. package/dist_ts/functions.elicitation.d.ts +49 -0
  76. package/dist_ts/functions.elicitation.js +418 -0
  77. package/dist_ts/functions.gatewaycli.d.ts +24 -0
  78. package/dist_ts/functions.gatewaycli.js +395 -0
  79. package/dist_ts/functions.gatewayroute.d.ts +135 -0
  80. package/dist_ts/functions.gatewayroute.js +366 -0
  81. package/dist_ts/functions.inferencecli.d.ts +3 -3
  82. package/dist_ts/functions.inferencecli.js +62 -10
  83. package/dist_ts/functions.inferencecliarguments.d.ts +9 -2
  84. package/dist_ts/functions.inferencecliarguments.js +59 -10
  85. package/dist_ts/functions.inferencelaunch.d.ts +35 -7
  86. package/dist_ts/functions.inferencelaunch.js +143 -16
  87. package/dist_ts/functions.mcpfleetworkertools.d.ts +63 -70
  88. package/dist_ts/functions.mcpfleetworkertools.js +32 -4
  89. package/dist_ts/functions.proxycapacity.d.ts +50 -0
  90. package/dist_ts/functions.proxycapacity.js +142 -0
  91. package/dist_ts/functions.proxycapacitycli.d.ts +30 -0
  92. package/dist_ts/functions.proxycapacitycli.js +65 -0
  93. package/dist_ts/functions.proxycontract.d.ts +21 -4
  94. package/dist_ts/functions.proxycontract.js +12 -5
  95. package/dist_ts/functions.proxyharnessconfig.d.ts +7 -0
  96. package/dist_ts/functions.proxyharnessconfig.js +11 -1
  97. package/dist_ts/functions.remotecli.d.ts +30 -3
  98. package/dist_ts/functions.remotecli.js +44 -18
  99. package/dist_ts/interfaces.auth.d.ts +25 -4
  100. package/dist_ts/interfaces.auth.js +8 -1
  101. package/dist_ts/plugins.d.ts +2 -0
  102. package/dist_ts/plugins.js +4 -1
  103. package/dist_ts_authswitch/authority-placement.js +3 -17
  104. package/dist_ts_authswitch/authority-usagelimit.d.ts +29 -0
  105. package/dist_ts_authswitch/authority-usagelimit.js +66 -2
  106. package/dist_ts_authswitch/authority-usagewindows.d.ts +6 -0
  107. package/dist_ts_authswitch/authority-usagewindows.js +15 -1
  108. package/dist_ts_interfaces/devices.d.ts +133 -3
  109. package/dist_ts_interfaces/devices.js +3 -2
  110. package/dist_ts_interfaces/elicitations.d.ts +125 -0
  111. package/dist_ts_interfaces/elicitations.js +7 -0
  112. package/dist_ts_interfaces/fleetworkers.d.ts +119 -5
  113. package/dist_ts_interfaces/fleetworkers.js +14 -2
  114. package/dist_ts_interfaces/gateway.d.ts +151 -0
  115. package/dist_ts_interfaces/gateway.js +66 -0
  116. package/dist_ts_interfaces/index.d.ts +3 -0
  117. package/dist_ts_interfaces/index.js +4 -1
  118. package/dist_ts_interfaces/interfaces.d.ts +3 -1
  119. package/dist_ts_interfaces/interfaces.js +2 -2
  120. package/dist_ts_interfaces/management.d.ts +4 -4
  121. package/dist_ts_interfaces/management.js +3 -2
  122. package/dist_ts_interfaces/mcprequests.d.ts +18 -2
  123. package/dist_ts_interfaces/mcprequests.js +3 -1
  124. package/dist_ts_interfaces/nativesessions.d.ts +14 -0
  125. package/dist_ts_interfaces/proxycapacity.d.ts +99 -0
  126. package/dist_ts_interfaces/proxycapacity.js +74 -0
  127. package/dist_ts_interfaces/requests.d.ts +3 -3
  128. package/dist_ts_interfaces/requests.fleetworkers.js +2 -2
  129. package/dist_ts_interfaces/requests.js +1 -1
  130. package/dist_ts_interfaces/requests.promptreply.d.ts +18 -0
  131. package/dist_ts_interfaces/sessionfeed.d.ts +3 -2
  132. package/dist_ts_interfaces/sessionfeed.js +1 -1
  133. package/package.json +5 -4
  134. package/readme.md +267 -26
  135. package/third-party-notices.md +1 -1
  136. package/ts/00_commitinfo_data.ts +1 -1
  137. package/ts/aglapi/aglapisurface.document.ts +804 -9
  138. package/ts/aglapi/interfaces.ts +3 -0
  139. package/ts/classes.authmodels.ts +22 -3
  140. package/ts/classes.authstore.ts +15 -1
  141. package/ts/classes.claudeharness.ts +80 -9
  142. package/ts/classes.cli.ts +7 -3
  143. package/ts/classes.codexclientadapter.ts +41 -5
  144. package/ts/classes.controller.ts +276 -32
  145. package/ts/classes.controllermanagement.ts +40 -7
  146. package/ts/classes.gatewayclient.ts +401 -0
  147. package/ts/classes.gatewayclientstore.ts +272 -0
  148. package/ts/classes.inferencegateway.ts +69 -23
  149. package/ts/classes.inferencerouter.ts +12 -0
  150. package/ts/classes.inferenceservice.ts +27 -0
  151. package/ts/classes.inferencespend.ts +46 -13
  152. package/ts/classes.mcpclient.ts +26 -4
  153. package/ts/classes.mcpcontrollerhost.ts +17 -0
  154. package/ts/classes.mcptools.ts +47 -5
  155. package/ts/classes.mcpvalidation.ts +5 -0
  156. package/ts/classes.opencodeclient.ts +2 -0
  157. package/ts/classes.proxycontrol.ts +43 -13
  158. package/ts/classes.proxycontrolclient.ts +39 -6
  159. package/ts/classes.proxydaemon.ts +57 -27
  160. package/ts/classes.proxyleaseholder.ts +43 -11
  161. package/ts/classes.proxymonitor.ts +12 -0
  162. package/ts/classes.proxystore.ts +21 -8
  163. package/ts/classes.sessionfeed.ts +1 -1
  164. package/ts/classes.trustedproxysecrets.ts +5 -0
  165. package/ts/classes.validation.ts +52 -0
  166. package/ts/driver/functions.drivertools.ts +1 -1
  167. package/ts/fleet/classes.codexworkers.ts +8 -6
  168. package/ts/fleet/classes.workers.ts +101 -17
  169. package/ts/fleet/functions.workervalidation.ts +35 -9
  170. package/ts/fleet/interfaces.workers.ts +11 -4
  171. package/ts/functions.confinedrelay.ts +65 -0
  172. package/ts/functions.controllermanagementsurface.ts +15 -0
  173. package/ts/functions.deviceapi.ts +24 -1
  174. package/ts/functions.elicitation.ts +443 -0
  175. package/ts/functions.gatewaycli.ts +436 -0
  176. package/ts/functions.gatewayroute.ts +429 -0
  177. package/ts/functions.inferencecli.ts +62 -13
  178. package/ts/functions.inferencecliarguments.ts +56 -9
  179. package/ts/functions.inferencelaunch.ts +143 -16
  180. package/ts/functions.mcpfleetworkertools.ts +34 -4
  181. package/ts/functions.proxycapacity.ts +191 -0
  182. package/ts/functions.proxycapacitycli.ts +104 -0
  183. package/ts/functions.proxycontract.ts +17 -4
  184. package/ts/functions.proxyharnessconfig.ts +11 -0
  185. package/ts/functions.remotecli.ts +56 -20
  186. package/ts/interfaces.auth.ts +29 -4
  187. package/ts/plugins.ts +5 -0
  188. package/ts_authswitch/authority-placement.ts +2 -15
  189. package/ts_authswitch/authority-usagelimit.ts +84 -1
  190. package/ts_authswitch/authority-usagewindows.ts +13 -0
  191. package/ts_interfaces/devices.schema.json +476 -2
  192. package/ts_interfaces/devices.ts +146 -2
  193. package/ts_interfaces/elicitations.ts +148 -0
  194. package/ts_interfaces/fleetworkers.ts +96 -4
  195. package/ts_interfaces/gateway.ts +242 -0
  196. package/ts_interfaces/index.ts +3 -0
  197. package/ts_interfaces/interfaces.ts +3 -1
  198. package/ts_interfaces/management.ts +6 -4
  199. package/ts_interfaces/mcprequests.ts +19 -0
  200. package/ts_interfaces/nativesessions.ts +16 -0
  201. package/ts_interfaces/proxycapacity.ts +162 -0
  202. package/ts_interfaces/requests.fleetworkers.ts +1 -1
  203. package/ts_interfaces/requests.promptreply.ts +22 -0
  204. package/ts_interfaces/requests.ts +4 -0
  205. package/ts_interfaces/sessionfeed.ts +3 -2
  206. package/ts_web/00_commitinfo_data.ts +1 -1
  207. package/ts_web/classes.browserpresentation.ts +13 -5
  208. package/ts_web/classes.elicitationcards.ts +106 -0
  209. package/ts_web/classes.nativesessionstate.ts +38 -1
  210. package/ts_web/elements.accounts.ts +40 -113
  211. package/ts_web/elements.configurationpane.ts +24 -37
  212. package/ts_web/elements.devices.ts +4 -17
  213. package/ts_web/elements.fleetworker.ts +27 -2
  214. package/ts_web/elements.flexlimitstrip.ts +21 -70
  215. package/ts_web/elements.harnesscontrollerapp.ts +159 -186
  216. package/ts_web/functions.sessionchat.ts +5 -0
@@ -5,6 +5,9 @@ import {
5
5
  aglProxyConfinedIdPattern,
6
6
  aglProxyConfinedMountPoint,
7
7
  aglProxyDefaultPort,
8
+ aglProxyRelayDefaultPort,
9
+ aglProxyRelayFile,
10
+ aglProxyRelayMountPoint,
8
11
  aglProxyUnitName,
9
12
  defaultProxyClientProvider,
10
13
  inferencePlanPattern,
@@ -24,9 +27,12 @@ export const inferenceCliHelp = `Usage:
24
27
  agl proxy service install [--port ${aglProxyDefaultPort}] | enable | start | stop | status
25
28
  agl proxy serve [--port ${aglProxyDefaultPort}]
26
29
  agl proxy status [--json]
30
+ agl proxy capacity [--provider anthropic|openai] [--min-headroom 15] [--json] [--wait [--max-seconds <seconds>]]
27
31
  agl proxy credential <client> [--provider openai|anthropic] [--delivery file|none] [--write <path>] [--rotate] | --version
28
32
  agl proxy run codex|claude|opencode [--provider openai|anthropic] [--account <id>] [--plan <name>] [--model <id>] -- [harness arguments]
29
33
  agl proxy confined run [--provider anthropic|openai] -- docker run [docker options] <image> [command]
34
+ agl proxy confined run --harness codex [--provider openai] -- docker run [docker options] <image> \\
35
+ node ${aglProxyRelayMountPoint}/${aglProxyRelayFile} -- codex exec …
30
36
  agl proxy confined end <run id>
31
37
 
32
38
  The proxy runs as the ${aglProxyUnitName} user unit (serve runs it in a terminal instead).
@@ -47,8 +53,22 @@ ChatGPT accounts answer it translated, as for run claude --provider openai. It a
47
53
  --provider openai sets) right after docker run, prints the run's id on standard error, and ends the credential when the
48
54
  container exits. The socket is the proxy user's (0600): run the container as that uid (--user), or as root under
49
55
  rootless Docker. Root of a rootful daemon connects as well while it keeps CAP_DAC_OVERRIDE (--cap-drop ALL takes it).
56
+ --harness codex starts Codex's container instead, on the ChatGPT pool's ChatGPT accounts alone (never an OpenAI API
57
+ key): the listener serves it GET /openai/v1/models and POST /openai/v1/responses alone, and refuses a request that
58
+ declares a hosted tool. Codex reaches the socket through AGL's relay, mounted read-only at ${aglProxyRelayMountPoint}:
59
+ the container's command runs node ${aglProxyRelayMountPoint}/${aglProxyRelayFile} -- codex exec …, and the relay listens
60
+ on 127.0.0.1:${aglProxyRelayDefaultPort} inside the container, which therefore keeps a network of its own: --network host
61
+ and --network container:… are refused. It passes AGL_PROXY_SOCKET and MODELPROFILE_PROXY_TOKEN, and no model.
50
62
  confined end ends a run's credential at once, and its launcher stops the container; agl proxy status lists the runs
51
- with their pools.
63
+ with their harnesses and pools.
64
+ capacity answers each pool's room for new work: the headroom its members add now, summed. Its members are its
65
+ subscription sign-ins that have not lapsed and whose reading states a counted plan (Claude accounts: max; ChatGPT
66
+ accounts: every plan but free); one that takes no work now adds nothing. A pool is open when its room reaches
67
+ --min-headroom (15 unless given) and no provider 429 hit a member within five minutes (a proxy watches for five minutes
68
+ after its start before it says so); otherwise it waits until the first moment the members' readings foresee enough room.
69
+ Each member names its binding window and when its headroom next grows. Exit status: 0 when every pool reported is open,
70
+ 2 when one waits, 1 on a failure. --wait (with --provider) asks again until the pool is open, at most --max-seconds when
71
+ given, and exits 2 when that time ran out.
52
72
  Repeat --account or --plan to restrict automatic routing. Only accounts the account service holds are eligible.
53
73
  ChatGPT pools: /openai/v1/responses, /anthropic/v1/messages (translated), and each prefix's /models.
54
74
  Claude pools: /anthropic/v1/messages, /anthropic/v1/messages/count_tokens and /anthropic/v1/models, sent on as Claude Code sent them.
@@ -58,12 +78,13 @@ Use x-agl-session-id for custom clients; native session headers and prompt_cache
58
78
  Switches use full history with a cold cache. Provider-only references require a full-history retry; opaque account state never crosses accounts.
59
79
  `;
60
80
 
61
- export type TInferenceCommand = 'serve' | 'run' | 'credential' | 'status' | 'service' | 'confined';
81
+ export type TInferenceCommand = 'serve' | 'run' | 'credential' | 'status' | 'capacity' | 'service' | 'confined';
62
82
  export type TInferenceServiceAction = 'install' | 'enable' | 'start' | 'stop' | 'status';
63
83
  export type TInferenceConfinedAction = 'run' | 'end';
64
84
 
65
85
  export interface IInferenceCliArguments {
66
86
  command: TInferenceCommand;
87
+ /** `run`'s harness; for `confined run`, `codex` when `--harness codex` names it (Claude Code otherwise). */
67
88
  harness?: TInferenceHarness;
68
89
  client?: string;
69
90
  serviceAction?: TInferenceServiceAction;
@@ -81,6 +102,12 @@ export interface IInferenceCliArguments {
81
102
  /** `credential --version`: the release only, no client. */
82
103
  version: boolean;
83
104
  json: boolean;
105
+ /** `capacity --min-headroom`: the room a pool needs, a non-negative integer. */
106
+ minHeadroom?: number;
107
+ /** `capacity --wait`: ask again until the pool is open. */
108
+ wait: boolean;
109
+ /** `capacity --max-seconds`: how long `--wait` waits at most. */
110
+ maxSeconds?: number;
84
111
  args: string[];
85
112
  }
86
113
 
@@ -89,17 +116,18 @@ const commandOptions: Record<TInferenceCommand, readonly string[]> = {
89
116
  run: ['--provider', '--account', '--plan', '--model'],
90
117
  credential: ['--provider', '--delivery', '--write', '--rotate'],
91
118
  status: ['--json'],
119
+ capacity: ['--provider', '--min-headroom', '--json', '--wait', '--max-seconds'],
92
120
  service: ['--port'],
93
121
  confined: [],
94
122
  };
95
- const flags = new Set(['--rotate', '--json']);
123
+ const flags = new Set(['--rotate', '--json', '--wait']);
96
124
 
97
125
  export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferenceCliArguments => {
98
126
  const argv = [...argvArg];
99
127
  const command = argv.shift() as TInferenceCommand | undefined;
100
128
  if (!command || !Object.hasOwn(commandOptions, command)) throw new Error(inferenceCliHelp);
101
129
  const result: IInferenceCliArguments = { command, port: aglProxyDefaultPort, policy: {}, rotate: false, version: false, json: false,
102
- args: [] };
130
+ wait: false, args: [] };
103
131
  if (command === 'run') {
104
132
  const harness = argv.shift();
105
133
  if (!['codex', 'claude', 'opencode'].includes(harness ?? '')) throw new Error(inferenceCliHelp);
@@ -128,11 +156,20 @@ export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferen
128
156
  return result;
129
157
  }
130
158
  if (action !== 'run') throw new Error(inferenceCliHelp);
131
- if (argv[0] === '--provider') {
132
- argv.shift();
159
+ // Each option at most once, before `--`.
160
+ while (argv.length && argv[0] !== '--') {
161
+ const name = argv.shift();
133
162
  const value = argv.shift();
134
- if (!inferenceProviders.includes(value as TInferenceProvider)) throw new Error('--provider is openai or anthropic.');
135
- result.provider = value as TInferenceProvider;
163
+ if (name === '--provider' && result.provider === undefined) {
164
+ if (!inferenceProviders.includes(value as TInferenceProvider)) throw new Error('--provider is openai or anthropic.');
165
+ result.provider = value as TInferenceProvider;
166
+ } else if (name === '--harness' && result.harness === undefined) {
167
+ if (value !== 'codex') throw new Error('--harness is codex: Codex on the ChatGPT pool. Claude Code runs without it.');
168
+ result.harness = 'codex';
169
+ } else throw new Error(inferenceCliHelp);
170
+ }
171
+ if (result.harness === 'codex' && result.provider === 'anthropic') {
172
+ throw new Error('Codex runs on the ChatGPT pool\'s ChatGPT accounts; --provider anthropic serves Claude Code alone.');
136
173
  }
137
174
  if (argv.shift() !== '--' || !argv.length) throw new Error(inferenceCliHelp);
138
175
  result.confinedAction = 'run';
@@ -148,7 +185,7 @@ export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferen
148
185
  throw new Error(`Unknown proxy option: ${name}`);
149
186
  }
150
187
  if (flags.has(name)) {
151
- if (name === '--rotate') result.rotate = true; else result.json = true;
188
+ if (name === '--rotate') result.rotate = true; else if (name === '--wait') result.wait = true; else result.json = true;
152
189
  continue;
153
190
  }
154
191
  const value = argv.shift();
@@ -168,6 +205,12 @@ export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferen
168
205
  } else if (name === '--delivery') {
169
206
  if (!proxyCredentialDeliveries.includes(value as TProxyCredentialDelivery)) throw new Error('--delivery is file or none.');
170
207
  result.delivery = value as TProxyCredentialDelivery;
208
+ } else if (name === '--min-headroom') {
209
+ if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value))) throw new Error('--min-headroom is a whole percent, 0 or more.');
210
+ result.minHeadroom = Number(value);
211
+ } else if (name === '--max-seconds') {
212
+ if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) throw new Error('--max-seconds is a whole number of seconds, 1 or more.');
213
+ result.maxSeconds = Number(value);
171
214
  } else if (name === '--write') {
172
215
  if (!path.isAbsolute(value)) throw new Error('--write needs an absolute path.');
173
216
  result.write = path.normalize(value);
@@ -176,6 +219,10 @@ export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferen
176
219
  result.modelId = value;
177
220
  }
178
221
  }
222
+ if (command === 'capacity') {
223
+ if (result.wait && result.provider === undefined) throw new Error('--wait waits for one pool: name it with --provider.');
224
+ if (result.maxSeconds !== undefined && !result.wait) throw new Error('--max-seconds bounds --wait, which it needs.');
225
+ }
179
226
  if (accounts.length > 64 || plans.length > 32) throw new Error('The proxy policy exceeds its account or plan limit.');
180
227
  if (accounts.length) result.policy.accountIds = [...new Set(accounts)];
181
228
  if (plans.length) result.policy.plans = [...new Set(plans)];
@@ -1,9 +1,9 @@
1
1
  import * as path from 'node:path';
2
2
  import type { TInferenceModel } from './classes.inferencerouter.js';
3
3
  import type { TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
4
- import { aglProxyConfinedMountPoint } from './functions.proxycontract.js';
4
+ import { aglProxyConfinedMountPoint, aglProxyRelayMountPoint } from './functions.proxycontract.js';
5
5
  import { aglProxyProviderId, claudeProxyEnvironment, claudeProxyReservedVariables, claudeRoutingVariables, codexProxyProvider,
6
- openCodeProxyProvider, proxyHarnessModels } from './functions.proxyharnessconfig.js';
6
+ codexRoutingVariables, openCodeProxyProvider, proxyHarnessModels } from './functions.proxyharnessconfig.js';
7
7
 
8
8
  export type TInferenceHarness = 'codex' | 'claude' | 'opencode';
9
9
  export interface IInferenceLaunchOptions {
@@ -160,23 +160,140 @@ export const inferenceHarnessLaunch = (optionsArg: IInferenceLaunchOptions): { a
160
160
  return { environment, args: args[0] !== undefined && openCodeCommands.has(args[0]) ? args : [...selection, ...args] };
161
161
  };
162
162
 
163
- /** A confined run's pool, as its launcher configures Claude Code for it: a ChatGPT-pool run with the pool's models. */
164
- export type TConfinedLaunchPool = { provider: 'anthropic' } | { provider: 'openai'; models: readonly TInferenceModel[] };
163
+ /**
164
+ * A confined run's harness and pool, as its launcher configures the container for it: Claude Code on the Claude pool, Claude
165
+ * Code on the ChatGPT pool with the pool's models, or Codex on the ChatGPT pool with the host directory that holds AGL's
166
+ * relay for it (`writeConfinedRelay`).
167
+ */
168
+ export type TConfinedLaunchPool = { provider: 'anthropic' } | { provider: 'openai'; models: readonly TInferenceModel[] }
169
+ | { harness: 'codex'; relayDirectory: string };
170
+
171
+ /**
172
+ * `docker run`'s options as Docker 29.7.1 lists them (`docker run --help`, and the hidden `--disable-content-trust`): those
173
+ * that take no value, those that take one, and the one-letter forms of each. `dockerRunNetworks` takes an option it does
174
+ * not know to take a value, but never one that is a network option itself (`dockerNetworkOption`): an unknown option can
175
+ * make it read on into the container's command, so it may find more networks than Docker does, never fewer.
176
+ */
177
+ const dockerRunFlags: ReadonlySet<string> = new Set(['--detach', '--disable-content-trust', '--help', '--init', '--interactive',
178
+ '--no-healthcheck', '--oom-kill-disable', '--privileged', '--publish-all', '--quiet', '--read-only', '--rm', '--sig-proxy',
179
+ '--tty', '--use-api-socket']);
180
+ const dockerRunValueOptions: ReadonlySet<string> = new Set(['--add-host', '--annotation', '--attach', '--blkio-weight',
181
+ '--blkio-weight-device', '--cap-add', '--cap-drop', '--cgroup-parent', '--cgroupns', '--cidfile', '--cpu-period', '--cpu-quota',
182
+ '--cpu-rt-period', '--cpu-rt-runtime', '--cpu-shares', '--cpus', '--cpuset-cpus', '--cpuset-mems', '--detach-keys', '--device',
183
+ '--device-cgroup-rule', '--device-read-bps', '--device-read-iops', '--device-write-bps', '--device-write-iops', '--dns',
184
+ '--dns-option', '--dns-search', '--domainname', '--entrypoint', '--env', '--env-file', '--expose', '--gpus', '--group-add',
185
+ '--health-cmd', '--health-interval', '--health-retries', '--health-start-interval', '--health-start-period', '--health-timeout',
186
+ '--hostname', '--ip', '--ip6', '--ipc', '--isolation', '--label', '--label-file', '--link', '--link-local-ip', '--log-driver',
187
+ '--log-opt', '--mac-address', '--memory', '--memory-reservation', '--memory-swap', '--memory-swappiness', '--mount', '--name',
188
+ '--network', '--network-alias', '--oom-score-adj', '--pid', '--pids-limit', '--platform', '--publish', '--pull', '--restart',
189
+ '--runtime', '--security-opt', '--shm-size', '--stop-signal', '--stop-timeout', '--storage-opt', '--sysctl', '--tmpfs',
190
+ '--ulimit', '--user', '--userns', '--uts', '--volume', '--volume-driver', '--volumes-from', '--workdir']);
191
+ const dockerRunShortFlags: ReadonlySet<string> = new Set(['d', 'i', 'P', 'q', 't']);
192
+ const dockerRunShortValueOptions: ReadonlySet<string> = new Set(['a', 'c', 'e', 'h', 'l', 'm', 'p', 'u', 'v', 'w']);
193
+ /** `--network` or its alias `--net`, alone or with its value after `=`. */
194
+ const dockerNetworkOption = /^--net(?:work)?(?:=|$)/u;
195
+
196
+ /**
197
+ * The `--network` values `docker run`'s options (`optionsArg`, what follows `run`) give the container, in every spelling
198
+ * Docker takes: `--network` or its alias `--net`, with the value after `=` or as the next argument; see
199
+ * `dockerNetworkName` for what a value names. Reading stops at the image, the first argument that is no option, or at `--`.
200
+ * A known option that takes a value takes the next argument whatever it reads like, as Docker does (`-e --network=host`
201
+ * sets a variable); an option only assumed to take one never takes a network option.
202
+ */
203
+ export const dockerRunNetworks = (optionsArg: readonly string[]): string[] => {
204
+ const networks: string[] = [];
205
+ const takesNext = (knownArg: boolean, indexArg: number): boolean =>
206
+ knownArg || !dockerNetworkOption.test(optionsArg[indexArg + 1] ?? '');
207
+ for (let index = 0; index < optionsArg.length; index++) {
208
+ const argument = optionsArg[index]!;
209
+ if (argument === '--' || !argument.startsWith('-') || argument === '-') break;
210
+ const long = /^(--[^=]+)(?:=(.*))?$/su.exec(argument);
211
+ if (long) {
212
+ const [, name, value] = long;
213
+ if (name === '--network' || name === '--net') {
214
+ const network = value ?? optionsArg[++index];
215
+ if (network !== undefined) networks.push(network);
216
+ } else if (value === undefined && !dockerRunFlags.has(name!) && takesNext(dockerRunValueOptions.has(name!), index)) index++;
217
+ continue;
218
+ }
219
+ // One-letter options, alone or grouped (`-it`); one that takes a value, or one this list does not know, takes the rest
220
+ // of the group or the next argument.
221
+ for (let at = 1; at < argument.length; at++) {
222
+ if (dockerRunShortFlags.has(argument[at]!)) continue;
223
+ if (at === argument.length - 1 && takesNext(dockerRunShortValueOptions.has(argument[at]!), index)) index++;
224
+ break;
225
+ }
226
+ }
227
+ return networks;
228
+ };
229
+
230
+ /**
231
+ * The network a `--network` value names, as Docker 29.7.1's command line reads it (`NetworkOpt`): a value in which
232
+ * `\w+=\w+` occurs anywhere is its long form, comma-separated `key=value` fields whose keys it trims and lower-cases, and
233
+ * whose last `name` field names the network; any other value is the network's name itself. `undefined` for a long form
234
+ * this does not read whole: one with a quote or a line break (Docker reads the fields as CSV), a field without `=`, or no
235
+ * `name` field.
236
+ */
237
+ export const dockerNetworkName = (valueArg: string): string | undefined => {
238
+ if (!/\w+=\w+/u.test(valueArg)) return valueArg;
239
+ if (/["\r\n]/u.test(valueArg)) return undefined;
240
+ let name: string | undefined;
241
+ for (const field of valueArg.split(',')) {
242
+ const at = field.indexOf('=');
243
+ if (at < 0) return undefined;
244
+ if (field.slice(0, at).trim().toLowerCase() === 'name') name = field.slice(at + 1).trim();
245
+ }
246
+ return name;
247
+ };
248
+
249
+ /**
250
+ * A Codex run's container keeps a network namespace of its own: AGL's relay listens on `127.0.0.1` inside it, which on
251
+ * the host's network (`host`) or another container's (`container:…`) would be that loopback's, where the proxy's own
252
+ * port is and every process of the host or that container could reach the confined route over TCP (ruling U13-162). A
253
+ * long-form value whose network this cannot read is refused as well.
254
+ */
255
+ const assertOwnNetwork = (optionsArg: readonly string[]): void => {
256
+ for (const value of dockerRunNetworks(optionsArg)) {
257
+ const network = dockerNetworkName(value);
258
+ if (network === undefined) {
259
+ throw new Error(`A Codex confined run's container needs a network namespace of its own, and AGL cannot read which `
260
+ + `network --network ${value} names (Docker's long form: comma-separated key=value fields, the network in name=, no `
261
+ + 'quotes). Use --network none.');
262
+ }
263
+ if (network === 'host' || network.startsWith('container:')) {
264
+ throw new Error(`A Codex confined run's container needs a network namespace of its own, and --network ${value} shares `
265
+ + 'another\'s: AGL\'s relay listens on 127.0.0.1 inside the container, which would put the confined route on that '
266
+ + 'loopback. Use --network none.');
267
+ }
268
+ }
269
+ };
270
+
271
+ /** `--mount` separates its fields with commas and reads quotes; a directory naming either cannot be passed safely. */
272
+ const assertMountable = (directoryArg: string, whatArg: string): void => {
273
+ if (/[,"'\n]/u.test(directoryArg)) {
274
+ throw new Error(`${whatArg} ${directoryArg} cannot be mounted: it holds a comma, quote or line break.`);
275
+ }
276
+ };
165
277
 
166
278
  /**
167
279
  * A confined run's `docker run`: the given command, with the confined listener's directory mounted read-only at
168
- * `aglProxyConfinedMountPoint` and Claude Code's settings for it added right after `run`, before the launcher's own
280
+ * `aglProxyConfinedMountPoint` and the harness's settings for it added right after `run`, before the launcher's own
169
281
  * options and image. Claude Code inside reaches the proxy through the socket alone (`ANTHROPIC_UNIX_SOCKET`, which
170
282
  * Claude Code sends its API requests through as plain HTTP to `ANTHROPIC_BASE_URL`'s path), on the run's credential
171
283
  * (`ANTHROPIC_AUTH_TOKEN`), and sends nothing beyond its model requests. On the Claude pool it reads the pool's models
172
284
  * from the proxy; on the ChatGPT pool it gets the variables `agl proxy run claude --provider openai` gives it
173
285
  * (`claudeChatGptEnvironment`: the pool's default model for every alias, its context window), but neither that command's
174
286
  * configuration directory, which lies in the AGL home, nor its `/model` picker, an option of the container's command
175
- * that the launcher does not touch. The container gets each variable by name from the docker command's environment, so
176
- * the credential never appears on a command line; that environment drops every variable that would give Claude Code
177
- * another login or route, and on the ChatGPT pool every model variable it sets, so `-e NAME` of one of them passes
178
- * nothing. The mount is the socket's own directory, which holds nothing else and survives a proxy restart, unlike a
179
- * mount of the socket file. Only `docker run` and `docker container run` are taken.
287
+ * that the launcher does not touch. A Codex run (AGL-1614) also gets AGL's relay's directory mounted read-only at
288
+ * `aglProxyRelayMountPoint`, which its command runs Codex through, the socket's path in the container
289
+ * (`AGL_PROXY_SOCKET`) for the relay and the run's credential (`MODELPROFILE_PROXY_TOKEN`) for Codex's provider command;
290
+ * no model variable: Codex reads the pool's catalog through the relay, and the command names its model. The container
291
+ * gets each variable by name from the docker command's environment, so the credential never appears on a command line;
292
+ * that environment drops every variable that would give the harness another login or route -- Claude Code's always, and
293
+ * for a Codex run Codex's and OpenAI's (`codexRoutingVariables`) -- and on the ChatGPT pool every model variable a Claude
294
+ * Code run sets, so `-e NAME` of one of them passes nothing. The mount is the socket's own directory, which holds nothing
295
+ * else and survives a proxy restart, unlike a mount of the socket file. Only `docker run` and `docker container run` are
296
+ * taken.
180
297
  */
181
298
  export const confinedDockerLaunch = (optionsArg: {
182
299
  args: readonly string[];
@@ -194,25 +311,35 @@ export const confinedDockerLaunch = (optionsArg: {
194
311
  throw new Error('A confined run starts its container with `docker run` (or `docker container run`) and its arguments.');
195
312
  }
196
313
  const directory = path.dirname(optionsArg.socketPath);
197
- // `--mount` separates its fields with commas and reads quotes; a directory naming either cannot be passed safely.
198
- if (/[,"'\n]/u.test(directory)) throw new Error(`The confined listener's directory ${directory} cannot be mounted: it holds a comma, quote or line break.`);
314
+ assertMountable(directory, 'The confined listener\'s directory');
315
+ const pool = optionsArg.pool;
316
+ const relayDirectory = 'harness' in pool ? pool.relayDirectory : undefined;
317
+ if (relayDirectory !== undefined) {
318
+ assertMountable(relayDirectory, 'The confined run\'s relay directory');
319
+ assertOwnNetwork(args.slice(runAt));
320
+ }
199
321
  const socket = `${aglProxyConfinedMountPoint}/${path.basename(optionsArg.socketPath)}`;
200
- const variables: Record<string, string> = optionsArg.pool.provider === 'anthropic' ? {
322
+ const variables: Record<string, string> = 'harness' in pool ? {
323
+ AGL_PROXY_SOCKET: socket,
324
+ MODELPROFILE_PROXY_TOKEN: optionsArg.token,
325
+ } : pool.provider === 'anthropic' ? {
201
326
  ...claudeProxyEnvironment(optionsArg.baseUrl),
202
327
  ANTHROPIC_UNIX_SOCKET: socket,
203
328
  ANTHROPIC_AUTH_TOKEN: optionsArg.token,
204
329
  } : {
205
- ...claudeChatGptEnvironment({ baseUrl: `${optionsArg.baseUrl}/anthropic`, token: optionsArg.token,
206
- models: optionsArg.pool.models }),
330
+ ...claudeChatGptEnvironment({ baseUrl: `${optionsArg.baseUrl}/anthropic`, token: optionsArg.token, models: pool.models }),
207
331
  ANTHROPIC_UNIX_SOCKET: socket,
208
332
  };
209
333
  const environment = { ...optionsArg.environment };
210
334
  for (const name of claudeProxyReservedVariables) delete environment[name];
211
- if (optionsArg.pool.provider === 'openai') for (const name of claudeChatGptVariables) delete environment[name];
335
+ if ('harness' in pool) for (const name of codexRoutingVariables) delete environment[name];
336
+ else if (pool.provider === 'openai') for (const name of claudeChatGptVariables) delete environment[name];
212
337
  return {
213
338
  command,
214
339
  args: [...args.slice(0, runAt),
215
340
  '--mount', `type=bind,source=${directory},target=${aglProxyConfinedMountPoint},readonly`,
341
+ ...(relayDirectory === undefined ? []
342
+ : ['--mount', `type=bind,source=${relayDirectory},target=${aglProxyRelayMountPoint},readonly`]),
216
343
  ...Object.keys(variables).flatMap((nameArg) => ['--env', nameArg]),
217
344
  ...args.slice(runAt)],
218
345
  environment: { ...environment, ...variables },
@@ -1,5 +1,6 @@
1
+ import * as plugins from './plugins.js';
1
2
  import { fleetWorkerRequestSchemas } from './fleet/functions.workervalidation.js';
2
- import type { TFleetWorkerAction } from '../ts_interfaces/fleetworkers.js';
3
+ import { fleetWorkerReadActions, type TFleetWorkerAction, type TFleetWorkerResponse } from '../ts_interfaces/fleetworkers.js';
3
4
 
4
5
  const descriptions: Record<TFleetWorkerAction, string> = {
5
6
  start: 'Start a named Claude background worker or a Codex thread on the existing shared daemon, using a Configuration master worker profile. Returns a job handle.',
@@ -12,12 +13,41 @@ const descriptions: Record<TFleetWorkerAction, string> = {
12
13
  archive: 'Archive a settled worker. Codex archives natively; Claude archives the AGL registry only and retains its transcript/worktree. Returns a job handle.',
13
14
  refresh: 'Start a fresh thread from the settled predecessor\'s self-contained Handoff report. Store the successor before retiring the predecessor. With profile, the successor launches on that configured profile, which must run the predecessor\'s harness (only move changes the harness); without it the successor keeps the predecessor\'s recorded profile. Returns a job handle.',
14
15
  move: 'Move a settled Claude lane to a new shared-daemon Codex thread with its Handoff report. Identify the successor before retiring Claude. Returns a job handle.',
15
- list: 'List this owner\'s durable native worker bindings, unresolved dispatch fences and attributed lost resolutions.',
16
- status: 'Observe a controller-owned worker job. Jobs are transient; bindings and unresolved dispatches survive restart. Inspect unknown native outcomes before retrying.',
16
+ list: 'List this owner\'s fleet workers as summaries, newest first, in pages of limit (1-100, default 50): identity, ticket, state, native id, cwd, the native status, newest turn outcome and native wait last observed, and fence flags (an unresolved dispatch with its action and since, a lost or reconfirmed dispatch, a recorded error). total, fenced and failed (recorded errors and failed turn outcomes) count the whole filtered set, so a page never hides a fence. Continue with nextCursor and the same filter (archived, ticketKey, state, harness); a cursor of another filter or one after a worker no longer held as it was is refused. view full returns every full record unpaged; fleet_worker_get returns one worker whole.',
17
+ get: 'Read one of this owner\'s fleet workers, archived ones included, by name or id: its full record (dispatch fence, lost, reconfirmed and re-bind resolutions with their attribution and proof, error) and the native status, turn outcome and start, native wait and excerpt the controller last observed.',
18
+ status: 'Read a fleet operation job (the handle a fleet_worker_* action returns), not a host job. Jobs are transient; bindings and unresolved dispatches survive restart. Inspect unknown native outcomes before retrying.',
19
+ 'job-wait': 'Wait until a fleet operation job (the handle a fleet_worker_* action returns, not a host job) succeeds or fails, or timeoutMs (at most 240000) passes; timedOut tells which. Waiting, a timeout or an abandoned wait never cancels the job. A job the controller no longer holds (jobs end with a controller restart or eviction) is JOB_UNAVAILABLE, not failed: read the worker with fleet_worker_get.',
17
20
  'native-message': 'Wake a settled (done, blocked or stopped) Claude Code background job that no fleet worker binds with an attributed message, through Claude Code itself (`claude --bg --resume <id> <text>`), as the browser\'s native session send does. nativeId is the full session id or a unique prefix of at least 8 characters; an ambiguous prefix is refused. A running, failed or held job, a fleet worker\'s session and a project conversation are refused with their reason. The message arrives behind the same attribution header as session_message, naming the sender label and the local owner capability, never as the job\'s user. A native wake holds no dispatch fence, writes no ticket comment and does not observe the woken turn; the receipt names the command that adopts the job as a fleet worker. Returns a job handle; an unknown outcome is never retried.',
18
21
  watch: 'Read the one bounded fleet event stream: worker turn endings, reports during turns, reaped Claude worker observations, release outcomes, and host load. Continue with the returned epoch/cursor; reset explicitly signals restart or retained-history gaps.',
19
22
  };
23
+ /** The tools' own inputs where they differ from the private request's: MCP `fleet_worker_list` lists summaries unless told otherwise. */
24
+ const toolInputSchemas: Partial<Record<TFleetWorkerAction, plugins.z.ZodType<Record<string, unknown>>>> = {
25
+ list: fleetWorkerRequestSchemas.list.extend({ view: plugins.z.enum(['summary', 'full']).default('summary') }),
26
+ };
20
27
  export const fleetWorkerToolDefinitions = (Object.keys(fleetWorkerRequestSchemas) as TFleetWorkerAction[]).map((action) => ({
21
28
  name: action === 'watch' ? 'fleet_watch' : `fleet_worker_${action.replaceAll('-', '_')}`, action, description: descriptions[action],
22
- inputSchema: fleetWorkerRequestSchemas[action], readOnly: ['list', 'status', 'watch'].includes(action),
29
+ inputSchema: toolInputSchemas[action] ?? fleetWorkerRequestSchemas[action], readOnly: (fleetWorkerReadActions as readonly string[]).includes(action),
23
30
  }));
31
+ /**
32
+ * One private controller request is bounded by the private request timeout (30 s), so `fleet_worker_job_wait` waits in
33
+ * slices of at most this long, each a fresh request.
34
+ */
35
+ export const fleetWorkerJobWaitSliceMs = 20_000;
36
+ /**
37
+ * Waits for a fleet operation job in slices until it settles or `timeoutMs` passed, on a monotonic clock: `slice` asks
38
+ * the controller for one wait of at most `fleetWorkerJobWaitSliceMs`. The controller times each slice, so a timed-out
39
+ * slice that covered the remaining wait ends it.
40
+ */
41
+ export const waitForFleetWorkerJob = async (
42
+ slice: (timeoutMs: number) => Promise<TFleetWorkerResponse<'job-wait'>>,
43
+ timeoutMs: number,
44
+ monotonicNow: () => number = () => performance.now(),
45
+ ): Promise<TFleetWorkerResponse<'job-wait'>> => {
46
+ const deadline = monotonicNow() + timeoutMs;
47
+ while (true) {
48
+ const remainingMs = Math.max(0, Math.ceil(deadline - monotonicNow()));
49
+ const sliceMs = Math.min(fleetWorkerJobWaitSliceMs, remainingMs);
50
+ const result = await slice(sliceMs);
51
+ if (!result.timedOut || sliceMs === remainingMs || monotonicNow() >= deadline) return result;
52
+ }
53
+ };
@@ -0,0 +1,191 @@
1
+ import * as plugins from './plugins.js';
2
+ import type { IInferenceAccountStatus } from './classes.inferencerouter.js';
3
+ import {
4
+ proxyCapacityQuietMs,
5
+ type IProxyCapacityMember,
6
+ type IProxyCapacityPool,
7
+ type IProxyCapacityWindow,
8
+ type TProxyCapacityProvider,
9
+ type TProxyCapacityVerdict,
10
+ type TProxyCapacityWaitReason,
11
+ } from '../ts_interfaces/proxycapacity.js';
12
+
13
+ /**
14
+ * Which plans a pool counts, by the plan name its member's held reading states: `only` the plans listed, or every plan
15
+ * `except` them. A Claude account counts on Max alone (Anthropic's `organization_type` `claude_max`, both Max tiers;
16
+ * Claude Code reads the tier apart, from `rate_limit_tier`), a ChatGPT account on every plan but Free.
17
+ */
18
+ export interface IProxyCapacityPlanRule {
19
+ counts: 'only' | 'except';
20
+ plans: readonly string[];
21
+ }
22
+
23
+ export const proxyCapacityPlans: Readonly<Record<TProxyCapacityProvider, IProxyCapacityPlanRule>> = {
24
+ anthropic: { counts: 'only', plans: ['max'] },
25
+ openai: { counts: 'except', plans: ['free'] },
26
+ };
27
+
28
+ /** Whether a pool counts an account of the plan `planArg` names. */
29
+ export const proxyCapacityPlanCounts = (providerArg: TProxyCapacityProvider, planArg: string): boolean => {
30
+ const rule = proxyCapacityPlans[providerArg];
31
+ return rule.plans.includes(planArg) === (rule.counts === 'only');
32
+ };
33
+
34
+ /** The plan a held reading of the pool's kind states, whatever its age; `null` without one. */
35
+ export const proxyCapacityHeldPlan = (providerArg: TProxyCapacityProvider,
36
+ usageArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): string | null => {
37
+ const reading = usageArg?.reading;
38
+ if (providerArg === 'anthropic') return reading?.kind === 'anthropic' ? reading.status.plan?.name || null : null;
39
+ return reading?.kind === 'openai' ? reading.rateLimits.plan || null : null;
40
+ };
41
+
42
+ /** One account of the proxy as the capacity judges it. */
43
+ export interface IProxyCapacityAccount {
44
+ /** As `InferenceRouter.accountStatus` judged it. */
45
+ status: IInferenceAccountStatus;
46
+ /** The usage reading the status judged it on, or `undefined` while none is held. */
47
+ usage: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined;
48
+ /** The newest provider 429 on it the proxy saw (epoch milliseconds), or `null`; and until when it rests after one (0: it does not). */
49
+ quota: { lastAt: number | null; restUntil: number };
50
+ }
51
+
52
+ export interface IProxyCapacityOptions {
53
+ /** The room the pool needs: a non-negative integer, in headroom percent summed over its members. */
54
+ minHeadroom: number;
55
+ /** Since when the proxy observes provider 429s (epoch milliseconds): its start. */
56
+ observedSince: number;
57
+ /** Epoch milliseconds. */
58
+ now: number;
59
+ }
60
+
61
+ /** A member's headroom over time: what it adds now, and each later moment that changes, with what it adds from then on. */
62
+ interface IMemberProjection {
63
+ member: IProxyCapacityMember;
64
+ now: number;
65
+ steps: Array<{ at: number; headroom: number }>;
66
+ }
67
+
68
+ /** What a projection adds to the room at `atArg`, no earlier than now. */
69
+ const headroomAt = (projectionArg: IMemberProjection, atArg: number): number => {
70
+ let headroom = projectionArg.now;
71
+ for (const step of projectionArg.steps) {
72
+ if (step.at > atArg) break;
73
+ headroom = step.headroom;
74
+ }
75
+ return headroom;
76
+ };
77
+
78
+ const iso = (atArg: number): string => new Date(atArg).toISOString();
79
+
80
+ const capacityWindow = (windowArg: plugins.authswitchUsageWindows.IAuthSwitchUsageWindow): IProxyCapacityWindow => ({
81
+ name: plugins.authswitchUsageWindows.authSwitchUsageWindowName(windowArg).slice(0, 128),
82
+ durationSeconds: windowArg.durationSeconds,
83
+ usedPercent: plugins.authswitchUsageWindows.authSwitchUsageWindowPercent(windowArg),
84
+ estimated: windowArg.estimatedUsedPercent !== null,
85
+ resetAt: windowArg.resetAt,
86
+ });
87
+
88
+ /**
89
+ * One member's projection. An account that takes work adds its headroom (`authSwitchHeadroomGrowth`) and grows as its
90
+ * windows reset. One that does not adds 0 until it takes work again -- a provider 429's rest ends (`cooling`), or the
91
+ * windows and provider refusal its limit is held by lift (`reserved`, `exhausted`: the limit's reset, never before the
92
+ * rest of a 429) -- and from then on what its windows leave it. One the proxy cannot judge (`unavailable`: a stale
93
+ * reading, a sign-in, model list or payment problem), or whose reading counts no window, adds 0 with no growth
94
+ * foreseen. A canceled account adds nothing from its lapse on.
95
+ */
96
+ const projectMember = (accountArg: IProxyCapacityAccount, planArg: string, nowArg: number): IMemberProjection => {
97
+ const { status, usage, quota } = accountArg;
98
+ const base = { accountId: status.id, plan: planArg, state: status.state };
99
+ const recheckAt = status.unavailable?.reason === 'usage_unread' ? status.unavailable.retryAt ?? null : null;
100
+ if (status.state === 'unavailable' || status.headroom === null || !usage?.reading) {
101
+ return { now: 0, steps: [], member: { ...base, headroom: 0, binding: null, growsAt: null, growsTo: null, recheckAt } };
102
+ }
103
+ const growth = plugins.authswitchUsageLimit.authSwitchHeadroomGrowth(usage.reading, status.maxUsagePercent, nowArg,
104
+ status.reserveLiftUntil);
105
+ if (growth.headroom === null) {
106
+ return { now: 0, steps: [], member: { ...base, headroom: 0, binding: null, growsAt: null, growsTo: null, recheckAt } };
107
+ }
108
+ const windowsHeadroomAt = (atArg: number): number => {
109
+ let headroom = growth.headroom!;
110
+ for (const step of growth.steps) {
111
+ if (step.at > atArg) break;
112
+ headroom = step.headroom;
113
+ }
114
+ return headroom;
115
+ };
116
+ // When it takes work again: now, a known moment ahead, or never as far as the reading says.
117
+ const statedReset = status.resetAt === null ? Number.NaN : Date.parse(status.resetAt);
118
+ const returns = status.state === 'available' ? -Infinity
119
+ : status.state === 'cooling' ? statedReset
120
+ : Math.max(statedReset, quota.restUntil);
121
+ const takesWorkFrom = status.state === 'available' ? -Infinity
122
+ : Number.isFinite(returns) && returns > nowArg ? returns : Infinity;
123
+ const lapses = status.lifecycle === 'canceled' && status.lapsesAt !== null ? Date.parse(status.lapsesAt) : Infinity;
124
+ const adds = (atArg: number): number => atArg >= takesWorkFrom && atArg < lapses ? windowsHeadroomAt(atArg) : 0;
125
+ const moments = [...new Set([...growth.steps.map((stepArg) => stepArg.at), takesWorkFrom, lapses])]
126
+ .filter((atArg) => Number.isFinite(atArg) && atArg > nowArg)
127
+ .sort((left, right) => left - right);
128
+ const current = adds(nowArg);
129
+ const steps: Array<{ at: number; headroom: number }> = [];
130
+ let previous = current;
131
+ for (const at of moments) {
132
+ const headroom = adds(at);
133
+ if (headroom !== previous) steps.push({ at, headroom });
134
+ previous = headroom;
135
+ }
136
+ let before = current;
137
+ const grows = steps.find((stepArg) => {
138
+ const grew = stepArg.headroom > before;
139
+ before = stepArg.headroom;
140
+ return grew;
141
+ });
142
+ return { now: current, steps, member: { ...base, headroom: current,
143
+ binding: growth.binding ? capacityWindow(growth.binding) : null,
144
+ growsAt: grows ? iso(grows.at) : null, growsTo: grows ? grows.headroom : null, recheckAt } };
145
+ };
146
+
147
+ /**
148
+ * A pool's room for new work (AGL-1097). Its members are the pool's subscription sign-ins that have not lapsed and whose
149
+ * held reading states a plan the pool counts (`proxyCapacityPlans`), stale or not; API keys never count. The room is
150
+ * the headroom its members add now (see `projectMember`), summed.
151
+ *
152
+ * The pool is open when the room reaches `minHeadroom` and it is quiet: no provider 429 on a member within
153
+ * `proxyCapacityQuietMs`, which the proxy can say only once it has observed that long. Otherwise it waits until the
154
+ * first moment the members' readings foresee the room at the minimum once it is quiet (`room`), or until it is quiet when
155
+ * the room is there by then (`provider-429`, or `quiet-unobserved` while the proxy has not observed long enough); with
156
+ * no such moment foreseen, without an end (`until` and `seconds` `null`). Each projected moment is the earliest the room
157
+ * can be there, as no reading foresees the usage spent meanwhile.
158
+ */
159
+ export const proxyPoolCapacity = (providerArg: TProxyCapacityProvider, accountsArg: readonly IProxyCapacityAccount[],
160
+ optionsArg: IProxyCapacityOptions): IProxyCapacityPool => {
161
+ const { now, minHeadroom, observedSince } = optionsArg;
162
+ const counted = accountsArg.flatMap((accountArg) => {
163
+ const { status } = accountArg;
164
+ if (status.provider !== providerArg || status.credential !== 'subscription' || status.lifecycle === 'lapsed') return [];
165
+ const plan = proxyCapacityHeldPlan(providerArg, accountArg.usage);
166
+ return plan !== null && proxyCapacityPlanCounts(providerArg, plan) ? [{ account: accountArg, plan }] : [];
167
+ }).sort((left, right) => left.account.status.id.localeCompare(right.account.status.id));
168
+ const projections = counted.map(({ account, plan }) => projectMember(account, plan, now));
169
+ const roomAt = (atArg: number): number => projections.reduce((sumArg, projectionArg) => sumArg + headroomAt(projectionArg, atArg), 0);
170
+ const room = roomAt(now);
171
+ const lastQuota = counted.reduce<number | null>((latestArg, { account }) => account.quota.lastAt === null ? latestArg
172
+ : Math.max(latestArg ?? -Infinity, account.quota.lastAt), null);
173
+ // When the pool is quiet, and why it is not before.
174
+ const quiet: Array<{ until: number; reason: TProxyCapacityWaitReason }> = [
175
+ ...(lastQuota !== null ? [{ until: lastQuota + proxyCapacityQuietMs, reason: 'provider-429' as const }] : []),
176
+ { until: observedSince + proxyCapacityQuietMs, reason: 'quiet-unobserved' as const },
177
+ ].filter((entryArg) => entryArg.until > now).sort((left, right) => right.until - left.until);
178
+ const quietFrom = quiet[0]?.until ?? now;
179
+ let verdict: TProxyCapacityVerdict;
180
+ if (!quiet.length && room >= minHeadroom) verdict = { state: 'open' };
181
+ else {
182
+ const moments = [...new Set(projections.flatMap((projectionArg) => projectionArg.steps.map((stepArg) => stepArg.at)))]
183
+ .filter((atArg) => atArg > quietFrom).sort((left, right) => left - right);
184
+ const enough = roomAt(quietFrom) >= minHeadroom ? quietFrom : moments.find((atArg) => roomAt(atArg) >= minHeadroom);
185
+ verdict = enough === undefined ? { state: 'wait', reason: 'room', until: null, seconds: null }
186
+ : { state: 'wait', reason: enough > quietFrom || !quiet.length ? 'room' : quiet[0].reason, until: iso(enough),
187
+ seconds: Math.max(1, Math.ceil((enough - now) / 1000)) };
188
+ }
189
+ return { provider: providerArg, minHeadroom, room, members: projections.map((projectionArg) => projectionArg.member),
190
+ last429At: lastQuota === null ? null : iso(lastQuota), verdict };
191
+ };