agl 43.1.0 → 43.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/changelog.md +32 -0
- package/dist_serve/bundle.js +5950 -5530
- package/dist_serve/bundle.js.map +2 -2
- package/dist_serve/bundle.js.third-party-notices.json +31 -31
- package/dist_serve/bundle.js.third-party-notices.txt +31 -31
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/aglapi/aglapisurface.document.js +521 -17
- package/dist_ts/aglapi/interfaces.d.ts +3 -0
- package/dist_ts/aglapi/interfaces.js +2 -1
- package/dist_ts/classes.accountsactions.d.ts +3 -1
- package/dist_ts/classes.accountsactions.js +21 -3
- package/dist_ts/classes.authmodels.js +17 -4
- package/dist_ts/classes.authstore.js +16 -2
- package/dist_ts/classes.claudeharness.d.ts +16 -0
- package/dist_ts/classes.claudeharness.js +24 -2
- package/dist_ts/classes.cli.d.ts +4 -2
- package/dist_ts/classes.cli.js +6 -3
- package/dist_ts/classes.codexclientadapter.d.ts +11 -0
- package/dist_ts/classes.codexclientadapter.js +14 -2
- package/dist_ts/classes.controller.d.ts +175 -11
- package/dist_ts/classes.controller.js +1213 -173
- package/dist_ts/classes.controllerdevices.d.ts +2 -0
- package/dist_ts/classes.controllerdevices.js +6 -1
- package/dist_ts/classes.controllermanagement.d.ts +14 -4
- package/dist_ts/classes.controllermanagement.js +20 -2
- package/dist_ts/classes.gatewayclient.d.ts +115 -0
- package/dist_ts/classes.gatewayclient.js +336 -0
- package/dist_ts/classes.gatewayclientstore.d.ts +97 -0
- package/dist_ts/classes.gatewayclientstore.js +261 -0
- package/dist_ts/classes.inbox.d.ts +72 -0
- package/dist_ts/classes.inbox.js +231 -0
- package/dist_ts/classes.inferencerouter.d.ts +19 -0
- package/dist_ts/classes.inferencerouter.js +15 -3
- package/dist_ts/classes.inferenceservice.d.ts +9 -0
- package/dist_ts/classes.inferenceservice.js +28 -2
- package/dist_ts/classes.mcpclient.d.ts +4 -1
- package/dist_ts/classes.mcpclient.js +42 -6
- package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -1
- package/dist_ts/classes.mcpcontrollerhost.js +11 -1
- package/dist_ts/classes.mcptools.d.ts +3 -3
- package/dist_ts/classes.mcptools.js +38 -8
- package/dist_ts/classes.mcpvalidation.d.ts +5 -0
- package/dist_ts/classes.mcpvalidation.js +38 -2
- package/dist_ts/classes.nativesessions.d.ts +17 -4
- package/dist_ts/classes.nativesessions.js +41 -9
- package/dist_ts/classes.opencodeclient.d.ts +23 -2
- package/dist_ts/classes.opencodeclient.js +47 -3
- package/dist_ts/classes.proxycontrol.d.ts +11 -0
- package/dist_ts/classes.proxycontrol.js +7 -1
- package/dist_ts/classes.proxycontrolclient.d.ts +17 -0
- package/dist_ts/classes.proxycontrolclient.js +35 -1
- package/dist_ts/classes.proxydaemon.js +8 -1
- package/dist_ts/classes.proxymonitor.d.ts +7 -0
- package/dist_ts/classes.proxymonitor.js +13 -1
- package/dist_ts/classes.publishedset.d.ts +38 -0
- package/dist_ts/classes.publishedset.js +50 -0
- package/dist_ts/classes.sessionfeed.d.ts +3 -3
- package/dist_ts/classes.sessionfeed.js +18 -26
- package/dist_ts/classes.systemmetricssampler.d.ts +6 -0
- package/dist_ts/classes.systemmetricssampler.js +15 -3
- package/dist_ts/classes.ticketstore.d.ts +50 -3
- package/dist_ts/classes.ticketstore.js +45 -8
- package/dist_ts/classes.trustedproxysecrets.d.ts +2 -0
- package/dist_ts/classes.trustedproxysecrets.js +5 -1
- package/dist_ts/driver/classes.directreports.d.ts +14 -4
- package/dist_ts/driver/classes.directreports.js +25 -6
- package/dist_ts/driver/classes.driverservice.d.ts +44 -3
- package/dist_ts/driver/classes.driverservice.js +50 -16
- package/dist_ts/fleet/classes.claudeworkers.d.ts +21 -5
- package/dist_ts/fleet/classes.claudeworkers.js +142 -46
- package/dist_ts/fleet/classes.codexworkers.d.ts +16 -4
- package/dist_ts/fleet/classes.codexworkers.js +22 -5
- package/dist_ts/fleet/classes.workercommand.d.ts +6 -1
- package/dist_ts/fleet/classes.workercommand.js +15 -4
- package/dist_ts/fleet/classes.workers.d.ts +5 -1
- package/dist_ts/fleet/classes.workers.js +8 -2
- package/dist_ts/fleet/functions.unbounddrivers.js +2 -2
- package/dist_ts/fleet/functions.workervalidation.js +2 -2
- package/dist_ts/fleet/interfaces.workers.d.ts +21 -3
- package/dist_ts/fleet/interfaces.workers.js +1 -1
- package/dist_ts/functions.agentmessage.d.ts +3 -0
- package/dist_ts/functions.agentmessage.js +4 -1
- package/dist_ts/functions.controllermanagementsurface.d.ts +4 -0
- package/dist_ts/functions.controllermanagementsurface.js +15 -1
- package/dist_ts/functions.deviceapi.d.ts +151 -4
- package/dist_ts/functions.deviceapi.js +893 -38
- package/dist_ts/functions.fleetworkercli.d.ts +1 -1
- package/dist_ts/functions.fleetworkercli.js +11 -8
- package/dist_ts/functions.gatewaycli.d.ts +24 -0
- package/dist_ts/functions.gatewaycli.js +395 -0
- package/dist_ts/functions.gatewayroute.d.ts +135 -0
- package/dist_ts/functions.gatewayroute.js +366 -0
- package/dist_ts/functions.inferencecli.js +32 -1
- package/dist_ts/functions.inferencecliarguments.d.ts +8 -2
- package/dist_ts/functions.inferencecliarguments.js +31 -3
- package/dist_ts/functions.mcpfleetworkertools.js +2 -2
- package/dist_ts/functions.proxycapacity.d.ts +50 -0
- package/dist_ts/functions.proxycapacity.js +142 -0
- package/dist_ts/functions.proxycapacitycli.d.ts +30 -0
- package/dist_ts/functions.proxycapacitycli.js +65 -0
- package/dist_ts/functions.remotecli.d.ts +30 -3
- package/dist_ts/functions.remotecli.js +44 -18
- package/dist_ts/functions.ticketvalidation.js +11 -2
- package/dist_ts/interfaces.auth.d.ts +25 -4
- package/dist_ts/interfaces.auth.js +15 -1
- package/dist_ts/plugins.d.ts +5 -1
- package/dist_ts/plugins.js +10 -2
- package/dist_ts_authswitch/authority-contract.d.ts +25 -0
- package/dist_ts_authswitch/authority-contract.js +1 -1
- package/dist_ts_authswitch/authority-overview.d.ts +8 -0
- package/dist_ts_authswitch/authority-overview.js +17 -6
- package/dist_ts_authswitch/authority-placement.d.ts +20 -16
- package/dist_ts_authswitch/authority-placement.js +19 -26
- package/dist_ts_authswitch/authority-renewal.d.ts +34 -0
- package/dist_ts_authswitch/authority-renewal.js +56 -0
- package/dist_ts_authswitch/authority-usagelimit.d.ts +29 -0
- package/dist_ts_authswitch/authority-usagelimit.js +66 -2
- package/dist_ts_authswitch/authority-usagewindows.d.ts +6 -0
- package/dist_ts_authswitch/authority-usagewindows.js +15 -1
- package/dist_ts_authswitch/classes.authoritybroker.d.ts +8 -0
- package/dist_ts_authswitch/classes.authoritybroker.js +35 -2
- package/dist_ts_authswitch/classes.authoritycli.d.ts +1 -0
- package/dist_ts_authswitch/classes.authoritycli.js +44 -3
- package/dist_ts_authswitch/classes.authorityclient.d.ts +6 -1
- package/dist_ts_authswitch/classes.authorityclient.js +12 -4
- package/dist_ts_authswitch/classes.authoritydaemon.js +8 -1
- package/dist_ts_authswitch/classes.authoritydatabase.js +6 -2
- package/dist_ts_authswitch/classes.authoritymodels.d.ts +7 -0
- package/dist_ts_authswitch/classes.authoritymodels.js +21 -5
- package/dist_ts_interfaces/devices.d.ts +1012 -5
- package/dist_ts_interfaces/devices.js +68 -2
- package/dist_ts_interfaces/fleetworkers.d.ts +5 -3
- package/dist_ts_interfaces/gateway.d.ts +151 -0
- package/dist_ts_interfaces/gateway.js +66 -0
- package/dist_ts_interfaces/inbox.d.ts +234 -0
- package/dist_ts_interfaces/inbox.js +101 -0
- package/dist_ts_interfaces/index.d.ts +3 -0
- package/dist_ts_interfaces/index.js +4 -1
- package/dist_ts_interfaces/interfaces.d.ts +10 -3
- package/dist_ts_interfaces/interfaces.js +4 -2
- package/dist_ts_interfaces/management.d.ts +4 -4
- package/dist_ts_interfaces/management.js +3 -2
- package/dist_ts_interfaces/mcprequests.d.ts +48 -6
- package/dist_ts_interfaces/mcprequests.js +12 -1
- package/dist_ts_interfaces/mcpworkspacerequests.d.ts +4 -1
- package/dist_ts_interfaces/mcpworkspacerequests.js +1 -1
- package/dist_ts_interfaces/nativesessions.d.ts +16 -3
- package/dist_ts_interfaces/plugins.d.ts +2 -1
- package/dist_ts_interfaces/plugins.js +4 -2
- package/dist_ts_interfaces/proxycapacity.d.ts +99 -0
- package/dist_ts_interfaces/proxycapacity.js +74 -0
- package/dist_ts_interfaces/requests.accounts.d.ts +21 -0
- package/dist_ts_interfaces/requests.accounts.js +3 -1
- package/dist_ts_interfaces/requests.d.ts +3 -2
- package/dist_ts_interfaces/requests.js +1 -1
- package/docs/authswitch.md +20 -1
- package/package.json +6 -5
- package/readme.md +191 -31
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/aglapi/aglapisurface.document.ts +520 -16
- package/ts/aglapi/interfaces.ts +1 -0
- package/ts/classes.accountsactions.ts +30 -3
- package/ts/classes.authmodels.ts +22 -3
- package/ts/classes.authstore.ts +15 -1
- package/ts/classes.claudeharness.ts +27 -1
- package/ts/classes.cli.ts +7 -3
- package/ts/classes.codexclientadapter.ts +14 -1
- package/ts/classes.controller.ts +1428 -249
- package/ts/classes.controllerdevices.ts +6 -0
- package/ts/classes.controllermanagement.ts +40 -7
- package/ts/classes.gatewayclient.ts +401 -0
- package/ts/classes.gatewayclientstore.ts +272 -0
- package/ts/classes.inbox.ts +239 -0
- package/ts/classes.inferencerouter.ts +27 -2
- package/ts/classes.inferenceservice.ts +28 -1
- package/ts/classes.mcpclient.ts +42 -3
- package/ts/classes.mcpcontrollerhost.ts +15 -0
- package/ts/classes.mcptools.ts +42 -9
- package/ts/classes.mcpvalidation.ts +32 -1
- package/ts/classes.nativesessions.ts +50 -12
- package/ts/classes.opencodeclient.ts +55 -4
- package/ts/classes.proxycontrol.ts +16 -0
- package/ts/classes.proxycontrolclient.ts +30 -0
- package/ts/classes.proxydaemon.ts +8 -0
- package/ts/classes.proxymonitor.ts +12 -0
- package/ts/classes.publishedset.ts +56 -0
- package/ts/classes.sessionfeed.ts +17 -20
- package/ts/classes.systemmetricssampler.ts +13 -2
- package/ts/classes.ticketstore.ts +73 -12
- package/ts/classes.trustedproxysecrets.ts +5 -0
- package/ts/driver/classes.directreports.ts +25 -6
- package/ts/driver/classes.driverservice.ts +75 -14
- package/ts/fleet/classes.claudeworkers.ts +112 -39
- package/ts/fleet/classes.codexworkers.ts +21 -6
- package/ts/fleet/classes.workercommand.ts +14 -4
- package/ts/fleet/classes.workers.ts +9 -2
- package/ts/fleet/functions.unbounddrivers.ts +1 -1
- package/ts/fleet/functions.workervalidation.ts +1 -1
- package/ts/fleet/interfaces.workers.ts +20 -5
- package/ts/functions.agentmessage.ts +3 -0
- package/ts/functions.controllermanagementsurface.ts +15 -0
- package/ts/functions.deviceapi.ts +1071 -34
- package/ts/functions.fleetworkercli.ts +10 -7
- package/ts/functions.gatewaycli.ts +436 -0
- package/ts/functions.gatewayroute.ts +429 -0
- package/ts/functions.inferencecli.ts +26 -0
- package/ts/functions.inferencecliarguments.ts +30 -4
- package/ts/functions.mcpfleetworkertools.ts +1 -1
- package/ts/functions.proxycapacity.ts +191 -0
- package/ts/functions.proxycapacitycli.ts +104 -0
- package/ts/functions.remotecli.ts +56 -20
- package/ts/functions.ticketvalidation.ts +11 -1
- package/ts/interfaces.auth.ts +36 -4
- package/ts/plugins.ts +12 -0
- package/ts_authswitch/authority-contract.ts +20 -0
- package/ts_authswitch/authority-overview.ts +28 -6
- package/ts_authswitch/authority-placement.ts +27 -32
- package/ts_authswitch/authority-renewal.ts +64 -0
- package/ts_authswitch/authority-usagelimit.ts +84 -1
- package/ts_authswitch/authority-usagewindows.ts +13 -0
- package/ts_authswitch/classes.authoritybroker.ts +34 -1
- package/ts_authswitch/classes.authoritycli.ts +49 -2
- package/ts_authswitch/classes.authorityclient.ts +14 -4
- package/ts_authswitch/classes.authoritydaemon.ts +9 -1
- package/ts_authswitch/classes.authoritydatabase.ts +5 -1
- package/ts_authswitch/classes.authoritymodels.ts +23 -3
- package/ts_authswitch/native-contracts.md +21 -0
- package/ts_authswitch/readme.md +1 -1
- package/ts_interfaces/devices.schema.json +3573 -603
- package/ts_interfaces/devices.ts +1093 -4
- package/ts_interfaces/fleetworkers.ts +5 -3
- package/ts_interfaces/gateway.ts +242 -0
- package/ts_interfaces/inbox.ts +287 -0
- package/ts_interfaces/index.ts +3 -0
- package/ts_interfaces/interfaces.ts +9 -2
- package/ts_interfaces/management.ts +6 -4
- package/ts_interfaces/mcprequests.ts +61 -4
- package/ts_interfaces/mcpworkspacerequests.ts +4 -2
- package/ts_interfaces/nativesessions.ts +17 -3
- package/ts_interfaces/plugins.ts +3 -1
- package/ts_interfaces/proxycapacity.ts +162 -0
- package/ts_interfaces/requests.accounts.ts +20 -0
- package/ts_interfaces/requests.ts +4 -0
- package/ts_web/00_commitinfo_data.ts +1 -1
- package/ts_web/accounts.plugins.ts +4 -2
- package/ts_web/classes.accountsreadmodel.ts +33 -0
- package/ts_web/classes.browserpresentation.ts +19 -6
- package/ts_web/classes.inboxfeed.ts +329 -0
- package/ts_web/classes.nativesessionstate.ts +9 -23
- package/ts_web/elements.accounts.ts +121 -113
- package/ts_web/elements.configurationpane.ts +24 -37
- package/ts_web/elements.deployments.ts +66 -2
- package/ts_web/elements.devices.ts +4 -17
- package/ts_web/elements.flexlimitstrip.ts +21 -70
- package/ts_web/elements.harnesscontrollerapp.ts +198 -222
- package/ts_web/elements.inbox.ts +808 -0
- package/ts_web/functions.inbox.ts +95 -0
- package/ts_web/functions.sessioncards.ts +40 -0
- package/ts_web/plugins.ts +2 -0
package/readme.md
CHANGED
|
@@ -128,6 +128,7 @@ authswitch limits # one row per account and usage window
|
|
|
128
128
|
authswitch account list # the stored records, with the ids the account commands take
|
|
129
129
|
authswitch account set <account-id> --max-usage 80 # keep 20% of each usage window for use outside AGL
|
|
130
130
|
authswitch account set <account-id> --lapses-at 2026-11-01T00:00:00Z # a canceled subscription ends then
|
|
131
|
+
authswitch account set <account-id> --renews-at 2026-10-20T09:00:00Z # a Claude subscription renews monthly from then
|
|
131
132
|
authswitch account recheck <account-id> # read a Claude account now; a healthy read clears its payment problem
|
|
132
133
|
authswitch --help
|
|
133
134
|
```
|
|
@@ -182,6 +183,17 @@ From the date on it is **lapsed**: the proxy routes nothing to it again, its ses
|
|
|
182
183
|
`authswitch account preuse --all` leaves it out. `authswitch list`, `limits` and `account list` show the lifecycle and
|
|
183
184
|
the date.
|
|
184
185
|
|
|
186
|
+
A Claude sign-in's monthly renewal is the owner's to set as well: `authswitch account set <account-id> --renews-at
|
|
187
|
+
<date-time>` takes any date and time the subscription renewed or renews -- a past one too, since every renewal is a
|
|
188
|
+
calendar month after it, on its day clamped to the month's last day (January 31st renews on February 28th, or 29th, and
|
|
189
|
+
March 31st) at its time in UTC -- and `--clear-renewal` removes it; the account's Details in Settings → Accounts show
|
|
190
|
+
it as **Renews** and set or clear it (`controller.accounts.renewal`, audited `accounts.renewal`). AGL derives no renewal
|
|
191
|
+
from what Claude states. The proxy then spends first the usage a window would still hold at the next renewal (see
|
|
192
|
+
placement below); a renewal changes nothing else, and an account with a lapse date ignores it. Whether Claude resets
|
|
193
|
+
usage windows at a renewal is not known. `authswitch list`, `limits` and `account list` show the next renewal
|
|
194
|
+
(`renews in 9d 4h (set by the owner)`; `--json`: `renewal { at, source: 'manual' }`), and `agl proxy status` too.
|
|
195
|
+
Any other account is refused one.
|
|
196
|
+
|
|
185
197
|
Flex uses every OpenAI account the service holds with a login of its own: each is the Flex connection `flex:authority:<accountId>`, listed wherever Flex accounts are chosen. Flex keeps no login of its own.
|
|
186
198
|
|
|
187
199
|
A Flex session on a ChatGPT account runs through AGL's inference proxy, on the controller's lease of that one account's pool (proxy client `flex`, policy `accountIds: [<accountId>]`): the account the session chose serves it, and the proxy authenticates as the account, applies its maximum usage and limits, and counts every answer's tokens in the [token usage](#token-usage) under the client `flex`. At the account's limit the run reports the limit and its reset; it never moves to another account. The account's model catalog is read by the proxy on that account too. The Flex child is given only the proxy's address and the lease credential, never an account token. When the proxy is not running, a Flex request on a ChatGPT account fails with `INFERENCE_PROXY_UNAVAILABLE`; there is no direct route to ChatGPT. An account whose access ChatGPT keeps rejecting, or the accounts service cannot renew, fails with `PROVIDER_REAUTH_REQUIRED`, repaired by signing it in again in **Settings → Accounts**. Removing an account ends the controller's lease of it at once.
|
|
@@ -334,6 +346,7 @@ agl proxy service install [--port 4100]
|
|
|
334
346
|
agl proxy service enable
|
|
335
347
|
agl proxy service start
|
|
336
348
|
agl proxy status [--json]
|
|
349
|
+
agl proxy capacity --provider anthropic --wait --max-seconds 3600 # wait until the Claude pool has room for new work
|
|
337
350
|
agl proxy credential opencode --delivery file # the proxy keeps it in <AGL home>/proxy/credentials/opencode
|
|
338
351
|
agl proxy credential mytool --write ~/.config/mytool/agl-proxy.key
|
|
339
352
|
agl proxy credential codex --rotate
|
|
@@ -386,8 +399,8 @@ none shows as unavailable), so a pool no request used since the proxy started is
|
|
|
386
399
|
find it -- naming as of when, whether its
|
|
387
400
|
newest values came from provider answers or the account service's own read, whether a window is estimated since, and
|
|
388
401
|
whether the service's last read was rate-limited -- with its lifecycle (canceled with its lapse date, or lapsed), its
|
|
389
|
-
placement score and its rank for the next new session (`--json`: `lifecycle`,
|
|
390
|
-
`placementRank`, `lastResort`; an OpenAI or Anthropic API key shows its month in place of a maximum usage, as of when
|
|
402
|
+
placement score and its rank for the next new session, and the next renewal its owner set (`--json`: `lifecycle`,
|
|
403
|
+
`lapsesAt`, `renewal { at, source: 'manual' }` or null, `placementScore`, `placementRank`, `lastResort`; an OpenAI or Anthropic API key shows its month in place of a maximum usage, as of when
|
|
391
404
|
the account service read its spend: `available ($12.40 of $50.00 this month)` with what is left of its limit as its
|
|
392
405
|
headroom and placement score, `available ($3.20 this month, no spend limit)` with neither, `at its spend limit` (or
|
|
393
406
|
`held until its month ends`, for an answer that could not be priced) with the month's end -- the month counts the
|
|
@@ -403,6 +416,52 @@ session of a client that names no credential goes to (`nextPlacement`), the late
|
|
|
403
416
|
sessions placed or moved with why (`recentPlacements`), the count of usage reports handed to the account service and
|
|
404
417
|
of hand-overs that failed, and exits non-zero while the proxy is down.
|
|
405
418
|
|
|
419
|
+
#### Pool capacity
|
|
420
|
+
|
|
421
|
+
`agl proxy capacity` answers whether a pool has room for new work, as one answer from the proxy, judged on the same
|
|
422
|
+
readings as `agl proxy status` -- for a script that starts confined runs (`agl proxy confined run`) only while a pool can
|
|
423
|
+
take them. The MCP tool `proxy_capacity` (`agl mcp`) gives the same answer to every caller, through the controller; it
|
|
424
|
+
never waits.
|
|
425
|
+
|
|
426
|
+
```sh
|
|
427
|
+
agl proxy capacity [--provider anthropic|openai] [--min-headroom 15] [--json]
|
|
428
|
+
agl proxy capacity --provider openai --min-headroom 40 --wait [--max-seconds 1800]
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
- **Members.** A pool counts its subscription sign-ins that have not lapsed and whose held reading states a counted plan,
|
|
432
|
+
however old the reading; API keys never count:
|
|
433
|
+
|
|
434
|
+
| Pool | Counts |
|
|
435
|
+
| --- | --- |
|
|
436
|
+
| `anthropic` (Claude accounts) | plan `max` only (both Max tiers: Anthropic names them `claude_max`) |
|
|
437
|
+
| `openai` (ChatGPT accounts) | every plan but `free` |
|
|
438
|
+
|
|
439
|
+
- **Headroom.** A member that takes work now adds its headroom: how far its fullest counted window is below its maximum
|
|
440
|
+
usage (100 when unset), the same `headroom` `agl proxy status` shows. A member that takes no work now -- cooling down
|
|
441
|
+
after a provider 429, at its limit or reserve, refused by its provider, or unavailable (a stale reading, a sign-in or
|
|
442
|
+
payment problem) -- adds 0. The pool's `room` is the members' headroom summed.
|
|
443
|
+
- **Binding window and growth.** Each member names the window its headroom is bound by (`binding`) and when that headroom
|
|
444
|
+
next grows (`growsAt`, to `growsTo`): the binding window's reset -- a five-hour window that binds grows long before a
|
|
445
|
+
weekly window that does not -- or the moment the member takes work again (its 429 rest's end, its provider's retry time,
|
|
446
|
+
the reset of the windows its limit is held by). `null` when nothing can grow it or the moment is unknown (a stale
|
|
447
|
+
reading names `recheckAt`, when the account service reads it next; a sign-in or payment problem names none).
|
|
448
|
+
- **Verdict.** `open` when `room` reaches the minimum (`--min-headroom`, any whole percent, 15 unless given) and no provider
|
|
449
|
+
429 hit a member within five minutes; the proxy keeps that record in memory from its start (`observedSince`), so for
|
|
450
|
+
its first five minutes it cannot say none came. Otherwise `wait` with a `reason` -- `room` (too little), `provider-429`
|
|
451
|
+
(`last429At` within five minutes) or `quiet-unobserved` (the proxy started less than five minutes ago) -- and `until`
|
|
452
|
+
with `seconds`: the first moment the members' readings foresee enough room once the pool is quiet. Usage spent meanwhile
|
|
453
|
+
is not foreseen, so that moment is the earliest the room can be there; with no such moment foreseen (a minimum beyond
|
|
454
|
+
every member's whole headroom, a pool without members), `until` and `seconds` are `null`.
|
|
455
|
+
|
|
456
|
+
The text names each member by the first 12 characters of its account id, never its label or email; `--json` and the MCP
|
|
457
|
+
tool answer `{ at, observedSince, pools: [{ provider, minHeadroom, room, members: [{ accountId, plan, state, headroom,
|
|
458
|
+
binding: { name, durationSeconds, usedPercent, estimated, resetAt }, growsAt, growsTo, recheckAt }], last429At, verdict }]
|
|
459
|
+
}`. It exits 0 when every pool it reports is open, 2 when one waits, and 1 when the proxy is down, runs an older AGL (it
|
|
460
|
+
names the release and the restart onto the installed one, as `agl proxy status` does) or cannot reach its account
|
|
461
|
+
service. `--wait` (with `--provider`) asks again after the pool's `seconds`, at most a minute apart, until the pool is
|
|
462
|
+
open (0) or `--max-seconds` ran out (2), and prints the last answer; without `--max-seconds` it waits as long as it
|
|
463
|
+
takes.
|
|
464
|
+
|
|
406
465
|
#### Usage reads
|
|
407
466
|
|
|
408
467
|
The accounts service reads each account's usage from the provider once every 10 minutes and no more often, on its
|
|
@@ -480,12 +539,12 @@ listener, a Unix socket that serves confined runs alone (see [Confined container
|
|
|
480
539
|
The router places a new session by how much usage each account can spend per hour, and keeps that account for the
|
|
481
540
|
session: the prompt cache always comes first, so a session is never placed again while its account can serve it. An
|
|
482
541
|
account's placement score is the least, over the windows its limit counts, of the headroom left below its threshold
|
|
483
|
-
divided by the hours until that window resets -- or until the account lapses, if that comes first
|
|
484
|
-
hour; a window whose reset passed but was not read again counts to the end of its next period
|
|
542
|
+
divided by the hours until that window resets -- or until the account lapses or renews, if that comes first (a renewal
|
|
543
|
+
counts only on an account without a lapse date) -- and at least one hour; a window whose reset passed but was not read again counts to the end of its next period
|
|
485
544
|
(`ts_authswitch/authority-placement.ts`). A new session goes to the account with the highest score per request it
|
|
486
545
|
serves now (`score / (1 + in flight)`), so new sessions spread over the accounts in proportion to what each can spend:
|
|
487
|
-
quota that resets soon, or is lost when the account lapses, is used first
|
|
488
|
-
spared. An account that lapses within a day comes after every other, and an account without a counted window after
|
|
546
|
+
quota that resets soon, or is lost when the account lapses, is used first -- as is quota an account would still hold at
|
|
547
|
+
its renewal, when its window resets after it -- and an account that resets in days is spared. An account that lapses within a day comes after every other, and an account without a counted window after
|
|
489
548
|
every scored one. Within the client's pool, only current quota exhaustion, a definite provider HTTP 429 before
|
|
490
549
|
forwarding output, the account lapsing or leaving the pool, or a Claude account taking no request for a reason of its
|
|
491
550
|
own (below) permits moving the session to another eligible account.
|
|
@@ -1063,12 +1122,12 @@ Each card is one of three kinds, named by its `mode`, and carries the server's n
|
|
|
1063
1122
|
|
|
1064
1123
|
## MCP Server
|
|
1065
1124
|
|
|
1066
|
-
The installed `agl` command includes a unified stdio MCP server that combines
|
|
1125
|
+
The installed `agl` command includes a unified stdio MCP server that combines 97 tools on one connection:
|
|
1067
1126
|
|
|
1068
1127
|
- Nine CrossHarness tools for explicit OpenCode and Codex harness-server connections.
|
|
1069
1128
|
- Six system inspection and reclaim-planning tools.
|
|
1070
1129
|
- Thirteen durable `tstask` tools.
|
|
1071
|
-
- Sixty-
|
|
1130
|
+
- Sixty-nine AGL controller tools for projects, task discovery, control and messaging, models, scratchpads, resource lifecycle and attachment, managed jobs, driver fleet operations, the shared project ticket board, the inference proxy's pool capacity, and challenge-only worker enrollment.
|
|
1072
1131
|
|
|
1073
1132
|
Configure an MCP host to execute:
|
|
1074
1133
|
|
|
@@ -1076,7 +1135,7 @@ Configure an MCP host to execute:
|
|
|
1076
1135
|
agl mcp --port 4097
|
|
1077
1136
|
```
|
|
1078
1137
|
|
|
1079
|
-
`--port` takes precedence over `AGL_CONTROLLER_PORT`; otherwise the controller port defaults to `4097`. `agl mcp` starts and exposes all
|
|
1138
|
+
`--port` takes precedence over `AGL_CONTROLLER_PORT`; otherwise the controller port defaults to `4097`. `agl mcp` starts and exposes all 97 tools without a running AGL controller. Only the AGL controller tools require a ready controller on the configured port; the CrossHarness, system, and durable-task tools remain available independently. `agl mcp` requires Linux x64 with Node.js `>=24.12.0 <27`.
|
|
1080
1139
|
|
|
1081
1140
|
On supported systems, a ready controller publishes a process- and generation-fenced private loopback endpoint under `$AGL_HOME/runtime/mcp`. The descriptor and bearer token remain owner-only runtime state. They are discovered and verified automatically; do not copy them into MCP configuration. The endpoint accepts only the explicitly registered, bounded AGL methods and is removed before controller shutdown proceeds.
|
|
1082
1141
|
|
|
@@ -1098,20 +1157,24 @@ A caller is one of three subjects:
|
|
|
1098
1157
|
- **Runtime** — a shared harness server. OpenCode runs one server per controller and addresses MCP servers per directory rather than per task, so an OpenCode-launched caller is identified as that runtime, not as one chat: it may act for its own tasks in the project named in each request. This is deliberately coarser than a terminal subject, and narrowing it requires per-task MCP servers upstream in OpenCode.
|
|
1099
1158
|
- **Task** — a chat AGL manages as a task, acting only for that task in that task's project. The subject exists in the model and is enforced everywhere, but **no task credential is issued yet**: AGL cannot stamp a per-task credential into a harness that shares one server across tasks. Until OpenCode can carry a task id into the MCP server it launches, OpenCode chats act through the runtime subject.
|
|
1100
1159
|
|
|
1101
|
-
Reading is open to every caller that holds the descriptor token, identified or not: `controller_status`, `projects_list`, `sessions_list`, `context_resolve`, `models_list`, `session_read` and `session_scratchpad_read` behave exactly as before. That keeps the cross-harness workflow intact, where a chat running outside any AGL terminal — and therefore without an AGL identity — inspects AGL-managed tasks. `resources_list` shows the unattached project resources to such a caller.
|
|
1160
|
+
Reading is open to every caller that holds the descriptor token, identified or not: `controller_status`, `projects_list`, `sessions_list`, `context_resolve`, `models_list`, `session_read` and `session_scratchpad_read` behave exactly as before, and `proxy_capacity` answers the inference proxy's pool capacity (see [Pool capacity](#pool-capacity)), naming accounts by id alone. That keeps the cross-harness workflow intact, where a chat running outside any AGL terminal — and therefore without an AGL identity — inspects AGL-managed tasks. `resources_list` shows the unattached project resources to such a caller.
|
|
1102
1161
|
|
|
1103
1162
|
Writing is not open. Task mutations (`session_send`, `session_scratchpad_update`, `session_model_set`, `session_rename`, `session_archive`, `session_stop`) require the calling chat to be the task itself, or its shared harness runtime; a terminal caller owns no task and an unidentified host owns nothing. Resource mutations, `project_add`, `session_create` and `browser_action` require an AGL identity as well, and so does every job tool: jobs belong to a project, and any identified caller of that project may inspect, wait for or stop them. Every caller must still run as the controller's local OS user; a remote MCP process cannot access this local endpoint without a separate authenticated transport.
|
|
1104
1163
|
|
|
1105
1164
|
One agent messages another task with `session_message`, and any caller holding the descriptor token may, identified or not: a chat running outside AGL can consult an AGL-managed task. The target is an active root task of the project named in the request; archived tasks and child conversations take no messages. The message is not the task's own input, so the controller puts a header in front of it that the receiving model and every client showing the native transcript read — `[Agent message via AGL from "<sender>" — <subject>; not from the user]`, a blank line, then the text. The sender is the label the caller declares (1 to 64 printable characters, required). The subject is what the controller proved about the caller: `task <harness>:"<title>"`, `terminal "<title>"`, `OpenCode runtime`, or `unidentified local caller (self-declared sender)`; titles are quoted with control and separator characters removed, so neither a label nor a title can forge that line. The caller chooses the delivery: `steer` into the running turn, `next-turn` or `queue` (see [Steering and pending messages](#steering-and-pending-messages)), and the result names how the message was delivered (`delivery`, with `turnId` when a Codex turn took it). OpenCode cannot be steered, and `expectedTurnId` applies only to a Codex steer (`DELIVERY_UNSUPPORTED` otherwise). A Codex steer names the turn it is for in `expectedTurnId`, the `codexActivity.turnId` of `session_read`: it is required to steer a turn another Codex client runs and optional for AGL's own turn, and a message for any other turn, or for one that ended, is refused before anything is sent (`TURN_ENDED`, `CONCURRENT_CHANGE`). A message waiting in a conversation says who sent it (`IControllerPendingPrompt.sender`), and every request that reaches the controller, refusals included, is audited as `session.message` with the caller and the declared sender (`senderLabel`); a request that fails the tool's schema is rejected before that. Text is limited to 16 KiB, and one caller may send one task at most 6 messages a minute and 60 an hour (`MESSAGE_RATE_LIMITED`); unidentified callers share one such budget per task. The per-conversation and controller-wide message limits apply as well. **Settings → Projects** has an **Agent messages** switch per project, on by default (`controller.project.agentmessages.update`); turned off, the project's tasks refuse agent messages with `AGENT_MESSAGES_DISABLED`.
|
|
1106
1165
|
|
|
1166
|
+
**Claude Code sessions outside AGL.** A Claude Code session that runs outside AGL, such as a driver started as a background job with `claude --bg`, is reached through the same tools when it belongs to the project: only a session of the host's own Claude Code home (`claude agents --json --all`, as the session list reads it; never a fleet profile's home) whose directory is the project folder itself, exactly, and that no AGL conversation of another project records. `sessions_list` names such sessions in `nativeSessions`, apart from the tasks: running ones first, all of them, then the newest 50 settled ones (`nativeSessionsTruncated` when more may exist); `nativeSessionsError` says why the inventory could not be read. Each session either names why it takes no message (`readOnly`: `running`, `unaddressable`, `notBackgroundJob`, `fleetWorker`, `jobFailed`, `jobHeld`, `directoryMissing`) or says how a background job takes one (`jobDelivery`). `session_read` with `{ harnessId: "claude", nativeId }` answers `kind: "native"`: the session, its newest transcript page and its scratchpad; `context_resolve` answers it as `nativeSession`. Neither records the session anywhere or resumes it.
|
|
1167
|
+
|
|
1168
|
+
`session_message` reaches only a background job, through Claude Code itself, with the header above naming the sender and the proven caller, whatever `delivery` asks for: a settled job (done, blocked or stopped) is woken with the message (`claude --bg --resume`; the result says `native: "wake"`, `delivery: "next-turn"`), and a running job gets it in its inbox through Claude Code's own SendMessage, run by a relay restricted to exactly the tools it needs (`native: "inbox"`, `delivery: "queue"`: accepted and queued there, not yet read). SendMessage addresses a running job by its session name, so a job without a name, or with one another running session of the host's or a fleet profile's home shares, is `unaddressable`. A running interactive session, a job Claude Code is still handing to its process, a failed or held job, a fleet worker's session and a session that is no background job take no message (`SESSION_READ_ONLY`; `session_read` names the reason). `expectedTurnId` is refused (`DELIVERY_UNSUPPORTED`). A held message, an unconfirmed wake and any send that may have reached the job are `OUTCOME_UNKNOWN` and never resent; the project's **Agent messages** switch and the per-task rate apply, and the request is audited as `session.message` with the sender and the send as `session.send`. The owner's own composer reaches the same jobs from the session list's native view.
|
|
1169
|
+
|
|
1107
1170
|
Agent messages are attribution and the owner's control, not a security boundary: any process of the same OS user can read the descriptor or reach a Codex app-server socket directly. The ownership rule for task mutations keeps an agent from acting *as* another task through the sanctioned tools; `session_message` lets it speak *to* one, labelled as such.
|
|
1108
1171
|
|
|
1109
1172
|
| Tools | Behavior |
|
|
1110
1173
|
| --- | --- |
|
|
1111
1174
|
| `controller_status`, `projects_list`, `project_add` | Inspect the controller and register existing project directories. |
|
|
1112
|
-
| `context_resolve`, `sessions_list` | Resolve an exact canonical project folder and discover its nonarchived native root tasks from the configured OpenCode, Flex, and Codex connections. |
|
|
1175
|
+
| `context_resolve`, `sessions_list` | Resolve an exact canonical project folder and discover its nonarchived native root tasks from the configured OpenCode, Flex, and Codex connections and AGL's own Claude Code conversations, plus, apart from them, the Claude Code sessions outside AGL that run in that folder (`nativeSessions`, see below). |
|
|
1113
1176
|
| `session_read`, `session_send` | Read a task, or submit text through the existing harness connection. Reading is open to any caller; sending requires the calling chat to own the task. |
|
|
1114
|
-
| `session_message` | Deliver an attributed message to another task of the project: steered into its running turn, as the next turn's input, or queued. Open to any caller unless the owner turned agent messages off for the project. |
|
|
1177
|
+
| `session_message` | Deliver an attributed message to another task of the project: steered into its running turn, as the next turn's input, or queued; or to a Claude Code background job outside AGL in the project folder, woken while it is settled or into its inbox while it runs. Open to any caller unless the owner turned agent messages off for the project. |
|
|
1115
1178
|
| `models_list`, `session_model_set` | Inspect available models and reasoning variants, the model each harness's new conversations run on (`defaults`, with a stored default the harness no longer offers named as `unavailableSetting`) and the order AGL's account placement takes Flex accounts in (`flexAccountPlacement`); save the model used by subsequent AGL submissions. Pass project and task IDs to use a particular Codex task's connection. Saving requires the calling chat to own the task. |
|
|
1116
1179
|
| `session_create`, `session_rename`, `session_archive`, `session_stop` | Create or rename a task, archive idle work, or interrupt a running task. Creation does not send a prompt and requires an AGL identity; the rest require the calling chat to own the task. |
|
|
1117
1180
|
| `session_scratchpad_read`, `session_scratchpad_update` | Read or revise shared task notes. Reading is open to any caller; revising requires the calling chat to own the task. |
|
|
@@ -1234,7 +1297,8 @@ whose Claude Code home holds it (or `none`) and the one command that adopts it o
|
|
|
1234
1297
|
`agl fleet worker adopt NAME --native-id ID --cwd DIR --profile PROFILE --ticket TICKET`, with
|
|
1235
1298
|
the job's name, directory and profile filled in. A job in the host's own Claude Code home also
|
|
1236
1299
|
carries `nativeMessage`, the `agl fleet worker native-message ID --message-file FILE --sender LABEL`
|
|
1237
|
-
command that wakes it once it settles
|
|
1300
|
+
command that wakes it once it settles, or reaches its inbox while it runs under a session name of its
|
|
1301
|
+
own; a job in a fleet profile's home has none, since
|
|
1238
1302
|
native-message refuses it. A job that an archived worker still binds is listed with
|
|
1239
1303
|
`adoptable: false` and that worker's name, and neither command, since a session stays bound to any worker.
|
|
1240
1304
|
The search reads each inventory and the comments for at most 20 seconds; what it could not read
|
|
@@ -1477,7 +1541,12 @@ authoritative for linked-worktree and other trust checks. A start that exits non
|
|
|
1477
1541
|
refused: the worker is `stopped` without a dispatch fence and can be archived. Any other
|
|
1478
1542
|
failed start keeps the fence. Relays group recipients by their observed permission mode (any
|
|
1479
1543
|
mode Claude Code records: `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`
|
|
1480
|
-
or `manual`), close stdin and
|
|
1544
|
+
or `manual`), close stdin and run with exactly the tools SendMessage, Read and ToolSearch:
|
|
1545
|
+
`--tools=SendMessage,Read,ToolSearch` and `--strict-mcp-config` (no configured MCP server) restrict
|
|
1546
|
+
them in every mode, bypassPermissions included, and `--allowedTools=SendMessage,Read,ToolSearch`
|
|
1547
|
+
pre-approves them. A relay whose `system`/`init` record lists any other tool, or none, is stopped
|
|
1548
|
+
as soon as it prints that record, before Claude Code calls the model, and fails without a dispatch
|
|
1549
|
+
fence; one that printed more than that before it was refused keeps the fence. A
|
|
1481
1550
|
relay addresses each recipient by its session name from `agents --json --all`, which is how SendMessage
|
|
1482
1551
|
resolves a recipient; a name that another live session shares refuses before anything is sent.
|
|
1483
1552
|
Each exact native tool receipt must prove queued delivery (`success: true` with a `msg_id`);
|
|
@@ -1749,7 +1818,7 @@ browser reaches it through three protected requests:
|
|
|
1749
1818
|
- `controller.driver.seen` resets that unread count. Every status change is pushed as a
|
|
1750
1819
|
`driver.changed` event.
|
|
1751
1820
|
|
|
1752
|
-
In the web UI the **Driver** button leads the top bar, before Terminals, Browsers, Workspaces,
|
|
1821
|
+
In the web UI the **Driver** button leads the top bar, before Inbox, Terminals, Browsers, Workspaces,
|
|
1753
1822
|
Board and Settings. It opens the driver in the main area as a full conversation: transcript,
|
|
1754
1823
|
composer and details, attached resources included. Its badge shows the activity as a dot,
|
|
1755
1824
|
pulsing while the driver works, in the warning colour when it needs input and the error colour
|
|
@@ -1794,9 +1863,11 @@ and is not sent once that turn has ended. The usual agent message limits apply:
|
|
|
1794
1863
|
the per-task rate. The report is the owner's and reached outside every project, so no project's
|
|
1795
1864
|
**Agent messages** switch applies to it. While a turn runs the modal reads again every 3
|
|
1796
1865
|
seconds. A report that is a Claude Code session the fleet does not run opens read-only, without
|
|
1797
|
-
transcript or steer box:
|
|
1798
|
-
|
|
1799
|
-
|
|
1866
|
+
transcript or steer box: the report's read and message paths have no Claude Code channel yet, so
|
|
1867
|
+
the modal says to adopt the session with a relaunch once it has settled. Elsewhere AGL does reach
|
|
1868
|
+
such a session through Claude Code itself: it wakes a settled background job, puts a message into a
|
|
1869
|
+
running job's inbox through Claude Code's own SendMessage, and resumes another settled session in
|
|
1870
|
+
its own Claude Code (see [Sessions outside every project](#sessions-outside-every-project)).
|
|
1800
1871
|
Leaving the driver closes the modal.
|
|
1801
1872
|
|
|
1802
1873
|
A fleet worker opened from the session list shows the same transcript in the main area; its
|
|
@@ -2456,7 +2527,9 @@ map directly to these methods; unwrap the named response field.
|
|
|
2456
2527
|
|
|
2457
2528
|
`viewer` is the person the controller identifies the caller as, the `id` its tickets name in
|
|
2458
2529
|
`createdBy` and `assignee`: the board's "assigned to me" compares against it. The columns carry
|
|
2459
|
-
display titles (`Backlog` … `Released`) next to their fixed ids.
|
|
2530
|
+
display titles (`Backlog` … `Released`) next to their fixed ids. `controller.ticket.comment`,
|
|
2531
|
+
`controller.ticket.ask` and `controller.ticket.move` are audited as `ticket.comment`, `ticket.ask`
|
|
2532
|
+
and `ticket.move` (the envelope alone), as a paired device's comments, questions and moves are.
|
|
2460
2533
|
|
|
2461
2534
|
`id` equals `key`. Every returned ticket carries its numeric `revision`, advanced by every
|
|
2462
2535
|
change to that ticket (including comments, links and move/reorder changes). Existing stored
|
|
@@ -2634,6 +2707,59 @@ ship from git; **Plan hotfix** turns an urgent bug found in a running version in
|
|
|
2634
2707
|
release plan, for the next version unless one is named. The view follows
|
|
2635
2708
|
`deployments.changed`.
|
|
2636
2709
|
|
|
2710
|
+
### Inbox
|
|
2711
|
+
|
|
2712
|
+
The controller keeps one list of what waits for the owner, and the browser and paired devices read the same
|
|
2713
|
+
list: an answer in any of them removes the item everywhere, because every item is read from the component that
|
|
2714
|
+
owns it and nothing about the Inbox is stored. It holds, in this order, the oldest first within each kind:
|
|
2715
|
+
|
|
2716
|
+
- session prompts: a permission, a question or an MCP form a harness holds for a conversation, for a direct child
|
|
2717
|
+
(an OpenCode subagent) of one, for a native session AGL runs a turn in, or for the driver's own session; a
|
|
2718
|
+
permission the owner's auto-accept answers waits for nobody and is not listed;
|
|
2719
|
+
- a wait a harness shows in its own client (Codex's approval, Claude Code's `requires_action`), listed as
|
|
2720
|
+
information only: it names the session and the host, and is answered in that client;
|
|
2721
|
+
- the driver's `needs input:` turn: the line and the transcript entry it ends, answered in the Driver view;
|
|
2722
|
+
- the owner's go's: a deploy plan's question (what the target runs, what it deploys, when, and what ships with it)
|
|
2723
|
+
and the question of a maintenance window the driver proposed; only the owner's answer is a go;
|
|
2724
|
+
- ticket questions that are open on a ticket that is not done, except those the owner asked.
|
|
2725
|
+
|
|
2726
|
+
Each item names where it lives and how it is answered, through the request its owner already takes: a session
|
|
2727
|
+
prompt through the session's reply (`controller.permission.reply`, `.question.reply`, `.elicitation.reply`, the
|
|
2728
|
+
`controller.nativesession.*.reply` of a native session, or a direct child's `controller.session.child.*.reply`),
|
|
2729
|
+
a go or a ticket question through `controller.ticket.answer`. A question takes one answer: the identical answer
|
|
2730
|
+
again is confirmed, a different one is refused (`ticket_question_answered`). A client never sends an answer again
|
|
2731
|
+
on its own when its outcome is unknown; the next list says whether the item still waits. `controller.ticket.answer`
|
|
2732
|
+
is audited as `ticket.answer`.
|
|
2733
|
+
|
|
2734
|
+
`controller.inbox.list` answers the list (`epoch`, `revision`, `items`, `total`, `limited`), and `inbox.changed`
|
|
2735
|
+
events carry its changes as deltas: the items that came or changed, the ids that left, every listed id in order
|
|
2736
|
+
(`order`) and the count; a client applies a delta only on its epoch at the next revision, and lists again
|
|
2737
|
+
otherwise and on `reset`. The controller sorts; clients show its order. An item whose JSON is over 64 KiB keeps
|
|
2738
|
+
its place without its payload (`omitted`) and is answered only where it lives; nothing is cut short. The list
|
|
2739
|
+
holds at most 200 items and 2 MiB; `total` counts them all and `limited` says some were left out. The filter
|
|
2740
|
+
chips are All, Sessions (session prompts, native waits, the driver), Board (ticket questions) and Deploys (go's)
|
|
2741
|
+
(`controllerInboxChipKinds`); `controllerInboxItemShown` filters by chip and search words.
|
|
2742
|
+
|
|
2743
|
+
The web app's top bar has an **Inbox** button between Driver and Terminals, with a badge in the
|
|
2744
|
+
warning colour counting what waits. It shows the Inbox in the main pane as Board shows the board:
|
|
2745
|
+
the list on the left (each item's kind, how long it waits, what is asked and where it lives), the
|
|
2746
|
+
chips All, Sessions, Board and Deploys with their counts, a search over the list in the browser,
|
|
2747
|
+
and the selected item beside the list, answered in place with the cards the conversation and the
|
|
2748
|
+
board use: a permission, a question, an MCP form, a ticket question, and a go with what the target
|
|
2749
|
+
runs, what it deploys, when and what ships with it, answered with the plan's own options (only the
|
|
2750
|
+
owner gives a go). **Open in session** and **Open ticket** go to the item's home; answering moves
|
|
2751
|
+
to the next item, and **Skip** (**Not now** on a go) only moves on and stores nothing. An answer
|
|
2752
|
+
from another browser or the phone takes the item out at once (`inbox.changed`). The driver's turn
|
|
2753
|
+
shows its `needs input:` line with **Open Driver**; a wait a harness shows in its own client says
|
|
2754
|
+
where it waits and that it is answered there; an item listed without its payload is answered in
|
|
2755
|
+
its session view or ticket. A question takes one answer: when another client answered first, the
|
|
2756
|
+
card keeps what the owner chose and shows the answer that stands until the owner moves on. An
|
|
2757
|
+
answer whose outcome is unknown (a lost connection, a time-out, the controller's `outcome_unknown`)
|
|
2758
|
+
keeps the card locked with the owner's draft, says so, and is never sent again on its own;
|
|
2759
|
+
**Check again** lists the Inbox again (and reads a ticket's question), and an item that still waits
|
|
2760
|
+
at its owner says so and takes an answer again; a check that cannot be made (the connection is down
|
|
2761
|
+
or the list cannot be read) leaves the card locked and says the check failed too. With nothing waiting the view says "Nothing waits for you".
|
|
2762
|
+
|
|
2637
2763
|
### Configuration: one master for every harness
|
|
2638
2764
|
|
|
2639
2765
|
AGL keeps one **master configuration** and projects it onto Claude Code, Codex, OpenCode and Flex. The master is harness-agnostic and versioned in AGL's database; you never edit a harness's native files by hand again.
|
|
@@ -2754,7 +2880,9 @@ outside press dismiss the panel; the panel updates without rerendering the
|
|
|
2754
2880
|
workspace. The controller samples CPU, memory and network rates through a bounded
|
|
2755
2881
|
`smartsystem` worker. Initial network discovery and later topology rescans run
|
|
2756
2882
|
outside the controller event loop, keeping terminal echo and browser input
|
|
2757
|
-
responsive while metrics are collected. The controller owns
|
|
2883
|
+
responsive while metrics are collected. The controller owns those workers. On stop it lets each one
|
|
2884
|
+
finish its probe (up to 10 seconds) and exit by itself, so no probe's child process outlives the
|
|
2885
|
+
controller; a worker that hangs or fails makes the stop report it by name.
|
|
2758
2886
|
|
|
2759
2887
|
Clicking one footer reading opens only that reading's one-hour graph in a compact
|
|
2760
2888
|
anchored panel; network receive and transmit remain paired. **Stats** continues to
|
|
@@ -2873,12 +3001,12 @@ Its composer sends through the runtime that owns the session (`controller.native
|
|
|
2873
3001
|
|
|
2874
3002
|
- **Codex** threads take the message through the host's shared Codex server, steered into a running turn or else starting the next one.
|
|
2875
3003
|
- **Claude Code** sessions take a message only once they settled; AGL then resumes the session in its own directory. While Claude Code works in it, the view is a live read-only transcript and the composer unlocks once it settles. A permission reply grants once.
|
|
2876
|
-
- **Claude Code background jobs** (`claude --bg`, listed by `claude agents`) stay their session's owner
|
|
2877
|
-
- **From an agent or a script**, a job no fleet worker binds is reached the same way with `agl fleet worker native-message <session id or 8+ character prefix> --message-file FILE --sender LABEL` or the MCP tool `fleet_worker_native_message`, which hold the local-owner capability. It goes through the same send, under the same session lock and audit (`session.send`), but only to a background job: the text arrives behind the `session_message` header (`[Agent message via AGL from "LABEL" — the local AGL CLI of OS user "…", with the owner capability; not from the user]`), never as the job's user. A running or held job is refused with its reason and the adopt command to use once it settles, a failed job with the note that it takes no wake and its adopt command, and a fleet worker's session, a job in a fleet profile's home and a project conversation with their reason; an ambiguous prefix is refused. The receipt (`job.nativeMessage`) says it was a native wake,
|
|
3004
|
+
- **Claude Code background jobs** (`claude --bg`, listed by `claude agents`) stay their session's owner. A running job takes the message in its inbox through Claude Code's own SendMessage, run by the fleet's relay with exactly the tools it needs, addressed by the job's session name, which no other running session of the host's or a fleet profile's home may share (otherwise it stays read-only as `unaddressable` until it settles); the message arrives headed as the owner's agent message (`[Agent message via AGL from "Owner" — the owner, in AGL's native session view; not from the user]`, or `on a paired AGL device`), since a peer message names no sender of its own, and is accepted and queued there, not yet read. A held message or an unproven receipt fails the send without a resend. A message to a stopped, done or blocked job wakes that job through Claude Code itself, as `claude --bg --resume <session id> <message>` with no options, in the job's directory; AGL's own Claude Code never resumes a job's conversation. The send succeeds only when Claude Code confirms the wake under the job's own id and its inventory then shows that job live (it waits up to 30 s while Claude Code hands the job to its process) or already finished. A copy it started instead, or a message it saved for the job's next start, fails the send with what Claude Code printed: the message may have reached Claude Code, so AGL never resends it; inspect the job before sending again. A message that starts with `-` is refused, since Claude Code would read it as an option. Attachments of a job's message stay until the daily sweep, because Claude Code does not report when the woken turn ends.
|
|
3005
|
+
- **From an agent or a script**, a job no fleet worker binds is reached the same way with `agl fleet worker native-message <session id or 8+ character prefix> --message-file FILE --sender LABEL` or the MCP tool `fleet_worker_native_message`, which hold the local-owner capability, or, for a job in a project's folder, with MCP `session_message` (see [Caller identity](#caller-identity)). It goes through the same send, under the same session lock and audit (`session.send`), but only to a background job: the text arrives behind the `session_message` header (`[Agent message via AGL from "LABEL" — the local AGL CLI of OS user "…", with the owner capability; not from the user]`), never as the job's user. A running job with a session name of its own takes it in its inbox. A running job SendMessage cannot address, one Claude Code is still handing to its process, or a held job is refused with its reason and the adopt command to use once it settles, a failed job with the note that it takes no wake and its adopt command, and a fleet worker's session, a job in a fleet profile's home and a project conversation with their reason; an ambiguous prefix is refused. The receipt (`job.nativeMessage`) says whether it was a native wake (`native-wake`) or a message into the running job's inbox (`native-inbox`, accepted and queued, not yet read); neither holds a dispatch fence, writes a ticket comment or observes the turn that reads it, and the receipt names the command that adopts the job. `agl fleet worker message` never falls back to it: an id no worker binds is refused with the native-message command to run instead.
|
|
2878
3006
|
|
|
2879
3007
|
The attachments of any other native send are deleted once the turn that read them ends.
|
|
2880
3008
|
|
|
2881
|
-
A session AGL may not write to stays readable and names the reason above the transcript: another process runs it (AGL never becomes a second writer), it lives in a fleet profile's own Claude Code home, its directory no longer exists, an AGL project conversation records it (that conversation sends to it), a fleet worker runs it (the worker's view steers it), it is a failed background job (inspect it with `claude logs <id>` or `claude attach <id>`), or AGL's own Claude Code still holds a background job's conversation (Claude Code would wake a copy; the composer unlocks once AGL releases it). Nothing can stop a native session from here; whoever runs it stops it.
|
|
3009
|
+
A session AGL may not write to stays readable and names the reason above the transcript: another process runs it (AGL never becomes a second writer), it is a running background job without a session name of its own that SendMessage could address it by, it lives in a fleet profile's own Claude Code home, its directory no longer exists, an AGL project conversation records it (that conversation sends to it), a fleet worker runs it (the worker's view steers it), it is a failed background job (inspect it with `claude logs <id>` or `claude attach <id>`), or AGL's own Claude Code still holds a background job's conversation (Claude Code would wake a copy; the composer unlocks once AGL releases it). Nothing can stop a native session from here; whoever runs it stops it.
|
|
2882
3010
|
|
|
2883
3011
|
The scratchpad and Session Intelligence of a native session are kept per native session id. A fleet worker relaunched under a new session id therefore starts with an empty scratchpad. Session Intelligence on a native session reads that session only.
|
|
2884
3012
|
|
|
@@ -3136,9 +3264,9 @@ Paint needs SmartBrowser's Paint Chromium. The controller downloads it once, in
|
|
|
3136
3264
|
- **Integrity failed.** A download, archive or installed file that does not verify makes Paint unavailable; an installed binary that stops verifying is treated as tampering, its browsers are stopped and the install is deleted. After three failed verifications AGL stops retrying; **Retry Paint** in Settings resumes once the cause is fixed. Video keeps working throughout, on the independent system Chrome.
|
|
3137
3265
|
- **Capture unavailable.** A Paint browser that cannot capture a page keeps working for Video.
|
|
3138
3266
|
|
|
3139
|
-
Paint plays the page's sound through **Enable sound** in the view's toolbar, which the browser requires to be a click; sound needs the Paint browser. Video is unchanged.
|
|
3267
|
+
Paint plays the page's sound through **Enable sound** in the view's toolbar, which the browser requires to be a click; sound needs the Paint browser. Video is unchanged. The sound relay follows the page across a navigation and a viewport change. Known limits: after more than about eight sound sources in one Paint run (each navigation brings new ones), the sound of further sources does not come back until the view opens again; and a page playing a video currently ends both the sound and the page's video in Paint with an error in the journal (SmartBrowser's native media transport refuses its playback observations).
|
|
3140
3268
|
|
|
3141
|
-
Paint, sound and DevTools use their own pairs of authenticated streams beside the view's, bound like DevTools to the exact view, stream generation, lease authority and connection. A video playing in the page reaches a Paint view as the original video: for each one the controller asks the view for a further stream pair to its Paint renderer, and the view answers with a request whose response carries the pair. A navigation, resize or other rebind of the Paint source ends that pair on purpose and the next one opens to the same renderer; a pair that breaks closes only its own decoders. A page that Paint cannot capture for a while ends Paint with SmartBrowser's typed `unsupported` verdict, and the view switches to Video and says so. The renderer and decoder files are served from the controller's origin at `/browser-paint/` and `/browser-audio/`, content-addressed and verified; the page's content security policy allows WebAssembly compilation (`'wasm-unsafe-eval'`) and nothing else beyond the origin. **Settings → General** links the notices of every browser component, `/browser-notices/NOTICES.txt`, including the codec patent disclosure and the source offers of Paint Chromium; see `third-party-notices.md`.
|
|
3269
|
+
Paint, sound and DevTools use their own pairs of authenticated streams beside the view's, bound like DevTools to the exact view, stream generation, lease authority and connection. A video playing in the page reaches a Paint view as the original video: for each one the controller asks the view for a further stream pair to its Paint renderer, and the view answers with a request whose response carries the pair. A navigation, resize or other rebind of the Paint source ends that pair on purpose and the next one opens to the same renderer; a pair that breaks closes only its own decoders and is reported in the error journal as **Show the page's video in Paint** (the controller revoked the pair or it broke, the route broke its protocol, or a renderer request failed). Closing the view or switching to Video reports nothing. A page that Paint cannot capture for a while ends Paint with SmartBrowser's typed `unsupported` verdict, and the view switches to Video and says so. The renderer and decoder files are served from the controller's origin at `/browser-paint/` and `/browser-audio/`, content-addressed and verified; the page's content security policy allows WebAssembly compilation (`'wasm-unsafe-eval'`) and nothing else beyond the origin. **Settings → General** links the notices of every browser component, `/browser-notices/NOTICES.txt`, including the codec patent disclosure and the source offers of Paint Chromium; see `third-party-notices.md`.
|
|
3142
3270
|
|
|
3143
3271
|
#### DevTools and diagnostics
|
|
3144
3272
|
|
|
@@ -3283,6 +3411,7 @@ agl feed list [--state failed] [--json] | acknowledge <row-id> --updated-at <ms>
|
|
|
3283
3411
|
agl foreground [options]
|
|
3284
3412
|
agl temp-password [--port 4097] [--ttl-hours 24]
|
|
3285
3413
|
agl remote set|unset|secret import [--port 4097] [options]
|
|
3414
|
+
agl remote gateway enrol|status|sync|remove [--port 4097] [options]
|
|
3286
3415
|
agl help
|
|
3287
3416
|
agl --version
|
|
3288
3417
|
```
|
|
@@ -3553,7 +3682,7 @@ agl start --port 4097 # prints the setup code for https://agl.example.com
|
|
|
3553
3682
|
- A passkey belongs to its RP ID. When the origin or RP ID changes, the passkey is removed and every temporary password revoked, so nothing that signed in to the old origin signs in to the new one. The next `agl start` prints a fresh setup code to its terminal, never to a log: enroll the passkey at the new origin with it. Running `remote set` again with only other gateway sources keeps the passkey.
|
|
3554
3683
|
- `--gateway-source` names an address the proxy's connections arrive from (IPv4 or IPv6, repeatable, at most 16). Without one only a reverse proxy on this host reaches the controller.
|
|
3555
3684
|
- A paired device signs the public origin (see Paired Devices), so a changed origin removes every paired device as well; `remote set` says how many. Changing only the gateway sources or the RP ID keeps them.
|
|
3556
|
-
- `agl remote unset --port 4097` moves the port back to `http://localhost:4097` (RP ID `localhost`): it removes the passkey and every paired device, revokes every temporary password and forgets the trusted-proxy secret. The next start prints a setup code.
|
|
3685
|
+
- `agl remote unset --port 4097` moves the port back to `http://localhost:4097` (RP ID `localhost`): it removes the passkey and every paired device, revokes every temporary password and forgets the trusted-proxy secret. The next start prints a setup code. It is refused while the controller is enrolled with a gateway (see [AGL's own route on a dcrouter gateway](#agls-own-route-on-a-dcrouter-gateway)): `agl remote gateway remove` comes first. A `remote set` to another hostname is refused while enrolled as well.
|
|
3557
3686
|
- Both refuse while anything listens on the port, take start admission (no upgrade runs meanwhile), run as the local OS user (the trust `agl temp-password` has) and are audited as `remote.set` or `remote.unset`, attempted and then succeeded or failed, with the OS user and process and the public origin and RP ID the move goes from and to (never a secret).
|
|
3558
3687
|
- A start never moves a port: one that asks for another `--public-origin`, `--rp-id` or TLS mode is refused and names `agl remote set`. A new port can still start behind a reverse proxy on this host directly: `agl start --public-origin https://agl.example.com --rp-id agl.example.com --behind-tls-proxy`.
|
|
3559
3688
|
|
|
@@ -3610,9 +3739,35 @@ sudo ufw status verbose # the allow is listed before the deny, and no broader
|
|
|
3610
3739
|
|
|
3611
3740
|
The gateway source is the address the proxy's connections arrive from on this host. A router that translates addresses between the proxy and this host puts its own address there, and every host behind it then passes the source check: route without translation, or put the proxy on this host's network.
|
|
3612
3741
|
|
|
3742
|
+
### AGL's own route on a dcrouter gateway
|
|
3743
|
+
|
|
3744
|
+
A controller behind a [dcrouter](https://code.foss.global/serve.zone/dcrouter) gateway keeps its own route there, as Onebox and Cloudly keep theirs: it is a gateway client of type `custom` and writes one route for the hostname of its public origin. The route ends TLS at the gateway with the gateway's own certificate, forwards to the controller with the trusted-proxy secret, passes WebSockets, is reachable from private networks only (source profile `LOCAL NETWORK`, directly at the hub and over its VPN, never through RemoteIngress) and gets the gateway's own DNS record, unproxied. Every field is sent on every sync: the gateway fills an omitted one from what it stored or a default.
|
|
3745
|
+
|
|
3746
|
+
Enrol the stopped controller once, with a short-lived gateway admin token (dcrouter Ops UI → API Tokens, scope `tokens:manage`) in a file:
|
|
3747
|
+
|
|
3748
|
+
```sh
|
|
3749
|
+
agl stop --port 4097
|
|
3750
|
+
agl remote set --port 4097 --public-origin https://agl.example.com --gateway-source 192.0.2.10
|
|
3751
|
+
agl remote gateway enrol --port 4097 \
|
|
3752
|
+
--gateway-url https://gateway.example.com:3000 \
|
|
3753
|
+
--target-host 192.0.2.66 < ~/gateway-admin-token
|
|
3754
|
+
rm ~/gateway-admin-token # and revoke the token in the Ops UI
|
|
3755
|
+
agl start --port 4097
|
|
3756
|
+
```
|
|
3757
|
+
|
|
3758
|
+
- `enrol` reads the admin token from a pipe or file, never from a terminal, and uses it once to provision the gateway client `agl-<installation>-<port>` (derived from the controller database and the port, so every controller has its own and keeps it) with exactly this route's hostname and target and the capabilities `readRoutes`, `syncRoutes` and `syncDnsRecords`. The gateway issues a credential for that client, which AGL seals with the TPM and stores before it asks the gateway to confirm it; the gateway then revokes the client's older credentials. The admin token is never stored, logged or printed. `--gateway-url` is the gateway's API base URL (requests go to `<url>/typedrequest`): `https`, plain `http` only for a gateway on loopback (`127.0.0.0/8`, `::1`, `localhost`), since every request carries a credential, and no option skips certificate verification; a stored URL is held to the same rule at every sync and `remove` (problem `gateway_url_insecure`). A gateway that answers with a redirect is not followed: the request fails (`unreachable`), so the configured URL is the only one that ever sees a token. `--target-host` is the address the gateway reaches this host by (a loopback address for a gateway on this host; any other needs a `--gateway-source`); both are kept for the next `enrol`.
|
|
3759
|
+
- A confirmation whose answer is lost is asked for again at once; if the gateway still does not answer, `enrol` fails and the next `agl remote gateway enrol --port 4097` finishes it with the stored credential, without a token. Run `enrol` with a new admin token to renew the credential, for example after an admin changed the client's policy. Enrolling with another gateway, or for another hostname a leftover move left behind, first deletes the route of the earlier one.
|
|
3760
|
+
- The running controller syncs the route in the background once it is ready; its start never waits for the gateway. A sync checks the credential, deletes the client's routes for anything the controller no longer serves (an earlier hostname, which only a leftover leaves: an interrupted change or a move an earlier release made after a rollback; the sync then fails with `origin_changed` until `enrol`), writes the route with the trusted-proxy secret as a request header the gateway sets (`requestHeaders`, sent only to a gateway that announces `routes.requestHeaders`, dcrouter 34.5.0 or later; an earlier gateway would refuse the whole route), and reads it back: the route must name the secret header and, when the gateway names the route's source profile, be bound to `LOCAL NETWORK`. A gateway before dcrouter 34.5.0 names no profile, and the status then says the profile is unverified. A failure a later sync can fix (the gateway does not answer, its DNS provider is unavailable) is retried after 30 s, doubling up to 15 min, jittered; a written route is synced again after six hours. A gateway without `routes.requestHeaders` (one before dcrouter 34.5.0, or one downgraded) is waited for (`waiting`, "gateway lacks routes.requestHeaders: waiting"): no route is written, the controller asks again after 30 s doubling up to 15 min, then at every six-hour sync and every `sync`, and writes the route with the header as soon as the gateway announces it. Every sync sends the header, also to a route the gateway already holds, so a route whose stored header a gateway dropped gets it back at the next sync. A failure only the operator can fix stops the syncs until the next start or `sync`: a revoked or stale credential (enrol again), a refused route or one read back without the secret header or bound to another profile, and the DNS outcomes `record-conflict`, `zone-unmanaged` and `target-invalid`. `manual-satisfied` (records the gateway does not own already serve the route) counts as synced and shows as not owned.
|
|
3761
|
+
- `agl remote gateway status [--json]` shows the enrolment, the last sync, the problem and the next sync, from the running controller or, while it is stopped, from its database; `agl status --json` carries the same as `gateway`. Neither the browser nor a paired device sees it.
|
|
3762
|
+
- `agl remote gateway sync [--rotate]` asks the running controller to sync now, over its loopback management endpoint and only for a process of the controller's own OS user, which the controller proves from the kernel. `--rotate` first rotates the trusted-proxy secret: the previous one stays valid until a sync wrote the new one to the route and read it back, and is refused from then on. Nothing rotates the secret on its own.
|
|
3763
|
+
- `agl remote gateway remove` deletes the route and its DNS record on the gateway and forgets the credential (a gateway client cannot revoke its own; an admin deletes the client under Access → Gateway Clients, which revokes it). `agl remote unset` is refused while the controller is enrolled, and so is an `agl remote set` to another hostname (one that keeps the hostname, with another RP ID or gateway sources, is not): run `agl remote gateway remove`, then `agl remote set`, then `agl remote gateway enrol`. When the gateway cannot be reached or refuses the credential, `agl remote gateway remove --abandon` forgets the enrolment without it and prints the route key (`custom:<client>:controller-<port>:<hostname>`) and the client it left for an admin to delete.
|
|
3764
|
+
- `enrol`, `remove` and `--abandon` run against a stopped controller under start admission, like `remote set`; all of them and `sync` are audited as `remote.gateway.enrol`, `remote.gateway.remove`, `remote.gateway.abandon` and `remote.gateway.sync`, with the OS user and process and the route they acted on (never a credential).
|
|
3765
|
+
|
|
3766
|
+
The gateway client keeps its record in `agl_controller_gateway_clients`. An earlier release starts with it in place and leaves it alone, and 41.1.0 and later read the `remote.gateway.*` audit events as types they do not know.
|
|
3767
|
+
|
|
3613
3768
|
## Paired Devices
|
|
3614
3769
|
|
|
3615
|
-
A phone or a desktop app pairs with a controller and then reaches it as a device: it lists the session feed, reads a session's transcript, sends a message to a session and answers its permissions, questions and MCP elicitations. A device reaches nothing else: no terminals, settings,
|
|
3770
|
+
A phone or a desktop app pairs with a controller and then reaches it as a device: it lists the session feed, reads a session's transcript, sends a message to a session and answers its permissions, questions and MCP elicitations, lists the Inbox, reads and messages the driver, lists and messages the direct reports, reads the host's status, and works the shared board: it lists a column, opens a ticket, comments, asks and answers questions and moves a ticket. A device reaches nothing else: no terminals, settings, browsers or files, no creating, editing or assigning tickets (those stay in the browser), and of the accounts only their anonymous usage, read-only. It connects through the controller's public HTTPS origin (Remote Browser Access), so a controller in local mode pairs no device.
|
|
3616
3771
|
|
|
3617
3772
|
### Pairing a device
|
|
3618
3773
|
|
|
@@ -3632,12 +3787,17 @@ Settings → Devices lists every paired device with its model, when it paired, w
|
|
|
3632
3787
|
|
|
3633
3788
|
### The device protocol
|
|
3634
3789
|
|
|
3635
|
-
The device API is its own contract, separate from the browser's: `ts_interfaces/devices.ts` in the package, and the same contracts as JSON Schema in `ts_interfaces/devices.schema.json` (each contract's request and response, and every named type they reach). A device asks `device.hello` for the device protocol version (`major` 1, `minor`
|
|
3790
|
+
The device API is its own contract, separate from the browser's: `ts_interfaces/devices.ts` in the package, and the same contracts as JSON Schema in `ts_interfaces/devices.schema.json` (each contract's request and response, and every named type they reach). A device asks `device.hello` for the device protocol version (`major` 1, `minor` 3) and speaks one major; within it, changes only add. Minor 1 added MCP elicitations: `elicitations` in every `device.session.read` (empty while none is pending; each one a `form` with its `fields`, a `url` or an `unsupported` request with its `reason`) and `device.elicitation.reply`. Minor 2 added the Inbox: `device.inbox.list` and its `inbox.changed` event (the same list as the browser's, without host paths; each item says whether a device answers it: `session`, `child`, `ticket` or `none`), `device.ticket.answer` (a ticket question or a go, as the owner) and `childSessionId` on `device.permission.reply` and `device.question.reply` for a direct child the Inbox names; a client sends `childSessionId` only to a controller that answers `minor` 2 or later. Minor 3 added the driver and the direct reports: `device.driver.get`, `device.driver.seen`, `device.driver.read` and `device.driver.send`, `device.directreports.list` and `device.directreport.message`, and the events `driver.changed` and `directreports.changed`, the host's status, read-only: `device.host.get` and its `host.changed` event, and the shared board: `device.board.list`, `device.ticket.get`, `device.ticket.comment`, `device.ticket.ask` and `device.ticket.move`, and the `tickets.changed` event; a client calls them only on a controller that answers `minor` 3 or later. A device does not tell the controller its minor, so a client ignores keys it does not know; the iOS (HarnessKit) and Android clients of minor 0 do. Apps generate their clients from these files.
|
|
3636
3791
|
|
|
3637
|
-
- Before it is authenticated a connection reaches `device.hello`, `device.pair`, `device.auth.challenge` and `device.auth.prove`, under the controller's limits for unauthenticated requests: per connection, and in total together with the browser's sign-in requests. After that it reaches `device.sessions.list`, `device.session.read`, `device.session.send`, `device.permission.reply`, `device.question.reply` and `device.
|
|
3792
|
+
- Before it is authenticated a connection reaches `device.hello`, `device.pair`, `device.auth.challenge` and `device.auth.prove`, under the controller's limits for unauthenticated requests: per connection, and in total together with the browser's sign-in requests. After that it reaches `device.sessions.list`, `device.session.read`, `device.session.send`, `device.permission.reply`, `device.question.reply`, `device.elicitation.reply`, `device.inbox.list`, `device.ticket.answer`, `device.driver.get`, `device.driver.seen`, `device.driver.read`, `device.driver.send`, `device.directreports.list`, `device.directreport.message`, `device.host.get`, `device.board.list`, `device.ticket.get`, `device.ticket.comment`, `device.ticket.ask` and `device.ticket.move`, under the limits of the owner's browser. A device never reaches a method of the browser, and the browser never one of a device. A connection is one or the other for its whole life: a connection signed in as the browser cannot authenticate as a device, and one a device authenticated cannot sign in as the browser.
|
|
3638
3793
|
- The feed is the sidebar's session feed without terminal rows, host directories or tickets. A transcript page reduces a tool call to its name, title and status; its input and output stay on the controller. `device.session.read` without `before` returns the newest page, sized by the controller whatever `limit` says; with `before` it returns the next older page of `limit` messages (1 to 50, default 20). A device names a session only by the feed's row id, and reaches only what the feed lists.
|
|
3639
3794
|
- A message from a device is a direct message (it queues behind a running turn), never the browser's shared draft. A native session AGL does not write to (another process runs it, a fleet worker owns it) refuses it, as it refuses the browser.
|
|
3640
|
-
-
|
|
3795
|
+
- A device answers as the owner on its own authenticated connection, audited as the device. Its Inbox lists the driver's turn and the driver's own prompts without an answer (the driver session is no feed row), and a native wait as information. A child's answer is sent only after the controller proved the child a running direct child of the session, as it does for the browser.
|
|
3796
|
+
- The driver is the browser's Driver view on a device: `device.driver.get` answers its status (activity, unread turns, title, the `needs input:` line its last turn ended on, never its project or session), `device.driver.seen` marks its ended turns seen (one unread count for every client), `device.driver.read` pages its transcript as `device.session.read` does and lists its own prompts, which a device shows but does not answer, and `device.driver.send` sends it a direct message. Without a driver session read and send are refused with `driver_absent`: the owner starts the driver in the browser, a device never does.
|
|
3797
|
+
- `device.directreports.list` lists the active direct reports as the Driver view does, each by its name, with its session as the feed names it, status, projects, ticket, newest `result:` line, open questions and the fleet workers that report to it (name, harness, status, ticket; no directories or profiles), and whether it takes a message. `device.directreport.message` sends one the owner's message as the Driver view does: a fleet worker report is steered through its ticket and answers `fleet` once the steer succeeded (a failed steer is refused with `direct_report_failed` and the fleet's reason); a Codex thread takes it as the owner's agent message, `steer` into the turn AGL runs or `next-turn`. A turn another Codex client runs is refused with `direct_report_busy` (nothing was sent), a Claude Code session the fleet does not run with `direct_report_failed`, and messages to a report faster than its agent message rate with `rate_limited`. Messages are audited as `session.message` from `Owner` for the device.
|
|
3798
|
+
- The Host view is read-only (AGL-824): a device changes nothing on the host (no deploy or deploy probe, account, setting, upgrade or pairing). `device.host.get` answers what runs (`agl`: the AGL release, its start, its public origin, and whether a device reaches it through the gateway AGL keeps its route on, with where that route's sync stands, or through the owner's own reverse proxy; never the gateway's address, the client or the route's target), the device itself as the controller keeps it (`device`: name, model, when it paired and when it last connected; a device neither renames nor unpairs itself), the deploy targets (`deploys`: what each runs and since when, whether its probe answers, its newest release, the released versions it does not run (`undeployed`, newest first), and its planned deploys (`plans`: the ticket, the version, the owner's go and, for one queued into a maintenance window, the window's times); never a probe's address, the owner's notes on how it deploys and what a deploy interrupts, a failed probe's text, a plan's question or who deploys it, and the read runs no probe), the inference proxy's account pools (`pools`: each pool's verdict and room, and its accounts by plan and then the most used first, each only as its plan, state and the usage window it is bound by: no account id, and no order that stands in for one) and the API keys (`apiKeys`: per provider, how many keys are under their monthly spend limit, held at it, without one, or not read, judged by the rule AGL's inference proxy places by; no label, email, id or dollar amount). `deploys`, `pools` and `apiKeys` each answer `ready` or `unavailable` on their own, with the reason (`not_running`, `outdated`, or `failed` with the failure journal's `reference`), and the request still answers the others. `host.changed` (no payload) says when to read it again: the deploy targets, their planned deploys (tickets) or the accounts changed. Usage moves without an event, so a client reads it again when the Host view is opened or refreshed.
|
|
3799
|
+
- The shared board on a device is the browser's board (AGL-1637). `device.board.list` answers one column at a time, as the browser shows its cards (the tasks; an epic and a subtask open with `device.ticket.get`), in the column's order, `limit` (1 to 100, default 50) from `offset`, filtered as the browser filters: `text` (1 to 200 characters, in the key, title, description and source words), `project`, `epic` (the epic's own tasks), `assignee` (`{ kind: 'owner' }`, `{ kind: 'unassigned' }` or a session as the feed names it) and an AutoLabel (`openQuestion`, `planned`, `undeployed`). Every column's count under the same filters comes from the same read as the page, with `total`, the projects the board's tickets name, the epics a filter may choose and the board's `revision`: when a later page answers another revision, or `tickets.changed` arrives, a client reads the board again from offset 0. `device.ticket.get` answers a ticket with its description, source words, links and parent, one page of its discussion (comments and questions together in the order they were written, newest page first, at most `limit` of 1 to 50 and 256 KiB, `before` for the next older page), where it runs (`placement`, from the deploy monitor, `unavailable` on its own as a section of `device.host.get` is) and what it plans (`plans`: the release plan, the maintenance window and the deploy plan, with where the window stands and the owner's go while the monitor answers); no history of its other changes, no source attachments, no plan's question and nothing that names who deploys it. People appear by name: the owner as `kind: 'owner'`, never the owner's account, a person's id or a session the feed does not list (the driver's own session included). `device.ticket.comment` (Markdown, at most 64 KiB as the store keeps it), `device.ticket.ask` (text alone, at most 16 KiB, answered with text) and `device.ticket.move` (to the end of a column; "Move to…" stands in for the browser's drag) run the browser board's own function as the owner, audited as `ticket.comment`, `ticket.ask` and `ticket.move` for the device; `device.ticket.answer` answers a question. The controller decides every change: a refusal changes nothing and carries the ticket store's own code (`deviceTicketRefusalCodes`, such as `ticket_review_branch_required` for a move to review without a branch) and its reason. The app then keeps the owner's draft, reads the ticket again and shows the reason; it never sends a refused change again on its own. A change whose outcome AGL cannot tell is refused as `controller_unavailable` for now and stays fenced: the app reads the ticket again before the owner decides (AGL-1670 gives it a code of its own that a client never resends). Creating, editing and assigning tickets stay in the browser.
|
|
3800
|
+
- The controller pushes a device an allowlist of events in their own shape: feed changes, a session's change, its streaming text (snapshots and exact deltas), Inbox changes, the driver's changes (`driver.changed` with its status, also when its transcript or prompts changed, never its streaming text), the direct reports' changes (`directreports.changed`, with no payload, also when fleet workers or tickets changed), the host's changes (`host.changed`, with no payload, when the deploy targets or the accounts changed), the board's changes (`tickets.changed`, with no ticket key and with the board's revision when it moved, followed by `directreports.changed` and `host.changed`, since tickets hold the reports' questions and the planned deploys) and a resynchronization request. Every other event, and every event about a session the feed does not list, stays on the controller. A device that falls behind by 256 events or 4 MiB is resynchronized alone: on `sessions.changed` it lists the feed and reads the open session again, an open Driver view included (the driver's own changes may have folded into it).
|
|
3641
3801
|
- Through the gateway, a device's WebSocket upgrade carries the public origin as `Origin`, like a browser's (Admission).
|
|
3642
3802
|
|
|
3643
3803
|
## Security Boundaries
|
|
@@ -3645,7 +3805,7 @@ The device API is its own contract, separate from the browser's: `ts_interfaces/
|
|
|
3645
3805
|
- Local mode binds the controller to loopback only, and so does TLS-proxy mode without a gateway source. With one, a request from off loopback needs a configured gateway source address and the trusted-proxy secret, and only loopback connects without an `Origin`.
|
|
3646
3806
|
- The trusted-proxy secret is generated and TPM2-sealed in the controller's database; it is never read from the environment, written to a file or logged.
|
|
3647
3807
|
- Only `agl remote`, run by the local OS user against a stopped controller, changes a port's public origin, RP ID, TLS mode or gateway sources, and a changed origin or RP ID removes the passkey (a changed origin every paired device too).
|
|
3648
|
-
- A paired device holds its own key; the controller stores only its public key. A device reaches only the device scope (feed, bounded reads, direct sends, permission, question and elicitation answers), each connection proves the key over a fresh nonce, and revoking a device closes its connections at once. Pairing codes are single-use, live five minutes in memory only, and pairing is refused in local mode.
|
|
3808
|
+
- A paired device holds its own key; the controller stores only its public key. A device reaches only the device scope (feed, bounded reads, direct sends, permission, question and elicitation answers, the Inbox and ticket answers, the driver and the direct reports, the host's status, read-only, and the shared board's comments, questions and moves, as the owner), each connection proves the key over a fresh nonce, and revoking a device closes its connections at once. Pairing codes are single-use, live five minutes in memory only, and pairing is refused in local mode.
|
|
3649
3809
|
- The private OpenCode server always remains on loopback and uses a generated per-process password.
|
|
3650
3810
|
- Application RPC starts only after the exact TypedSocket package-major handshake.
|
|
3651
3811
|
- The management endpoint (`/management/typedrequest`, used by the CLI and the upgrade worker) answers only an HTTP `POST` of `application/json` from a loopback peer (`127.0.0.1` or `::1`), addressed to `127.0.0.1:<port>`, with no `Origin` and no forwarding header (`Forwarded`, `X-Forwarded-*`, `X-Real-IP`, `X-Harness-Controller-Proxy-Secret`), so a browser or a request a proxy forwards is refused, also in proxy mode. It serves only the status read and the upgrade methods; each upgrade method authorises itself against the upgrade token and its one-time grant, as it does over the socket, and every upgrade request counts against the controller's global unauthenticated preflight limit.
|