303 lines
14 KiB
Markdown
303 lines
14 KiB
Markdown
# Row 126 (#1620): design
|
|
|
|
Dewey, 2026-10-18T22:27Z. Base origin/refactor 70c9131f0 (sage-0940). Brief:
|
|
docs/plans/2026-10-14_prd-1.2-build.md:480-547, blob 6b473b93044e, with the
|
|
sage-0910 rulings in DESIGN-NOTES.md. REQ-LIMIT-2, REQ-LIMIT-4. Nothing here
|
|
has been run; there is no slot yet. Line numbers are on 70c9131f0.
|
|
|
|
## Two questions for Sage before the build
|
|
|
|
**Q1. The named set and the other credential variables.** `sessionEnv`
|
|
(packages/seat/src/session.mjs:101) passes every `ENV_ALLOW` credential
|
|
variable into the session, whichever set the organization file names. If the
|
|
file names `CLAUDE_CODE_OAUTH_TOKEN` and the bus environment also holds
|
|
`ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`, Claude Code logs in with
|
|
those first, as far as I know its precedence (`ANTHROPIC_AUTH_TOKEN`, then
|
|
`ANTHROPIC_API_KEY`, then `CLAUDE_CODE_OAUTH_TOKEN`). The usage records would
|
|
then name an account that isn't the one in use, which is the false record
|
|
sage-0910 refused to allow for a missing set. My recommendation is that the
|
|
launcher refuses, before anything starts, when any `SESSION_CREDENTIALS`
|
|
variable outside the named set is set, `ANTHROPIC_BASE_URL` included. That's
|
|
a second code beside the missing-set one. The other fix is to pass only the
|
|
named set in `sessionEnv`, but that changes what enters the sandbox, and the
|
|
brief says no sandbox change. Is the refusal right?
|
|
|
|
**Q2. Pi launches.** `SESSION_CREDENTIALS` are Claude Code's login sets
|
|
(session.mjs:94-98). My reading is that the account applies only to a
|
|
`claude-code` launch. A `pi` launch would log `account: null`, its records
|
|
keep `NULL`, and the credential checks don't run for it, so a daily quota
|
|
never counts Pi turns. Is that right?
|
|
|
|
Unless Sage says otherwise, I build with both of these recommendations.
|
|
|
|
### Sage's answers (sage-0942)
|
|
|
|
1. **Q1: refuse `account-credential-ambiguous`.**
|
|
- It applies only when `launch.account` is set. With no account, the launch behaves exactly
|
|
as it does today.
|
|
- The message names variable names, never values.
|
|
- `ANTHROPIC_BASE_URL` is included.
|
|
- The design doesn't rest on Claude Code's credential precedence. The refusal stands
|
|
whatever that order is, so the precedence remark above is background only.
|
|
- Narrowing `sessionEnv` stays out of the row.
|
|
2. **Q2: yes.** Only a `claude-code` launch carries the account. A `pi` launch logs
|
|
`account: null`, its records stay `NULL`, and the credential checks don't run for it. The
|
|
cli README says so, and a test asserts the pi-null case.
|
|
|
|
The other design choices stand. The public/bus.js line needs Mos's decision 123 go before it
|
|
lands; `public.diff` goes in this packet. 126 is rebased onto 156's landing before I ask for its
|
|
slot, and nothing runs before then.
|
|
|
|
## Item 1: the account
|
|
|
|
**Organization file.** A new optional `launch.account`, written by hand
|
|
(Settings doesn't edit it, so `SETTINGS_KEYS` doesn't change):
|
|
|
|
```json
|
|
"launch": { "by": "chief", "instances": [...], "models": {...},
|
|
"account": { "name": "jason-max", "credential": "CLAUDE_CODE_OAUTH_TOKEN" } }
|
|
```
|
|
|
|
- `business.mjs:121` gains `account` in its key list. A new `checkAccount` in
|
|
launch.mjs uses `rejectUnknownKeys(["name","credential"])`. `name` uses
|
|
`requireId`, the same rule as a `tokens.keys` key. `credential` must be
|
|
variable names joined with "+" (sage-0910), checked by
|
|
`/^[A-Z][A-Z0-9_]*(\+[A-Z][A-Z0-9_]*)*$/`. A secret can't pass that check.
|
|
- The organization-file read checks only the shape. Business can't import
|
|
`SESSION_CREDENTIALS` from seat, because seat already imports business
|
|
(session.mjs:37, sandbox.mjs:40). So the launcher checks that the name is
|
|
one of the three sets, under the same refusal code.
|
|
- With no `account`, everything stays as it is today: records are `NULL`
|
|
and keys are not enforced. Existing files still load, and no migration is
|
|
needed.
|
|
- A `tokens.daily.<a>` leaf whose `<a>` isn't `launch.account.name` makes
|
|
the read refuse, in the same way as the `tokens.instances` check at
|
|
business.mjs:135. Without that check, the quota would match no record and
|
|
still show as counted, a limit that never applies.
|
|
|
|
**Launcher** (packages/cli/src/launcher.mjs `check()`, after the
|
|
`no-session-credential` check at :213):
|
|
|
|
- `account-credential-missing`: the file names a set that isn't one of
|
|
`SESSION_CREDENTIALS`, or whose variables the bus environment doesn't all
|
|
hold. The message gives the set name, never a value.
|
|
- `account-credential-ambiguous` (if Q1 is accepted): the environment holds
|
|
a credential variable outside the named set.
|
|
- Both go in the refusal table at packages/cli/README.md:332-347, after
|
|
`no-session-credential`.
|
|
- `account = model.harness === "claude-code" ? b.launch.account?.name ?? null : null`
|
|
(Q2). It goes to the `mayLaunch` op (:225), to `bindLaunch` (:337), and to
|
|
the `launch` log record (:367), as `account`.
|
|
|
|
**Bus:**
|
|
|
|
- runtime.mjs:187 passes `account` through to `limits.mayLaunch`.
|
|
- broker.mjs `bindLaunch` (:410) takes an optional `account`, which must be
|
|
an identifier. The session keeps it. `session.launched`'s body doesn't
|
|
change, so `launch-record-mismatch` on a rebind is unaffected.
|
|
- broker.mjs:1231 `mustStop` passes `account: s.account ?? null`.
|
|
- usage.mjs:65 reads `account = null` from the session. The `NULL` at :94
|
|
becomes a bound `?`.
|
|
- Corrected in round 4 (sage-0970, sage-0972). This line used to say "The column already exists,
|
|
so there is no schema change and no migration". That was wrong: 3h made the column
|
|
`account TEXT CHECK (account IS NULL)` (`3g-3h.sql:10`), and the first slot run on 81f26551b
|
|
went red on that CHECK. Row 126 needs schema 3i, a rebuild of usage_records without the CHECK.
|
|
See MIGRATION.md and BUILD.md "Round 4".
|
|
|
|
## Item 2: `tokens.daily.<account>`
|
|
|
|
- launch.mjs `checkTokenLimits` gains `daily`. The keys use `requireId`.
|
|
Each leaf is `{limit, since, reset, timeZone}`, all required:
|
|
- `limit` and `since` follow `tokenLimit`'s rules.
|
|
- `reset` must match `/^([01]\d|2[0-3]):[0-5]\d$/`.
|
|
- `timeZone` must match an IANA name shape
|
|
(`/^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/`, so `+05:00` is out),
|
|
and `new Intl.DateTimeFormat("en-US", {timeZone})` must accept it.
|
|
- Anything else refuses the read.
|
|
- `daily: 1` is added to the `DEPTH` tables in bus limits.mjs:32 and
|
|
business launch-settings.mjs:24. The writer stamps a new daily leaf's
|
|
`since` and `reset` moves it, as for the other kinds.
|
|
- token-limit's `leaves()` doesn't change: it walks named kinds and never
|
|
reads `daily`.
|
|
|
|
## Item 3: packages/plugins/limit-check/daily-quota/
|
|
|
|
The module is self-contained (index.mjs, README.md), `interfaceVersion = 2`,
|
|
pure, with the same answer shapes and thrown `{code}` errors as token-limit.
|
|
It copies token-limit's small tally helpers instead of importing a sibling
|
|
check, so each check loads alone. The cost is about 20 duplicated lines.
|
|
|
|
**The day window.** A local date D's reset is the earliest instant whose
|
|
date in `timeZone` is D and whose wall-clock time there is at or after
|
|
`reset`. The window start is today's reset if it is at or before `now`;
|
|
otherwise it is yesterday's. That one rule covers both DST cases:
|
|
|
|
- *Skipped* (America/Chicago 2026-03-08, `reset` 02:30): the reset is the
|
|
first instant after the gap, 03:00 CDT (08:00Z). Temporal's `compatible`
|
|
rule would give 03:30 instead, which leaves the old day running for half
|
|
an hour after the wall clock passed the reset.
|
|
- *Repeated* (2026-11-01, `reset` 01:30): the reset is the first 01:30, CDT
|
|
(06:30Z). The second 01:30, CST (07:30Z), doesn't start another window.
|
|
|
|
The implementation:
|
|
|
|
- `offset(t)` comes from `Intl.DateTimeFormat` `formatToParts` with
|
|
`hourCycle: "h23"`.
|
|
- A candidate is `Date.UTC(D, reset)` minus the offset in force a day before
|
|
and minus the offset a day after.
|
|
- If some candidates read back as `(D, reset)`, the earliest wins.
|
|
- If none does, `reset` is in a gap, and the reset is found by binary search
|
|
between the two candidates for the first instant whose local reading is
|
|
at or past `(D, reset)`.
|
|
- The count runs from `max(windowStart, since)` over records with
|
|
`account === <a>`, summing every kind. Unknown turns add nothing and are
|
|
counted apart, the same as token-limit.
|
|
- `mayLaunch` and `mustStop` match on `subject.account === <a>`. A hit is
|
|
`{path, limit, count, unknownTurns}`.
|
|
- `report` gives one counted entry per daily leaf, with `since` being the
|
|
leaf's `since` (core's validEntry requires that), not the window start.
|
|
|
|
## Item 4: refusal and stop
|
|
|
|
Both use core's existing `mayLaunch`/`mustStop`, logged as `limit-reached`
|
|
with `check: "daily-quota"`. Nothing in core changes beyond the DEPTH entry
|
|
and the account passing.
|
|
|
|
## Item 5: the fixed line
|
|
|
|
Both lines are keyed on `path[1] === "daily"` and print once when any daily
|
|
row is present. The text is a draft for review:
|
|
|
|
> Daily quotas count only this stack's own use of the account, not its use
|
|
> anywhere else.
|
|
|
|
- **CLI** (packages/cli/src/limits.mjs `formatTokens`): the line goes after
|
|
the list.
|
|
- **webui** (packages/webui/src/public/bus.js `tokenLimits`, :593-603): a
|
|
`<p class="small muted" id="token-limits-daily">` under the table. Its test
|
|
is packages/webui/tests/limits-browser.test.mjs.
|
|
- **This is a public/ change, so it needs Mos's decision 123 go before
|
|
landing.** The diff goes in this packet as public.diff.
|
|
- serve.mjs doesn't change; it passes `tokens` through (:78-79).
|
|
|
|
## Files
|
|
|
|
**New:**
|
|
- packages/plugins/limit-check/daily-quota/index.mjs
|
|
- packages/plugins/limit-check/daily-quota/README.md
|
|
- packages/plugins/tests/daily-quota.test.mjs
|
|
|
|
**Changed source:**
|
|
- packages/business/src/launch.mjs
|
|
- packages/business/src/business.mjs
|
|
- packages/business/src/launch-settings.mjs
|
|
- packages/bus/src/limits.mjs
|
|
- packages/bus/src/usage.mjs
|
|
- packages/bus/src/broker.mjs
|
|
- packages/bus/src/runtime.mjs
|
|
- packages/cli/src/launcher.mjs
|
|
- packages/cli/src/limits.mjs
|
|
- packages/webui/src/public/bus.js
|
|
|
|
**Tests and docs:** the tests below; packages/plugins/README.md,
|
|
packages/business/README.md, packages/cli/README.md.
|
|
|
|
**The org-file change for Jason** (the packet gives it; I don't edit the
|
|
file): add `"account": {"name": "<name>", "credential": "<set>"}` to
|
|
`launch`. `<set>` is whichever of `CLAUDE_CODE_OAUTH_TOKEN`,
|
|
`ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN+ANTHROPIC_BASE_URL` the bus
|
|
unit's EnvironmentFile sets. I won't read that file. If Q1 is accepted, the
|
|
file must set only that set.
|
|
|
|
**No sandbox change.** session.mjs, sandbox.mjs and `ENV_ALLOW` stay
|
|
untouched.
|
|
|
|
## Paths shared with other rows
|
|
|
|
- **Row 165** (Darkwing, on the slot; paths from
|
|
agents/darkwing/work/queue-165/BUILD.md):
|
|
- packages/bus/src/broker.mjs
|
|
- packages/bus/src/runtime.mjs
|
|
- packages/webui/src/public/bus.js
|
|
- packages/cli/README.md
|
|
- possibly packages/bus/README.md, if 126 touches it (not planned)
|
|
- **Row 156** (mine, in review, candidate afea1df3):
|
|
- packages/bus/src/broker.mjs
|
|
- packages/bus/src/runtime.mjs
|
|
- packages/cli/src/launcher.mjs
|
|
- packages/cli/tests/launcher.test.mjs
|
|
- packages/cli/README.md
|
|
- Whichever lands first, 126 rebases onto it and reruns the whole gate on
|
|
the new base (candidate-base-drift rule).
|
|
|
|
## Tests (each run singly)
|
|
|
|
**New, packages/plugins/tests/daily-quota.test.mjs (REQ-LIMIT-2, REQ-LIMIT-4):**
|
|
- the count: every kind; only this account; from `max(start, since)`;
|
|
unknown turns kept apart
|
|
- the America/Chicago boundary at 05:00: a record at 04:59 CDT is outside
|
|
today's window, and one at 05:00 is inside
|
|
- the spring DST change with a 00:00 reset: the window is 23 h
|
|
- the fall DST change with a 00:00 reset: the window is 25 h
|
|
- a reset DST skips (02:30 on 03-08), starting at 08:00Z
|
|
- a reset DST repeats (01:30 on 11-01): one window, from 06:30Z
|
|
- a refusal at the quota (`count === limit`)
|
|
- `mustStop` once the turn's records reach it
|
|
- an allow after the next reset
|
|
- bad leaves throw a code (fail closed)
|
|
|
|
**Changed:**
|
|
- token-limit.test.mjs: token-limit ignores `tokens.daily`.
|
|
- packages/business/tests (the launch schema test file, picked at build
|
|
time):
|
|
- a bad `reset` refuses the read
|
|
- a bad `timeZone` refuses the read (a non-IANA name, an offset, an
|
|
unknown zone)
|
|
- a bad `account` refuses the read
|
|
- a daily key that isn't the account refuses the read
|
|
- launch-settings tests: a daily leaf gets its `since` stamped and reset.
|
|
- bus:
|
|
- limits.test.mjs: `limitLeaves` walks `daily`.
|
|
- limit-checks.test.mjs or limits-runtime.test.mjs: daily-quota loaded
|
|
through the loader refuses at the quota and allows after the reset.
|
|
- limit-stop.test.mjs: a stop at the end of the turn that crosses it, with
|
|
`account` on the subject.
|
|
- usage-broker.test.mjs: records carry the bound account.
|
|
- launcher.test.mjs:
|
|
- the launch log names the account
|
|
- `account-credential-missing`
|
|
- `account-credential-ambiguous`
|
|
- a pi launch logs `account: null`
|
|
- `mayLaunch` gets the account
|
|
- cli limits test: the fixed line.
|
|
- webui limits-browser.test.mjs: the fixed line.
|
|
- Hash pins and path-reading tests: I grep tests for every manifest path and
|
|
for 64-hex pins on the changed files before in-review.
|
|
|
|
## Mutants (one each, with the test that kills it)
|
|
|
|
| # | Mutant | Killed by |
|
|
|---|---|---|
|
|
| D01 | never steps back to yesterday | the boundary test |
|
|
| D02 | window computed in UTC | the Chicago boundary test |
|
|
| D03 | offset taken once from `now` | the two DST-change tests |
|
|
| D04 | skipped reset uses Temporal-style +gap (03:30) | the skip test |
|
|
| D05 | repeated reset takes the later 01:30 | the repeat test |
|
|
| D06 | ignores `since` | the count test |
|
|
| D07 | ignores account | the count test |
|
|
| D08 | `>=` becomes `>` | the refusal-at-quota test |
|
|
| D09 | token-limit walks `daily` | the ignores-daily test |
|
|
| D10 | schema drops the `reset` check | the bad reset test |
|
|
| D11 | schema drops the `timeZone` check | the bad zone test |
|
|
| D12 | no cross-check of the daily key against the account | the cross-check test |
|
|
| D13 | launcher skips the missing-set refusal | the missing-set refusal test |
|
|
| D14 | launcher skips the ambiguity refusal | the ambiguity refusal test |
|
|
| D15 | launch log omits the account | the log test |
|
|
| D16 | usage inserts `NULL` | the usage-broker test |
|
|
| D17 | broker `mustStop` omits the account | the limit-stop test |
|
|
| D18 | runtime drops the account from `mayLaunch` | the bus refusal test |
|
|
| D19 | bus DEPTH lacks `daily` | the limitLeaves and bus refusal tests |
|
|
| D20 | settings DEPTH lacks `daily` | the stamp test |
|
|
| D21 | CLI line removed | the CLI test |
|
|
| D22 | webui line removed | the browser test |
|