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.
This commit is contained in:
2026-10-22 10:21:53 +01:00
parent 7aa7007aee
commit f487257081
3 changed files with 468 additions and 0 deletions
@@ -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.
@@ -101,6 +101,34 @@ class _ChatThreadViewState extends State<ChatThreadView> {
});
}
/// 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<void> _openInfo() async {
final cupertino =
chatControlsStyleOf(context) == ChatControlsStyle.cupertino;
if (cupertino) {
await showCupertinoModalPopup<void>(
context: context,
builder: (sheetContext) => Align(
alignment: Alignment.bottomCenter,
child: SafeArea(
child: CupertinoPopupSurface(
child: _ChatInfoSheet(controller: _controller),
),
),
),
);
return;
}
await showModalBottomSheet<void>(
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<ChatThreadView> {
).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<ChatThreadView> {
);
}
/// 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
@@ -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<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() {
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);
});
}