From f48725708138aa315332846f470d0bddbc5ce812 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 10:21:53 +0100 Subject: [PATCH] feat(app): show recorded chat usage in a native info panel The chat thread header gains an Info action that opens a platform sheet (Material bottom sheet, Cupertino popup) with the four harness-reported usage facts in the web order and wording: rate, tokens, context and reported cost. Unknown facts read Unavailable; reported zeros stay zero. A live usage frame replaces an open panel without adding messages or touching turn state. --- .../conversation/chat_thread_controller.dart | 34 +++ .../chat/conversation/chat_thread_view.dart | 256 ++++++++++++++++++ .../conversation/chat_info_sheet_test.dart | 178 ++++++++++++ 3 files changed, 468 insertions(+) create mode 100644 app/test/features/chat/conversation/chat_info_sheet_test.dart diff --git a/app/lib/features/chat/conversation/chat_thread_controller.dart b/app/lib/features/chat/conversation/chat_thread_controller.dart index 198b6ca5..80209f06 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_sessions.dart'; import '../domain/chat_transcript.dart'; import 'chat_thread_cards.dart'; @@ -42,6 +43,7 @@ class ChatThreadController extends ChangeNotifier { bool _hasMore = false; String _cursor = ''; String _nativeTurnId = ''; + JsonMap? _usage; String? _error; bool _subscribed = false; @@ -59,6 +61,11 @@ class ChatThreadController extends ChangeNotifier { /// The server's opaque older-page cursor. Never interpreted, only passed back. String get cursor => _cursor; + + /// The latest recorded usage snapshot, or null before the harness reports. + /// Unknown fields stay null, so a viewer can distinguish them from zero. + JsonMap? get usage => _usage; + String? get error => _error; bool get subscribed => _subscribed; String? get subscriptionError => _subscriptionError; @@ -222,6 +229,16 @@ class ChatThreadController extends ChangeNotifier { unawaited(resync()); return; } + if (body['kind'] == 'usage') { + // 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; + _usage = usage; + _notify(); + return; + } if (body['kind'] == 'form') { final form = body['form']; if (form is! Map) return; @@ -240,6 +257,23 @@ class ChatThreadController extends ChangeNotifier { _notify(); } + /// Whether a normalized snapshot names a scope or carries a recorded fact. + /// A window of zero reports no usable limit, and a rate basis alone reports + /// no number at all, so neither counts as a fact on its own. + bool _reportedUsage(JsonMap usage) { + if ('${usage['scope'] ?? ''}'.isNotEmpty) return true; + if (usage['context_window'] is int && + (usage['context_window'] as int) > 0) { + return true; + } + return const [ + 'total_tokens', + 'context_tokens', + 'cost_usd', + 'output_tokens_per_second', + ].any((key) => usage[key] != null); + } + /// The pushed envelope body, or null for another message type. The server /// wraps `chat_event` in the typed envelope; domain code never sees the /// transport fields. diff --git a/app/lib/features/chat/conversation/chat_thread_view.dart b/app/lib/features/chat/conversation/chat_thread_view.dart index 9e089695..33b2fa38 100644 --- a/app/lib/features/chat/conversation/chat_thread_view.dart +++ b/app/lib/features/chat/conversation/chat_thread_view.dart @@ -101,6 +101,34 @@ class _ChatThreadViewState extends State { }); } + /// Reports the harness's recorded usage. The standard sheet is dismissed the + /// platform's way (drag/barrier/Back, or a popup tap) and closes explicitly. + Future _openInfo() async { + final cupertino = + chatControlsStyleOf(context) == ChatControlsStyle.cupertino; + if (cupertino) { + await showCupertinoModalPopup( + context: context, + builder: (sheetContext) => Align( + alignment: Alignment.bottomCenter, + child: SafeArea( + child: CupertinoPopupSurface( + child: _ChatInfoSheet(controller: _controller), + ), + ), + ), + ); + return; + } + await showModalBottomSheet( + context: context, + showDragHandle: true, + isScrollControlled: true, + useSafeArea: true, + builder: (sheetContext) => _ChatInfoSheet(controller: _controller), + ); + } + /// Local turns whose authoritative copy is not in the held transcript yet. /// A live user frame or a history page that carries the same operation, /// native id or message id hides the local copy instead of drawing it twice. @@ -195,6 +223,13 @@ class _ChatThreadViewState extends State { ).textTheme.navTitleTextStyle : Theme.of(context).textTheme.titleLarge, ), + ChatBarAction( + key: const Key('chat-info'), + label: 'Chat information', + onPressed: _openInfo, + materialIcon: Icons.info_outline, + cupertinoIcon: CupertinoIcons.info, + ), ], ), ), @@ -312,6 +347,227 @@ class _ChatThreadViewState extends State { ); } +/// One reported usage metric: its web label, whether the harness reported it, +/// and the displayed value. Unavailable is a word, never a zero. +typedef _ChatInfoMetric = ({ + String key, + String label, + bool available, + String value, +}); + +const _chatInfoUnavailable = 'Unavailable'; + +/// The four chat usage facts in the web order and wording. +/// +/// Values come only from [ChatThreadController.usage]; a missing count, amount +/// or window is "Unavailable". A reported zero stays a reported zero, and the +/// context row keeps the web's partial forms when only one side was reported. +List<_ChatInfoMetric> _chatInfoMetrics(JsonMap? usage) { + final scope = '${usage?['scope'] ?? ''}'; + final basis = '${usage?['rate_basis'] ?? ''}'; + final rate = _chatInfoAmount(usage?['output_tokens_per_second']); + final total = _chatInfoCount(usage?['total_tokens']); + final used = _chatInfoCount(usage?['context_tokens']); + final reportedWindow = _chatInfoCount(usage?['context_window']); + // The web treats a zero context window as no reported limit. + final limit = reportedWindow != null && reportedWindow > 0 + ? reportedWindow + : null; + final cost = _chatInfoAmount(usage?['cost_usd']); + final context = used != null && limit != null + ? '${_chatInfoInteger(used)} / ${_chatInfoInteger(limit)}' + : limit != null + ? '${_chatInfoInteger(limit)} limit' + : used != null + ? '${_chatInfoInteger(used)} used' + : _chatInfoUnavailable; + return [ + ( + key: 'rate', + label: basis == 'turn' ? 'Avg output rate' : 'Output rate', + available: rate != null, + value: rate == null ? _chatInfoUnavailable : _chatInfoRate(rate), + ), + ( + key: 'tokens', + label: scope == 'turn' ? 'Turn tokens' : 'Total tokens', + available: total != null, + value: total == null ? _chatInfoUnavailable : _chatInfoInteger(total), + ), + ( + key: 'context', + label: 'Context', + available: used != null || limit != null, + value: context, + ), + ( + key: 'cost', + label: 'Reported cost', + available: cost != null, + value: cost == null ? _chatInfoUnavailable : _chatInfoDollars(cost), + ), + ]; +} + +int? _chatInfoCount(Object? value) => value is int && value >= 0 ? value : null; + +num? _chatInfoAmount(Object? value) => + value is num && value.isFinite && value >= 0 ? value : null; + +String _chatInfoInteger(int value) { + final digits = value.toString(); + final grouped = StringBuffer(); + for (var index = 0; index < digits.length; index++) { + if (index > 0 && (digits.length - index) % 3 == 0) grouped.write(','); + grouped.write(digits[index]); + } + return grouped.toString(); +} + +String _chatInfoRate(num value) { + final atMostOneDecimal = value.toStringAsFixed(1); + final number = atMostOneDecimal.endsWith('.0') + ? atMostOneDecimal.substring(0, atMostOneDecimal.length - 2) + : atMostOneDecimal; + return value > 0 && value < 0.1 ? '<0.1 tok/s' : '$number tok/s'; +} + +String _chatInfoDollars(num value) { + if (value > 0 && value < 0.000001) return '<\$0.000001'; + final fixed = value.toStringAsFixed(6); + final point = fixed.indexOf('.'); + var decimals = fixed.substring(point + 1); + while (decimals.length > 4 && decimals.endsWith('0')) { + decimals = decimals.substring(0, decimals.length - 1); + } + final whole = int.parse(fixed.substring(0, point)); + return '\$${_chatInfoInteger(whole)}.$decimals'; +} + +/// The "Chat information" panel. It rebuilds from the controller, so metrics +/// that arrive while it is open replace the displayed snapshot. +class _ChatInfoSheet extends StatelessWidget { + const _ChatInfoSheet({required this.controller}); + + final ChatThreadController controller; + + @override + Widget build(BuildContext context) { + final cupertino = + chatControlsStyleOf(context) == ChatControlsStyle.cupertino; + return AnimatedBuilder( + animation: controller, + builder: (context, _) { + final titleStyle = cupertino + ? CupertinoTheme.of(context).textTheme.navTitleTextStyle + : Theme.of(context).textTheme.titleLarge; + final content = Column( + key: const Key('chat-info-sheet'), + mainAxisSize: MainAxisSize.min, + crossAxisAlignment: CrossAxisAlignment.stretch, + children: [ + Padding( + padding: const EdgeInsetsDirectional.fromSTEB(24, 8, 16, 4), + child: Row( + children: [ + Expanded( + child: Semantics( + header: true, + child: Text('Chat information', style: titleStyle), + ), + ), + if (cupertino) + CupertinoButton( + key: const Key('chat-info-close'), + padding: EdgeInsets.zero, + onPressed: () => Navigator.of(context).pop(), + child: const Text('Close'), + ) + else + TextButton( + key: const Key('chat-info-close'), + onPressed: () => Navigator.of(context).pop(), + child: const Text('Close'), + ), + ], + ), + ), + for (final metric in _chatInfoMetrics(controller.usage)) + _ChatInfoRow(metric: metric, cupertino: cupertino), + Padding( + padding: const EdgeInsetsDirectional.fromSTEB(24, 8, 24, 16), + child: Text( + 'Last reported by the harness. ' + 'Unavailable values are not estimated.', + style: + (cupertino + ? CupertinoTheme.of(context).textTheme.textStyle + : Theme.of(context).textTheme.bodySmall) + ?.copyWith( + color: cupertino + ? CupertinoColors.secondaryLabel.resolveFrom( + context, + ) + : Theme.of(context).colorScheme.onSurfaceVariant, + ), + ), + ), + ], + ); + if (!cupertino) return SingleChildScrollView(child: content); + // A tall text scale must scroll inside the popup rather than push its + // heading off-screen. The height follows the viewport, not a fixed size. + return ConstrainedBox( + constraints: BoxConstraints( + maxHeight: MediaQuery.sizeOf(context).height * 0.8, + ), + child: SingleChildScrollView(child: content), + ); + }, + ); + } +} + +class _ChatInfoRow extends StatelessWidget { + const _ChatInfoRow({required this.metric, required this.cupertino}); + + final _ChatInfoMetric metric; + final bool cupertino; + + @override + Widget build(BuildContext context) { + final secondary = cupertino + ? CupertinoColors.secondaryLabel.resolveFrom(context) + : Theme.of(context).colorScheme.onSurfaceVariant; + final labelStyle = + (cupertino + ? CupertinoTheme.of(context).textTheme.textStyle + : Theme.of(context).textTheme.bodySmall) + ?.copyWith(color: secondary); + final valueStyle = cupertino + ? CupertinoTheme.of(context).textTheme.textStyle + : Theme.of(context).textTheme.bodyLarge; + return Padding( + key: Key('chat-info-metric-${metric.key}'), + padding: const EdgeInsetsDirectional.fromSTEB(24, 6, 24, 6), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text(metric.label, style: labelStyle), + Text( + metric.value, + key: Key('chat-info-value-${metric.key}'), + style: metric.available + ? valueStyle + : valueStyle?.copyWith(color: secondary), + ), + ], + ), + ); + } +} + /// One recorded activity line for a turn. /// /// The line is a summary of the recorded sequence. Its wording and state come diff --git a/app/test/features/chat/conversation/chat_info_sheet_test.dart b/app/test/features/chat/conversation/chat_info_sheet_test.dart new file mode 100644 index 00000000..9c0b137b --- /dev/null +++ b/app/test/features/chat/conversation/chat_info_sheet_test.dart @@ -0,0 +1,178 @@ +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 '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, +}; + +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() { + testWidgets('reports the recorded facts with the web labels', (tester) async { + final gateway = await _thread(tester); + gateway.emitEvent( + _usageFrame({ + 'scope': 'session', + 'total_tokens': 132408, + 'context_tokens': 42000, + 'context_window': 200000, + 'cost_usd': 0.1423, + 'output_tokens_per_second': 24.6, + 'rate_basis': 'generation', + }), + ); + await tester.pump(); + + await _openInfo(tester); + + expect(find.text('Chat information'), findsOneWidget); + expect(find.text('Output rate'), findsOneWidget); + expect(find.text('24.6 tok/s'), findsOneWidget); + expect(find.text('Total tokens'), findsOneWidget); + expect(find.text('132,408'), findsOneWidget); + expect(find.text('Context'), findsOneWidget); + expect(find.text('42,000 / 200,000'), findsOneWidget); + expect(find.text('Reported cost'), findsOneWidget); + expect(find.text('\$0.1423'), findsOneWidget); + expect( + find.text( + 'Last reported by the harness. ' + 'Unavailable values are not estimated.', + ), + findsOneWidget, + ); + + // A snapshot that arrives while the panel is open replaces the shown one. + gateway.emitEvent( + _usageFrame({ + 'scope': 'turn', + 'total_tokens': 133000, + 'context_tokens': 3000, + 'context_window': 200000, + 'cost_usd': 0.2, + 'output_tokens_per_second': 10, + 'rate_basis': 'turn', + }), + ); + await tester.pumpAndSettle(); + + expect(find.text('Turn tokens'), findsOneWidget); + expect(find.text('133,000'), findsOneWidget); + expect(find.text('Avg output rate'), findsOneWidget); + expect(find.text('10 tok/s'), findsOneWidget); + }); + + testWidgets('unknown facts say Unavailable while reported zeros stay zero', ( + tester, + ) async { + final gateway = await _thread(tester); + gateway.emitEvent(_usageFrame({'scope': 'session'})); + await tester.pump(); + + await _openInfo(tester); + + expect(find.text('Unavailable'), findsNWidgets(4)); + expect(find.text('0'), findsNothing); + + await tester.tap(find.byKey(const Key('chat-info-close'))); + await tester.pumpAndSettle(); + + gateway.emitEvent( + _usageFrame({ + 'scope': 'session', + 'total_tokens': 0, + 'context_tokens': 0, + 'context_window': 1000, + 'cost_usd': 0, + 'output_tokens_per_second': 0, + }), + ); + await tester.pump(); + await _openInfo(tester); + + expect(find.text('Unavailable'), findsNothing); + expect(find.text('0 tok/s'), findsOneWidget); + expect(find.text('0'), findsOneWidget); + expect(find.text('0 / 1,000'), findsOneWidget); + expect(find.text('\$0.0000'), findsOneWidget); + }); + + testWidgets('the native sheet dismisses from Close and the barrier', ( + tester, + ) async { + final gateway = await _thread(tester); + gateway.emitEvent(_usageFrame({'scope': 'session', 'total_tokens': 5})); + await tester.pump(); + + await _openInfo(tester); + expect(find.byKey(const Key('chat-info-sheet')), findsOneWidget); + + await tester.tap(find.byKey(const Key('chat-info-close'))); + await tester.pumpAndSettle(); + expect(find.byKey(const Key('chat-info-sheet')), findsNothing); + expect(find.byKey(const Key('chat-info')), findsOneWidget); + + await _openInfo(tester); + expect(find.byKey(const Key('chat-info-sheet')), findsOneWidget); + + // The modal barrier above the sheet is the platform's dismiss target. + await tester.tapAt(const Offset(8, 8)); + await tester.pumpAndSettle(); + expect(find.byKey(const Key('chat-info-sheet')), findsNothing); + expect(find.byKey(const Key('chat-info')), findsOneWidget); + }); + + testWidgets('the Cupertino host opens and closes the native popup', ( + tester, + ) async { + final gateway = await _thread(tester, cupertino: true); + gateway.emitEvent(_usageFrame({'scope': 'session', 'total_tokens': 42})); + await tester.pump(); + + await _openInfo(tester); + expect(find.text('Chat information'), findsOneWidget); + expect(find.text('42'), findsOneWidget); + + await tester.tap(find.byKey(const Key('chat-info-close'))); + await tester.pumpAndSettle(); + expect(find.byKey(const Key('chat-info-sheet')), findsNothing); + expect(find.byKey(const Key('chat-info')), findsOneWidget); + }); +}