feat(app): add chat foundation

This commit is contained in:
2026-10-21 13:24:49 +01:00
parent 0e0ef5450e
commit 7cdb9e8338
6 changed files with 724 additions and 0 deletions
+3
View File
@@ -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/
@@ -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<List<JsonMap>> sessions() async =>
_maps((await gateway.call('chat_sessions'))['chat_sessions']);
Future<List<JsonMap>> models(String sessionId) async => _maps(
(await gateway.call('chat_models', {
'chat_query': {'session_id': sessionId},
}))['chat_models'],
);
Future<JsonMap> selectModel(
String sessionId,
String provider,
String model,
) => gateway.call('chat_model', {
'chat_model': {
'session_id': sessionId,
'provider': provider,
'model': model,
},
});
Future<List<JsonMap>> shells(String sessionId) async => _maps(
(await gateway.call('chat_shells', {
'chat_query': {'session_id': sessionId},
}))['chat_shells'],
);
Future<List<String>> directories() async =>
((await gateway.call('chat_directories'))['chat_directories'] as List? ??
const [])
.whereType<String>()
.toList();
Future<JsonMap> 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<JsonMap> subscribe(String sessionId) =>
gateway.call('chat_subscribe', {
'chat_subscribe': {'session_id': sessionId},
});
Future<JsonMap> 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<JsonMap> rename(String sessionId, String title) =>
gateway.call('chat_rename', {
'chat_rename': {'session_id': sessionId, 'title': title.trim()},
});
Future<JsonMap> star(String sessionId, bool starred) =>
gateway.call('chat_star', {
'chat_query': {'session_id': sessionId, 'starred': starred},
});
Future<JsonMap> close(String sessionId) => gateway.call('chat_close', {
'chat_query': {'session_id': sessionId},
});
Future<JsonMap> reopen(String sessionId) => gateway.call('chat_reopen', {
'chat_query': {'session_id': sessionId},
});
Future<JsonMap> prompt(
String sessionId,
String text, {
required String operationId,
List<String> files = const [],
}) {
final body = <String, dynamic>{
'session_id': sessionId,
'text': text.trim(),
'operation_id': operationId,
};
if (files.isNotEmpty) body['files'] = files;
return gateway.call('chat_prompt', {'chat_prompt': body});
}
Future<JsonMap> interrupt(String sessionId) =>
gateway.call('chat_interrupt', {
'chat_query': {'session_id': sessionId},
});
Future<JsonMap> 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<JsonMap> 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<JsonMap> _maps(Object? value) => (value as List? ?? const [])
.whereType<Map>()
.map((item) => Map<String, dynamic>.from(item))
.toList();
}
@@ -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<JsonMap> filterChatSessions(List<JsonMap> 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<JsonMap> sessions})> groupChatSessions(
List<JsonMap> sessions,
) {
final groups = <String, List<JsonMap>>{};
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<String, dynamic>.from(value);
final result = <String, dynamic>{};
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;
}
@@ -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>()
.map((m) => Map<String, dynamic>.from(m))
.toList();
final incoming = (page['messages'] as List? ?? const [])
.whereType<Map>()
.map((m) => Map<String, dynamic>.from(m))
.toList();
final latest = <Object, JsonMap>{};
for (final message in incoming) {
if (message['id'] != null) latest[message['id']] = message;
}
final combined = older ? [...incoming, ...held] : [...held, ...incoming];
final seen = <Object>{};
final messages = <JsonMap>[];
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<JsonMap> transcriptRows(List<JsonMap> messages) {
final rows = <JsonMap>[];
String? key;
final parts = <JsonMap>[];
void flush() {
if (key != null && parts.isNotEmpty) {
rows.add({
'kind': 'assistant',
'key': key,
'parts': List<JsonMap>.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<String, dynamic>.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<JsonMap> reconcileChatUser(List<JsonMap> 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<JsonMap>.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>()
.map((m) => Map<String, dynamic>.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': <JsonMap>[],
});
index = messages.length - 1;
}
final message = messages[index];
final parts = (message['parts'] as List? ?? const [])
.whereType<Map>()
.map((p) => Map<String, dynamic>.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<String, dynamic>.from(incoming));
} else {
final merged = {
...parts[partIndex],
...Map<String, dynamic>.from(incoming),
};
if (parts[partIndex]['state'] is Map && incoming['state'] is Map) {
merged['state'] = {
...Map<String, dynamic>.from(parts[partIndex]['state'] as Map),
...Map<String, dynamic>.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<String> 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<String, List<QueuedChatSend>> _sessions = {};
List<QueuedChatSend> 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;
}
}
+17
View File
@@ -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.
@@ -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<JsonMap> call(String type, [JsonMap fields = const {}]) async {
calls.add((type: type, fields: fields));
return reply;
}
@override
Stream<JsonMap> 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<JsonMap>;
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 = <String, dynamic>{
'sessionId': 's',
'messages': <JsonMap>[],
};
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<JsonMap>;
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');
},
);
});
}