M26-4: audit + spec out real usage_threshold_tokens enforcement #551
Labels
No labels
area:agents
area:dashboard
area:database
area:design
area:design-review
area:flows
area:infra
area:meta
area:security
area:sessions
area:webhook
area:workdir
security
type:bug
type:chore
type:meta
type:user-story
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
charles/claude-hooks#551
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
As an operator, I want
usage_threshold_tokensto actually halt or fail-over an agent when its token budget is exhausted, so that the dashboard ring (today purely cosmetic) reflects a real safety brake and the failover chain (M26-1) can includetoken_budgetas a trigger.Background
Audit performed during M26 design (PR #547 review):
usage_threshold_tokensinconfig/service.jsonis parsed by the loader →webhook-config.tsexposes it asusageThresholdTokens: number | null.apps/server/src/main.ts::handleUsageechoes it back onGET /usageasthreshold_tokens.M26-1's
failover.triggersenum deliberately excludestoken_budgetbecause the trigger has nothing to detect today. This ticket is the prerequisite that brings it back.Acceptance criteria
Audit (deliverable:
docs/specs/token-budget.md)usageThresholdTokensin the codebase. Document the count and call sites.computeUsage()already tracks: window granularity (week/day/all), per-agent vs. global, token type breakdown (input/output/cache).usage_resetknob ("week" | "day" | "all") or gets a new one.Implementation spec (in the same doc)
failover.triggers: whentoken_budgetis enabled and the active window's usage ≥ threshold, fire the same tier-bump path asauth_errorso failover state is unified.Follow-up tickets
Out of scope
References
failover.triggersenum that this story re-enables.apps/server/src/shared/config/webhook-config.ts:469(declaration)apps/server/src/main.ts:1390(handleUsage)apps/server/src/shared/config/service-config-schema.ts(Zod field)Audit shipped in PR #552 (
docs/specs/token-budget.md). Reference cleanups in PR #552 review fixup commit. M26-5/6/7 implementation also shipped in PR #552 follow-up commit (operator opted to skip filing separate tickets and bundle them):usage_threshold_tokens+ post-task hook +recordExternalTriggerglue. Loader rejects negative/non-int, stripstoken_budgetfrom single-tier chains, accepts on multi-tier. Audit'susage_reset: "all"caveat respected — gate skips when window is"all".last_failure_kind === "token_budget". Distinct from auth/rate-limit failures at a glance.Audit-doc cleanup landed in PR #552 review fixup: corrected file:line refs, fixed
UsageResultshape snippet (totalsnottotal_tokens,windowis object), called outusage_reset: "all"edge case, dual-cap UX caveat, repointed post-task hook reference fromagent-runner.ts:489(helper) to:981(M26-1 classifier hook).Closing — audit + spec + implementation all on main.