diff --git a/app/lib/features/chat/conversation/chat_account_usage_section.dart b/app/lib/features/chat/conversation/chat_account_usage_section.dart new file mode 100644 index 00000000..2fe0346b --- /dev/null +++ b/app/lib/features/chat/conversation/chat_account_usage_section.dart @@ -0,0 +1,173 @@ +import 'dart:async'; + +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; + +import '../domain/chat_account_usage.dart'; + +/// The info sheet's "Account usage" section: one progress bar per quota +/// window the harness reported, the plan and the report's age. It draws +/// nothing for an unknown quota, and one muted line when the harness has no +/// quota API. Reset countdowns tick while the sheet is open. +class ChatAccountUsageSection extends StatefulWidget { + const ChatAccountUsageSection({ + super.key, + required this.usage, + required this.cupertino, + this.now = DateTime.now, + }); + + final ChatAccountUsage? usage; + final bool cupertino; + final DateTime Function() now; + + @override + State createState() => + _ChatAccountUsageSectionState(); +} + +class _ChatAccountUsageSectionState extends State { + Timer? _tick; + + @override + void initState() { + super.initState(); + _tick = Timer.periodic(const Duration(seconds: 30), (_) { + if (mounted) setState(() {}); + }); + } + + @override + void dispose() { + _tick?.cancel(); + super.dispose(); + } + + @override + Widget build(BuildContext context) { + final usage = widget.usage; + if (usage == null) return const SizedBox.shrink(); + final cupertino = widget.cupertino; + final now = widget.now(); + final secondary = cupertino + ? CupertinoColors.secondaryLabel.resolveFrom(context) + : Theme.of(context).colorScheme.onSurfaceVariant; + final body = cupertino + ? CupertinoTheme.of(context).textTheme.textStyle + : Theme.of(context).textTheme.bodyMedium; + final title = cupertino + ? CupertinoTheme.of( + context, + ).textTheme.textStyle.copyWith(fontWeight: FontWeight.w600) + : Theme.of(context).textTheme.titleSmall; + final muted = body?.copyWith(color: secondary); + final asOf = chatQuotaAsOf(usage.asOf, now); + final plan = chatPlanLabel(usage.plan); + return Padding( + key: const Key('chat-account-usage'), + padding: const EdgeInsetsDirectional.fromSTEB(24, 12, 24, 6), + child: Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text('Account usage', style: title), + if (usage.unsupported) + Padding( + padding: const EdgeInsets.only(top: 4), + child: Text( + 'Not reported by ${usage.harness}', + key: const Key('chat-account-usage-unsupported'), + style: muted, + ), + ) + else ...[ + if (plan.isNotEmpty) + Padding( + padding: const EdgeInsets.only(top: 4), + child: Text( + usage.harness.isEmpty + ? '$plan plan' + : '${usage.harness} · $plan plan', + key: const Key('chat-account-usage-plan'), + style: muted, + ), + ), + for (final window in usage.windows) + _QuotaWindowRow( + window: window, + now: now, + cupertino: cupertino, + body: body, + muted: muted, + ), + if (asOf.isNotEmpty) + Padding( + padding: const EdgeInsets.only(top: 6), + child: Text( + asOf, + key: const Key('chat-account-usage-as-of'), + style: muted, + ), + ), + ], + ], + ), + ); + } +} + +class _QuotaWindowRow extends StatelessWidget { + const _QuotaWindowRow({ + required this.window, + required this.now, + required this.cupertino, + required this.body, + required this.muted, + }); + + final ChatQuotaWindow window; + final DateTime now; + final bool cupertino; + final TextStyle? body; + final TextStyle? muted; + + @override + Widget build(BuildContext context) { + final summary = chatQuotaSummary(window, now); + final fraction = (window.usedPercent / 100).clamp(0.0, 1.0); + final high = window.usedPercent >= 90; + // Cupertino has no linear progress control; the standard indicator is + // drawn with the system fill and tint colors, like UIProgressView. + final bar = cupertino + ? LinearProgressIndicator( + value: fraction, + backgroundColor: CupertinoColors.systemFill.resolveFrom(context), + color: + (high ? CupertinoColors.systemRed : CupertinoColors.activeBlue) + .resolveFrom(context), + borderRadius: BorderRadius.circular(2), + semanticsLabel: '${window.label} quota', + ) + : LinearProgressIndicator( + value: fraction, + color: high ? Theme.of(context).colorScheme.error : null, + borderRadius: BorderRadius.circular(2), + semanticsLabel: '${window.label} quota', + ); + return Padding( + key: Key('chat-account-window-${window.id}'), + padding: const EdgeInsets.only(top: 8), + child: Column( + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Text(window.label, style: body), + Padding(padding: const EdgeInsets.symmetric(vertical: 4), child: bar), + Text( + summary, + key: Key('chat-account-window-summary-${window.id}'), + style: muted, + ), + ], + ), + ); + } +} diff --git a/app/lib/features/chat/conversation/chat_thread_controller.dart b/app/lib/features/chat/conversation/chat_thread_controller.dart index 1b7dcdff..d70bdf4e 100644 --- a/app/lib/features/chat/conversation/chat_thread_controller.dart +++ b/app/lib/features/chat/conversation/chat_thread_controller.dart @@ -4,6 +4,7 @@ import 'package:flutter/foundation.dart'; import '../../../core/api_gateway.dart'; import '../data/chat_repository.dart'; +import '../domain/chat_account_usage.dart'; import '../domain/chat_sessions.dart'; import '../domain/chat_transcript.dart'; import 'chat_server_queue.dart'; @@ -73,6 +74,7 @@ class ChatThreadController extends ChangeNotifier { String? _liveAssistantMessageId; String? _awaitingResponseOperation; JsonMap? _usage; + ChatAccountUsage? _accountUsage; String? _error; bool _subscribed = false; @@ -147,6 +149,10 @@ class ChatThreadController extends ChangeNotifier { /// Unknown fields stay null, so a viewer can distinguish them from zero. JsonMap? get usage => _usage; + /// The harness account's latest reported quota, or null while unknown. It + /// is account state: a frame without one keeps the last known value. + ChatAccountUsage? get accountUsage => _accountUsage; + String? get error => _error; bool get subscribed => _subscribed; String? get subscriptionError => _subscriptionError; @@ -348,8 +354,14 @@ class ChatThreadController extends ChangeNotifier { // Usage replaces the last snapshot and never adds a message, runs a turn // or admits a queued prompt. An unusable snapshot keeps the previous // recorded values instead of replacing them with fabricated zeros. - final usage = chatUsageSnapshot(body['usage']); - if (usage == null || !_reportedUsage(usage)) return; + final raw = body['usage']; + final account = chatAccountUsage(raw is Map ? raw['account'] : null); + if (account != null) _accountUsage = account; + final usage = chatUsageSnapshot(raw); + if (usage == null || !_reportedUsage(usage)) { + if (account != null) _notify(transcript: false); + return; + } _usage = usage; _notify(transcript: false); return; diff --git a/app/lib/features/chat/conversation/chat_thread_view.dart b/app/lib/features/chat/conversation/chat_thread_view.dart index 79b7fc97..9ded817f 100644 --- a/app/lib/features/chat/conversation/chat_thread_view.dart +++ b/app/lib/features/chat/conversation/chat_thread_view.dart @@ -17,6 +17,7 @@ import '../ui/sessions/session_actions.dart'; import '../ui/transcript/chat_markdown_view.dart'; import '../ui/transcript/chat_message_view.dart'; import '../ui/transcript/chat_injected_rows.dart'; +import 'chat_account_usage_section.dart'; import 'chat_background_tasks.dart'; import 'chat_command_actions.dart'; import 'chat_composer_bar.dart'; @@ -1530,6 +1531,10 @@ class _ChatInfoSheet extends StatelessWidget { ), for (final metric in _chatInfoMetrics(controller.usage)) _ChatInfoRow(metric: metric, cupertino: cupertino), + ChatAccountUsageSection( + usage: controller.accountUsage, + cupertino: cupertino, + ), Padding( padding: const EdgeInsetsDirectional.fromSTEB(24, 8, 24, 16), child: Text( diff --git a/app/lib/features/chat/domain/chat_account_usage.dart b/app/lib/features/chat/domain/chat_account_usage.dart new file mode 100644 index 00000000..3b8a773a --- /dev/null +++ b/app/lib/features/chat/domain/chat_account_usage.dart @@ -0,0 +1,130 @@ +/// The harness account's subscription quota, as carried by a usage frame's +/// `usage.account` (see docs/cli.md). Only reported values are kept: a window +/// without a usable percentage is dropped and nothing is estimated. +library; + +/// One rolling quota window, e.g. "5-hour" or "Weekly". +class ChatQuotaWindow { + const ChatQuotaWindow({ + required this.id, + required this.label, + required this.usedPercent, + required this.resetsAt, + }); + + final String id; + final String label; + + /// 0–100; a harness may report more than 100 past a cap. + final double usedPercent; + + /// Epoch milliseconds, 0 when the harness did not say. + final int resetsAt; +} + +class ChatAccountUsage { + const ChatAccountUsage({ + required this.harness, + required this.plan, + required this.asOf, + required this.windows, + required this.unsupported, + }); + + /// Display name of the harness ("Claude Code", "Codex", "OpenCode"). + final String harness; + final String plan; + + /// Epoch milliseconds when the server received the report, 0 if unknown. + final int asOf; + final List windows; + + /// The harness exposes no quota at all. + final bool unsupported; +} + +int _millis(Object? value) => + value is num && value.isFinite && value > 0 ? value.toInt() : 0; + +/// Parses `usage.account`, or null when it reports nothing usable. +ChatAccountUsage? chatAccountUsage(Object? value) { + if (value is! Map) return null; + final harness = '${value['harness'] ?? ''}'.trim(); + if (value['unsupported'] == true) { + return ChatAccountUsage( + harness: harness.isEmpty ? 'the harness' : harness, + plan: '', + asOf: 0, + windows: const [], + unsupported: true, + ); + } + final windows = []; + final raw = value['windows']; + if (raw is List) { + for (final entry in raw) { + if (entry is! Map) continue; + final percent = entry['used_percent']; + final label = '${entry['label'] ?? ''}'.trim(); + if (percent is! num || !percent.isFinite || percent < 0) continue; + if (label.isEmpty) continue; + windows.add( + ChatQuotaWindow( + id: '${entry['id'] ?? label}', + label: label, + usedPercent: percent.toDouble(), + resetsAt: _millis(entry['resets_at']), + ), + ); + } + } + if (windows.isEmpty) return null; + return ChatAccountUsage( + harness: harness, + plan: '${value['plan'] ?? ''}'.trim(), + asOf: _millis(value['as_of']), + windows: List.unmodifiable(windows), + unsupported: false, + ); +} + +/// "42% used · resets in 2h 14m". The percentage is rounded, never clamped. +String chatQuotaSummary(ChatQuotaWindow window, DateTime now) { + final used = '${window.usedPercent.round()}% used'; + if (window.resetsAt <= 0) return used; + final left = DateTime.fromMillisecondsSinceEpoch( + window.resetsAt, + ).difference(now); + if (left.isNegative) return '$used · reset since this report'; + return '$used · resets in ${_countdown(left)}'; +} + +String _countdown(Duration left) { + if (left.inMinutes < 1) return 'under a minute'; + final days = left.inDays; + final hours = left.inHours % 24; + final minutes = left.inMinutes % 60; + if (days > 0) return hours > 0 ? '${days}d ${hours}h' : '${days}d'; + if (left.inHours > 0) { + return minutes > 0 ? '${left.inHours}h ${minutes}m' : '${left.inHours}h'; + } + return '${minutes}m'; +} + +/// "as of 5 min ago"; empty when the report time is unknown. +String chatQuotaAsOf(int asOf, DateTime now) { + if (asOf <= 0) return ''; + final age = now.difference(DateTime.fromMillisecondsSinceEpoch(asOf)); + if (age.inMinutes < 1) return 'as of just now'; + if (age.inHours < 1) return 'as of ${age.inMinutes} min ago'; + if (age.inDays < 1) return 'as of ${age.inHours} h ago'; + return 'as of ${age.inDays} d ago'; +} + +/// A native plan id as a label: "max" -> "Max", "self_serve_business" -> +/// "Self serve business". +String chatPlanLabel(String plan) { + final words = plan.replaceAll('_', ' ').trim(); + if (words.isEmpty) return ''; + return words[0].toUpperCase() + words.substring(1); +} diff --git a/app/notes/chat-account-usage.md b/app/notes/chat-account-usage.md new file mode 100644 index 00000000..1bf1e864 --- /dev/null +++ b/app/notes/chat-account-usage.md @@ -0,0 +1,13 @@ +# Chat info: account usage + +The chat information sheet shows an "Account usage" section from +`usage.account` (wire shape in docs/cli.md): one LinearProgressIndicator per +reported window ("42% used · resets in 2h 14m"), the plan and "as of ". +Cupertino draws the same indicator in system fill/tint colors, since Cupertino +has no linear progress control. An unknown quota hides the section; OpenCode +(no quota API) shows "Not reported by OpenCode". Countdowns tick every 30 s. + +Evidence: `test/features/chat/conversation/chat_account_usage_test.dart` +(both hosts), and captures from the probe fixture with `?chats=1"a=claude` +or `quota=opencode` (`tool/perf/perf_fixture.dart`), opened at +`/chat/perf-chat-0` and clicking the title, 560x1000, Material and Cupertino. diff --git a/app/test/features/chat/conversation/chat_account_usage_test.dart b/app/test/features/chat/conversation/chat_account_usage_test.dart new file mode 100644 index 00000000..dc29f34c --- /dev/null +++ b/app/test/features/chat/conversation/chat_account_usage_test.dart @@ -0,0 +1,230 @@ +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/chat/conversation/chat_thread_view.dart'; +import 'package:pipelines_app/features/chat/domain/chat_account_usage.dart'; + +import 'chat_thread_fixtures.dart'; + +Widget _host(Widget child) => MaterialApp( + theme: ThemeData(platform: TargetPlatform.android), + home: Scaffold(body: child), +); + +Widget _cupertinoHost(Widget child) => CupertinoApp( + theme: const CupertinoThemeData(brightness: Brightness.dark), + home: CupertinoPageScaffold(child: child), +); + +JsonMap _usageFrame(JsonMap usage) => { + 'session_id': 's', + 'kind': 'usage', + 'usage': usage, +}; + +/// Synthetic numbers in the server's `usage.account` wire shape. +JsonMap _claudeAccount(DateTime now) => { + 'harness': 'Claude Code', + 'source': 'rate_limit_event', + 'plan': 'max', + 'as_of': now.millisecondsSinceEpoch, + 'windows': [ + { + 'id': 'five_hour', + 'label': '5-hour', + 'used_percent': 42, + 'resets_at': now + .add(const Duration(hours: 2, minutes: 14, seconds: 40)) + .millisecondsSinceEpoch, + }, + { + 'id': 'seven_day', + 'label': 'Weekly', + 'used_percent': 93.4, + 'resets_at': now + .add(const Duration(days: 3, hours: 5, minutes: 10)) + .millisecondsSinceEpoch, + }, + ], +}; + +Future _thread( + WidgetTester tester, { + bool cupertino = false, +}) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + gateway.history = (_) async => chatPage([]); + final thread = ChatThreadView( + gateway: gateway, + sessionId: 's', + onBack: () {}, + ); + await tester.pumpWidget(cupertino ? _cupertinoHost(thread) : _host(thread)); + await tester.pumpAndSettle(); + return gateway; +} + +Future _openInfo(WidgetTester tester) async { + await tester.tap(find.byKey(const Key('chat-info'))); + await tester.pumpAndSettle(); +} + +void main() { + group('domain', () { + final now = DateTime.utc(2026, 11, 2, 12); + + test('parses reported windows and drops unusable ones', () { + final usage = chatAccountUsage({ + 'harness': 'Codex', + 'plan': 'plus', + 'as_of': now.millisecondsSinceEpoch, + 'windows': [ + {'id': 'primary', 'label': '5-hour', 'used_percent': 37}, + {'id': 'bad', 'label': 'Bad', 'used_percent': 'x'}, + {'id': 'neg', 'label': 'Neg', 'used_percent': -1}, + {'id': 'nolabel', 'used_percent': 5}, + ], + })!; + expect(usage.harness, 'Codex'); + expect(usage.windows.map((w) => w.id), ['primary']); + expect(usage.windows.single.resetsAt, 0); + expect(chatQuotaSummary(usage.windows.single, now), '37% used'); + }); + + test('unknown quota is null; an unsupported harness is explicit', () { + expect(chatAccountUsage(null), isNull); + expect(chatAccountUsage({'harness': 'Codex', 'windows': []}), isNull); + final none = chatAccountUsage({ + 'harness': 'OpenCode', + 'unsupported': true, + })!; + expect(none.unsupported, isTrue); + expect(none.harness, 'OpenCode'); + }); + + test('countdown and report age wording', () { + ChatQuotaWindow window(Duration left) => ChatQuotaWindow( + id: 'w', + label: 'W', + usedPercent: 99.6, + resetsAt: now.add(left).millisecondsSinceEpoch, + ); + expect( + chatQuotaSummary(window(const Duration(hours: 2, minutes: 14)), now), + '100% used · resets in 2h 14m', + ); + expect( + chatQuotaSummary(window(const Duration(minutes: 9)), now), + '100% used · resets in 9m', + ); + expect( + chatQuotaSummary(window(const Duration(seconds: 20)), now), + '100% used · resets in under a minute', + ); + expect( + chatQuotaSummary(window(const Duration(days: 2, hours: 3)), now), + '100% used · resets in 2d 3h', + ); + expect( + chatQuotaSummary(window(const Duration(minutes: -5)), now), + '100% used · reset since this report', + ); + final at = now.millisecondsSinceEpoch; + expect(chatQuotaAsOf(at, now), 'as of just now'); + expect(chatQuotaAsOf(at - 5 * 60000, now), 'as of 5 min ago'); + expect(chatQuotaAsOf(at - 3 * 3600000, now), 'as of 3 h ago'); + expect(chatQuotaAsOf(0, now), ''); + expect(chatPlanLabel('self_serve_business'), 'Self serve business'); + }); + }); + + for (final cupertino in [false, true]) { + final host = cupertino ? 'Cupertino' : 'Material'; + + testWidgets('$host: account usage shows windows, plan and age', ( + tester, + ) async { + final gateway = await _thread(tester, cupertino: cupertino); + gateway.emitEvent( + _usageFrame({ + 'scope': 'session', + 'total_tokens': 1200, + 'account': _claudeAccount(DateTime.now()), + }), + ); + await tester.pump(); + await _openInfo(tester); + + expect(find.text('Account usage'), findsOneWidget); + expect(find.text('Claude Code · Max plan'), findsOneWidget); + expect(find.text('5-hour'), findsOneWidget); + expect(find.text('42% used · resets in 2h 14m'), findsOneWidget); + expect(find.text('Weekly'), findsOneWidget); + expect(find.text('93% used · resets in 3d 5h'), findsOneWidget); + expect(find.text('as of just now'), findsOneWidget); + final bars = tester + .widgetList( + find.byType(LinearProgressIndicator), + ) + .toList(); + expect(bars.map((bar) => bar.value), [ + closeTo(.42, 1e-9), + closeTo(.934, 1e-9), + ]); + expect(bars.first.semanticsLabel, '5-hour quota'); + // Token metrics are still shown beside the quota. + expect(find.text('1,200'), findsOneWidget); + }); + + testWidgets( + '$host: unknown quota hides the section; no-API harness says so', + (tester) async { + final gateway = await _thread(tester, cupertino: cupertino); + gateway.emitEvent(_usageFrame({'scope': 'session', 'total_tokens': 5})); + await tester.pump(); + await _openInfo(tester); + expect(find.byKey(const Key('chat-account-usage')), findsNothing); + expect(find.text('Account usage'), findsNothing); + expect(find.byType(LinearProgressIndicator), findsNothing); + + gateway.emitEvent( + _usageFrame({ + 'scope': 'session', + 'total_tokens': 6, + 'account': {'harness': 'OpenCode', 'unsupported': true}, + }), + ); + await tester.pumpAndSettle(); + expect(find.text('Account usage'), findsOneWidget); + expect(find.text('Not reported by OpenCode'), findsOneWidget); + expect(find.byType(LinearProgressIndicator), findsNothing); + }, + ); + } + + testWidgets('an account-only frame keeps the recorded token metrics', ( + tester, + ) async { + final gateway = await _thread(tester); + gateway.emitEvent( + _usageFrame({'scope': 'session', 'total_tokens': 132408}), + ); + await tester.pump(); + gateway.emitEvent(_usageFrame({'account': _claudeAccount(DateTime.now())})); + await tester.pump(); + await _openInfo(tester); + + expect(find.text('132,408'), findsOneWidget); + expect(find.text('42% used · resets in 2h 14m'), findsOneWidget); + + // A later frame without an account keeps the last known quota. + gateway.emitEvent( + _usageFrame({'scope': 'session', 'total_tokens': 140000}), + ); + await tester.pumpAndSettle(); + expect(find.text('140,000'), findsOneWidget); + expect(find.text('42% used · resets in 2h 14m'), findsOneWidget); + }); +} diff --git a/app/tool/perf/perf_fixture.dart b/app/tool/perf/perf_fixture.dart index 42081073..28918602 100644 --- a/app/tool/perf/perf_fixture.dart +++ b/app/tool/perf/perf_fixture.dart @@ -5,7 +5,9 @@ // `?hits=N` N more `release` run hits in Search; // `?chats=N` N chat sessions in the chat list, each opening a short // markdown transcript; -// `?graph=1` run 7 carries its pinned graph (plan -> build). +// `?graph=1` run 7 carries its pinned graph (plan -> build); +// `?quota=claude|opencode` (with `?chats=N`) pushes a usage frame with +// that harness's account quota after a chat subscribes. import 'package:pipelines_app/core/api_gateway.dart'; Map _params = const {}; @@ -16,6 +18,56 @@ int get _hits => int.tryParse(_params['hits'] ?? '') ?? 0; int get _chats => int.tryParse(_params['chats'] ?? '') ?? 0; bool get perfRunGraph => _params['graph'] == '1'; +/// Unsolicited envelopes that follow a reply: the `?quota=` usage frame. +List perfChatFollowUps(JsonMap request) { + final quota = _params['quota']; + if (_chats == 0 || quota == null || request['type'] != 'chat_subscribe') { + return const []; + } + final now = DateTime.now(); + int at(Duration offset) => now.add(offset).millisecondsSinceEpoch; + final account = quota == 'opencode' + ? {'harness': 'OpenCode', 'unsupported': true} + : { + 'harness': 'Claude Code', + 'source': 'rate_limit_event', + 'plan': 'max', + 'as_of': at(const Duration(minutes: -4)), + 'windows': [ + { + 'id': 'five_hour', + 'label': '5-hour', + 'used_percent': 42, + 'resets_at': at( + const Duration(hours: 2, minutes: 14, seconds: 30), + ), + }, + { + 'id': 'seven_day', + 'label': 'Weekly', + 'used_percent': 93, + 'resets_at': at(const Duration(days: 3, hours: 5)), + }, + ], + }; + return [ + { + 'type': 'chat_event', + 'chat_event': { + 'session_id': (request['chat_subscribe'] as Map?)?['session_id'], + 'kind': 'usage', + 'usage': { + 'scope': 'session', + 'total_tokens': 132408, + 'context_tokens': 42000, + 'context_window': 200000, + 'account': account, + }, + }, + }, + ]; +} + /// Run 7's pinned graph for `?graph=1`. JsonMap perfRunGraphFixture() => { 'name': 'Release train', diff --git a/app/tool/search_selection_probe_entry.dart b/app/tool/search_selection_probe_entry.dart index fb3d3b21..28125fe7 100644 --- a/app/tool/search_selection_probe_entry.dart +++ b/app/tool/search_selection_probe_entry.dart @@ -506,9 +506,14 @@ class _FixtureChannel implements WebSocketChannel { final decoded = jsonDecode(data); if (decoded is! Map) return; final reply = probeReply(decoded); - if (reply == null) return; + final followUps = perfChatFollowUps(decoded); + if (reply == null && followUps.isEmpty) return; Future.delayed(const Duration(milliseconds: 120), () { - if (!_incoming.isClosed) _incoming.add(jsonEncode(reply)); + if (_incoming.isClosed) return; + if (reply != null) _incoming.add(jsonEncode(reply)); + for (final frame in followUps) { + _incoming.add(jsonEncode(frame)); + } }); } diff --git a/docs/cli.md b/docs/cli.md index b54b6516..a81da118 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -419,6 +419,19 @@ are session metadata: no assistant/tool message is created and no queued prompt is admitted or completed by a usage update. Subscriptions replay retained usage; native readback refreshes it where supported. +`usage.account` is the account's subscription quota as the harness reported it, +absent when unknown: +`{"harness","source","plan","as_of","windows":[{"id","label","used_percent","resets_at"}],"unsupported"}`. +`used_percent` is 0–100 (it can exceed 100); `as_of` and `resets_at` are epoch +milliseconds. Claude Code fills it from its `rate_limit_event` stream lines +(5-hour and weekly windows; plan from the initialize `account`), shared by every +chat on the same account; API-key logins never report one. Codex reads +`account/rateLimits/read` once per connection (again when a chat opens after +five minutes) and merges `account/rateLimits/updated` notifications. +OpenCode has no quota API, so it sends `{"harness":"OpenCode","unsupported":true}`. +A usage frame with only `account` updates the quota and leaves token figures as +they were. No quota is estimated and no model call is made to obtain one. + The brokered OpenCode chat exposes the operator's own sessions, separate from the sessions pipeline runs create. The protocol types are: diff --git a/internal/claude/claude.go b/internal/claude/claude.go index c9c8c20b..0cb98ce8 100644 --- a/internal/claude/claude.go +++ b/internal/claude/claude.go @@ -102,6 +102,10 @@ type Chat struct { mu sync.Mutex sessions map[string]*session closed bool + + // quotas is the latest rate_limit_event quota per account (see quota.go). + quotaMu sync.Mutex + quotas map[string]*protocol.ChatAccountUsage } func New(ctx context.Context) *Chat { @@ -269,8 +273,10 @@ type session struct { usage *protocol.ChatEventFrame compaction *protocol.ChatEventFrame - prompts []promptRecord - models []protocol.ChatModel + // account is the signed-in account the live process reported. + account accountIdentity + prompts []promptRecord + models []protocol.ChatModel // model is the requested selection; modelActual is the model the CLI last // reported for a message. appliedModel is what the live process was told. @@ -310,6 +316,9 @@ func (s *session) emit(frame protocol.ChatEventFrame) { } s.mu.Lock() if frame.Kind == protocol.ChatEventUsage && frame.Usage != nil { + usage := *frame.Usage + usage.Account = s.chat.accountUsage(s.account.key) + frame.Usage = &usage s.usage = &frame } if frame.Kind == protocol.ChatEventCompaction && frame.Compaction != nil { @@ -337,7 +346,14 @@ func (s *session) subscribe() chan protocol.ChatEventFrame { s.mu.Lock() s.subs[ch] = struct{}{} if s.usage != nil { - ch <- *s.usage + // Account quota may have moved since (another chat on the account). + frame := *s.usage + usage := *frame.Usage + usage.Account = s.chat.accountUsage(s.account.key) + frame.Usage = &usage + ch <- frame + } else if account := s.chat.accountUsage(s.account.key); account != nil { + ch <- protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventUsage, Usage: &protocol.ChatUsage{Account: account}} } if s.compaction != nil { ch <- *s.compaction diff --git a/internal/claude/process.go b/internal/claude/process.go index a0b4d824..bcf540e7 100644 --- a/internal/claude/process.go +++ b/internal/claude/process.go @@ -121,22 +121,23 @@ func (s *session) spawn(ctx context.Context) (*process, error) { // before any user turn so an approval is never silently denied. initCtx, cancel := context.WithTimeout(ctx, initializeTimeout) defer cancel() - models, err := p.initialize(initCtx) + models, account, err := p.initialize(initCtx) if err != nil { p.close() return nil, err } s.mu.Lock() s.models = models + s.account = account s.lastErr = "" s.mu.Unlock() return p, nil } -func (p *process) initialize(ctx context.Context) ([]protocol.ChatModel, error) { +func (p *process) initialize(ctx context.Context) ([]protocol.ChatModel, accountIdentity, error) { raw, err := p.request(ctx, "initialize", map[string]any{"subtype": "initialize"}) if err != nil { - return nil, fmt.Errorf("initialize Claude Code: %w%s", err, p.diagnostic()) + return nil, accountIdentity{}, fmt.Errorf("initialize Claude Code: %w%s", err, p.diagnostic()) } var reply struct { Models []struct { @@ -145,9 +146,10 @@ func (p *process) initialize(ctx context.Context) ([]protocol.ChatModel, error) DisplayName string `json:"displayName"` Description string `json:"description"` } `json:"models"` + Account json.RawMessage `json:"account"` } if err := json.Unmarshal(raw, &reply); err != nil { - return nil, errors.New("Claude Code returned an invalid initialize response") + return nil, accountIdentity{}, errors.New("Claude Code returned an invalid initialize response") } models := make([]protocol.ChatModel, 0, len(reply.Models)) for _, m := range reply.Models { @@ -161,9 +163,9 @@ func (p *process) initialize(ctx context.Context) ([]protocol.ChatModel, error) models = append(models, protocol.ChatModel{ID: m.Value, Provider: Backend, Name: name}) } if len(models) == 0 { - return nil, errors.New("Claude Code reported no models; check that the CLI is signed in") + return nil, accountIdentity{}, errors.New("Claude Code reported no models; check that the CLI is signed in") } - return models, nil + return models, decodeAccountIdentity(reply.Account), nil } // request sends one control request and waits for its control_response. diff --git a/internal/claude/quota.go b/internal/claude/quota.go new file mode 100644 index 00000000..c3c19cbb --- /dev/null +++ b/internal/claude/quota.go @@ -0,0 +1,213 @@ +package claude + +import ( + "encoding/json" + "math" + "strings" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// Account quota comes only from what Claude Code already sends: the +// `rate_limit_event` stream-json line (SDKRateLimitEvent, verified against the +// installed CLI 2.1.316's message schema) and the `account` object of the +// initialize control response. Nothing here starts a request or a model call. +// +// rate_limit_info carries the currently limiting window at the top level +// (rateLimitType, utilization 0-1, resetsAt epoch seconds) and, for +// subscription logins, unifiedWindows with every tracked window +// (five_hour, seven_day, seven_day_overage_included). The CLI emits a new +// event whenever a window's rounded percentage, reset, status or threshold +// moves. API-key, Bedrock and Vertex sessions never receive one. + +const quotaHarness = "Claude Code" +const quotaSource = "rate_limit_event" + +// accountIdentity is the signed-in account a process reported at initialize. +// key is never sent to clients; it only shares quota between sessions. +type accountIdentity struct { + key string + plan string +} + +func decodeAccountIdentity(raw json.RawMessage) accountIdentity { + var account struct { + Email string `json:"email"` + Organization string `json:"organization"` + SubscriptionType string `json:"subscriptionType"` + APIProvider string `json:"apiProvider"` + } + if len(raw) == 0 || json.Unmarshal(raw, &account) != nil { + return accountIdentity{} + } + key := strings.TrimSpace(account.Email) + "\x00" + strings.TrimSpace(account.Organization) + "\x00" + account.APIProvider + if strings.Trim(key, "\x00") == "" { + key = "" + } + return accountIdentity{key: key, plan: strings.TrimSpace(account.SubscriptionType)} +} + +type rateLimitWindowInfo struct { + Utilization *float64 `json:"utilization"` + ResetsAt *float64 `json:"resetsAt"` +} + +type rateLimitInfo struct { + Status string `json:"status"` + ResetsAt *float64 `json:"resetsAt"` + RateLimitType string `json:"rateLimitType"` + Utilization *float64 `json:"utilization"` + UnifiedWindows map[string]*rateLimitWindowInfo `json:"unifiedWindows"` +} + +// quotaWindowOrder lists the windows Claude Code names, in display order. +var quotaWindowOrder = []struct{ id, label string }{ + {"five_hour", "5-hour"}, + {"seven_day", "Weekly"}, + {"seven_day_opus", "Weekly (Opus)"}, + {"seven_day_sonnet", "Weekly (Sonnet)"}, + {"seven_day_overage_included", "Weekly (included)"}, +} + +func quotaWindowLabel(id string) (string, bool) { + for _, w := range quotaWindowOrder { + if w.id == id { + return w.label, true + } + } + return "", false +} + +func quotaWindow(id string, utilization, resetsAt *float64) (protocol.ChatQuotaWindow, bool) { + label, ok := quotaWindowLabel(id) + if !ok || utilization == nil || math.IsNaN(*utilization) || math.IsInf(*utilization, 0) || *utilization < 0 { + return protocol.ChatQuotaWindow{}, false + } + w := protocol.ChatQuotaWindow{ID: id, Label: label, UsedPercent: math.Round(*utilization*1000) / 10} + if resetsAt != nil && *resetsAt > 0 && !math.IsInf(*resetsAt, 0) { + w.ResetsAt = int64(*resetsAt * 1000) + } + return w, true +} + +// mergeRateLimit folds one rate_limit_info into previous (which may be nil) +// and reports the new snapshot, or nil when the event names no usable window. +// Windows the event does not mention keep their last reported value. +func mergeRateLimit(previous *protocol.ChatAccountUsage, raw json.RawMessage, plan string, now time.Time) *protocol.ChatAccountUsage { + var info rateLimitInfo + if len(raw) == 0 || json.Unmarshal(raw, &info) != nil { + return nil + } + windows := map[string]protocol.ChatQuotaWindow{} + if previous != nil { + for _, w := range previous.Windows { + windows[w.ID] = w + } + } + changed := false + if w, ok := quotaWindow(info.RateLimitType, info.Utilization, info.ResetsAt); ok { + windows[w.ID] = w + changed = true + } + for id, window := range info.UnifiedWindows { + if window == nil { + continue + } + if w, ok := quotaWindow(id, window.Utilization, window.ResetsAt); ok { + windows[w.ID] = w + changed = true + } + } + if !changed { + return nil + } + next := &protocol.ChatAccountUsage{Harness: quotaHarness, Source: quotaSource, Plan: plan, AsOf: now.UnixMilli()} + if next.Plan == "" && previous != nil { + next.Plan = previous.Plan + } + for _, entry := range quotaWindowOrder { + if w, ok := windows[entry.id]; ok { + next.Windows = append(next.Windows, w) + } + } + return next +} + +// accountUsage returns a copy of the latest quota for an account key. +func (c *Chat) accountUsage(key string) *protocol.ChatAccountUsage { + if key == "" { + return nil + } + c.quotaMu.Lock() + defer c.quotaMu.Unlock() + return c.quotas[key].Clone() +} + +// handleRateLimit records a rate_limit_event for the session's account and +// republishes the latest usage snapshot, with the new quota, to every session +// of that account. +func (s *session) handleRateLimit(raw json.RawMessage) { + s.mu.Lock() + account := s.account + s.mu.Unlock() + key := account.key + if key == "" { + // An account the CLI did not identify still belongs to this session. + key = "session:" + s.id + s.mu.Lock() + s.account.key = key + s.mu.Unlock() + } + c := s.chat + c.quotaMu.Lock() + next := mergeRateLimit(c.quotas[key], raw, account.plan, time.Now()) + if next == nil { + c.quotaMu.Unlock() + return + } + if c.quotas == nil { + c.quotas = map[string]*protocol.ChatAccountUsage{} + } + c.quotas[key] = next + c.quotaMu.Unlock() + c.mu.Lock() + targets := make([]*session, 0, len(c.sessions)) + for _, other := range c.sessions { + targets = append(targets, other) + } + c.mu.Unlock() + if !containsSession(targets, s) { + targets = append(targets, s) + } + for _, target := range targets { + target.mu.Lock() + same := target.account.key == key + target.mu.Unlock() + if same { + target.republishUsage() + } + } +} + +func containsSession(list []*session, s *session) bool { + for _, other := range list { + if other == s { + return true + } + } + return false +} + +// republishUsage emits the retained token snapshot (or an empty one) so the +// account quota attached by emit reaches watchers without inventing tokens. +func (s *session) republishUsage() { + s.mu.Lock() + usage := &protocol.ChatUsage{} + if s.usage != nil && s.usage.Usage != nil { + copy := *s.usage.Usage + usage = © + } + s.mu.Unlock() + s.emit(protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventUsage, Usage: usage}) +} diff --git a/internal/claude/quota_test.go b/internal/claude/quota_test.go new file mode 100644 index 00000000..4239d5f5 --- /dev/null +++ b/internal/claude/quota_test.go @@ -0,0 +1,105 @@ +package claude + +import ( + "context" + "encoding/json" + "reflect" + "testing" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// Shaped like Claude Code 2.1.316's SDKRateLimitEvent.rate_limit_info; +// the numbers are synthetic. +const unifiedRateLimit = `{"status":"allowed_warning","resetsAt":1900000000,"rateLimitType":"seven_day", + "utilization":0.8,"isUsingOverage":false,"surpassedThreshold":0.75, + "unifiedWindows":{"five_hour":{"utilization":0.125,"resetsAt":1899990000,"status":"allowed"}, + "seven_day":{"utilization":0.8,"resetsAt":1900000000,"status":"allowed_warning","surpassedThreshold":0.75}}}` + +func TestMergeRateLimitReadsUnifiedWindows(t *testing.T) { + now := time.UnixMilli(1_800_000_000_000) + got := mergeRateLimit(nil, json.RawMessage(unifiedRateLimit), "max", now) + want := &protocol.ChatAccountUsage{ + Harness: "Claude Code", Source: "rate_limit_event", Plan: "max", AsOf: now.UnixMilli(), + Windows: []protocol.ChatQuotaWindow{ + {ID: "five_hour", Label: "5-hour", UsedPercent: 12.5, ResetsAt: 1_899_990_000_000}, + {ID: "seven_day", Label: "Weekly", UsedPercent: 80, ResetsAt: 1_900_000_000_000}, + }, + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("merged = %+v\nwant %+v", got, want) + } +} + +func TestMergeRateLimitKeepsUnmentionedWindowsAndIgnoresStatusOnly(t *testing.T) { + now := time.UnixMilli(1_800_000_000_000) + first := mergeRateLimit(nil, json.RawMessage(unifiedRateLimit), "pro", now) + // A top-level-only event (older CLIs, or no unifiedWindows) updates its window. + later := now.Add(time.Minute) + next := mergeRateLimit(first, json.RawMessage(`{"status":"allowed","rateLimitType":"five_hour","utilization":0.5,"resetsAt":1899990000}`), "", later) + if next == nil || len(next.Windows) != 2 || next.Windows[0].UsedPercent != 50 || next.Windows[1].UsedPercent != 80 { + t.Fatalf("merge = %+v", next) + } + if next.Plan != "pro" || next.AsOf != later.UnixMilli() { + t.Fatalf("plan/as_of = %q %d", next.Plan, next.AsOf) + } + for _, raw := range []string{ + `{"status":"rejected","rateLimitType":"five_hour"}`, // no utilization: nothing to show + `{"status":"allowed","rateLimitType":"overage","utilization":0.2}`, + `not json`, + } { + if got := mergeRateLimit(first, json.RawMessage(raw), "", later); got != nil { + t.Fatalf("%s merged into %+v", raw, got) + } + } +} + +func TestDecodeAccountIdentity(t *testing.T) { + got := decodeAccountIdentity(json.RawMessage(`{"email":"a@example.invalid","organization":"Org","subscriptionType":"max","apiProvider":"firstParty"}`)) + if got.key == "" || got.plan != "max" { + t.Fatalf("identity = %+v", got) + } + if empty := decodeAccountIdentity(json.RawMessage(`{}`)); empty.key != "" || empty.plan != "" { + t.Fatalf("empty account = %+v", empty) + } +} + +func TestRateLimitEventReachesEverySessionOfTheAccount(t *testing.T) { + t.Setenv("FAKE_CLAUDE_RATE_LIMIT", "1") + chat := testChat(t) + first := newCreatedChat(t, chat) + frames := subscribe(t, chat, first.ID) + if err := chat.Prompt(context.Background(), first.ID, "hello"); err != nil { + t.Fatal(err) + } + quota := waitFrame(t, frames, "account usage", func(frame protocol.ChatEventFrame) bool { + return frame.Kind == protocol.ChatEventUsage && frame.Usage != nil && frame.Usage.Account != nil + }).Usage.Account + if quota.Plan != "max" || len(quota.Windows) != 2 || quota.Windows[0].Label != "5-hour" || quota.Windows[0].UsedPercent != 42 || + quota.Windows[1].Label != "Weekly" || quota.Windows[1].UsedPercent != 73.1 || quota.Windows[1].ResetsAt != 1_900_400_000_000 { + t.Fatalf("account usage = %+v", quota) + } + // The token snapshot that follows still carries the quota. + tokens := waitFrame(t, frames, "token usage", func(frame protocol.ChatEventFrame) bool { + return frame.Kind == protocol.ChatEventUsage && frame.Usage != nil && frame.Usage.TotalTokens != nil + }).Usage + if tokens.Account == nil || len(tokens.Account.Windows) != 2 { + t.Fatalf("token usage lost the account quota: %+v", tokens) + } + + // A second chat on the same account learns the quota once its process + // identifies the account, without a turn of its own. + second := newCreatedChat(t, chat) + s := chat.sessionFor(second.ID, "") + if _, err := s.ensureProcess(context.Background()); err != nil { + t.Fatal(err) + } + other := subscribe(t, chat, second.ID) + replayed := waitFrame(t, other, "replayed account usage", func(frame protocol.ChatEventFrame) bool { + return frame.Kind == protocol.ChatEventUsage && frame.Usage != nil && frame.Usage.Account != nil + }).Usage + if replayed.Scope != "" || replayed.TotalTokens != nil || len(replayed.Account.Windows) != 2 { + t.Fatalf("replay invented token usage or lost quota: %+v", replayed) + } +} diff --git a/internal/claude/testdata/fake-claude.py b/internal/claude/testdata/fake-claude.py index 2f7ff236..521f24a0 100644 --- a/internal/claude/testdata/fake-claude.py +++ b/internal/claude/testdata/fake-claude.py @@ -126,6 +126,14 @@ def user_message(text): def finish(message_id): + # Shape of SDKRateLimitEvent in Claude Code 2.1.316 (synthetic numbers). + if os.environ.get("FAKE_CLAUDE_RATE_LIMIT"): + send({"type": "rate_limit_event", "uuid": "rate-%d" % state["turn"], "session_id": state["session"], + "rate_limit_info": {"status": "allowed", "resetsAt": 1900000000, "rateLimitType": "five_hour", + "utilization": 0.42, "isUsingOverage": False, + "unifiedWindows": { + "five_hour": {"utilization": 0.42, "resetsAt": 1900000000, "status": "allowed"}, + "seven_day": {"utilization": 0.731, "resetsAt": 1900400000}}}}) send({"type": "result", "subtype": "success", "is_error": False, "result": "Hello world", "session_id": state["session"], "total_cost_usd": 0.25, "usage": {"input_tokens": 10, "output_tokens": 20}}) @@ -160,6 +168,8 @@ def handle(line): {"value": "haiku", "displayName": "Haiku", "description": "Haiku model"}, ], "commands": [], "agents": [], + "account": {"email": "fixture@example.invalid", "organization": "Fixture Org", + "subscriptionType": "max", "apiProvider": "firstParty"}, }) elif subtype == "set_model": state["model"] = request.get("model") diff --git a/internal/claude/translate.go b/internal/claude/translate.go index bc60102e..314a6960 100644 --- a/internal/claude/translate.go +++ b/internal/claude/translate.go @@ -38,6 +38,8 @@ type lineEnvelope struct { // a task notification, a reminder); see classifyInjected. Origin json.RawMessage `json:"origin"` IsMeta bool `json:"isMeta"` + // RateLimitInfo is the payload of a rate_limit_event line (see quota.go). + RateLimitInfo json.RawMessage `json:"rate_limit_info"` } type contentBlock struct { @@ -115,6 +117,8 @@ func (s *session) handleLine(p *process, line []byte) { s.handleUser(envelope) case "result": s.handleResult(envelope) + case "rate_limit_event": + s.handleRateLimit(envelope.RateLimitInfo) case "system": if envelope.Subtype == "task_notification" { s.finishNotifiedTask(line) diff --git a/internal/codex/chat.go b/internal/codex/chat.go index b1aca9c7..35320d78 100644 --- a/internal/codex/chat.go +++ b/internal/codex/chat.go @@ -68,6 +68,12 @@ type Chat struct { usage map[string]usageSnapshot usageOrder uint64 modes map[string]string + + // Account quota (quota.go): merged native snapshot and the read schedule. + quota *quotaState + accountReads bool + accountReading bool + accountReadAt time.Time } type pendingForm struct { @@ -139,6 +145,10 @@ func Open(ctx context.Context) (*Chat, error) { c.Close() return nil, fmt.Errorf("initialize Codex app-server: %w", err) } + c.mu.Lock() + c.accountReads = true + c.mu.Unlock() + c.readAccountRateLimits() return c, nil } @@ -279,6 +289,11 @@ func (c *Chat) respond(id json.RawMessage, result any) { func (c *Chat) emit(frame protocol.ChatEventFrame) { c.mu.Lock() + if frame.Kind == protocol.ChatEventUsage && frame.Usage != nil { + usage := *frame.Usage + usage.Account = c.accountLocked() + frame.Usage = &usage + } if frame.Kind == protocol.ChatEventUsage && !c.retainUsageLocked(frame) { c.mu.Unlock() return @@ -343,12 +358,21 @@ func (c *Chat) subscribe(id string) chan protocol.ChatEventFrame { } c.subs[id][ch] = struct{}{} if snapshot, ok := c.usage[id]; ok { - ch <- snapshot.frame + frame := snapshot.frame + if frame.Usage != nil { + usage := *frame.Usage + usage.Account = c.accountLocked() + frame.Usage = &usage + } + ch <- frame + } else if account := c.accountLocked(); account != nil { + ch <- protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: &protocol.ChatUsage{Account: account}} } if frame, ok := c.compactions[id]; ok { ch <- frame } c.mu.Unlock() + c.readAccountRateLimits() return ch } @@ -764,6 +788,10 @@ func (c *Chat) handleNotification(msg rpcMessage) { c.receiveUsage(msg.Params) return } + if msg.Method == "account/rateLimits/updated" { + c.receiveRateLimits(msg.Params) + return + } if msg.Method == "serverRequest/resolved" { var p struct { ThreadID string `json:"threadId"` diff --git a/internal/codex/quota.go b/internal/codex/quota.go new file mode 100644 index 00000000..aa7a7d78 --- /dev/null +++ b/internal/codex/quota.go @@ -0,0 +1,207 @@ +package codex + +import ( + "context" + "encoding/json" + "fmt" + "math" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// Account quota, verified against the App Server schema generated by the +// installed codex-cli 0.164.0 (`codex app-server generate-ts`): +// v2/GetAccountRateLimitsResponse.ts, RateLimitSnapshot.ts, RateLimitWindow.ts, +// AccountRateLimitsUpdatedNotification.ts and PlanType.ts. +// +// `account/rateLimits/read` is an account read, not a model call; it runs once +// per connection and again only when a chat is opened after the cached copy is +// older than accountReadInterval. `account/rateLimits/updated` is a sparse +// rolling update that the App Server pushes itself; it is merged into the +// latest read, and a null field never clears a known value. + +const accountReadInterval = 5 * time.Minute +const accountReadTimeout = 10 * time.Second + +type rateLimitWindow struct { + UsedPercent *float64 `json:"usedPercent"` + WindowDurationMins *int64 `json:"windowDurationMins"` + ResetsAt *int64 `json:"resetsAt"` +} + +type rateLimitSnapshot struct { + LimitID *string `json:"limitId"` + Primary *rateLimitWindow `json:"primary"` + Secondary *rateLimitWindow `json:"secondary"` + PlanType *string `json:"planType"` +} + +// quotaState is the merged native snapshot behind the published quota. +type quotaState struct { + limitID string + primary *rateLimitWindow + secondary *rateLimitWindow + plan string + asOf time.Time +} + +// windowLabel names a window by its native duration: "5-hour", "Weekly". +func windowLabel(minutes *int64, fallback string) string { + if minutes == nil || *minutes <= 0 { + return fallback + } + m := *minutes + switch { + case m == 7*24*60: + return "Weekly" + case m == 24*60: + return "Daily" + case m%(24*60) == 0: + return fmt.Sprintf("%d-day", m/(24*60)) + case m%60 == 0: + return fmt.Sprintf("%d-hour", m/60) + default: + return fmt.Sprintf("%d-minute", m) + } +} + +func quotaWindow(id, fallback string, w *rateLimitWindow) (protocol.ChatQuotaWindow, bool) { + if w == nil || w.UsedPercent == nil || math.IsNaN(*w.UsedPercent) || math.IsInf(*w.UsedPercent, 0) || *w.UsedPercent < 0 { + return protocol.ChatQuotaWindow{}, false + } + out := protocol.ChatQuotaWindow{ID: id, Label: windowLabel(w.WindowDurationMins, fallback), UsedPercent: *w.UsedPercent} + if w.ResetsAt != nil && *w.ResetsAt > 0 { + // RateLimitWindow.resetsAt is Unix seconds (codex-rs RateLimitWindow). + out.ResetsAt = *w.ResetsAt * 1000 + } + return out, true +} + +// merge folds a (possibly sparse) snapshot into the state and reports whether +// anything usable changed. A snapshot for another metered limit is ignored. +func (q *quotaState) merge(s *rateLimitSnapshot, now time.Time) bool { + if s == nil { + return false + } + if s.LimitID != nil && *s.LimitID != "" { + if q.limitID != "" && q.limitID != *s.LimitID { + return false + } + q.limitID = *s.LimitID + } + changed := false + if s.Primary != nil && s.Primary.UsedPercent != nil { + q.primary, changed = s.Primary, true + } + if s.Secondary != nil && s.Secondary.UsedPercent != nil { + q.secondary, changed = s.Secondary, true + } + if s.PlanType != nil && *s.PlanType != "" && *s.PlanType != "unknown" { + changed = changed || q.plan != *s.PlanType + q.plan = *s.PlanType + } + if changed { + q.asOf = now + } + return changed +} + +func (q *quotaState) account() *protocol.ChatAccountUsage { + if q == nil { + return nil + } + out := &protocol.ChatAccountUsage{Harness: "Codex", Source: "account/rateLimits", Plan: q.plan, AsOf: q.asOf.UnixMilli()} + if w, ok := quotaWindow("primary", "Primary", q.primary); ok { + out.Windows = append(out.Windows, w) + } + if w, ok := quotaWindow("secondary", "Secondary", q.secondary); ok { + out.Windows = append(out.Windows, w) + } + if len(out.Windows) == 0 { + return nil + } + return out +} + +// accountLocked is the published quota. Called under mu. +func (c *Chat) accountLocked() *protocol.ChatAccountUsage { + return c.quota.account() +} + +// readAccountRateLimits performs the one cheap native read, when due. It never +// runs on the reader goroutine (call waits on a response the reader delivers). +func (c *Chat) readAccountRateLimits() { + c.mu.Lock() + due := c.accountReads && !c.closed && !c.accountReading && time.Since(c.accountReadAt) >= accountReadInterval + if due { + c.accountReading = true + c.accountReadAt = time.Now() + } + c.mu.Unlock() + if !due { + return + } + go func() { + defer func() { + c.mu.Lock() + c.accountReading = false + c.mu.Unlock() + }() + ctx, cancel := context.WithTimeout(c.ctx, accountReadTimeout) + defer cancel() + raw, err := c.call(ctx, "account/rateLimits/read", map[string]any{"excludeResetCreditDetails": true}) + if err != nil { + return // API-key logins and older servers have no quota; stay unknown + } + var reply struct { + RateLimits *rateLimitSnapshot `json:"rateLimits"` + } + if json.Unmarshal(raw, &reply) == nil { + c.applyRateLimits(reply.RateLimits) + } + }() +} + +func (c *Chat) receiveRateLimits(raw json.RawMessage) { + var p struct { + RateLimits *rateLimitSnapshot `json:"rateLimits"` + } + if json.Unmarshal(raw, &p) == nil { + c.applyRateLimits(p.RateLimits) + } +} + +// applyRateLimits merges a snapshot and republishes every watched or retained +// session's usage with the new quota. Token figures are never invented: a +// session without a token snapshot gets an account-only frame. +func (c *Chat) applyRateLimits(s *rateLimitSnapshot) { + c.mu.Lock() + if c.quota == nil { + c.quota = "aState{} + } + if !c.quota.merge(s, time.Now()) { + c.mu.Unlock() + return + } + ids := map[string]bool{} + for id := range c.subs { + ids[id] = true + } + for id := range c.usage { + ids[id] = true + } + frames := make([]protocol.ChatEventFrame, 0, len(ids)) + for id := range ids { + usage := &protocol.ChatUsage{} + if snapshot, ok := c.usage[id]; ok && snapshot.frame.Usage != nil { + copy := *snapshot.frame.Usage + usage = © + } + frames = append(frames, protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: usage}) + } + c.mu.Unlock() + for _, frame := range frames { + c.emit(frame) + } +} diff --git a/internal/codex/quota_test.go b/internal/codex/quota_test.go new file mode 100644 index 00000000..cf806b03 --- /dev/null +++ b/internal/codex/quota_test.go @@ -0,0 +1,109 @@ +package codex + +import ( + "encoding/json" + "reflect" + "sync" + "testing" + "time" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +func waitAccount(t *testing.T, ch <-chan protocol.ChatEventFrame) protocol.ChatEventFrame { + t.Helper() + deadline := time.After(5 * time.Second) + for { + select { + case frame := <-ch: + if frame.Kind == protocol.ChatEventUsage && frame.Usage != nil && frame.Usage.Account != nil { + return frame + } + case <-deadline: + t.Fatal("no account usage frame") + } + } +} + +func TestAccountRateLimitsReadOnceAndMergeSparseUpdates(t *testing.T) { + var mu sync.Mutex + reads := 0 + chat := modelTestChat(t, func(method string, raw json.RawMessage) any { + if method != "account/rateLimits/read" { + t.Errorf("unexpected method %s", method) + return &rpcError{Code: -32601, Message: "unexpected"} + } + var params map[string]any + if json.Unmarshal(raw, ¶ms) != nil || params["excludeResetCreditDetails"] != true { + t.Errorf("read params = %s", raw) + } + mu.Lock() + reads++ + mu.Unlock() + return json.RawMessage(modelFixture(t, "account-rate-limits-read")) + }) + chat.accountReads = true + ch := chat.subscribe(fixtureThread) + read := waitAccount(t, ch) + want := []protocol.ChatQuotaWindow{ + {ID: "primary", Label: "5-hour", UsedPercent: 37, ResetsAt: 1_900_000_000_000}, + {ID: "secondary", Label: "Weekly", UsedPercent: 12, ResetsAt: 1_900_500_000_000}, + } + account := read.Usage.Account + if account.Harness != "Codex" || account.Plan != "plus" || account.Source != "account/rateLimits" || account.AsOf <= 0 || !reflect.DeepEqual(account.Windows, want) { + t.Fatalf("read account = %+v", account) + } + if read.Usage.Scope != "" || read.Usage.TotalTokens != nil { + t.Fatalf("account-only frame invented token usage: %+v", read.Usage) + } + + // The sparse update moves the 5-hour window and keeps the weekly one and + // the plan, and the token snapshot that follows carries the merged quota. + var update rpcMessage + if err := json.Unmarshal(modelFixture(t, "account-rate-limits-updated"), &update); err != nil { + t.Fatal(err) + } + chat.handleNotification(update) + merged := waitAccount(t, ch).Usage.Account + if merged.Plan != "plus" || len(merged.Windows) != 2 || merged.Windows[0].UsedPercent != 41 || merged.Windows[1].UsedPercent != 12 { + t.Fatalf("merged account = %+v", merged) + } + chat.receiveUsage(json.RawMessage(`{"threadId":"` + fixtureThread + `","tokenUsage":{"total":{"totalTokens":5},"last":{}}}`)) + tokens := waitAccount(t, ch).Usage + if tokens.TotalTokens == nil || *tokens.TotalTokens != 5 || tokens.Account.Windows[0].UsedPercent != 41 { + t.Fatalf("token usage = %+v", tokens) + } + + // Another metered limit's update is not this account's codex quota. + chat.handleNotification(rpcMessage{Method: "account/rateLimits/updated", Params: json.RawMessage(`{"rateLimits":{"limitId":"other","primary":{"usedPercent":99,"windowDurationMins":300,"resetsAt":null}}}`)}) + // A second subscriber within the interval replays the cache, no new read. + second := chat.subscribe(fixtureThread) + replayed := waitAccount(t, second).Usage + if replayed.Account.Windows[0].UsedPercent != 41 || replayed.TotalTokens == nil { + t.Fatalf("replay = %+v", replayed) + } + mu.Lock() + defer mu.Unlock() + if reads != 1 { + t.Fatalf("account reads = %d, want 1", reads) + } +} + +func TestAccountRateLimitsUnknownStaysHidden(t *testing.T) { + chat := usageTestChat() + ch := chat.subscribe("thread") + // A failed/absent read leaves no quota, and an update without windows adds none. + chat.receiveRateLimits(json.RawMessage(`{"rateLimits":{"limitId":null,"primary":null,"secondary":null,"planType":"unknown"}}`)) + chat.receiveRateLimits(json.RawMessage(`not json`)) + if len(ch) != 0 { + t.Fatalf("unknown quota published: %+v", <-ch) + } + if got := windowLabel(nil, "Primary"); got != "Primary" { + t.Fatalf("label without duration = %q", got) + } + for minutes, want := range map[int64]string{300: "5-hour", 10080: "Weekly", 1440: "Daily", 4320: "3-day", 45: "45-minute"} { + if got := windowLabel(&minutes, ""); got != want { + t.Fatalf("label(%d) = %q, want %q", minutes, got, want) + } + } +} diff --git a/internal/codex/testdata/README.md b/internal/codex/testdata/README.md index 092becb4..584cb64c 100644 --- a/internal/codex/testdata/README.md +++ b/internal/codex/testdata/README.md @@ -42,3 +42,14 @@ before `turn/start`. Files retain the existing attachment-store retention rules. History keeps local file/image parts; native image parts use the stored basename while a companion text input retains the original display name. All wire tests use fake JSON-RPC servers, never the production control socket. + +## Account rate limits + +`account-rate-limits-read.json` (an `account/rateLimits/read` result) and +`account-rate-limits-updated.json` (an `account/rateLimits/updated` +notification) follow the schema generated by the installed codex-cli 0.164.0 +(`codex app-server generate-ts`: `v2/GetAccountRateLimitsResponse.ts`, +`RateLimitSnapshot.ts`, `RateLimitWindow.ts`, +`AccountRateLimitsUpdatedNotification.ts`). Numbers are synthetic. `resetsAt` +is Unix seconds; `usedPercent` is 0-100. The update is sparse: null fields keep +the previously read values. diff --git a/internal/codex/testdata/account-rate-limits-read.json b/internal/codex/testdata/account-rate-limits-read.json new file mode 100644 index 00000000..0f839a9d --- /dev/null +++ b/internal/codex/testdata/account-rate-limits-read.json @@ -0,0 +1,19 @@ +{ + "ordinaryUsageAllowed": true, + "rateLimits": { + "limitId": "codex", + "limitName": null, + "normalModelSlug": null, + "primary": {"usedPercent": 37, "windowDurationMins": 300, "resetsAt": 1900000000}, + "secondary": {"usedPercent": 12, "windowDurationMins": 10080, "resetsAt": 1900500000}, + "credits": {"hasCredits": false, "unlimited": false, "balance": null}, + "individualLimit": null, + "spendControlReached": null, + "planType": "plus", + "rateLimitReachedType": null + }, + "rateLimitsByLimitId": null, + "rateLimitResetCredits": null, + "accountId": null, + "rateLimitUpsell": null +} diff --git a/internal/codex/testdata/account-rate-limits-updated.json b/internal/codex/testdata/account-rate-limits-updated.json new file mode 100644 index 00000000..eb7f269c --- /dev/null +++ b/internal/codex/testdata/account-rate-limits-updated.json @@ -0,0 +1,17 @@ +{ + "method": "account/rateLimits/updated", + "params": { + "rateLimits": { + "limitId": "codex", + "limitName": null, + "normalModelSlug": null, + "primary": {"usedPercent": 41, "windowDurationMins": 300, "resetsAt": 1900000000}, + "secondary": null, + "credits": null, + "individualLimit": null, + "spendControlReached": null, + "planType": null, + "rateLimitReachedType": null + } + } +} diff --git a/internal/opencode/chat_test.go b/internal/opencode/chat_test.go index 718ba1cd..e9059e4b 100644 --- a/internal/opencode/chat_test.go +++ b/internal/opencode/chat_test.go @@ -38,7 +38,7 @@ func TestNormalizeChatEvent(t *testing.T) { {name: "tool running", payload: `{"type":"session.tool.called","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","input":{"command":"ls"}}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolRunning}, {name: "tool completed", payload: `{"type":"session.tool.success","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","content":[{"type":"text","text":"ok"}]}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolCompleted}, {name: "tool failed", payload: `{"type":"session.tool.failed","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","error":{"type":"tool","message":"boom"}}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolError}, - {name: "usage", payload: `{"type":"session.usage.updated","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","tokens":{"input":12,"output":34},"cost":0.001}}`, wantOK: true, wantKind: protocol.ChatEventUsage, wantUsage: &protocol.ChatUsage{InputTokens: 12, OutputTokens: 34, Cost: 0.001, Scope: "session", CostUSD: usageFloat(.001)}}, + {name: "usage", payload: `{"type":"session.usage.updated","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","tokens":{"input":12,"output":34},"cost":0.001}}`, wantOK: true, wantKind: protocol.ChatEventUsage, wantUsage: &protocol.ChatUsage{InputTokens: 12, OutputTokens: 34, Cost: 0.001, Scope: "session", CostUSD: usageFloat(.001), Account: &protocol.ChatAccountUsage{Harness: "OpenCode", Unsupported: true}}}, {name: "message id fallback", payload: `{"type":"session.step.started","data":{"sessionID":"ses_1","index":1}}`, state: prior, wantOK: true, wantKind: protocol.ChatEventStep, wantMsg: "msg_prev", wantStep: protocol.ChatStepStarted}, {name: "foreign session skipped", payload: `{"type":"session.text.delta","data":{"sessionID":"ses_other","delta":"x"}}`, wantOK: false}, {name: "unknown type skipped", payload: `{"type":"session.created","data":{"sessionID":"ses_1"}}`, wantOK: false}, diff --git a/internal/opencode/chat_usage.go b/internal/opencode/chat_usage.go index af35e6cd..bf301113 100644 --- a/internal/opencode/chat_usage.go +++ b/internal/opencode/chat_usage.go @@ -40,6 +40,16 @@ func tokenSum(values ...*int64) *int64 { return &total } +// openCodeAccount says OpenCode reports no account quota. OpenCode 2.0.32's +// API (provider, integration, model and session routes) has no plan, usage or +// quota read, and its only rate-limit data is the x-ratelimit-* headers of a +// failed provider request (AI.Error.RateLimit), which is neither a plan quota +// nor available before a limit is hit. That covers the OpenCode Go and Zen +// subscriptions too. Nothing is estimated in its place. +func openCodeAccount() *protocol.ChatAccountUsage { + return &protocol.ChatAccountUsage{Harness: "OpenCode", Unsupported: true} +} + func decodeUsageSnapshot(data []byte) *protocol.ChatUsage { var record struct { Tokens usageTokens `json:"tokens"` @@ -48,9 +58,9 @@ func decodeUsageSnapshot(data []byte) *protocol.ChatUsage { Output int `json:"outputTokens"` } if json.Unmarshal(data, &record) != nil { - return &protocol.ChatUsage{Scope: "session"} + return &protocol.ChatUsage{Scope: "session", Account: openCodeAccount()} } - u := &protocol.ChatUsage{Scope: "session", InputTokens: record.Input, OutputTokens: record.Output} + u := &protocol.ChatUsage{Scope: "session", InputTokens: record.Input, OutputTokens: record.Output, Account: openCodeAccount()} if record.Tokens.Input != nil { u.InputTokens = int(*record.Tokens.Input) } @@ -96,7 +106,7 @@ func (c *Chat) Usage(ctx context.Context, id string) (*protocol.ChatUsage, error return nil, fmt.Errorf("invalid OpenCode session id") } if c.conn.Backend == "v1" { - return &protocol.ChatUsage{Scope: "session"}, nil + return &protocol.ChatUsage{Scope: "session", Account: openCodeAccount()}, nil } data, err := c.call(ctx, "get", "/api/session/"+id, nil) if err != nil { diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index a6f10a5d..4a0e3e70 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -594,6 +594,46 @@ type ChatUsage struct { // RateBasis distinguishes a generation interval from a whole turn (which // can include tools/waits). Never estimate tokens from text/character counts. RateBasis string `json:"rate_basis,omitempty"` + // Account is the latest account quota the harness reported (or a note that + // it has no quota API). It is account state, not session state: a snapshot + // carries the latest value known when it was sent. Nil means unknown. + Account *ChatAccountUsage `json:"account,omitempty"` +} + +// ChatAccountUsage is a harness account's subscription quota as the harness +// itself reported it. Nothing is estimated: windows are only those the +// harness named, and Unsupported says the harness exposes no quota at all. +type ChatAccountUsage struct { + // Harness is the display name ("Claude Code", "Codex", "OpenCode"). + Harness string `json:"harness"` + // Source names the native report, e.g. "rate_limit_event". + Source string `json:"source,omitempty"` + // Plan is the harness's plan identifier when it reports one ("max", "plus"). + Plan string `json:"plan,omitempty"` + // AsOf is when the server received the report (epoch milliseconds). + AsOf int64 `json:"as_of,omitempty"` + Windows []ChatQuotaWindow `json:"windows,omitempty"` + Unsupported bool `json:"unsupported,omitempty"` +} + +// ChatQuotaWindow is one rolling quota window. UsedPercent is 0-100 (it can +// exceed 100 when the harness says usage ran past the cap); ResetsAt is epoch +// milliseconds, 0 when the harness did not say. +type ChatQuotaWindow struct { + ID string `json:"id"` + Label string `json:"label"` + UsedPercent float64 `json:"used_percent"` + ResetsAt int64 `json:"resets_at,omitempty"` +} + +// Clone returns a deep copy (nil stays nil). +func (a *ChatAccountUsage) Clone() *ChatAccountUsage { + if a == nil { + return nil + } + copy := *a + copy.Windows = append([]ChatQuotaWindow(nil), a.Windows...) + return © } // ChatShell is the state of one shell command the agent started, carried by a diff --git a/internal/protocol/chat_usage_test.go b/internal/protocol/chat_usage_test.go index dfd5e1f7..6fc3793f 100644 --- a/internal/protocol/chat_usage_test.go +++ b/internal/protocol/chat_usage_test.go @@ -20,3 +20,28 @@ func TestChatUsageUnknownAndReportedZeroAreDistinct(t *testing.T) { } } } + +func TestChatAccountUsageWireShapeAndClone(t *testing.T) { + if data, _ := json.Marshal(ChatUsage{}); strings.Contains(string(data), "account") { + t.Fatalf("unknown account quota was serialized: %s", data) + } + account := &ChatAccountUsage{Harness: "Codex", Source: "account/rateLimits", Plan: "plus", AsOf: 1700000000000, + Windows: []ChatQuotaWindow{{ID: "primary", Label: "5-hour", UsedPercent: 0, ResetsAt: 1700000600000}}} + data, _ := json.Marshal(ChatUsage{Account: account}) + want := `{"account":{"harness":"Codex","source":"account/rateLimits","plan":"plus","as_of":1700000000000,"windows":[{"id":"primary","label":"5-hour","used_percent":0,"resets_at":1700000600000}]}}` + if string(data) != want { + t.Fatalf("wire = %s\nwant %s", data, want) + } + copy := account.Clone() + copy.Windows[0].UsedPercent = 50 + if account.Windows[0].UsedPercent != 0 { + t.Fatal("clone shares windows") + } + if (*ChatAccountUsage)(nil).Clone() != nil { + t.Fatal("nil clone") + } + unsupported, _ := json.Marshal(ChatAccountUsage{Harness: "OpenCode", Unsupported: true}) + if string(unsupported) != `{"harness":"OpenCode","unsupported":true}` { + t.Fatalf("unsupported wire = %s", unsupported) + } +} diff --git a/internal/server/chat_hub.go b/internal/server/chat_hub.go index 6dc964f4..ab9394d8 100644 --- a/internal/server/chat_hub.go +++ b/internal/server/chat_hub.go @@ -307,6 +307,7 @@ func cloneChatUsage(usage *protocol.ChatUsage) *protocol.ChatUsage { return nil } copy := *usage + copy.Account = usage.Account.Clone() if usage.TotalTokens != nil { value := *usage.TotalTokens copy.TotalTokens = &value