agl 43.2.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 +20 -0
- package/dist_serve/bundle.js +2845 -2638
- package/dist_serve/bundle.js.map +2 -2
- package/dist_serve/bundle.js.third-party-notices.json +1 -1
- package/dist_serve/bundle.js.third-party-notices.txt +1 -1
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/aglapi/aglapisurface.document.js +197 -17
- package/dist_ts/classes.accountsactions.d.ts +3 -1
- package/dist_ts/classes.accountsactions.js +21 -3
- package/dist_ts/classes.claudeharness.d.ts +16 -0
- package/dist_ts/classes.claudeharness.js +24 -2
- package/dist_ts/classes.codexclientadapter.d.ts +11 -0
- package/dist_ts/classes.codexclientadapter.js +14 -2
- package/dist_ts/classes.controller.d.ts +165 -11
- package/dist_ts/classes.controller.js +1095 -170
- package/dist_ts/classes.controllerdevices.d.ts +2 -0
- package/dist_ts/classes.controllerdevices.js +6 -1
- package/dist_ts/classes.inbox.d.ts +72 -0
- package/dist_ts/classes.inbox.js +231 -0
- package/dist_ts/classes.inferencerouter.d.ts +10 -0
- package/dist_ts/classes.inferencerouter.js +5 -3
- package/dist_ts/classes.inferenceservice.js +2 -2
- package/dist_ts/classes.mcpclient.d.ts +1 -1
- package/dist_ts/classes.mcpclient.js +24 -6
- package/dist_ts/classes.mcpcontrollerhost.js +3 -1
- package/dist_ts/classes.mcptools.js +13 -8
- package/dist_ts/classes.mcpvalidation.d.ts +5 -0
- package/dist_ts/classes.mcpvalidation.js +32 -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.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/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.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.inferencecli.js +3 -1
- package/dist_ts/functions.mcpfleetworkertools.js +2 -2
- package/dist_ts/functions.ticketvalidation.js +11 -2
- package/dist_ts/interfaces.auth.d.ts +1 -1
- package/dist_ts/interfaces.auth.js +9 -1
- package/dist_ts/plugins.d.ts +3 -1
- package/dist_ts/plugins.js +7 -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 +17 -10
- package/dist_ts_authswitch/authority-renewal.d.ts +34 -0
- package/dist_ts_authswitch/authority-renewal.js +56 -0
- 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/inbox.d.ts +234 -0
- package/dist_ts_interfaces/inbox.js +101 -0
- package/dist_ts_interfaces/index.d.ts +1 -0
- package/dist_ts_interfaces/index.js +2 -1
- package/dist_ts_interfaces/interfaces.d.ts +10 -3
- package/dist_ts_interfaces/interfaces.js +4 -2
- package/dist_ts_interfaces/mcprequests.d.ts +34 -4
- package/dist_ts_interfaces/mcprequests.js +11 -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/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 +3 -3
- package/readme.md +112 -26
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/aglapi/aglapisurface.document.ts +196 -16
- package/ts/classes.accountsactions.ts +30 -3
- package/ts/classes.claudeharness.ts +27 -1
- package/ts/classes.codexclientadapter.ts +14 -1
- package/ts/classes.controller.ts +1294 -246
- package/ts/classes.controllerdevices.ts +6 -0
- package/ts/classes.inbox.ts +239 -0
- package/ts/classes.inferencerouter.ts +15 -2
- package/ts/classes.inferenceservice.ts +1 -1
- package/ts/classes.mcpclient.ts +24 -3
- package/ts/classes.mcpcontrollerhost.ts +2 -0
- package/ts/classes.mcptools.ts +12 -7
- package/ts/classes.mcpvalidation.ts +27 -1
- package/ts/classes.nativesessions.ts +50 -12
- package/ts/classes.opencodeclient.ts +55 -4
- 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/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.deviceapi.ts +1071 -34
- package/ts/functions.fleetworkercli.ts +10 -7
- package/ts/functions.inferencecli.ts +2 -0
- package/ts/functions.mcpfleetworkertools.ts +1 -1
- package/ts/functions.ticketvalidation.ts +11 -1
- package/ts/interfaces.auth.ts +8 -0
- package/ts/plugins.ts +7 -0
- package/ts_authswitch/authority-contract.ts +20 -0
- package/ts_authswitch/authority-overview.ts +28 -6
- package/ts_authswitch/authority-placement.ts +25 -17
- package/ts_authswitch/authority-renewal.ts +64 -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/inbox.ts +287 -0
- package/ts_interfaces/index.ts +1 -0
- package/ts_interfaces/interfaces.ts +9 -2
- package/ts_interfaces/mcprequests.ts +43 -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/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 +10 -5
- package/ts_web/classes.inboxfeed.ts +329 -0
- package/ts_web/classes.nativesessionstate.ts +9 -23
- package/ts_web/elements.accounts.ts +81 -0
- package/ts_web/elements.deployments.ts +66 -2
- package/ts_web/elements.harnesscontrollerapp.ts +107 -37
- 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.
|
|
@@ -387,8 +399,8 @@ none shows as unavailable), so a pool no request used since the proxy started is
|
|
|
387
399
|
find it -- naming as of when, whether its
|
|
388
400
|
newest values came from provider answers or the account service's own read, whether a window is estimated since, and
|
|
389
401
|
whether the service's last read was rate-limited -- with its lifecycle (canceled with its lapse date, or lapsed), its
|
|
390
|
-
placement score and its rank for the next new session (`--json`: `lifecycle`,
|
|
391
|
-
`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
|
|
392
404
|
the account service read its spend: `available ($12.40 of $50.00 this month)` with what is left of its limit as its
|
|
393
405
|
headroom and placement score, `available ($3.20 this month, no spend limit)` with neither, `at its spend limit` (or
|
|
394
406
|
`held until its month ends`, for an answer that could not be priced) with the month's end -- the month counts the
|
|
@@ -527,12 +539,12 @@ listener, a Unix socket that serves confined runs alone (see [Confined container
|
|
|
527
539
|
The router places a new session by how much usage each account can spend per hour, and keeps that account for the
|
|
528
540
|
session: the prompt cache always comes first, so a session is never placed again while its account can serve it. An
|
|
529
541
|
account's placement score is the least, over the windows its limit counts, of the headroom left below its threshold
|
|
530
|
-
divided by the hours until that window resets -- or until the account lapses, if that comes first
|
|
531
|
-
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
|
|
532
544
|
(`ts_authswitch/authority-placement.ts`). A new session goes to the account with the highest score per request it
|
|
533
545
|
serves now (`score / (1 + in flight)`), so new sessions spread over the accounts in proportion to what each can spend:
|
|
534
|
-
quota that resets soon, or is lost when the account lapses, is used first
|
|
535
|
-
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
|
|
536
548
|
every scored one. Within the client's pool, only current quota exhaustion, a definite provider HTTP 429 before
|
|
537
549
|
forwarding output, the account lapsing or leaving the pool, or a Claude account taking no request for a reason of its
|
|
538
550
|
own (below) permits moving the session to another eligible account.
|
|
@@ -1151,14 +1163,18 @@ Writing is not open. Task mutations (`session_send`, `session_scratchpad_update`
|
|
|
1151
1163
|
|
|
1152
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`.
|
|
1153
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
|
+
|
|
1154
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.
|
|
1155
1171
|
|
|
1156
1172
|
| Tools | Behavior |
|
|
1157
1173
|
| --- | --- |
|
|
1158
1174
|
| `controller_status`, `projects_list`, `project_add` | Inspect the controller and register existing project directories. |
|
|
1159
|
-
| `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). |
|
|
1160
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. |
|
|
1161
|
-
| `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. |
|
|
1162
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. |
|
|
1163
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. |
|
|
1164
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. |
|
|
@@ -1281,7 +1297,8 @@ whose Claude Code home holds it (or `none`) and the one command that adopts it o
|
|
|
1281
1297
|
`agl fleet worker adopt NAME --native-id ID --cwd DIR --profile PROFILE --ticket TICKET`, with
|
|
1282
1298
|
the job's name, directory and profile filled in. A job in the host's own Claude Code home also
|
|
1283
1299
|
carries `nativeMessage`, the `agl fleet worker native-message ID --message-file FILE --sender LABEL`
|
|
1284
|
-
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
|
|
1285
1302
|
native-message refuses it. A job that an archived worker still binds is listed with
|
|
1286
1303
|
`adoptable: false` and that worker's name, and neither command, since a session stays bound to any worker.
|
|
1287
1304
|
The search reads each inventory and the comments for at most 20 seconds; what it could not read
|
|
@@ -1524,7 +1541,12 @@ authoritative for linked-worktree and other trust checks. A start that exits non
|
|
|
1524
1541
|
refused: the worker is `stopped` without a dispatch fence and can be archived. Any other
|
|
1525
1542
|
failed start keeps the fence. Relays group recipients by their observed permission mode (any
|
|
1526
1543
|
mode Claude Code records: `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`
|
|
1527
|
-
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
|
|
1528
1550
|
relay addresses each recipient by its session name from `agents --json --all`, which is how SendMessage
|
|
1529
1551
|
resolves a recipient; a name that another live session shares refuses before anything is sent.
|
|
1530
1552
|
Each exact native tool receipt must prove queued delivery (`success: true` with a `msg_id`);
|
|
@@ -1796,7 +1818,7 @@ browser reaches it through three protected requests:
|
|
|
1796
1818
|
- `controller.driver.seen` resets that unread count. Every status change is pushed as a
|
|
1797
1819
|
`driver.changed` event.
|
|
1798
1820
|
|
|
1799
|
-
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,
|
|
1800
1822
|
Board and Settings. It opens the driver in the main area as a full conversation: transcript,
|
|
1801
1823
|
composer and details, attached resources included. Its badge shows the activity as a dot,
|
|
1802
1824
|
pulsing while the driver works, in the warning colour when it needs input and the error colour
|
|
@@ -1841,9 +1863,11 @@ and is not sent once that turn has ended. The usual agent message limits apply:
|
|
|
1841
1863
|
the per-task rate. The report is the owner's and reached outside every project, so no project's
|
|
1842
1864
|
**Agent messages** switch applies to it. While a turn runs the modal reads again every 3
|
|
1843
1865
|
seconds. A report that is a Claude Code session the fleet does not run opens read-only, without
|
|
1844
|
-
transcript or steer box:
|
|
1845
|
-
|
|
1846
|
-
|
|
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)).
|
|
1847
1871
|
Leaving the driver closes the modal.
|
|
1848
1872
|
|
|
1849
1873
|
A fleet worker opened from the session list shows the same transcript in the main area; its
|
|
@@ -2503,7 +2527,9 @@ map directly to these methods; unwrap the named response field.
|
|
|
2503
2527
|
|
|
2504
2528
|
`viewer` is the person the controller identifies the caller as, the `id` its tickets name in
|
|
2505
2529
|
`createdBy` and `assignee`: the board's "assigned to me" compares against it. The columns carry
|
|
2506
|
-
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.
|
|
2507
2533
|
|
|
2508
2534
|
`id` equals `key`. Every returned ticket carries its numeric `revision`, advanced by every
|
|
2509
2535
|
change to that ticket (including comments, links and move/reorder changes). Existing stored
|
|
@@ -2681,6 +2707,59 @@ ship from git; **Plan hotfix** turns an urgent bug found in a running version in
|
|
|
2681
2707
|
release plan, for the next version unless one is named. The view follows
|
|
2682
2708
|
`deployments.changed`.
|
|
2683
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
|
+
|
|
2684
2763
|
### Configuration: one master for every harness
|
|
2685
2764
|
|
|
2686
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.
|
|
@@ -2801,7 +2880,9 @@ outside press dismiss the panel; the panel updates without rerendering the
|
|
|
2801
2880
|
workspace. The controller samples CPU, memory and network rates through a bounded
|
|
2802
2881
|
`smartsystem` worker. Initial network discovery and later topology rescans run
|
|
2803
2882
|
outside the controller event loop, keeping terminal echo and browser input
|
|
2804
|
-
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.
|
|
2805
2886
|
|
|
2806
2887
|
Clicking one footer reading opens only that reading's one-hour graph in a compact
|
|
2807
2888
|
anchored panel; network receive and transmit remain paired. **Stats** continues to
|
|
@@ -2920,12 +3001,12 @@ Its composer sends through the runtime that owns the session (`controller.native
|
|
|
2920
3001
|
|
|
2921
3002
|
- **Codex** threads take the message through the host's shared Codex server, steered into a running turn or else starting the next one.
|
|
2922
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.
|
|
2923
|
-
- **Claude Code background jobs** (`claude --bg`, listed by `claude agents`) stay their session's owner
|
|
2924
|
-
- **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.
|
|
2925
3006
|
|
|
2926
3007
|
The attachments of any other native send are deleted once the turn that read them ends.
|
|
2927
3008
|
|
|
2928
|
-
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.
|
|
2929
3010
|
|
|
2930
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.
|
|
2931
3012
|
|
|
@@ -3183,9 +3264,9 @@ Paint needs SmartBrowser's Paint Chromium. The controller downloads it once, in
|
|
|
3183
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.
|
|
3184
3265
|
- **Capture unavailable.** A Paint browser that cannot capture a page keeps working for Video.
|
|
3185
3266
|
|
|
3186
|
-
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).
|
|
3187
3268
|
|
|
3188
|
-
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`.
|
|
3189
3270
|
|
|
3190
3271
|
#### DevTools and diagnostics
|
|
3191
3272
|
|
|
@@ -3686,7 +3767,7 @@ The gateway client keeps its record in `agl_controller_gateway_clients`. An earl
|
|
|
3686
3767
|
|
|
3687
3768
|
## Paired Devices
|
|
3688
3769
|
|
|
3689
|
-
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.
|
|
3690
3771
|
|
|
3691
3772
|
### Pairing a device
|
|
3692
3773
|
|
|
@@ -3706,12 +3787,17 @@ Settings → Devices lists every paired device with its model, when it paired, w
|
|
|
3706
3787
|
|
|
3707
3788
|
### The device protocol
|
|
3708
3789
|
|
|
3709
|
-
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.
|
|
3710
3791
|
|
|
3711
|
-
- 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.
|
|
3712
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.
|
|
3713
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.
|
|
3714
|
-
-
|
|
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).
|
|
3715
3801
|
- Through the gateway, a device's WebSocket upgrade carries the public origin as `Origin`, like a browser's (Admission).
|
|
3716
3802
|
|
|
3717
3803
|
## Security Boundaries
|
|
@@ -3719,7 +3805,7 @@ The device API is its own contract, separate from the browser's: `ts_interfaces/
|
|
|
3719
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`.
|
|
3720
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.
|
|
3721
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).
|
|
3722
|
-
- 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.
|
|
3723
3809
|
- The private OpenCode server always remains on loopback and uses a generated per-process password.
|
|
3724
3810
|
- Application RPC starts only after the exact TypedSocket package-major handshake.
|
|
3725
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.
|