Chat info: account quota per harness (Claude rate_limit_event, Codex account/rateLimits, OpenCode unsupported)

Usage frames carry optional usage.account {harness, source, plan, as_of,
windows[{id,label,used_percent,resets_at}], unsupported}. Claude Code quota
comes from its rate_limit_event stream lines and the initialize account
(plan), shared across chats on the same account. Codex reads
account/rateLimits/read once per connection (re-read when a chat opens after
5 min) and merges account/rateLimits/updated. OpenCode exposes no quota API
and says so. The app's chat info sheet shows an Account usage section with a
progress bar and reset countdown per window, Material and Cupertino.
This commit is contained in:
2026-11-02 18:57:13 +00:00
parent 8a402c1114
commit 10049b8062
26 changed files with 1469 additions and 19 deletions
@@ -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<ChatAccountUsageSection> createState() =>
_ChatAccountUsageSectionState();
}
class _ChatAccountUsageSectionState extends State<ChatAccountUsageSection> {
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,
),
],
),
);
}
}
@@ -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;
@@ -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(
@@ -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<ChatQuotaWindow> 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 = <ChatQuotaWindow>[];
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);
}
+13
View File
@@ -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 <age>".
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&quota=claude`
or `quota=opencode` (`tool/perf/perf_fixture.dart`), opened at
`/chat/perf-chat-0` and clicking the title, 560x1000, Material and Cupertino.
@@ -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<FakeChatGateway> _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<void> _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<LinearProgressIndicator>(
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);
});
}
+53 -1
View File
@@ -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<String, String> _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<JsonMap> 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',
+7 -2
View File
@@ -506,9 +506,14 @@ class _FixtureChannel implements WebSocketChannel {
final decoded = jsonDecode(data);
if (decoded is! Map<String, dynamic>) return;
final reply = probeReply(decoded);
if (reply == null) return;
final followUps = perfChatFollowUps(decoded);
if (reply == null && followUps.isEmpty) return;
Future<void>.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));
}
});
}
+13
View File
@@ -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:
+19 -3
View File
@@ -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
+8 -6
View File
@@ -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.
+213
View File
@@ -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 = &copy
}
s.mu.Unlock()
s.emit(protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventUsage, Usage: usage})
}
+105
View File
@@ -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)
}
}
+10
View File
@@ -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")
+4
View File
@@ -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)
+29 -1
View File
@@ -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"`
+207
View File
@@ -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 = &quotaState{}
}
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 = &copy
}
frames = append(frames, protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: usage})
}
c.mu.Unlock()
for _, frame := range frames {
c.emit(frame)
}
}
+109
View File
@@ -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, &params) != 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)
}
}
}
+11
View File
@@ -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.
+19
View File
@@ -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
}
@@ -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
}
}
}
+1 -1
View File
@@ -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},
+13 -3
View File
@@ -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 {
+40
View File
@@ -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 &copy
}
// ChatShell is the state of one shell command the agent started, carried by a
+25
View File
@@ -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)
}
}
+1
View File
@@ -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