Migrate from custom chat component to flutter_chat_ui package

[LeftTwixWand]

We currently use our own custom-built chat component in the Flutter client. This is maintenance-heavy and we'd rather switch to a proven, ready-made package.
The top candidate is flutter_chat_ui from Flyer Chat (82k+ downloads, backend-agnostic). It provides a complete Chat widget with text, images, files, Markdown, reactions, typing indicators, and more.
Tasks:

Add flutter_chat_ui to pubspec.yaml
Replace the custom chat widget with the package's Chat component
Wire up our existing message stream, send logic, and MCP integration
Ensure styling and theming match the current 3D-topology UI
Remove or deprecate the old custom component code
Test on desktop

References:

Package: https://pub.dev/packages/flutter_chat_ui
Docs: https://docs.flyer.chat/flutter/chat-ui/overview

[LeftTwixWand]

Design — universal response streaming, and a chat UI we don't maintain

Supersedes the original task list on this issue. The issue asked for a widget swap; the research
says the widget swap alone buys ~80 lines and leaves the real problem — we throw the model's token
stream away one layer above the journal.

What the research found

The pub package named ai is a dead end. pub.dev/packages/ai v0.1.10, unverified uploader,
101 total downloads: "Library that help construct neural networks (AI) with Dart" — MLP and
autoencoder, weights persisted to JSON. No streaming, no chat, no LLM providers.

flutter_chat_ui supports streaming, but streaming is bring-your-own. flutter_chat_ui 2.11.1
(Apache-2.0, flyer.chat, 82k downloads) with flutter_chat_core 2.9.0 and the
flyer_chat_text_stream_message 2.3.0 addon. The addon is a seam, not an engine: you insert a
TextStreamMessage placeholder, supply StreamState(text:, isComplete:, hasError:) from your own
state manager, and replace it with a final TextMessage on completion. The package animates chunks
and owns nothing else. Note the addon has 2.6k downloads and 1 like — it is lightly travelled.

We already stream, then discard it. Agent.Respond (src/modules/ai/DigitalBrain.Modules.AI/Agent.cs:41)
calls GetStreamingResponseAsync(request, options).ToChatResponseAsync(). The deltas exist and are
collapsed on arrival. ChatResponder.ExecuteAsync (os/DigitalBrain.OS.Behaviors/ChatResponder.cs:21)
awaits one Respond and returns answer.Text; ChatEventFeed.ProjectTurns
(src/modules/flutter/DigitalBrain.Modules.Flutter.Http/ChatEventFeed.cs:49) projects only whole
UserMessaged/AssistantResponded synapses.

Orleans 10.2.2 does request-response streaming natively. IAsyncEnumerable<T> returns from grain
methods, supported since 7.2, with batching (WithBatchSize), built-in backpressure and cancellation.
Learn's own guidance steers to IAsyncEnumerable for request-response and reserves Orleans Streams
for pub-sub with several subscribers.

AIContent is the answer to files and images — we invent nothing. ChatResponseUpdate.Contents
is IList<AIContent>, and AIContent is already
[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")] over TextContent ("text"),
DataContent ("data", inline bytes), UriContent ("uri", hosted), HostedFileContent,
TextReasoningContent, ErrorContent, UsageContent, FunctionCallContent.

Two guards constrain the shape.
PublicSurface.NoShippedPackageExportsAgentFrameworkTypes
(src/DigitalBrain.PublishGate.Tests/Contracts/PublicSurface.cs:18) bans Microsoft.Agents.AI from
shipped public surface, so the streaming element type is ChatResponseUpdate, never
AgentRunResponseUpdate — Microsoft.Agents.AI.Workflows 1.15.0 stays internal.
NeuronConcurrency.RequireSerializedTurns (src/core/kernel/DigitalBrain/Neuron/NeuronConcurrency.cs:31)
refuses [AlwaysInterleave] on neuron methods, and Orleans' IAsyncEnumerableGrainExtension.StartEnumeration
carries that attribute.

Contracts

Microsoft.Extensions.AI types only.

// DigitalBrain.Modules.AI.Contracts
public interface ILLM : INeuron
{
    Task<ChatResponse> Respond(IReadOnlyList<ChatMessage> messages);
    IAsyncEnumerable<ChatResponseUpdate> RespondStreaming(
        IReadOnlyList<ChatMessage> messages, CancellationToken cancellationToken = default);
}

IAgent gains the same pair. They stay separate vocabularies — AiSurface.IllmDoesNotInheritIAgent
continues to hold.

Streaming becomes primary and Respond becomes the wrapper:
Respond(m) => RespondStreaming(m, ct).ToChatResponseAsync(). Agent and LLM each end with one
implementation where they have two today, using the framework's own collapse helper. This is a net
deletion.

Agent continues to emit CapabilityToolSelected — now as FunctionCallContent items surface in the
update stream rather than after a collapsed response.

ChatResponseUpdate and AIContent are serialized through the already-referenced
Microsoft.Orleans.Serialization.SystemTextJson codec, so the $type discriminator survives the
Orleans hop and the SSE hop unchanged. Files and images therefore need no contract change when
they arrive — only a new Dart branch.

The graph

The HTTP edge can only address IChat, so the chat neuron is in the streaming path:

// IChat
IAsyncEnumerable<ChatResponseUpdate> SendStreaming(
    SendMessage message, CancellationToken cancellationToken = default);

ChatNeuron.SendStreaming remembers the user turn, calls IAssistant.RespondStreaming, yields chunks
through to the edge, accumulates, then remembers the assistant turn and emits AssistantResponded on
completion. The journal ends with exactly the two facts it holds today — no delta pollution, and
CLAUDE.md's "journals hold causal facts only" stays true rather than nominal.

This retires the UserMessaged → ChatResponderNeuron → AssistantAnswered round-trip for chat.
Deleted: ChatResponder, ChatResponderNeuron, AssistantAnswered, and the chat path's use of
PreRailBehaviorContext. IBehavior, IIntentProgram<,> and PreRailBehaviorContext themselves
remain for other behaviors.

The reentrancy trap is not violated: chat → assistant is a forward call to a different neuron, and
CLAUDE.md already records that the chat neuron is occupied for the whole model-plus-capability chain,
so this is no regression.

The wire

POST /chats/{chatName}/messages/stream    → text/event-stream

event: chat-delta
data: {"role":"assistant","contents":[{"$type":"text","text":"Hel"}]}

Frames carry ChatResponseUpdate serialized by Microsoft.Extensions.AI's own STJ contract. We author
no DTO. Dart reads contents[].$type, renders "text" today, and keeps unrecognised types as opaque
parts so a future "data" or "uri" frame does not crash an older client.

The existing GET /chats/{chatName}/events journal feed is unchanged. On stream completion the
Flutter client discards its TextStreamMessage and lets the durable turn arrive through the journal
feed as the single source of truth — no reconciliation, no double-render, journal stays authoritative.
ActivityScreen and BrainScreen need no change; ChatTurnEvent survives untouched because both
still consume it.

No new .NET packages. Microsoft.Extensions.AI 10.8.3 and
Microsoft.Orleans.Serialization.SystemTextJson 10.2.2 are already in Directory.Packages.props.

Flutter

clients/digitalbrain_flutter/shell/pubspec.yaml gains flutter_chat_ui, flutter_chat_core,
flyer_chat_text_message, flyer_chat_text_stream_message, uuid.

Package defaults with a derived theme — no bespoke message chrome. chat_screen.dart collapses to a
Chat(chatController:, currentUserId:, theme:, builders: Builders(textStreamMessageBuilder: ...), onMessageSend:), plus a small ChangeNotifier holding StreamState per streamId (the addon
requires the host to own this) and a BrainChatTheme mapping BrainPalette → ChatColors and
BrainType → ChatTypography.

Deleted (~250 lines): _Journal, _JournalTurn, _EmptyJournal, _AwaitingTurn, _Composer,
_SubmitIntent, _scrollToLatest, the ScrollController and its didUpdateWidget branch.
Kept: _StatusBar, the navigation rail, the navigation bar, _FailureNotice — chrome we own that
the package does not cover.

The per-message sequence gutter goes. It duplicated ActivityScreen, which already renders sequence,
command id and synapse name (clients/digitalbrain_flutter/shell/lib/activity_screen.dart:135-138).

digitalbrain_flutter gains a streaming client method beside watchChatTurns, reusing the existing
SSE line-splitting shape in sse_chat_frames.dart.

Two unknowns, proved before they are built on

Both are claims, not facts, and get a failing test first.

1. A neuron returning IAsyncEnumerable<T> must not trip RequireSerializedTurns. Orleans installs
   IAsyncEnumerableGrainExtension at runtime rather than on the neuron type, so the guard's
   GetInterfaces() scan should not see the [AlwaysInterleave] method — unverified.
2. IAsyncEnumerable must survive the neuron's EmitAsync/commit machinery mid-enumeration.

If either fails, the fallback is the Orleans Streams side channel, at the cost of a stream provider in
the topology.

Proof

ScriptedChatClient already implements GetStreamingResponseAsync
(src/core/testing/DigitalBrain.Testing/Edges/ScriptedChatClient.cs:67), so deterministic streaming
tests need no test-double change.

Failing-first, in order:

1. a neuron returning IAsyncEnumerable does not trip RequireSerializedTurns;
2. ChatResponseUpdate round-trips the Orleans STJ codec with $type intact, including a
   DataContent item — proving the files/images claim rather than asserting it;
3. SendStreaming yields more than one chunk and journals exactly one AssistantResponded.

Then the gates:

dotnet build DigitalBrain.slnx -c Release
dotnet test DigitalBrain.slnx -c Release
cd clients/digitalbrain_wire          ; dart test
cd clients/digitalbrain_flutter       ; dart analyze ; dart test
cd clients/digitalbrain_flutter/shell ; flutter analyze ; flutter test ; flutter build windows

Then the live oracle — dotnet test os/tests/DigitalBrain.OS.Product.Tests -c Release -- -explicit only,
extended to assert multi-chunk delivery against a real Gemma4 turn, confirmed in the journal through
digitalbrain-mcp (read_chat_transcript, read_neuron_journal) with one correlation id.

clients/digitalbrain_flutter/shell/test/chat_screen_test.dart (358 lines) is rewritten: it currently
pins chat_journal, chat_composer, chat_send, turn_N and the literal 'thinking', all of which
this design removes.

Expect the build to fail on the pinned-alias contract when IChat, IAgent and ILLM gain methods.
That guard is correct; updating the pin is part of the work.

What this deliberately does not do

• No token deltas in the journal — they are content, not causal facts.
• No Orleans Streams unless unknown 1 or 2 forces it.
• No DataContent/UriContent rendering in Flutter yet. The contract carries them from day one; the
  Dart branch lands when a producer exists. Nothing is built without a consumer.
• No new content model, DTO, or wire vocabulary of our own.

[LeftTwixWand]

Scope change — a root cause found while implementing

Implementation of the streaming design surfaced a kernel bug that is more serious than the feature
this issue started as. Recording it here because it changes what this issue delivers.

Streamed capability calls are never journaled

Orleans does not dispatch an IAsyncEnumerable<T>-returning grain method directly. It routes through
Orleans.Runtime.AsyncEnumeratorProxy<T> as IAsyncEnumerableGrainExtension.StartEnumeration
followed by repeated MoveNext.

Both reification filters open with the same gate:

if (!CapabilityInvocation.IsRequest(context.InterfaceMethod)) { await context.Invoke(); return; }

For a streamed call, context.InterfaceMethod is StartEnumeration — declared on an Orleans
interface, not on IChat or ILLM. So IsRequest returns false and both
OutgoingReificationFilter and IncomingReificationFilter early-out. No
BeginCapabilityRequestAsync, no RecordCapabilityOutcomeAsync, no SynapseDelivery, no causal
lineage.

Neuron-to-neuron streaming appears to "just work" precisely because it bypasses the journal.

Why that matters here

OwnerBoundCallFilter does not gate on IsRequest, so it still runs — and refuses unattributed
clients, because StartEnumeration's declaring type carries no [ClientEntryPoint]:

NeuronAuthorizationException: 'StartEnumeration' is not a client entry point,
so an unattributed caller cannot be authorized to reach '...'

That refusal is a symptom of the same blindness, not a separate problem. Owner isolation is
unaffected — it reads context.SourceId, not the method — so this is an observability hole, not a
security hole.

The product impact is the point: ship streaming as originally planned and a chat turn journals
UserMessaged and AssistantResponded while the chat→assistant model hop leaves no trace, where the
non-streaming path journals it today. It fails silently and green, and the audit gap widens as more of
the product moves onto streaming.

Revised scope for this issue

1. Kernel — teach CapabilityInvocation and the filters to resolve the real contract method through
   Orleans' async-enumerable dispatch. One capability request per enumeration: begin at
   StartEnumeration keyed by Orleans' requestId, terminal Completed / Failed / new Abandoned
   (enumerator disposed undrained). Chunks are never journaled. The client-entry-point refusal resolves
   as a consequence.
2. AI module — IAgent streaming; DirectAgentSession through MAF's RunStreamingAsync.
3. Orchestration — Concurrent/GroupChat gain set-once participants at a fresh orchestration id,
   plus a capability so the assistant can spin up a multi-model team from chat. The ratified
   "participant change on the same id demands migration or reset" contract is preserved; each line-up
   gets its own id. Supervised Accept/Continue/Cancel remain deliberately unbuilt.
4. Chat, edge, Flutter — IChat.SendStreaming, retire the ChatResponder behavior round-trip, SSE
   delta endpoint, and the flutter_chat_ui migration this issue originally asked for.

Corrections to the earlier comment on this issue

• The claim that adding any [Alias] breaks the build until the pinned contract is updated is wrong
  for method-level aliases. DBGEN002 inspects only type-level [Alias] on a neuron contract interface.
• Concurrent and GroupChat are not dead weight. They work, and Microsoft Agent Framework is
  already under the hood via MafParticipantAdapter, NeuronChatClient and DirectAgentSession
  (durable, encrypted, fingerprinted MAF session state). What they lacked was a product door and a
  streaming path — both now in scope above.

Landed so far

• b88df995 — guard tests: an IAsyncEnumerable-returning neuron does not trip
  RequireSerializedTurns; ChatResponseUpdate round-trips the Orleans STJ codec with the AIContent
$type discriminator intact for TextContent and DataContent.
• 3d70dc0d — ILLM.RespondStreaming is now primary; Respond is
  RespondStreaming(...).ToChatResponseAsync(), one implementation replacing two.