feat(chat): per-user daily token budget for non-admin users (#62)

[gangtao]

Implements the token-budget half of #62 (question cap deferred, per your call).

What

Operators can cap daily LLM token consumption per non-admin user. admin is exempt. The limit is per-role (daily_token_limit), with a global fallback via config.

How

• Metering — the /chat handler sums usage_metadata tokens across every model call in a turn (the tool loop makes several), with a response_metadata fallback for gateways that only pass the raw shape.
• Storage — an append-only chat_usage stream (ts, username, tokens), written independent of TPK_CHAT_AUDIT so the budget can't be silently disabled by turning auditing off. Reads fail open (an unreachable store never wrongly blocks a user); writes are best-effort.
• Limits — kg_roles.daily_token_limit (uint32, _add_column_if_missing migration; existing roles → 0 = unlimited). Effective limit = the role's own, else the global TPK_DAILY_TOKEN_LIMIT / [server].daily_token_limit (0 = unlimited).
• Enforcement — before running the agent, a non-admin at/over budget gets HTTP 429 with a friendly message + reset time (next UTC midnight). Enforcement is inherently next-turn (a turn's cost is only known once it runs), so the crossing turn completes and the next is blocked.
• UI — role editor gains a "Daily token budget per user" field (add + edit); the chat surfaces the 429 with the server's reset message instead of a bare HTTP code.

Enforcement/metering are only active when a usage store is present (built in the production path), so existing unit tests that inject a fake agent are untouched and never hit a DB.

Caveat (documented in the issue)

Some gateways omit usage_metadata — those turns count as 0 tokens (free). A token budget is only as good as the meter; verify against your gateway.

Tests / verification

• 118 unit tests pass (+11 new): usage helpers + fail-open, config precedence, enforcement (over / under / admin-bypass / no-store), metering.
• Backend round-trips (role limit, daily per-user count) added for both backends.
• Verified end-to-end on live timeplusd: schema, role-limit round-trip, and per-user daily counting.
• web build + check:sanitize green.

🤖 Generated with Claude Code

[gangtao]

Added user-facing budget display (commit c05ca94): a new GET /chat/usage returns {limited, used, limit, remaining, reset} for the current user, and the chat UI shows used / limit, tokens left, and the reset time in the header and empty state — refreshed on load and after each turn. limited: false (admins / unlimited / no store) shows no indicator. 120 unit tests green; web build + sanitize pass.

[gangtao]

Code review

Found 2 issues:

1. A role/user daily_token_limit of 0 means "inherit the next level down", but the role-level comments, the API error, and the role UI label all call it "unlimited". Since the global default is now 500000, setting a role to 0 silently caps it at 500000, not unlimited — the opposite of what the label says. effective_daily_limit's own docstring ("0 at every level means unlimited") contradicts its code, which falls through role 0 to the global default. The per-user field is already labeled correctly ("0 = inherit role/global"); the role level and the shared docstring should match.

timeplus-knowledge/src/tpk/usage.py

Lines 24 to 33 in 802adfa

	def effective_daily_limit(user_limit: int, role, global_default: int) -> int:
	"""The daily token budget that applies to a user, by precedence (#62):
	the user's own override, else their role's limit, else the global fallback.
	0 at every level means unlimited. `role` may be a Role or None (an
	unreadable/absent role falls through to the global)."""
	ul = int(user_limit or 0)
	if ul > 0:
	return ul
	role_limit = getattr(role, "daily_token_limit", 0) or 0
	return int(role_limit) if role_limit > 0 else max(int(global_default), 0)

timeplus-knowledge/src/tpk/auth.py

Lines 91 to 94 in 802adfa

	capabilities: list[str] = field(default_factory=lambda: list(DEFAULT_CAPABILITIES))
	# Daily per-user token budget for members of this role (0 = unlimited). See
	# #62; a global fallback (config.daily_token_limit) applies when this is 0.
	daily_token_limit: int = 0

2. daily_token_limit bypasses the bounded-delegation guard. _guard_grant bounds only capabilities and entry_keys against the actor's own grant, so a non-admin users:manage delegate can set any manageable user's or role's daily_token_limit to 0/inherit or an arbitrarily large value — handing out unlimited LLM spend through the very endpoints feat: role-based function capabilities across API + UI (closes #23) #24 hardened against privilege escalation. Recommend restricting daily_token_limit changes to admin.

timeplus-knowledge/src/tpk/api.py

Lines 429 to 436 in 802adfa

	existing = auth_mod.get_role(client, body.name, prefix=prefix)
	if existing is not None:
	_guard_grant(client, actor, existing.capabilities, existing.entry_keys)
	_guard_grant(client, actor, caps, body.entry_keys)
	auth_mod.upsert_role(client, auth_mod.Role(
	body.name, body.entry_keys, body.description, caps,
	daily_token_limit=body.daily_token_limit), prefix=prefix)
	return {"ok": True}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[gangtao]

Both issues fixed in b3d45ef:

1. Relabeled role/user daily_token_limit of 0 as "inherit" (not "unlimited") across the comments, API error, effective_daily_limit docstring, and role UI labels; corrected the /chat/usage docstring. Added a precedence test that a role limit of 0 inherits the global default.
2. Added _guard_token_limit — only an admin may change a per-user/role token budget; a non-admin users:manage delegate can still manage users/roles as long as the budget is unchanged (403 otherwise). New test_manager_cannot_set_token_budget, verified against live timeplusd.

Full suite green; web build + sanitize pass.