From 7cdb9e8338d00e747928c9938e61fe33f74a1204 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 13:24:49 +0100 Subject: [PATCH] feat(app): add chat foundation --- app/.gitignore | 3 + .../features/chat/data/chat_repository.dart | 146 ++++++++++ .../features/chat/domain/chat_sessions.dart | 64 +++++ .../features/chat/domain/chat_transcript.dart | 235 ++++++++++++++++ app/notes/F4.md | 17 ++ .../features/chat/chat_foundation_test.dart | 259 ++++++++++++++++++ 6 files changed, 724 insertions(+) create mode 100644 app/lib/features/chat/data/chat_repository.dart create mode 100644 app/lib/features/chat/domain/chat_sessions.dart create mode 100644 app/lib/features/chat/domain/chat_transcript.dart create mode 100644 app/notes/F4.md create mode 100644 app/test/features/chat/chat_foundation_test.dart diff --git a/app/.gitignore b/app/.gitignore index 3820a95c..e747ec42 100644 --- a/app/.gitignore +++ b/app/.gitignore @@ -43,3 +43,6 @@ app.*.map.json /android/app/debug /android/app/profile /android/app/release + +# Chat's source adapter lives in a directory commonly ignored as generated data. +!lib/features/chat/data/ diff --git a/app/lib/features/chat/data/chat_repository.dart b/app/lib/features/chat/data/chat_repository.dart new file mode 100644 index 00000000..8053ef5c --- /dev/null +++ b/app/lib/features/chat/data/chat_repository.dart @@ -0,0 +1,146 @@ +import '../../../core/api_gateway.dart'; + +/// Chat wire adapter. ApiGateway supplies request ids and returns full envelopes. +class ChatRepository { + ChatRepository(this.gateway); + final ApiGateway gateway; + + Future> sessions() async => + _maps((await gateway.call('chat_sessions'))['chat_sessions']); + Future> models(String sessionId) async => _maps( + (await gateway.call('chat_models', { + 'chat_query': {'session_id': sessionId}, + }))['chat_models'], + ); + Future selectModel( + String sessionId, + String provider, + String model, + ) => gateway.call('chat_model', { + 'chat_model': { + 'session_id': sessionId, + 'provider': provider, + 'model': model, + }, + }); + Future> shells(String sessionId) async => _maps( + (await gateway.call('chat_shells', { + 'chat_query': {'session_id': sessionId}, + }))['chat_shells'], + ); + Future> directories() async => + ((await gateway.call('chat_directories'))['chat_directories'] as List? ?? + const []) + .whereType() + .toList(); + + Future history( + String sessionId, { + int limit = 50, + String cursor = '', + }) async { + final reply = await gateway.call('chat_messages', { + 'chat_query': {'session_id': sessionId, 'limit': limit, 'cursor': cursor}, + }); + final page = reply['chat_history']; + if (page is Map) { + return { + 'messages': _maps(page['messages']), + 'nextCursor': '${page['next_cursor'] ?? ''}', + 'hasMore': page['has_more'] == true, + }; + } + return { + 'messages': _maps(reply['chat_messages']), + 'nextCursor': '', + 'hasMore': false, + }; + } + + Future subscribe(String sessionId) => + gateway.call('chat_subscribe', { + 'chat_subscribe': {'session_id': sessionId}, + }); + Future create({ + required String title, + required String directory, + required String operationId, + String backend = 'opencode', + String instructions = '', + }) => gateway.call('chat_create', { + 'chat_create': { + 'title': title, + 'directory': directory, + 'operation_id': operationId, + if (backend.isNotEmpty && backend != 'opencode') 'backend': backend, + if (instructions.trim().isNotEmpty) 'instructions': instructions.trim(), + }, + }); + Future rename(String sessionId, String title) => + gateway.call('chat_rename', { + 'chat_rename': {'session_id': sessionId, 'title': title.trim()}, + }); + Future star(String sessionId, bool starred) => + gateway.call('chat_star', { + 'chat_query': {'session_id': sessionId, 'starred': starred}, + }); + Future close(String sessionId) => gateway.call('chat_close', { + 'chat_query': {'session_id': sessionId}, + }); + Future reopen(String sessionId) => gateway.call('chat_reopen', { + 'chat_query': {'session_id': sessionId}, + }); + + Future prompt( + String sessionId, + String text, { + required String operationId, + List files = const [], + }) { + final body = { + 'session_id': sessionId, + 'text': text.trim(), + 'operation_id': operationId, + }; + if (files.isNotEmpty) body['files'] = files; + return gateway.call('chat_prompt', {'chat_prompt': body}); + } + + Future interrupt(String sessionId) => + gateway.call('chat_interrupt', { + 'chat_query': {'session_id': sessionId}, + }); + Future answerForm( + String sessionId, + String formId, + JsonMap answers, { + String action = '', + }) => gateway.call('chat_answer', { + 'chat_answer': { + 'session_id': sessionId, + 'form_id': formId, + 'answers': answers, + if (action.isNotEmpty) 'action': action, + }, + }); + Future replyPermission( + String sessionId, + String requestId, + String decision, { + String client = 'web', + String message = '', + }) => gateway.call('chat_reply', { + 'chat_reply': { + 'session_id': sessionId, + 'request_id': requestId, + 'decision': decision, + 'client': client, + if (message.trim().isNotEmpty) 'message': message.trim(), + }, + }); + + static List _maps(Object? value) => (value as List? ?? const []) + .whereType() + .map((item) => Map.from(item)) + .toList(); +} diff --git a/app/lib/features/chat/domain/chat_sessions.dart b/app/lib/features/chat/domain/chat_sessions.dart new file mode 100644 index 00000000..76bacdf6 --- /dev/null +++ b/app/lib/features/chat/domain/chat_sessions.dart @@ -0,0 +1,64 @@ +import '../../../core/api_gateway.dart'; + +/// Pure session-list operations. Unknown server fields remain on each row. +String chatSessionTitle(JsonMap session) { + final title = '${session['title'] ?? ''}'; + if (title.trim().isNotEmpty) return title; + final id = '${session['id'] ?? ''}'; + return id.isEmpty ? 'Untitled chat' : id.substring(0, id.length.clamp(0, 18)); +} + +List filterChatSessions(List sessions, String query) { + final needle = query.trim().toLowerCase(); + if (needle.isEmpty) return sessions; + return sessions + .where( + (session) => + '${chatSessionTitle(session)}\u0000${session['directory'] ?? ''}' + .toLowerCase() + .contains(needle), + ) + .toList(); +} + +/// Directory groups retain server recency order, both within and between groups. +List<({String directory, List sessions})> groupChatSessions( + List sessions, +) { + final groups = >{}; + for (final session in sessions) { + groups.putIfAbsent('${session['directory'] ?? ''}', () => []).add(session); + } + return groups.entries + .map((entry) => (directory: entry.key, sessions: entry.value)) + .toList(); +} + +String chatSessionActivity({required bool running, required bool unseen}) => + running + ? 'streaming' + : unseen + ? 'new' + : 'idle'; + +/// Native reported values only; missing and invalid values remain unavailable. +JsonMap? chatUsageSnapshot(Object? value) { + if (value is! Map || value is List) return null; + final usage = Map.from(value); + final result = {}; + for (final key in ['total_tokens', 'context_tokens', 'context_window']) { + final n = usage[key]; + result[key] = n is int && n >= 0 ? n : null; + } + for (final key in ['cost_usd', 'output_tokens_per_second']) { + final n = usage[key]; + result[key] = n is num && n.isFinite && n >= 0 ? n : null; + } + result['scope'] = ['session', 'turn'].contains(usage['scope']) + ? usage['scope'] + : ''; + result['rate_basis'] = ['generation', 'turn'].contains(usage['rate_basis']) + ? usage['rate_basis'] + : ''; + return result.values.any((v) => v != null && v != '') ? result : null; +} diff --git a/app/lib/features/chat/domain/chat_transcript.dart b/app/lib/features/chat/domain/chat_transcript.dart new file mode 100644 index 00000000..b766f15e --- /dev/null +++ b/app/lib/features/chat/domain/chat_transcript.dart @@ -0,0 +1,235 @@ +import '../../../core/api_gateway.dart'; + +/// Merge chronological history pages by message id. Incoming authoritative +/// copies replace held copies without changing their order; cursor is opaque. +JsonMap mergeChatHistory(JsonMap previous, JsonMap page, {bool older = false}) { + final held = (previous['messages'] as List? ?? const []) + .whereType() + .map((m) => Map.from(m)) + .toList(); + final incoming = (page['messages'] as List? ?? const []) + .whereType() + .map((m) => Map.from(m)) + .toList(); + final latest = {}; + for (final message in incoming) { + if (message['id'] != null) latest[message['id']] = message; + } + final combined = older ? [...incoming, ...held] : [...held, ...incoming]; + final seen = {}; + final messages = []; + for (final message in combined) { + final id = message['id']; + if (id != null && !seen.add(id)) continue; + messages.add(id == null ? message : latest[id] ?? message); + } + return { + 'messages': messages, + 'nextCursor': '${page['nextCursor'] ?? ''}', + 'hasMore': page['hasMore'] == true, + 'loaded': true, + 'loading': false, + }; +} + +/// Consecutive assistant messages form one answer turn. All part fields (also +/// future/unknown protocol types) are preserved in original order. +List transcriptRows(List messages) { + final rows = []; + String? key; + final parts = []; + void flush() { + if (key != null && parts.isNotEmpty) { + rows.add({ + 'kind': 'assistant', + 'key': key, + 'parts': List.of(parts), + }); + } + key = null; + parts.clear(); + } + + for (final message in messages) { + if (message['role'] == 'assistant') { + key ??= '${message['id'] ?? ''}'; + for (final part in (message['parts'] as List? ?? const [])) { + if (part is Map) parts.add(Map.from(part)); + } + } else { + flush(); + rows.add({'kind': 'user', 'key': message['id'], 'message': message}); + } + } + flush(); + return rows; +} + +/// Replace a local optimistic user row when its server echo identifies the +/// same operation/native message; otherwise append once by authoritative id. +List reconcileChatUser(List messages, JsonMap remote) { + final operation = remote['operation_id']; + final nativeId = remote['native_message_id']; + final id = remote['id']; + final index = messages.indexWhere( + (message) => + (operation != null && message['operation_id'] == operation) || + (nativeId != null && message['native_message_id'] == nativeId) || + (id != null && message['id'] == id), + ); + if (index < 0) return [...messages, remote]; + final result = List.of(messages); + result[index] = remote; + return result; +} + +/// Fold a live chat frame into an immutable thread snapshot. Text and reasoning +/// deltas append by part id, tool snapshots merge without dropping prior fields, +/// and step frames update turn activity. Frames for another session are ignored. +JsonMap applyChatEvent(JsonMap thread, JsonMap frame) { + final session = thread['sessionId']; + if (session != null && + frame['session_id'] != null && + session != frame['session_id']) { + return thread; + } + final messages = (thread['messages'] as List? ?? const []) + .whereType() + .map((m) => Map.from(m)) + .toList(); + final kind = frame['kind']; + if (kind == 'user') { + final part = frame['part']; + final text = part is Map ? part['text'] : null; + final id = frame['message_id']; + if (text is! String || + text.isEmpty || + id == null || + messages.any( + (m) => + m['id'] == id || + (frame['operation_id'] != null && + m['operation_id'] == frame['operation_id']), + )) { + return thread; + } + messages.add({ + 'id': id, + 'session_id': frame['session_id'], + 'role': 'user', + 'client': frame['client'], + 'operation_id': frame['operation_id'], + 'parts': [ + {'type': 'text', 'text': text}, + ...(frame['attachments'] is List + ? frame['attachments'] as List + : const []), + ], + }); + return {...thread, 'messages': messages}; + } + if (kind == 'text' || kind == 'reasoning' || kind == 'tool') { + final incoming = frame['part']; + if (incoming is! Map || incoming['id'] == null) return thread; + final messageId = frame['message_id']; + var index = messages.indexWhere( + (m) => m['id'] == messageId && m['role'] == 'assistant', + ); + if (index < 0) { + messages.add({ + 'id': messageId, + 'session_id': frame['session_id'], + 'role': 'assistant', + 'parts': [], + }); + index = messages.length - 1; + } + final message = messages[index]; + final parts = (message['parts'] as List? ?? const []) + .whereType() + .map((p) => Map.from(p)) + .toList(); + final partIndex = parts.indexWhere( + (p) => p['id'] == incoming['id'] && p['type'] == kind, + ); + if (kind == 'text' || kind == 'reasoning') { + final delta = frame['delta']; + if (delta is! String || delta.isEmpty) return thread; + if (partIndex < 0) { + parts.add({'type': kind, 'id': incoming['id'], 'text': delta}); + } else { + parts[partIndex] = { + ...parts[partIndex], + 'text': '${parts[partIndex]['text'] ?? ''}$delta', + }; + } + } else if (partIndex < 0) { + parts.add(Map.from(incoming)); + } else { + final merged = { + ...parts[partIndex], + ...Map.from(incoming), + }; + if (parts[partIndex]['state'] is Map && incoming['state'] is Map) { + merged['state'] = { + ...Map.from(parts[partIndex]['state'] as Map), + ...Map.from(incoming['state'] as Map), + }; + } + parts[partIndex] = merged; + } + messages[index] = {...message, 'parts': parts}; + return {...thread, 'messages': messages, 'running': true}; + } + if (kind == 'step' && frame['step'] is Map) { + final step = frame['step'] as Map; + if (step['intermediate'] == true) return thread; + return { + ...thread, + 'running': step['status'] != 'ended', + 'nativeTurnId': step['status'] == 'ended' + ? '' + : (step['turn_id'] ?? thread['nativeTurnId'] ?? ''), + }; + } + return thread; +} + +/// Queue serialized sends per session; operation ids survive retries/replays. +class QueuedChatSend { + QueuedChatSend({ + required this.operationId, + required this.text, + this.files = const [], + }); + final String operationId; + final String text; + final List files; + + /// Retry the same immutable intent with the same idempotency key. + QueuedChatSend retry() => QueuedChatSend( + operationId: operationId, + text: text, + files: List.unmodifiable(files), + ); +} + +class ChatSendQueue { + final Map> _sessions = {}; + List forSession(String sessionId) => + List.unmodifiable(_sessions[sessionId] ?? const []); + bool enqueue(String sessionId, QueuedChatSend send) { + final queue = _sessions.putIfAbsent(sessionId, () => []); + if (queue.any((item) => item.operationId == send.operationId)) return false; + queue.add(send); + return true; + } + + QueuedChatSend? takeNext(String sessionId) { + final queue = _sessions[sessionId]; + if (queue == null || queue.isEmpty) return null; + final result = queue.removeAt(0); + if (queue.isEmpty) _sessions.remove(sessionId); + return result; + } +} diff --git a/app/notes/F4.md b/app/notes/F4.md new file mode 100644 index 00000000..a2578786 --- /dev/null +++ b/app/notes/F4.md @@ -0,0 +1,17 @@ +# F4 chat foundation + +Non-visual chat foundations for the UI lane, using the shared `ApiGateway` and no socket ownership. + +## Imports and API + +- `package:pipelines_app/features/chat/domain/chat_sessions.dart`: `chatSessionTitle`, `filterChatSessions`, `groupChatSessions`, `chatSessionActivity`, and `chatUsageSnapshot`. +- `package:pipelines_app/features/chat/domain/chat_transcript.dart`: `mergeChatHistory`, `transcriptRows`, `reconcileChatUser`, `applyChatEvent`, `QueuedChatSend`, and `ChatSendQueue`. +- `package:pipelines_app/features/chat/data/chat_repository.dart`: `ChatRepository(gateway)`; exposes sessions, directories, history, subscribe, create/rename/star/close/reopen, prompt/interrupt, form answer, permission reply, models/shells and model selection. `gateway.frames` remains the UI/controller's unsolicited event source. + +History uses `chat_history.next_cursor` verbatim, falls back to legacy `chat_messages`, and replaces duplicate authoritative messages while preserving order. `transcriptRows` preserves unknown part maps. Live fold supports user echoes, text/reasoning deltas, tool state snapshots, and step activity; UI should retain its richer thread/timing state as needed. Queue operation IDs are stable across retry objects and deduplicated within each session. Usage values remain unavailable unless reported and valid. + +Wire envelopes are asserted in `test/features/chat/chat_foundation_test.dart`. Current backend has no `chat_forms` or `chat_permissions` list command; forms and permissions arrive as live events and are answered through `chat_answer` / `chat_reply`. + +## Verification + +`/Users/alan/development/flutter/bin/flutter test test/features/chat` passed. Nonvisual foundation: UI/browser review and captures are not applicable at this stage. Web is the only permitted target; Android/iOS remain unverified. diff --git a/app/test/features/chat/chat_foundation_test.dart b/app/test/features/chat/chat_foundation_test.dart new file mode 100644 index 00000000..76e74353 --- /dev/null +++ b/app/test/features/chat/chat_foundation_test.dart @@ -0,0 +1,259 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/chat/data/chat_repository.dart'; +import 'package:pipelines_app/features/chat/domain/chat_sessions.dart'; +import 'package:pipelines_app/features/chat/domain/chat_transcript.dart'; + +class RecordingGateway implements ApiGateway { + final calls = <({String type, JsonMap fields})>[]; + JsonMap reply = {}; + @override + Future call(String type, [JsonMap fields = const {}]) async { + calls.add((type: type, fields: fields)); + return reply; + } + + @override + Stream get frames => const Stream.empty(); +} + +void main() { + group('chat domain', () { + test( + 'filters/groups in server order and keeps server usage unknowns unavailable', + () { + final sessions = [ + {'id': 'a', 'directory': '/work', 'title': 'First'}, + {'id': 'b', 'directory': '/else', 'title': 'Second'}, + {'id': 'c', 'directory': '/work', 'title': 'Third'}, + ]; + expect(filterChatSessions(sessions, 'ELSE').single['id'], 'b'); + expect(groupChatSessions(sessions).map((g) => g.directory), [ + '/work', + '/else', + ]); + expect(chatSessionActivity(running: true, unseen: true), 'streaming'); + expect( + chatUsageSnapshot({ + 'total_tokens': 3, + 'context_window': 'unknown', + })!['context_window'], + isNull, + ); + expect(chatUsageSnapshot({'legacy_tokens': 9}), isNull); + }, + ); + + test( + 'merges pages by id, retains idless events, replaces authority, and folds parts', + () { + final first = mergeChatHistory({}, { + 'messages': [ + { + 'id': 'a', + 'role': 'assistant', + 'parts': [ + {'type': 'reasoning', 'text': 'think'}, + ], + }, + { + 'role': 'assistant', + 'parts': [ + {'type': 'future_part', 'payload': 4}, + ], + }, + {'id': 'u', 'role': 'user', 'text': 'hello', 'operation_id': 'op'}, + ], + 'nextCursor': 'opaque/1', + 'hasMore': true, + }); + final older = mergeChatHistory(first, { + 'messages': [ + { + 'id': 'a', + 'role': 'assistant', + 'parts': [ + {'type': 'text', 'text': 'final'}, + ], + }, + ], + 'nextCursor': '', + 'hasMore': false, + }, older: true); + expect(older['nextCursor'], ''); + final msgs = older['messages'] as List; + expect(msgs.map((m) => m['id']), ['a', null, 'u']); + expect( + (transcriptRows(msgs).first['parts'] as List).map((p) => p['type']), + ['text', 'future_part'], + ); + expect( + reconcileChatUser(msgs, { + 'id': 'remote', + 'role': 'user', + 'operation_id': 'op', + }).where((m) => m['operation_id'] == 'op').length, + 1, + ); + }, + ); + + test( + 'send queue is session-scoped and operation IDs deduplicate retries', + () { + final queue = ChatSendQueue(); + final send = QueuedChatSend( + operationId: 'stable', + text: ' prompt ', + files: ['/tmp/a'], + ); + expect(queue.enqueue('s1', send), isTrue); + expect(queue.enqueue('s1', send.retry()), isFalse); + expect(queue.enqueue('s2', send.retry()), isTrue); + expect(queue.takeNext('s1')!.operationId, 'stable'); + expect(queue.takeNext('s1'), isNull); + expect(queue.forSession('s2').single.files, ['/tmp/a']); + }, + ); + + test( + 'live text/reasoning append, tool snapshots merge, and steps settle only activity', + () { + var thread = { + 'sessionId': 's', + 'messages': [], + }; + thread = applyChatEvent(thread, { + 'kind': 'text', + 'session_id': 's', + 'message_id': 'a', + 'part': {'id': 'p'}, + 'delta': 'one', + }); + thread = applyChatEvent(thread, { + 'kind': 'text', + 'session_id': 's', + 'message_id': 'a', + 'part': {'id': 'p'}, + 'delta': ' two', + }); + thread = applyChatEvent(thread, { + 'kind': 'reasoning', + 'session_id': 's', + 'message_id': 'a', + 'part': {'id': 'r'}, + 'delta': 'hidden', + }); + thread = applyChatEvent(thread, { + 'kind': 'tool', + 'session_id': 's', + 'message_id': 'a', + 'part': { + 'id': 't', + 'type': 'tool', + 'state': {'input': 'x'}, + }, + }); + thread = applyChatEvent(thread, { + 'kind': 'tool', + 'session_id': 's', + 'message_id': 'a', + 'part': { + 'id': 't', + 'type': 'tool', + 'state': {'status': 'completed'}, + }, + }); + final parts = + ((thread['messages'] as List).single as JsonMap)['parts'] + as List; + expect(parts[0]['text'], 'one two'); + expect(parts[1]['text'], 'hidden'); + expect(parts[2]['state'], {'input': 'x', 'status': 'completed'}); + expect(thread['running'], true); + thread = applyChatEvent(thread, { + 'kind': 'step', + 'session_id': 's', + 'step': {'status': 'ended', 'turn_id': 'turn'}, + }); + expect(thread['running'], false); + expect( + applyChatEvent(thread, {'kind': 'text', 'session_id': 'other'}), + same(thread), + ); + }, + ); + }); + + group('chat wire adapter', () { + late RecordingGateway gateway; + late ChatRepository repo; + setUp(() { + gateway = RecordingGateway(); + repo = ChatRepository(gateway); + }); + test('uses web envelopes and opaque history cursor', () async { + gateway.reply = { + 'chat_history': { + 'messages': [ + {'id': 'm', 'role': 'user'}, + ], + 'next_cursor': 'opaque', + 'has_more': true, + }, + }; + final page = await repo.history('s', cursor: 'before', limit: 17); + expect(page['nextCursor'], 'opaque'); + expect(gateway.calls.last.type, 'chat_messages'); + expect(gateway.calls.last.fields, { + 'chat_query': {'session_id': 's', 'cursor': 'before', 'limit': 17}, + }); + await repo.subscribe('s'); + expect(gateway.calls.last.fields, { + 'chat_subscribe': {'session_id': 's'}, + }); + }); + test( + 'sends stable operation id, omits empty files, and builds action envelopes', + () async { + await repo.prompt('s', ' hi ', operationId: 'same'); + expect(gateway.calls.last.fields, { + 'chat_prompt': { + 'session_id': 's', + 'text': 'hi', + 'operation_id': 'same', + }, + }); + await repo.answerForm('s', 'f', {'choice': 'yes'}, action: 'submit'); + expect(gateway.calls.last.fields, { + 'chat_answer': { + 'session_id': 's', + 'form_id': 'f', + 'answers': {'choice': 'yes'}, + 'action': 'submit', + }, + }); + await repo.replyPermission('s', 'r', 'once', message: ' approved '); + expect(gateway.calls.last.fields, { + 'chat_reply': { + 'session_id': 's', + 'request_id': 'r', + 'decision': 'once', + 'client': 'web', + 'message': 'approved', + }, + }); + await repo.create(title: 'New', directory: '~', operationId: 'create'); + expect(gateway.calls.last.fields, { + 'chat_create': { + 'title': 'New', + 'directory': '~', + 'operation_id': 'create', + }, + }); + await repo.selectModel('s', 'provider', 'model'); + expect(gateway.calls.last.type, 'chat_model'); + }, + ); + }); +}