Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(chat): buffer streaming mention tags so partial mentions never render as raw text (#4473)

Eric Hayes228685d1e999
diff --git a/js/app/packages/app/component/split-layout/componentRegistry.tsx b/js/app/packages/app/component/split-layout/componentRegistry.tsx
index 9add6078b5..0cea5cd0ec 100644
--- a/js/app/packages/app/component/split-layout/componentRegistry.tsx
+++ b/js/app/packages/app/component/split-layout/componentRegistry.tsx
@@ -414,6 +414,12 @@ if (LOCAL_ONLY) {
'http-stream',
lazy(() => import('@core/component/AI/component/debug/HttpStream'))
);
+ registerComponent(
+ 'static-markdown-stream',
+ lazy(
+ () => import('@core/component/AI/component/debug/StaticMarkdownStream')
+ )
+ );
registerComponent(
'resize',
lazy(() => import('@core/internal/ResizeDemo'))
diff --git a/js/app/packages/core/component/AI/component/debug/StaticMarkdownStream.tsx b/js/app/packages/core/component/AI/component/debug/StaticMarkdownStream.tsx
new file mode 100644
index 0000000000..e6e4ffbb43
--- /dev/null
+++ b/js/app/packages/core/component/AI/component/debug/StaticMarkdownStream.tsx
@@ -0,0 +1,336 @@
+import {
+ type BufferedChatMessageStream,
+ bufferedStream,
+} from '@core/component/AI/util/stream';
+import {
+ StaticMarkdown,
+ StaticMarkdownContext,
+} from '@core/component/LexicalMarkdown/component/core/StaticMarkdown';
+import { aiChatTheme } from '@core/component/LexicalMarkdown/theme';
+import PlayIcon from '@phosphor-icons/core/regular/play.svg?component-solid';
+import StopIcon from '@phosphor-icons/core/regular/stop.svg?component-solid';
+import TrashIcon from '@phosphor-icons/core/regular/trash.svg?component-solid';
+import type { ChatStream } from '@service-cognition/generated/schemas';
+import {
+ type ChatStreamController,
+ createStreamController,
+} from '@service-connection/stream';
+import { Button, cn } from '@ui';
+import {
+ createEffect,
+ createMemo,
+ createRoot,
+ createSignal,
+ onCleanup,
+ Show,
+} from 'solid-js';
+
+const SAMPLE_TEXT = `Here is a streamed Macro XML sample:
+
+<m-document-mention>{"documentId":"6a2b138d-dfbe-439a-a78b-282471a1e165","documentName":"Streaming notes","blockName":"md","blockParams":{}}</m-document-mention>
+
+This should render atomically instead of showing partial XML.
+
+\`\`\`ts
+const literal = '<m-document-mention>{"documentId":"inside-code"}</m-document-mention>';
+\`\`\`
+
+And another tag:
+
+<m-await>{"awaitId":"debug-await","text":"Waiting","inline":true}</m-await>`;
+
+type StreamRun = {
+ controller: ChatStreamController;
+ dispose: () => void;
+ stream: BufferedChatMessageStream;
+};
+
+function clampNumber(value: number, min: number, max: number) {
+ if (Number.isNaN(value)) return min;
+ return Math.max(min, Math.min(max, value));
+}
+
+function textPart(text: string, runId: number): ChatStream {
+ return {
+ type: 'chat_message_response',
+ chat_id: 'static-markdown-stream-debug',
+ message_id: `static-markdown-stream-debug-${runId}`,
+ stream_id: `static-markdown-stream-debug-${runId}`,
+ content: { type: 'text', text },
+ };
+}
+
+function streamText(parts: ChatStream[]) {
+ return parts
+ .map((part) =>
+ part.type === 'chat_message_response' && part.content.type === 'text'
+ ? part.content.text
+ : ''
+ )
+ .join('');
+}
+
+function makeRun(runId: number, onData: (text: string) => void): StreamRun {
+ return createRoot((dispose) => {
+ const controller = createStreamController<'chat'>({
+ entity_type: 'chat',
+ entity_id: 'static-markdown-stream-debug',
+ stream_id: `static-markdown-stream-debug-${runId}`,
+ });
+ const stream = bufferedStream(controller.stream);
+
+ createEffect(() => {
+ onData(streamText(stream.data()));
+ });
+
+ return { controller, dispose, stream };
+ });
+}
+
+export default function StaticMarkdownStreamDebug() {
+ const [sourceText, setSourceText] = createSignal(SAMPLE_TEXT);
+ const [renderedText, setRenderedText] = createSignal('');
+ const [chunkMin, setChunkMin] = createSignal(3);
+ const [chunkMax, setChunkMax] = createSignal(18);
+ const [delayMin, setDelayMin] = createSignal(15);
+ const [delayMax, setDelayMax] = createSignal(70);
+ const [activeRun, setActiveRun] = createSignal<StreamRun>();
+ const [rawChunks, setRawChunks] = createSignal(0);
+ const [startedAt, setStartedAt] = createSignal<number>();
+ const [completedAt, setCompletedAt] = createSignal<number>();
+
+ let timeout: ReturnType<typeof setTimeout> | undefined;
+ let runId = 0;
+
+ const isStreaming = () => !!activeRun() && completedAt() === undefined;
+ const elapsedMs = createMemo(() => {
+ const start = startedAt();
+ if (!start) return 0;
+ return Math.round((completedAt() ?? Date.now()) - start);
+ });
+ const progress = createMemo(() => {
+ const total = sourceText().length;
+ if (total === 0) return 100;
+ return Math.min(100, Math.round((renderedText().length / total) * 100));
+ });
+
+ function clearTimeoutIfNeeded() {
+ if (timeout) clearTimeout(timeout);
+ timeout = undefined;
+ }
+
+ function stopRun() {
+ clearTimeoutIfNeeded();
+ const run = activeRun();
+ if (run && !run.stream.isDone()) {
+ run.controller.setDone();
+ }
+ run?.dispose();
+ setActiveRun(undefined);
+ if (startedAt() && completedAt() === undefined) {
+ setCompletedAt(Date.now());
+ }
+ }
+
+ function resetOutput() {
+ stopRun();
+ setRenderedText('');
+ setRawChunks(0);
+ setStartedAt(undefined);
+ setCompletedAt(undefined);
+ }
+
+ function nextSize() {
+ const min = clampNumber(chunkMin(), 1, 500);
+ const max = Math.max(min, clampNumber(chunkMax(), 1, 1000));
+ return min + Math.floor(Math.random() * (max - min + 1));
+ }
+
+ function nextDelay() {
+ const min = clampNumber(delayMin(), 0, 2000);
+ const max = Math.max(min, clampNumber(delayMax(), 0, 5000));
+ return min + Math.floor(Math.random() * (max - min + 1));
+ }
+
+ function startStream() {
+ resetOutput();
+ runId += 1;
+
+ const text = sourceText();
+ const run = makeRun(runId, setRenderedText);
+ setActiveRun(run);
+ setStartedAt(Date.now());
+ setCompletedAt(undefined);
+
+ let offset = 0;
+ const pushNext = () => {
+ if (offset >= text.length) {
+ run.controller.setDone();
+ setCompletedAt(Date.now());
+ clearTimeoutIfNeeded();
+ return;
+ }
+
+ const size = nextSize();
+ const chunk = text.slice(offset, offset + size);
+ offset += chunk.length;
+ setRawChunks((count) => count + 1);
+ run.controller.setData((parts) => [...parts, textPart(chunk, runId)]);
+ timeout = setTimeout(pushNext, nextDelay());
+ };
+
+ pushNext();
+ }
+
+ onCleanup(() => {
+ stopRun();
+ });
+
+ return (
+ <div class="size-full overflow-auto bg-surface text-ink">
+ <div class="mx-auto flex w-full max-w-7xl flex-col gap-4 p-4">
+ <div class="flex flex-wrap items-center justify-between gap-3 border-b border-edge-muted pb-3">
+ <div>
+ <h1 class="text-base font-semibold">Static Markdown Stream</h1>
+ <div class="text-xs text-ink-muted">
+ {renderedText().length.toLocaleString()} /{' '}
+ {sourceText().length.toLocaleString()} chars · {rawChunks()} raw
+ chunks · {elapsedMs()} ms
+ </div>
+ </div>
+ <div class="flex items-center gap-2">
+ <Button
+ variant="active"
+ size="sm"
+ onClick={startStream}
+ disabled={isStreaming()}
+ >
+ <PlayIcon />
+ Stream
+ </Button>
+ <Button
+ variant="base"
+ size="sm"
+ onClick={stopRun}
+ disabled={!isStreaming()}
+ >
+ <StopIcon />
+ Stop
+ </Button>
+ <Button variant="ghost" size="sm" onClick={resetOutput}>
+ <TrashIcon />
+ Reset
+ </Button>
+ </div>
+ </div>
+
+ <div class="grid min-h-[72vh] grid-cols-1 gap-4 xl:grid-cols-[minmax(360px,0.9fr)_minmax(480px,1.1fr)]">
+ <div class="flex min-h-0 flex-col gap-3">
+ <div class="grid grid-cols-2 gap-2 sm:grid-cols-4">
+ <label class="flex flex-col gap-1 text-xs text-ink-muted">
+ Chunk min
+ <input
+ value={chunkMin()}
+ type="number"
+ min="1"
+ max="500"
+ onInput={(e) =>
+ setChunkMin(Number(e.currentTarget.value) || 1)
+ }
+ class="h-8 rounded-sm border border-edge-muted bg-transparent px-2 text-sm text-ink outline-none focus:border-accent"
+ />
+ </label>
+ <label class="flex flex-col gap-1 text-xs text-ink-muted">
+ Chunk max
+ <input
+ value={chunkMax()}
+ type="number"
+ min="1"
+ max="1000"
+ onInput={(e) =>
+ setChunkMax(Number(e.currentTarget.value) || 1)
+ }
+ class="h-8 rounded-sm border border-edge-muted bg-transparent px-2 text-sm text-ink outline-none focus:border-accent"
+ />
+ </label>
+ <label class="flex flex-col gap-1 text-xs text-ink-muted">
+ Delay min ms
+ <input
+ value={delayMin()}
+ type="number"
+ min="0"
+ max="2000"
+ onInput={(e) =>
+ setDelayMin(Number(e.currentTarget.value) || 0)
+ }
+ class="h-8 rounded-sm border border-edge-muted bg-transparent px-2 text-sm text-ink outline-none focus:border-accent"
+ />
+ </label>
+ <label class="flex flex-col gap-1 text-xs text-ink-muted">
+ Delay max ms
+ <input
+ value={delayMax()}
+ type="number"
+ min="0"
+ max="5000"
+ onInput={(e) =>
+ setDelayMax(Number(e.currentTarget.value) || 0)
+ }
+ class="h-8 rounded-sm border border-edge-muted bg-transparent px-2 text-sm text-ink outline-none focus:border-accent"
+ />
+ </label>
+ </div>
+
+ <div class="flex min-h-0 flex-1 flex-col gap-2">
+ <div class="flex items-center justify-between">
+ <span class="text-sm font-medium">Input</span>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => setSourceText(SAMPLE_TEXT)}
+ >
+ Sample
+ </Button>
+ </div>
+ <textarea
+ value={sourceText()}
+ onInput={(e) => setSourceText(e.currentTarget.value)}
+ spellcheck={false}
+ class="min-h-[420px] flex-1 resize-none rounded-sm border border-edge-muted bg-transparent p-3 font-mono text-xs leading-relaxed text-ink outline-none focus:border-accent"
+ />
+ </div>
+ </div>
+
+ <div class="flex min-h-0 flex-col gap-3">
+ <div class="flex items-center justify-between">
+ <div class="text-sm font-medium">Rendered Output</div>
+ <div class="flex items-center gap-2 text-xs text-ink-muted">
+ <span
+ class={cn(
+ 'inline-block size-2 rounded-full',
+ isStreaming() ? 'bg-accent animate-pulse' : 'bg-edge'
+ )}
+ />
+ {progress()}%
+ </div>
+ </div>
+ <div class="min-h-[420px] flex-1 overflow-auto rounded-sm border border-edge-muted bg-message p-4">
+ <Show
+ when={renderedText().length > 0}
+ fallback={
+ <div class="text-sm text-ink-muted">
+ Paste text and start the stream.
+ </div>
+ }
+ >
+ <StaticMarkdownContext theme={aiChatTheme}>
+ <StaticMarkdown markdown={renderedText()} target="internal" />
+ </StaticMarkdownContext>
+ </Show>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/js/app/packages/core/component/AI/component/message/AssistantMessageParts.test.tsx b/js/app/packages/core/component/AI/component/message/AssistantMessageParts.test.tsx
index 7fb4ed5f35..ff82246028 100644
--- a/js/app/packages/core/component/AI/component/message/AssistantMessageParts.test.tsx
+++ b/js/app/packages/core/component/AI/component/message/AssistantMessageParts.test.tsx
@@ -15,6 +15,10 @@ const lifecycle = vi.hoisted(() => ({
markdownMounts: 0,
mcpCleanups: new Map<string, number>(),
mcpMounts: new Map<string, number>(),
+ streamTailStateUpdates: [] as Array<{
+ state: unknown;
+ key: string | undefined;
+ }>,
thinkingCleanups: 0,
thinkingMounts: 0,
toolCleanups: new Map<string, number>(),
@@ -24,6 +28,9 @@ const lifecycle = vi.hoisted(() => ({
vi.mock('@core/component/AI/context', () => ({
useChatContext: () => ({
chatId: () => 'chat-1',
+ setStreamTailState: (state: unknown, key?: string) => {
+ lifecycle.streamTailStateUpdates.push({ state, key });
+ },
}),
}));
@@ -41,13 +48,24 @@ vi.mock(
const solid = await vi.importActual<typeof import('solid-js')>('solid-js');
return {
- ChatMessageMarkdown: (props: { text: string }) => {
+ ChatMessageMarkdown: (props: {
+ text: string;
+ setStateRef?: (state: unknown, key?: string) => void;
+ stateRefKey?: string;
+ }) => {
solid.onMount(() => {
lifecycle.markdownMounts += 1;
});
solid.onCleanup(() => {
lifecycle.markdownCleanups += 1;
});
+ solid.createEffect(() => {
+ const setStateRef = props.setStateRef;
+ const key = props.stateRefKey;
+ if (!setStateRef) return;
+ setStateRef(() => null, key);
+ solid.onCleanup(() => setStateRef(undefined, key));
+ });
return <div data-testid="markdown">{props.text}</div>;
},
};
@@ -157,6 +175,7 @@ describe('AssistantMessageParts streaming identity', () => {
lifecycle.markdownMounts = 0;
lifecycle.mcpCleanups.clear();
lifecycle.mcpMounts.clear();
+ lifecycle.streamTailStateUpdates = [];
lifecycle.thinkingCleanups = 0;
lifecycle.thinkingMounts = 0;
lifecycle.toolCleanups.clear();
@@ -242,4 +261,65 @@ describe('AssistantMessageParts streaming identity', () => {
expect(lifecycle.mcpCleanups.get('search') ?? 0).toBe(0);
disposeStream();
});
+
+ it('registers resumed markdown as the stream tail after a hidden tool response', async () => {
+ let append!: (item: ChatStream) => void;
+ let disposeStream!: () => void;
+ const data = createRoot((dispose) => {
+ disposeStream = dispose;
+ const [items, setItems] = createSignal<ChatStream[]>([]);
+ append = (item) => setItems((prev) => [...prev, item]);
+ return items;
+ });
+
+ render(() => <StreamedAssistantParts data={data} />);
+
+ append(response({ text: '```ts\n', type: 'text' }));
+ await waitFor(() =>
+ expect(
+ lifecycle.streamTailStateUpdates.some(
+ (update) =>
+ typeof update.state === 'function' &&
+ update.key === 'message-1:text:0'
+ )
+ ).toBe(true)
+ );
+
+ append(
+ response({
+ id: 'tool-1',
+ json: { query: 'mentions' },
+ name: 'Search',
+ type: 'toolCall',
+ })
+ );
+ await waitFor(() =>
+ expect(
+ lifecycle.streamTailStateUpdates.some(
+ (update) => update.state === undefined
+ )
+ ).toBe(true)
+ );
+
+ append(
+ response({
+ id: 'tool-1',
+ json: { results: [] },
+ name: 'Search',
+ type: 'toolCallResponseJson',
+ })
+ );
+
+ append(response({ text: '<m-document-mention>', type: 'text' }));
+ await waitFor(() =>
+ expect(
+ lifecycle.streamTailStateUpdates.some(
+ (update) =>
+ typeof update.state === 'function' &&
+ update.key === 'message-1:text:1'
+ )
+ ).toBe(true)
+ );
+ disposeStream();
+ });
});
diff --git a/js/app/packages/core/component/AI/component/message/AssistantMessageParts.tsx b/js/app/packages/core/component/AI/component/message/AssistantMessageParts.tsx
index 2d08b4e0a2..0270638b46 100644
--- a/js/app/packages/core/component/AI/component/message/AssistantMessageParts.tsx
+++ b/js/app/packages/core/component/AI/component/message/AssistantMessageParts.tsx
@@ -8,6 +8,7 @@ import type { AssistantMessagePart } from '@service-cognition/generated/schemas/
import type { ChatMessageWithAttachments } from '@service-cognition/generated/schemas/chatMessageWithAttachments';
import {
type Accessor,
+ createEffect,
createMemo,
createSelector,
Match,
@@ -108,6 +109,20 @@ export function AssistantMessageParts(props: {
part.type !== 'toolCallResponseJson' && part.type !== 'toolCallErr'
);
});
+ const streamingTailTextIndex = createMemo(() => {
+ if (!props.isStreaming) return;
+ const visibleParts = parts();
+ const index = visibleParts.length - 1;
+ const tail = visibleParts[index];
+ if (tail?.type !== 'text' || tail.text.trim().length === 0) return;
+ return index;
+ });
+
+ createEffect(() => {
+ if (!props.isStreaming || streamingTailTextIndex() === undefined) {
+ chat.setStreamTailState(undefined);
+ }
+ });
const isThinkingDone = createMemo(() => {
if (!props.isStreaming) return true;
@@ -314,6 +329,13 @@ export function AssistantMessageParts(props: {
<ChatMessageMarkdown
text={text()}
generating={() => outer.isStreaming}
+ setStateRef={
+ outer.isStreaming &&
+ props.item().index === streamingTailTextIndex()
+ ? chat.setStreamTailState
+ : undefined
+ }
+ stateRefKey={`${outer.message.id}:${props.item().key}`}
/>
</Show>
);
diff --git a/js/app/packages/core/component/AI/component/message/ChatMessageMarkdown.tsx b/js/app/packages/core/component/AI/component/message/ChatMessageMarkdown.tsx
index 9911d846bc..3de2f0e261 100644
--- a/js/app/packages/core/component/AI/component/message/ChatMessageMarkdown.tsx
+++ b/js/app/packages/core/component/AI/component/message/ChatMessageMarkdown.tsx
@@ -1,6 +1,7 @@
// import '@core/component/AI/css/prism-theme.css';
import { StaticMarkdown } from '@core/component/LexicalMarkdown/component/core/StaticMarkdown';
import { aiChatTheme } from '@core/component/LexicalMarkdown/theme';
+import type { EditorState } from 'lexical';
import type { Accessor } from 'solid-js';
function sliceUnclosedBrackets(text: string): string {
@@ -21,6 +22,12 @@ export function ChatMessageMarkdown(props: {
text: string;
generating: Accessor<boolean>;
rootRef?: (ref: HTMLDivElement) => void;
+ /* receives this message's parsed editor state accessor */
+ setStateRef?: (
+ state: Accessor<EditorState | null> | undefined,
+ key?: string
+ ) => void;
+ stateRefKey?: string;
}) {
const text = () => {
if (props.generating()) {
@@ -36,6 +43,8 @@ export function ChatMessageMarkdown(props: {
markdown={text()}
theme={aiChatTheme}
rootRef={props.rootRef}
+ setStateRef={props.setStateRef}
+ stateRefKey={props.stateRefKey}
target="internal"
/>
);
diff --git a/js/app/packages/core/component/AI/state/createChatController.ts b/js/app/packages/core/component/AI/state/createChatController.ts
index ab198923cb..38f50b813e 100644
--- a/js/app/packages/core/component/AI/state/createChatController.ts
+++ b/js/app/packages/core/component/AI/state/createChatController.ts
@@ -1,9 +1,14 @@
import type { ChatMessageWithAttachments } from '@core/component/AI/types';
import { asChatMessage } from '@core/component/AI/util/message';
-import { bufferedStream } from '@core/component/AI/util/stream';
+import {
+ bufferedStream,
+ createMentionBufferPlugin,
+} from '@core/component/AI/util/stream';
+import { tailContext } from '@core/component/LexicalMarkdown/tailContext';
import { toast } from '@core/component/Toast/Toast';
import type { ChatMessageStream } from '@service-connection/stream';
import { getEntityStreams } from '@service-connection/stream';
+import type { EditorState } from 'lexical';
import type { Accessor, Owner, Setter } from 'solid-js';
import {
createEffect,
@@ -43,6 +48,15 @@ export type ChatController = {
dispatch: (event: ControllerEvent) => void;
/** Escape hatch for debug components that set stream directly */
setStream: Setter<ChatMessageStream | undefined>;
+ /**
+ * Ref to the renderer's parsed editor state for the streaming message's
+ * tail text part. The renderer sets it; the stream's Macro XML buffering
+ * reads it to skip buffering tags that land in code blocks.
+ */
+ setStreamTailState: (
+ state: Accessor<EditorState | null> | undefined,
+ key?: string
+ ) => void;
};
export type ChatControllerOptions = {
@@ -71,6 +85,19 @@ export function createChatController(
createSignal<ChatMessageWithAttachments[]>(initialMessages);
const [stream, setStream] = createSignal<ChatMessageStream>();
+ /*
+ The renderer's parsed editor state for the streaming message's tail text
+ part (set from AssistantMessageParts as it renders). Macro XML buffering
+ reads the node tree the renderer already built — never parses — to skip
+ buffering tags that land in code blocks, where they render literally.
+ */
+ let streamTailState: Accessor<EditorState | null> | undefined;
+ let streamTailStateKey: string | undefined;
+ function streamTailInCode(): boolean {
+ const state = streamTailState?.();
+ return state ? tailContext(state).inCode : false;
+ }
+
function executeEffects(effects: SideEffect[]) {
for (const effect of effects) {
match(effect)
@@ -143,16 +170,21 @@ export function createChatController(
function dispatch(event: ControllerEvent) {
// Handle stream attachment through the state transition
if (event.type === 'stream_connected' && 'stream' in event) {
+ /* the previous message's tail state must not answer for this stream */
+ streamTailState = undefined;
+ streamTailStateKey = undefined;
+ const makeStream = () =>
+ bufferedStream(event.stream, [
+ createMentionBufferPlugin(streamTailInCode),
+ ]);
const { owner = getOwner() } = event;
- let newStream: ChatMessageStream;
+ let newStream: ReturnType<typeof bufferedStream>;
if (owner) {
- const ownedStream = runWithOwner(owner, () =>
- bufferedStream(event.stream)
- );
+ const ownedStream = runWithOwner(owner, makeStream);
if (!ownedStream) return;
newStream = ownedStream;
} else {
- newStream = bufferedStream(event.stream);
+ newStream = makeStream();
}
setStream(newStream);
@@ -218,5 +250,16 @@ export function createChatController(
dispatch,
setStream,
+ setStreamTailState: (state, key) => {
+ if (!state) {
+ if (key === undefined || key === streamTailStateKey) {
+ streamTailState = undefined;
+ streamTailStateKey = undefined;
+ }
+ return;
+ }
+ streamTailState = state;
+ streamTailStateKey = key;
+ },
};
}
diff --git a/js/app/packages/core/component/AI/util/stream/bufferedStream.test.ts b/js/app/packages/core/component/AI/util/stream/bufferedStream.test.ts
new file mode 100644
index 0000000000..93d88bde5f
--- /dev/null
+++ b/js/app/packages/core/component/AI/util/stream/bufferedStream.test.ts
@@ -0,0 +1,216 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { tailContext } from '@core/component/LexicalMarkdown/tailContext';
+import { $convertFromMarkdownString } from '@lexical/markdown';
+import { ALL_TRANSFORMERS, SupportedNodeTypes } from '@lexical-core';
+import type { ChatStream } from '@service-cognition/generated/schemas';
+import {
+ type ChatStreamController,
+ createStreamController,
+} from '@service-connection/stream';
+import { createEditor, type EditorState } from 'lexical';
+import { createEffect, createRoot } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { bufferedStream } from './bufferedStream';
+import {
+ createMentionBufferPlugin,
+ MENTION_CLOSE,
+ MENTION_OPEN,
+} from './mentionPlugin';
+import type { StreamPlugin } from './types';
+
+/* the real module opens a websocket connection at import time */
+vi.mock('@service-connection/websocket', () => ({
+ createConnectionWebsocketEffect: () => {},
+}));
+
+const MENTION = `${MENTION_OPEN}{"documentId":"6a2b138d-dfbe-439a-a78b-282471a1e165","documentName":"","blockName":"md","blockParams":{}}${MENTION_CLOSE}`;
+
+/* matches TARGET_LATENCY_MS / PLUGIN_HOLD_FLUSH_MS in bufferedStream.ts */
+const TICK_MS = 6;
+const HOLD_FLUSH_MS = 2_000;
+
+function textPart(text: string): ChatStream {
+ return {
+ type: 'chat_message_response',
+ chat_id: 'chat',
+ message_id: 'message',
+ stream_id: 'stream',
+ content: { type: 'text', text },
+ };
+}
+
+let disposers: (() => void)[] = [];
+
+function setup(plugins?: StreamPlugin[]) {
+ let source!: ChatStreamController;
+ let out!: ReturnType<typeof bufferedStream>;
+ const dispose = createRoot((dispose) => {
+ source = createStreamController<'chat'>({
+ entity_type: 'chat',
+ entity_id: 'entity',
+ stream_id: 'stream',
+ });
+ out = plugins
+ ? bufferedStream(source.stream, plugins)
+ : bufferedStream(source.stream);
+ return dispose;
+ });
+ disposers.push(dispose);
+ const text = () =>
+ out
+ .data()
+ .map((part) =>
+ part.type === 'chat_message_response' && part.content.type === 'text'
+ ? part.content.text
+ : ''
+ )
+ .join('');
+ return { source, out, text };
+}
+
+beforeEach(() => {
+ vi.useFakeTimers();
+});
+
+afterEach(() => {
+ disposers.forEach((dispose) => dispose());
+ disposers = [];
+ vi.useRealTimers();
+});
+
+describe('bufferedStream Macro XML buffering', () => {
+ it('never shows a partial mention tag and emits the mention atomically', () => {
+ const { source, text } = setup();
+ const full = `See this ${MENTION} for details`;
+ source.setData([textPart(full)]);
+
+ let sawMention = false;
+ for (let i = 0; i < full.length + 10; i++) {
+ const snapshot = text();
+ /* any tag text visible must be the complete mention */
+ if (snapshot.includes('<')) {
+ expect(snapshot).toContain(MENTION);
+ sawMention = true;
+ }
+ vi.advanceTimersByTime(TICK_MS);
+ }
+ expect(sawMention).toBe(true);
+ expect(text()).toBe(full);
+ });
+
+ it('flushes an unclosed mention when the stream ends', () => {
+ const { source, out, text } = setup();
+ const unclosed = `Hi ${MENTION_OPEN}{"documentId":"abc`;
+ source.setData([textPart(unclosed)]);
+ vi.advanceTimersByTime(TICK_MS * (unclosed.length + 10));
+ /* the open tag is still held back */
+ expect(text()).toBe('Hi ');
+ expect(out.isHolding()).toBe(true);
+
+ source.setDone();
+ expect(text()).toBe(unclosed);
+ expect(out.isDone()).toBe(true);
+ expect(out.isHolding()).toBe(false);
+ });
+
+ it('force-flushes a mention that stalls open without a stream end', () => {
+ const { source, out, text } = setup();
+ const stalled = `Hi ${MENTION_OPEN}{"documentId":"abc`;
+ source.setData([textPart(stalled)]);
+ vi.advanceTimersByTime(TICK_MS * (stalled.length + 10));
+ expect(text()).toBe('Hi ');
+
+ vi.advanceTimersByTime(HOLD_FLUSH_MS);
+ expect(text()).toBe(stalled);
+ expect(out.isDone()).toBe(false);
+ });
+
+ it('emits a mention split across a burst of parts (catch-up path) atomically', () => {
+ const { source, text } = setup();
+ const half = Math.floor(MENTION.length / 2);
+ const parts = [
+ 'Intro ',
+ MENTION.slice(0, half),
+ MENTION.slice(half),
+ ' tail',
+ ];
+ /* a burst larger than the catch-up threshold lands all at once */
+ source.setData(parts.map(textPart));
+ vi.advanceTimersByTime(TICK_MS);
+ expect(text()).toBe(parts.join(''));
+ });
+
+ it('streams a mention inside a code fence as raw text without holding', () => {
+ /* Simulate the renderer: it parses the released text into an editor
+ state as it arrives, exactly like StaticMarkdown does. The context
+ query below only READS that state — the query itself never parses. */
+ const editor = createEditor({
+ namespace: 'renderer-sim',
+ nodes: SupportedNodeTypes,
+ onError: (error) => {
+ throw error;
+ },
+ });
+ let tailState: EditorState | undefined;
+ const tailInCode = () =>
+ tailState ? tailContext(tailState).inCode : false;
+ const { source, text } = setup([createMentionBufferPlugin(tailInCode)]);
+ createRoot((dispose) => {
+ disposers.push(dispose);
+ createEffect(() => {
+ const markdown = text();
+ editor.update(
+ () => $convertFromMarkdownString(markdown, ALL_TRANSFORMERS),
+ { discrete: true }
+ );
+ tailState = editor.getEditorState();
+ });
+ });
+
+ const fence = '```\nlet x = 1\n';
+ const full = `${fence}${MENTION}\n\`\`\``;
+ source.setData([textPart(full)]);
+
+ /* with nothing held, exactly one character lands per tick — a partial
+ tag is visible mid-fence, proving the mention was not buffered */
+ vi.advanceTimersByTime(TICK_MS * (fence.length + 9));
+ expect(text()).toBe(full.slice(0, fence.length + 10));
+
+ vi.advanceTimersByTime(TICK_MS * (full.length + 10));
+ expect(text()).toBe(full);
+ });
+
+ it('passes non-mention angle brackets through without stalling', () => {
+ const { source, text } = setup();
+ const full = 'a < b and <div> renders';
+ source.setData([textPart(full)]);
+ /* well under the hold-flush window */
+ vi.advanceTimersByTime(TICK_MS * (full.length + 10));
+ expect(text()).toBe(full);
+ });
+
+ it('runs custom plugins over every emitted unit', () => {
+ const upper: StreamPlugin = {
+ transform: (part) =>
+ part.type === 'chat_message_response' && part.content.type === 'text'
+ ? [
+ {
+ ...part,
+ content: {
+ ...part.content,
+ text: part.content.text.toUpperCase(),
+ },
+ },
+ ]
+ : [part],
+ flush: () => [],
+ isHolding: () => false,
+ };
+ const { source, text } = setup([upper]);
+ source.setData([textPart('abc')]);
+ vi.advanceTimersByTime(TICK_MS * 10);
+ expect(text()).toBe('ABC');
+ });
+});
diff --git a/js/app/packages/core/component/AI/util/stream/bufferedStream.ts b/js/app/packages/core/component/AI/util/stream/bufferedStream.ts
index 429c027d48..b09c523271 100644
--- a/js/app/packages/core/component/AI/util/stream/bufferedStream.ts
+++ b/js/app/packages/core/component/AI/util/stream/bufferedStream.ts
@@ -7,8 +7,10 @@ import {
type ChatStreamController,
createStreamController,
} from '@service-connection/stream';
-import { createEffect, on } from 'solid-js';
+import { createEffect, createSignal, on } from 'solid-js';
import { match, P } from 'ts-pattern';
+import { createMentionBufferPlugin } from './mentionPlugin';
+import type { BufferedChatMessageStream, StreamPlugin } from './types';
/* Target latency between character */
const TARGET_LATENCY_MS = 6;
@@ -17,6 +19,12 @@ const TARGET_LATENCY_MS = 6;
the source stream. This can happen on reconnects
*/
const CATCHUP_LATENCY_CHUNKS = 2;
+/*
+ A plugin may hold output back while it decides how to render it. If the
+ source goes quiet (no new data and no stream end) before the plugin
+ resolves, force a flush so held content is never stuck invisibly.
+*/
+const PLUGIN_HOLD_FLUSH_MS = 2_000;
/*
Communicates what part of source stream has been consumed
@@ -46,6 +54,10 @@ type BufferedStream = {
source: ChatMessageStream;
controller: ChatStreamController;
dispatch: (event: BufferEvent) => void;
+ /* emit units to the output, routed through the plugin chain */
+ emit: (parts: ChatStream[]) => void;
+ /* flush every plugin, then complete the output stream */
+ finish: () => void;
};
type BufferState =
@@ -253,7 +265,7 @@ function createSmoothConsumer(
if (!part) {
stream.dispatch({ event: 'consumer-done' });
} else {
- stream.controller.setData((p) => [...p, part]);
+ stream.emit([part]);
timeout = setTimeout(takeOne, TARGET_LATENCY_MS);
}
}
@@ -281,7 +293,7 @@ function createCatchUpConsumer(
): ConsumerHandle {
const consumed = prev ? prev : createConsumed();
const rest = consumed.takeRemaining(stream);
- stream.controller.setData((p) => [...p, ...rest]);
+ stream.emit(rest);
stream.dispatch({ event: 'catch-up-done' });
/* Nothing to tear down; just surface the advanced marker. */
@@ -331,8 +343,8 @@ function transition(
/* flush anything buffered past the consumed marker before completing */
const consumed = state.consumed ?? createConsumed();
const rest = consumed.takeRemaining(state.stream);
- state.stream.controller.setData((p) => [...p, ...rest]);
- state.stream.controller.setDone();
+ state.stream.emit(rest);
+ state.stream.finish();
return { type: 'done', stream: state.stream };
})
/* ignore waiting [consumer-done, catch-up-done, fall-behind-detected] */
@@ -343,7 +355,7 @@ function transition(
([state, _]) => {
if (state.stream.source.isDone()) {
state.consumer.cleanup();
- state.stream.controller.setDone();
+ state.stream.finish();
return { type: 'done', stream: state.stream };
} else {
const consumed = state.consumer.cleanup();
@@ -367,7 +379,7 @@ function transition(
([state, _e]) => {
if (state.stream.source.isDone()) {
state.consumer.cleanup();
- state.stream.controller.setDone();
+ state.stream.finish();
return { type: 'done', stream: state.stream };
} else {
const consumed = state.consumer.cleanup();
@@ -406,25 +418,89 @@ function createEventQueue<E>(handler: (event: E) => void) {
};
}
+/**
+ * Flushes every plugin in chain order: what an earlier plugin releases still
+ * passes through the plugins after it before the later ones flush themselves.
+ */
+function flushPlugins(plugins: StreamPlugin[]): ChatStream[] {
+ const out: ChatStream[] = [];
+ plugins.forEach((plugin, i) => {
+ let parts = plugin.flush();
+ for (const later of plugins.slice(i + 1)) {
+ parts = parts.flatMap((part) => later.transform(part));
+ }
+ out.push(...parts);
+ });
+ return out;
+}
+
/**
* Wraps a raw chat stream in a smoothing buffer. Rather than dumping tokens as
* they arrive, it replays them character-by-character at a steady cadence for a
* typewriter feel, while still snapping forward to the live position whenever it
- * falls too far behind (e.g. on reconnect). The returned stream emits the same
- * content in the same order as the source — only the chunking and timing differ.
+ * falls too far behind (e.g. on reconnect). Every outgoing unit is routed
+ * through the plugin chain (by default the Macro XML buffer, which keeps partial
+ * `<m-...>` tags from rendering as raw text); with no plugins the
+ * returned stream emits the same content in the same order as the source —
+ * only the chunking and timing differ.
*
* Solid is used purely to observe the source (`data`/`isDone`); all sequencing
* runs through the FIFO event queue feeding the `transition` state machine.
*/
-export function bufferedStream(source: ChatMessageStream): ChatMessageStream {
+export function bufferedStream(
+ source: ChatMessageStream,
+ plugins: StreamPlugin[] = [createMentionBufferPlugin()]
+): BufferedChatMessageStream {
const controller = createStreamController<'chat'>(source.id);
+ const [isHolding, setIsHolding] = createSignal(false);
+
+ let holdFlushTimeout: ReturnType<typeof setTimeout> | undefined;
+
+ function updateHolding() {
+ setIsHolding(plugins.some((plugin) => plugin.isHolding()));
+ }
+
+ function push(parts: ChatStream[]) {
+ if (parts.length === 0) return;
+ controller.setData((p) => [...p, ...parts]);
+ }
+
+ function forceFlushHeld() {
+ if (holdFlushTimeout) clearTimeout(holdFlushTimeout);
+ holdFlushTimeout = undefined;
+ push(flushPlugins(plugins));
+ updateHolding();
+ }
+
+ function emit(parts: ChatStream[]) {
+ push(
+ plugins.reduce<ChatStream[]>(
+ (acc, plugin) => acc.flatMap((part) => plugin.transform(part)),
+ parts
+ )
+ );
+ /* re-arm the stalled-hold flush: any emission counts as source activity */
+ if (holdFlushTimeout) clearTimeout(holdFlushTimeout);
+ holdFlushTimeout = undefined;
+ if (plugins.some((plugin) => plugin.isHolding())) {
+ holdFlushTimeout = setTimeout(forceFlushHeld, PLUGIN_HOLD_FLUSH_MS);
+ }
+ updateHolding();
+ }
+
+ function finish() {
+ if (holdFlushTimeout) clearTimeout(holdFlushTimeout);
+ push(flushPlugins(plugins));
+ updateHolding();
+ controller.setDone();
+ }
let state: BufferState;
const dispatch = createEventQueue<BufferEvent>((event) => {
state = transition(state, event);
});
- const stream: BufferedStream = { source, controller, dispatch };
+ const stream: BufferedStream = { source, controller, dispatch, emit, finish };
state = { type: 'waiting', stream };
/* Solid only bridges the reactive inputs into the queue */
@@ -444,5 +520,8 @@ export function bufferedStream(source: ChatMessageStream): ChatMessageStream {
})
);
- return controller.stream;
+ return {
+ ...controller.stream,
+ isHolding,
+ };
}
diff --git a/js/app/packages/core/component/AI/util/stream/index.ts b/js/app/packages/core/component/AI/util/stream/index.ts
index ec0ed45960..edfb9d3257 100644
--- a/js/app/packages/core/component/AI/util/stream/index.ts
+++ b/js/app/packages/core/component/AI/util/stream/index.ts
@@ -1,4 +1,5 @@
export * from './bufferedStream';
+export * from './mentionPlugin';
export * from './mockStream';
export * from './networkProfile';
export * from './pausableStream';
diff --git a/js/app/packages/core/component/AI/util/stream/mentionPlugin.test.ts b/js/app/packages/core/component/AI/util/stream/mentionPlugin.test.ts
new file mode 100644
index 0000000000..a91200c9f5
--- /dev/null
+++ b/js/app/packages/core/component/AI/util/stream/mentionPlugin.test.ts
@@ -0,0 +1,200 @@
+import type { ChatStream } from '@service-cognition/generated/schemas';
+import { describe, expect, it } from 'vitest';
+import {
+ createMentionBufferPlugin,
+ MAX_MACRO_XML_LENGTH,
+ MAX_MENTION_LENGTH,
+ MENTION_CLOSE,
+ MENTION_OPEN,
+} from './mentionPlugin';
+
+const MENTION = `${MENTION_OPEN}{"documentId":"6a2b138d-dfbe-439a-a78b-282471a1e165","documentName":"","blockName":"md","blockParams":{}}${MENTION_CLOSE}`;
+const OTHER_MACRO_XML_TAGS = [
+ '<m-user-mention>{"userId":"u1","email":"[email protected]"}</m-user-mention>',
+ '<m-date-mention>{"date":"2026-07-08","displayFormat":"Today"}</m-date-mention>',
+ '<m-contact-mention>{"contactId":"c1","name":"Ness Chu"}</m-contact-mention>',
+ '<m-pr-mention>{"id":"foreign-1","label":"macro/macro#123"}</m-pr-mention>',
+ '<m-group-mention>{"groupAlias":"here"}</m-group-mention>',
+ '<m-theme-mention>{"name":"onboarding","data":{}}</m-theme-mention>',
+ '<m-await>{"awaitId":"a1","text":"Waiting","inline":true}</m-await>',
+ '<m-future-widget>{"value":1}</m-future-widget>',
+];
+
+function textPart(text: string, message_id = 'message'): ChatStream {
+ return {
+ type: 'chat_message_response',
+ chat_id: 'chat',
+ message_id,
+ stream_id: 'stream',
+ content: { type: 'text', text },
+ };
+}
+
+function toolCallPart(): ChatStream {
+ return {
+ type: 'chat_message_response',
+ chat_id: 'chat',
+ message_id: 'message',
+ stream_id: 'stream',
+ content: { type: 'toolCall', id: '1', name: 'tool', json: {} },
+ };
+}
+
+function textOf(parts: ChatStream[]): string {
+ return parts
+ .map((part) =>
+ part.type === 'chat_message_response' && part.content.type === 'text'
+ ? part.content.text
+ : ''
+ )
+ .join('');
+}
+
+/* feed a string one character at a time, collecting everything released */
+function feedChars(
+ plugin: ReturnType<typeof createMentionBufferPlugin>,
+ text: string
+): ChatStream[] {
+ return Array.from(text).flatMap((char) => plugin.transform(textPart(char)));
+}
+
+describe('Macro XML buffer plugin', () => {
+ it('passes plain text straight through', () => {
+ const plugin = createMentionBufferPlugin();
+ const out = plugin.transform(textPart('hello world'));
+ expect(textOf(out)).toBe('hello world');
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('holds a partial mention and releases it whole once the tag closes', () => {
+ const plugin = createMentionBufferPlugin();
+ const before = MENTION.slice(0, -1);
+ const held = feedChars(plugin, `see ${before}`);
+ /* everything before the tag is released, the open tag is held */
+ expect(textOf(held)).toBe('see ');
+ expect(plugin.isHolding()).toBe(true);
+
+ const released = plugin.transform(textPart(MENTION.slice(-1)));
+ expect(released).toHaveLength(1);
+ expect(textOf(released)).toBe(MENTION);
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('never releases a partial Macro XML tag while it is streaming', () => {
+ for (const macroXml of [MENTION, ...OTHER_MACRO_XML_TAGS]) {
+ const plugin = createMentionBufferPlugin();
+ let emitted = '';
+ for (const char of Array.from(`a ${macroXml} b`)) {
+ emitted += textOf(plugin.transform(textPart(char)));
+ /* at no point may a fragment of the tag be visible */
+ if (emitted.includes('<')) {
+ expect(emitted).toContain(macroXml);
+ }
+ }
+ expect(emitted).toBe(`a ${macroXml} b`);
+ }
+ });
+
+ it('releases text with non-Macro XML tags unchanged', () => {
+ const plugin = createMentionBufferPlugin();
+ const text = '1 < 2 and <div> is html <m-other-tag>';
+ const out = textOf(feedChars(plugin, text)) + textOf(plugin.flush());
+ expect(out).toBe(text);
+ });
+
+ it('handles a mention split across large chunks', () => {
+ const plugin = createMentionBufferPlugin();
+ const half = Math.floor(MENTION.length / 2);
+ const first = plugin.transform(
+ textPart(`before ${MENTION.slice(0, half)}`)
+ );
+ expect(textOf(first)).toBe('before ');
+ const second = plugin.transform(textPart(`${MENTION.slice(half)} after`));
+ expect(textOf(second)).toBe(`${MENTION} after`);
+ /* the completed mention is a single atomic part */
+ expect(textOf([second[0]])).toBe(MENTION);
+ });
+
+ it('flushes held text unchanged when the mention never closes', () => {
+ const plugin = createMentionBufferPlugin();
+ const unclosed = `${MENTION_OPEN}{"documentId":"abc`;
+ feedChars(plugin, unclosed);
+ expect(plugin.isHolding()).toBe(true);
+ expect(textOf(plugin.flush())).toBe(unclosed);
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('gives up on an open mention that grows past the size cap', () => {
+ const plugin = createMentionBufferPlugin();
+ const runaway = `${MENTION_OPEN}{"documentId":"${'x'.repeat(MAX_MENTION_LENGTH)}`;
+ const out = textOf(feedChars(plugin, runaway));
+ /* once past the cap the whole tag is released and later text flows freely */
+ expect(out).toBe(runaway);
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('gives up on any open Macro XML tag that grows past the size cap', () => {
+ const plugin = createMentionBufferPlugin();
+ const runaway = `<m-future-widget>${'x'.repeat(MAX_MACRO_XML_LENGTH)}`;
+ const out = textOf(feedChars(plugin, runaway));
+ expect(out).toBe(runaway);
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('gives up on an unterminated Macro XML tag name that grows past the size cap', () => {
+ const plugin = createMentionBufferPlugin();
+ const runaway = `<m-${'x'.repeat(MAX_MACRO_XML_LENGTH)}`;
+ const out = textOf(feedChars(plugin, runaway));
+ expect(out).toBe(runaway);
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('releases held text before a non-text part to preserve order', () => {
+ const plugin = createMentionBufferPlugin();
+ feedChars(plugin, MENTION_OPEN);
+ const out = plugin.transform(toolCallPart());
+ expect(textOf(out)).toBe(MENTION_OPEN);
+ expect(out.at(-1)).toMatchObject({ content: { type: 'toolCall' } });
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('keeps source message metadata on text released as-is', () => {
+ const plugin = createMentionBufferPlugin();
+ plugin.transform(textPart('<m-doc', 'message-a'));
+ const out = plugin.transform(textPart('x tail', 'message-b'));
+ const ids = out.map((part) =>
+ part.type === 'chat_message_response' ? part.message_id : undefined
+ );
+ expect(textOf(out)).toBe('<m-docx tail');
+ expect(ids).toEqual(['message-a', 'message-b']);
+ });
+
+ it('handles several mentions in one message', () => {
+ const plugin = createMentionBufferPlugin();
+ const text = `a ${MENTION} b ${MENTION} c`;
+ const out = textOf(feedChars(plugin, text)) + textOf(plugin.flush());
+ expect(out).toBe(text);
+ });
+
+ it('passes a complete mention through unmerged when the tag lands in code', () => {
+ const plugin = createMentionBufferPlugin(() => true);
+ const out = feedChars(plugin, MENTION);
+ /* released as the original one-char units, never held or merged */
+ expect(out).toHaveLength(MENTION.length);
+ expect(textOf(out)).toBe(MENTION);
+ expect(plugin.isHolding()).toBe(false);
+ });
+
+ it('releases a held tag when the code context turns out to be code', () => {
+ let inCode = false;
+ const plugin = createMentionBufferPlugin(() => inCode);
+ feedChars(plugin, MENTION_OPEN.slice(0, 10));
+ expect(plugin.isHolding()).toBe(true);
+
+ /* e.g. the renderer catches up and reports the tag is inside a fence */
+ inCode = true;
+ const out = plugin.transform(textPart(MENTION_OPEN[10]));
+ expect(textOf(out)).toBe(MENTION_OPEN.slice(0, 11));
+ expect(plugin.isHolding()).toBe(false);
+ });
+});
diff --git a/js/app/packages/core/component/AI/util/stream/mentionPlugin.ts b/js/app/packages/core/component/AI/util/stream/mentionPlugin.ts
new file mode 100644
index 0000000000..1a1b2513dc
--- /dev/null
+++ b/js/app/packages/core/component/AI/util/stream/mentionPlugin.ts
@@ -0,0 +1,159 @@
+import type {
+ AssistantMessagePart,
+ ChatStream,
+} from '@service-cognition/generated/schemas';
+import type { StreamPlugin } from './types';
+
+export const MENTION_OPEN = '<m-document-mention>';
+export const MENTION_CLOSE = '</m-document-mention>';
+export const MACRO_XML_PREFIX = '<m-';
+const MACRO_XML_OPEN_TAG = /^<(m-[a-zA-Z0-9_-]+)>/;
+/*
+ Most inline Macro XML tags are compact. If a held tag grows past this,
+ stop holding so malformed tags and large block payloads do not stay hidden.
+*/
+export const MAX_MACRO_XML_LENGTH = 4096;
+export const MAX_MENTION_LENGTH = MAX_MACRO_XML_LENGTH;
+
+type ChatResponse = Extract<ChatStream, { type: 'chat_message_response' }>;
+type TextContent = Extract<AssistantMessagePart, { type: 'text' }>;
+type TextResponse = ChatResponse & { content: TextContent };
+
+function isTextResponse(part: ChatStream): part is TextResponse {
+ return part.type === 'chat_message_response' && part.content.type === 'text';
+}
+
+function toTextPart(template: TextResponse, text: string): TextResponse {
+ return { ...template, content: { ...template.content, text } };
+}
+
+/*
+ Reports whether streamed text is currently landing in a code context.
+ Must be cheap: it is re-read while a candidate tag is held (which also
+ lets a late answer — e.g. a renderer that hasn't caught up yet — correct
+ an earlier hold).
+*/
+export type IsCodeContext = () => boolean;
+
+/**
+ * Holds back text that looks like an in-progress Macro XML tag (`<m-...>`) so
+ * the viewer never sees raw internal markup dripping in character by character;
+ * a completed tag is released as one atomic text part so it renders as its
+ * parsed node immediately. Text held for a tag that turns out not to be Macro
+ * XML is released unchanged, and an open tag that grows past
+ * MAX_MACRO_XML_LENGTH is given up on — combined with the buffered stream's
+ * flush-on-quiet and flush-on-done, an unclosed tag is never held forever.
+ *
+ * A tag streaming into a code context (fenced block or inline code) renders
+ * literally, so it is never held; `isCodeContext` reports what the message
+ * renderer's already-parsed node tree says about where text is landing.
+ */
+export function createMentionBufferPlugin(
+ isCodeContext: IsCodeContext = () => false
+): StreamPlugin {
+ /*
+ Text consumed from the stream but not yet released, split by source part so
+ released text keeps its original message metadata.
+ */
+ const segments: { template: TextResponse; text: string }[] = [];
+
+ const pending = () => segments.map((s) => s.text).join('');
+
+ /* Release the first `count` held characters as text parts, one per source segment. */
+ function release(count: number): ChatStream[] {
+ const out: ChatStream[] = [];
+ while (count > 0 && segments.length > 0) {
+ const segment = segments[0];
+ if (segment.text.length <= count) {
+ out.push(toTextPart(segment.template, segment.text));
+ count -= segment.text.length;
+ segments.shift();
+ } else {
+ out.push(toTextPart(segment.template, segment.text.slice(0, count)));
+ segment.text = segment.text.slice(count);
+ count = 0;
+ }
+ }
+ return out;
+ }
+
+ /* Release the first `count` held characters merged into a single text part. */
+ function releaseMerged(count: number): ChatStream[] {
+ const template = segments[0]?.template;
+ if (!template) return [];
+ const text = release(count)
+ .map((part) => (isTextResponse(part) ? part.content.text : ''))
+ .join('');
+ return [toTextPart(template, text)];
+ }
+
+ function canBecomeMacroXml(text: string): boolean {
+ if (MACRO_XML_PREFIX.startsWith(text)) return true;
+ return /^<m-[a-zA-Z0-9_-]*$/.test(text);
+ }
+
+ /*
+ Release everything held that can no longer become (part of) Macro XML.
+ Only holds from a '<' that is still a viable Macro XML prefix onward.
+ */
+ function drain(): ChatStream[] {
+ const out: ChatStream[] = [];
+ for (;;) {
+ const text = pending();
+ if (text.length === 0) break;
+ const tagStart = text.indexOf('<');
+ /* no possible mention start -> release everything */
+ if (tagStart === -1) {
+ out.push(...release(text.length));
+ break;
+ }
+ /* release the text before the possible mention start */
+ if (tagStart > 0) {
+ out.push(...release(tagStart));
+ continue;
+ }
+ const openTag = text.match(MACRO_XML_OPEN_TAG);
+ const viableMacroXml = !!openTag || canBecomeMacroXml(text);
+ if (viableMacroXml && !isCodeContext()) {
+ if (text.length > MAX_MACRO_XML_LENGTH) {
+ out.push(...release(text.length));
+ break;
+ }
+ if (openTag) {
+ const closeTag = `</${openTag[1]}>`;
+ const close = text.indexOf(closeTag, openTag[0].length);
+ /* a complete Macro XML tag -> release it as one atomic part */
+ if (close !== -1) {
+ out.push(...releaseMerged(close + closeTag.length));
+ continue;
+ }
+ }
+ /* Macro XML (or a prefix that may become it) still streaming -> hold */
+ break;
+ }
+ /* not Macro XML here (wrong tag, or inside code where the tag renders
+ literally) -> release up to the next '<' */
+ const next = text.indexOf('<', 1);
+ out.push(...release(next === -1 ? text.length : next));
+ }
+ return out;
+ }
+
+ return {
+ transform(part) {
+ if (!isTextResponse(part)) {
+ /* a non-text part interrupts any held XML; release held text first to preserve order */
+ return [...release(pending().length), part];
+ }
+ if (part.content.text.length === 0) return [];
+ segments.push({ template: part, text: part.content.text });
+ return drain();
+ },
+ flush() {
+ return release(pending().length);
+ },
+ isHolding() {
+ return segments.length > 0;
+ },
+ };
+}
diff --git a/js/app/packages/core/component/AI/util/stream/types.ts b/js/app/packages/core/component/AI/util/stream/types.ts
index 08584d7a45..b53023b755 100644
--- a/js/app/packages/core/component/AI/util/stream/types.ts
+++ b/js/app/packages/core/component/AI/util/stream/types.ts
@@ -1,4 +1,28 @@
+import type { ChatStream } from '@service-cognition/generated/schemas';
import type { ChatMessageStream } from '@service-connection/stream';
+import type { Accessor } from 'solid-js';
export type StreamItem = ReturnType<ChatMessageStream['data']>[number];
export type NetworkDelay = (index: number) => number;
export type Splitter = (items: StreamItem[]) => StreamItem[];
+
+export type BufferedChatMessageStream = ChatMessageStream & {
+ /* True while a stream plugin is holding output back for more input. */
+ isHolding: Accessor<boolean>;
+};
+
+/**
+ * Rewrites the units a buffered stream emits, sitting between the buffering
+ * consumers and the output controller. A plugin may hold units back (return
+ * fewer than it was given) and release them later — the buffered stream
+ * flushes every plugin when the source finishes, and force-flushes if the
+ * source goes quiet while a plugin is holding, so held content is never
+ * stuck invisibly.
+ */
+export interface StreamPlugin {
+ /* Process one outgoing unit; returns the units ready to emit now (empty while holding). */
+ transform(part: ChatStream): ChatStream[];
+ /* Release everything held, as close to the original units as possible. */
+ flush(): ChatStream[];
+ /* True while output is held back waiting on more input. */
+ isHolding(): boolean;
+}
diff --git a/js/app/packages/core/component/LexicalMarkdown/component/core/StaticMarkdown.tsx b/js/app/packages/core/component/LexicalMarkdown/component/core/StaticMarkdown.tsx
index 3c83ef7332..50f4594b55 100644
--- a/js/app/packages/core/component/LexicalMarkdown/component/core/StaticMarkdown.tsx
+++ b/js/app/packages/core/component/LexicalMarkdown/component/core/StaticMarkdown.tsx
@@ -55,6 +55,7 @@ import {
createEffect,
createMemo,
createSignal,
+ onCleanup,
Show,
useContext,
} from 'solid-js';
@@ -836,23 +837,25 @@ function Render(
return '';
}
-function MapRender(props: {
- children: LexicalNode[];
- theme: EditorThemeClasses;
- lazy: boolean;
-}) {
+function MapRender(
+ props: {
+ children: LexicalNode[];
+ theme: EditorThemeClasses;
+ } & StaticRenderOptions
+) {
return props.children.map((child) => (
<Render node={child} theme={props.theme} lazy={props.lazy} />
));
}
-function Document(props: {
- rootNode: RootNode;
- theme: EditorThemeClasses;
- lazy: boolean;
- rootRef?: (ref: HTMLDivElement) => void;
- singleLine?: boolean;
-}): JSX.Element {
+function Document(
+ props: {
+ rootNode: RootNode;
+ theme: EditorThemeClasses;
+ rootRef?: (ref: HTMLDivElement) => void;
+ singleLine?: boolean;
+ } & StaticRenderOptions
+): JSX.Element {
return (
<div
class={cn(
@@ -882,6 +885,14 @@ export function StaticMarkdown(props: {
parentEditor?: LexicalEditor;
theme?: EditorThemeClasses;
setEditorRef?: (editor: LexicalEditor) => void;
+ /* Accessor for the parsed state this instance renders. Unlike setEditorRef
+ (which may hand back the shared context editor), the state snapshot is
+ always this instance's own parse of its markdown. */
+ setStateRef?: (
+ state: Accessor<EditorState | null> | undefined,
+ key?: string
+ ) => void;
+ stateRefKey?: string;
rootRef?: (ref: HTMLDivElement) => void;
target?: 'internal' | 'external' | 'both';
singleLine?: boolean;
@@ -893,6 +904,13 @@ export function StaticMarkdown(props: {
lazy: parentLazy,
} = useContext(context);
let [editorState, setEditorState] = createSignal<EditorState | null>(null);
+ createEffect(() => {
+ const setStateRef = props.setStateRef;
+ const key = props.stateRefKey;
+ if (!setStateRef) return;
+ setStateRef(editorState, key);
+ onCleanup(() => setStateRef(undefined, key));
+ });
if (contextEditor === null) {
console.warn(
diff --git a/js/app/packages/core/component/LexicalMarkdown/tailContext.test.ts b/js/app/packages/core/component/LexicalMarkdown/tailContext.test.ts
new file mode 100644
index 0000000000..bd1a30b55c
--- /dev/null
+++ b/js/app/packages/core/component/LexicalMarkdown/tailContext.test.ts
@@ -0,0 +1,51 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { $convertFromMarkdownString } from '@lexical/markdown';
+import { ALL_TRANSFORMERS, SupportedNodeTypes } from '@lexical-core';
+import { createEditor, type EditorState } from 'lexical';
+import { describe, expect, it } from 'vitest';
+import { tailContext } from './tailContext';
+
+/* parse the way the message renderer does, then query the resulting state */
+function parse(markdown: string): EditorState {
+ const editor = createEditor({
+ namespace: 'tail-context-test',
+ nodes: SupportedNodeTypes,
+ onError: (error) => {
+ throw error;
+ },
+ });
+ editor.update(() => $convertFromMarkdownString(markdown, ALL_TRANSFORMERS), {
+ discrete: true,
+ });
+ return editor.getEditorState();
+}
+
+describe('tailContext', () => {
+ it('plain paragraph text is not code', () => {
+ expect(tailContext(parse('hello world')).inCode).toBe(false);
+ });
+
+ it('tail inside an unclosed fence is code', () => {
+ expect(tailContext(parse('intro\n```ts\nconst x = 1;')).inCode).toBe(true);
+ });
+
+ it('text after a closed fence is not code', () => {
+ expect(tailContext(parse('```ts\nconst x = 1;\n```\nafter')).inCode).toBe(
+ false
+ );
+ });
+
+ it('tail of a closed inline code span is code', () => {
+ expect(tailContext(parse('see `foo`')).inCode).toBe(true);
+ });
+
+ it('an unclosed backtick is not code (yet)', () => {
+ expect(tailContext(parse('see `foo')).inCode).toBe(false);
+ });
+
+ it('empty markdown is not code', () => {
+ expect(tailContext(parse('')).inCode).toBe(false);
+ });
+});
diff --git a/js/app/packages/core/component/LexicalMarkdown/tailContext.ts b/js/app/packages/core/component/LexicalMarkdown/tailContext.ts
new file mode 100644
index 0000000000..57b5a3d54e
--- /dev/null
+++ b/js/app/packages/core/component/LexicalMarkdown/tailContext.ts
@@ -0,0 +1,27 @@
+import { $isCodeNode } from '@lexical/code';
+import { $getRoot, $isTextNode, type EditorState } from 'lexical';
+
+export type TailContext = {
+ /* type of the deepest node at the very end of the document */
+ nodeType: string;
+ /* true when the tail is inside a fenced code block or inline code */
+ inCode: boolean;
+};
+
+/**
+ * Reports the node context at the very end of an already-parsed editor state —
+ * the node streamed text is currently landing in. This is a read of existing
+ * state, not a parse: pair it with the state the message renderer already
+ * maintains so stream-side heuristics (e.g. mention buffering) make the same
+ * call the renderer made.
+ */
+export function tailContext(state: EditorState): TailContext {
+ return state.read(() => {
+ const tail = $getRoot().getLastDescendant();
+ if (!tail) return { nodeType: 'root', inCode: false };
+ const inCode =
+ ($isTextNode(tail) && tail.hasFormat('code')) ||
+ [tail, ...tail.getParents()].some($isCodeNode);
+ return { nodeType: tail.getType(), inCode };
+ });
+}