feat(coding-agent): enforced RLM token budgets with per-depth schedules

[BeeGass]

Recursion depth is already capped by rlmMaxDepth, but nothing caps what a recursion tree spends. Node count grows as fanout^depth, so a per-agent limit does not bound total cost: three children per node at depth 8 is 9,840 agents, and a fixed per-agent allowance only makes each of them individually modest.

This adds a token budget for delegation, enforced by the host rather than requested in a prompt. The budget is what a chat may spend on subagents; the thread the user is talking to is never capped by it.

Usage

Budgeting a single delegation is the default path and needs no configuration:

await rlm("audit the retry logic", token_budget=200_000)
await rlm("quick lookup", token_budget=(50_000, 150_000))

The grant is drawn from the session's pool and bounds that child and every descendant it spawns. The recursion prompt instructs the model to size a budget for each delegation, so this is doctrine rather than an advanced option.

A tree-wide policy can also be set per chat or globally:

/rlm-token-budget                                show status
/rlm-token-budget 400k                           400k of subagent spend for this chat
/rlm-token-budget 200k-600k                      range form
/rlm-token-budget 1m --floor 50k --ceiling 400k  bound any single grant
/rlm-token-budget off

Resolution follows /rlm-max-depth: chat > inherited > global > env > default off. A subagent stops at inherited, because a child is funded by its parent and falling through to the global default would re-seed every child with a full root-sized budget, multiplying spend by fanout per depth instead of bounding it.

Allocation

There is one rule. A session holds a pool and decides for itself how much of it each child is worth. A grant is drawn from the pool and never returned, so the sum of everything a subtree receives is bounded by the budget however unevenly the caller allocates it:

/rlm-token-budget 1m   ->  pool 1000000
  token_budget=500_000 -> granted, 500000 left
  token_budget=300_000 -> granted, 200000 left
  token_budget=300_000 -> refused: 200000 tokens left to grant, 300000 needed

A range grants as much of its ceiling as the pool affords and refuses the child when even the floor cannot be met, so a child is never funded below the point where it could finish. A child spawned without token_budget= receives whatever is left, which is why the recursion prompt instructs the model to size every delegation. --floor and --ceiling bound any single grant.

Uneven allocation is deliberate: a caller may weight one child far above its siblings, and the pool remains the bound.

Enforcement

Three points, all in the host:

1. Between turns. shouldStopAfterTurn ends the loop once the allowance is spent. The turn that crossed it is preserved.
2. At prompt admission. The agent loop always runs at least one turn per prompt (shouldStopBeforeTurn is gated on !firstTurn), so an exhausted session refuses new prompts. Without this the cap would be a cap plus one fully charged turn for every later message.
3. At spawn. runRlmChild reserves the child allowance after the last failure path and before any session state exists, then refuses when the schedule cannot fund a child.

Aborting is deliberately not used. An aborted turn reports stopReason: "aborted", which accounting refuses to charge, so aborting on overrun would silently un-charge the turn that tripped the limit.

Durability and visibility

Spend is persisted with the session, so resuming a chat resumes its remaining allowance, and a subagent rehydrated after a daemon restart keeps the grant it was spawned with rather than running unbudgeted.

When a budget stops a run the interactive client explains it instead of the session going quiet:

RLM token budget spent: 512345 of 500000 tokens used.
This run stopped at the end of the turn; later turns stop the same way until the budget changes.
Raise it with /rlm-token-budget <tokens> or turn it off with /rlm-token-budget off.

The active allowance is also stated in the system prompt so the model can wrap up rather than being cut off mid-thought, and budgeted rows in the agents view show budget 12k/500k.

Daemon protocol

Adds get_rlm_token_budget_status and set_rlm_token_budget, gated at DAEMON_SCHEMA_REVISION 16 with DAEMON_PROTOCOL_VERSION held at 7, following the additive schema-gated precedent rather than bumping the protocol. DAEMON_SCHEMA_ID is recomputed, the getter is classified read-only, and both DAEMON_COMMAND_TYPES allowlists are updated. Both compatibility directions are tested: a new client writes nothing to a daemon at the preceding revision and throws DaemonCapabilityUnavailableError before any socket write; a daemon at revision 16 accepts.

Compatibility

The change is additive: +2523 / -4 across 35 files. The four deletions are the rlm.run kwarg contract, the schema revision, its digest, and one test import.

With no budget configured the feature is inert, and this is asserted rather than assumed: no budget state, unchanged spawn behaviour, an agent loop that is never stopped, and no new kernel environment variables.

Verification

npm run check exits 0. The budget-touching suites are 676 tests across 14 files, all passing.

The full suite was run on this branch and on unmodified upstream/main for comparison. This branch
introduces no new failing test file. The failures that remain are the same pre-existing ones on both
sides: they spawn real daemons and reach the network.

Two rounds of adversarial review were run against the implementation, the second after the design was
simplified. The second round found that the central invariant did not actually hold, and the fixes for
that are the last commit on the branch. Each has a regression test:

• The pool was read stale, so a subagent that had spent most of its grant still delegated the full
  amount. Chained three deep this spent 270k tokens under a 100k budget.
• Branch navigation reset spend from the branch, refunding grants whose children were still running.
• /rlm-token-budget off inside a subagent removed a cap its parent had imposed.
• Daemon rehydration recorded what was left of a grant rather than the grant, so a resumed child came
  back smaller than its parent had funded.

Reviewing this

The commits are ordered to be read in sequence. The first two add the feature; the middle ones fix defects found in an adversarial review of that first draft (a refilling pool, a leaked reservation, a silent stop); the last two are the design corrections that came out of using it, and are the ones worth reading closely: fix: budget delegation, not the thread the user is talking to, and refactor: let the caller allocate the budget instead of a schedule, which removes the per-depth schedules in favour of one allocation rule.

Worth attention:

• _reserveRlmChildAllowance and _applyRlmTokenBudgetAllowance in agent-session.ts, which hold the bound; between them they are the whole allocation model.
• The prompt-admission refusal, which is the one place the enforcement is not in the agent loop.
• DAEMON_SCHEMA_ID, which is a digest over the wire types and will fail its test if the shapes drift.

Known limitations

• Enforcement granularity is one turn. A session is stopped at the first turn boundary after it crosses
  its grant, so a subagent funded below the cost of a single turn still overshoots once. The budget
  bounds how much work is started, not the cost of work already in flight.
• A spawn that fails after its reservation keeps the grant. The tokens are not returned to the pool, so
  a transient runtime failure permanently costs the pool that grant. Refunding it is not obviously safe:
  a child that started may already have spent, and the test doubles that abort spawns cannot be
  distinguished from real failures at that point. Left as a known cost rather than a risky refund.
• A budget bounds tokens, not wall-clock or concurrency.
• The interactive surfaces are covered by prototype-level tests plus manual exercise of
  /rlm-token-budget, not an automated TUI round trip. The exhaustion notice in particular has been
  asserted in tests but not yet observed rendering in a live terminal.

Note

Enforce RLM token budgets with per-depth schedules across subagent sessions

• Introduces a token budgeting system for RLM subagents: each session can be given a token allowance that is tracked, persisted, and enforced across the subagent tree.
• Adds rlm-token-budget.ts as a central module for budget types, validation, token parsing (k/m suffixes), and the /rlm-token-budget command parser.
• AgentSession resolves budget config from chat state, inherited config, global settings, or env; refuses to spawn subagents when the pool is drained and emits an rlm_token_budget_exhausted event at turn boundaries.
• The daemon protocol is bumped to schema revision 16 with two new commands (get_rlm_token_budget_status, set_rlm_token_budget) gated at minSchemaRevision: 16.
• Interactive mode gains a /rlm-token-budget slash command for viewing and updating budgets per-chat or globally, and surfaces exhaustion notices in the transcript.
• Budget config and spend/grant counters are persisted in session history so they survive resume and branch navigation; branch switches preserve maximum recorded spend rather than resetting it.
• Risk: sessions with an exhausted allowance will refuse to admit new turns, which is a hard stop for any subagent that has consumed its grant.

^{Macroscope summarized 074113c.}

[BeeGass]

Update on what's landed since I opened this: 7 commits, net -247 lines. It got smaller, which wasn't the plan but is probably the right outcome.

Two of them are design fixes that only showed up once I actually used the thing.

Setting a 3000 budget and just talking to the agent printed spent 7477 of 1500 in my own thread. It was capping the conversation rather than the delegation, which isn't what a delegation budget is for. Depth 0 is never charged now, and the whole budget is the pool it hands out (143e7aaf5).

The per-depth schedules are gone (3553f9882, -707 lines). Deriving each grant from depth, factor and fanout took the decision away from the agent writing the child's task, and stranded tokens on siblings that never got spawned. A session now just holds a pool and spends it however it likes. Same bound, far less machinery, and it's the reason flat/geometric/split no longer exist.

Then a second review found the bound wasn't actually holding (29cc5e918). The pool was read stale, so a subagent that had spent 90k of a 100k grant still handed out a full 100k downstream: 270k spent under a 100k budget three levels deep. Same commit fixes branch navigation refilling the pool, /rlm-token-budget off inside a subagent lifting the cap its parent set, and daemon rehydration shrinking resumed children. All four have regression tests.

The rest is cleanup: a changelog bullet I'd accidentally appended to the frozen 0.0.1 entry, a dead export encoding the opposite policy to the one that ships, and some duplicated prompt text.

Still true: enforcement lands on turn boundaries, so a child funded below one turn's cost overshoots once. And a spawn that dies after its reservation keeps the grant. I tried refunding that and reverted it, since a child that already started may have spent, and at that point the two look the same.