@dxos/plugin-assistant 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

package/src/components/ChatThread/ChatThread.tsx

@@ -2,24 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type CSSProperties, forwardRef, useCallback, useEffect, useMemo, useState } from 'react';
+import React, { forwardRef, useCallback, useEffect, useMemo, useState } from 'react';
 
 import { PublicKey } from '@dxos/keys';
 import { type Identity } from '@dxos/react-client/halo';
 import { type ThemedClassName, setRef } from '@dxos/react-ui';
-import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-components';
+import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-markdown';
 import { type Message } from '@dxos/types';
-import { mx } from '@dxos/ui-theme';
 import { keyToFallback } from '@dxos/util';
 
+import { type Assistant } from '../../types';
 import { type ChatEvent } from '../Chat';
-import { blockToMarkdown, componentRegistry } from './registry';
+import { componentRegistry, createBlockRenderer } from './registry';
 import { MessageSyncer } from './sync';
 
 const defaultOptions: MarkdownStreamProps['options'] = {
   autoScroll: true,
-  // wire: true,
-  cursor: true,
+  cursor: false,
+  fader: false,
+  typewriter: true,
 };
 
 export type ChatThreadProps = ThemedClassName<
@@ -27,13 +28,27 @@ export type ChatThreadProps = ThemedClassName<
     identity?: Identity;
     messages?: Message.Message[];
     error?: Error;
+    viewType?: Assistant.ChatView;
     onEvent?: (event: ChatEvent) => void;
-  } & Pick<MarkdownStreamProps, 'options' | 'debug'>
+  } & Pick<MarkdownStreamProps, 'options' | 'debug' | 'extensions' | 'footer'>
 >;
 
-// TODO(burdon): Memo thread position.
 export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThreadProps>(
-  ({ classNames, identity, messages = [], error, options = defaultOptions, debug = false, onEvent }, forwardedRef) => {
+  (
+    {
+      classNames,
+      identity,
+      messages = [],
+      error,
+      options = defaultOptions,
+      footer,
+      debug = false,
+      extensions,
+      viewType,
+      onEvent,
+    },
+    forwardedRef,
+  ) => {
     const [controller, setController] = useState<MarkdownStreamController | null>(null);
     const handleMarkdownStreamRef = useCallback(
       (instance: MarkdownStreamController | null) => {
@@ -54,10 +69,14 @@ export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThread
     }, [controller, error]);
 
     // Update document.
-    const syncer = useMemo(() => controller && new MessageSyncer(controller, blockToMarkdown), [controller]);
+    const renderer = useMemo(() => createBlockRenderer(viewType), [viewType]);
+    const syncer = useMemo(() => controller && new MessageSyncer(controller, renderer), [controller, renderer]);
     useEffect(() => {
-      const reset = syncer?.append(messages, true);
-      if (reset) {
+      if (!syncer) {
+        return;
+      }
+
+      if (syncer.update(messages)) {
         controller?.scrollToBottom('instant');
       }
     }, [controller, syncer, messages]);
@@ -76,19 +95,15 @@ export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThread
     );
 
     return (
-      <div
-        role='none'
-        className={mx('flex h-full w-full justify-center overflow-hidden', classNames)}
-        style={
-          {
-            '--user-fill': `var(--color-${userHue}-fill)`,
-          } as CSSProperties
-        }
-      >
+      <div data-hue={userHue} className='contents'>
         <MarkdownStream
+          key={viewType}
+          classNames={classNames}
           registry={componentRegistry}
           options={options}
           debug={debug}
+          extensions={extensions}
+          footer={footer}
           onEvent={handleEvent}
           ref={handleMarkdownStreamRef}
         />

package/src/components/ChatThread/DEBUG.md

@@ -0,0 +1,41 @@
+# Dataflow from AI to Codemirror
+
+AiSession (packages/core/assistant/src/conversation/session.ts)
+│
+│ emits ephemeral Trace events containing
+│ PartialBlock { messageId, role, block: ContentBlock.Any }
+│ via AgentService.Session.subscribeEphemeral(): Stream<Trace.Message>
+▼
+AiChatProcessor (packages/plugins/plugin-assistant/src/processor/processor.ts)
+│
+│ Stream.runForEach → if Trace.isOfType(PartialBlock) →
+│ #handleEphemeralMessage(event.data)
+│ → upserts Message.Message into #streaming atom
+│ → finalizes into #messages atom on complete block
+▼
+Chat.tsx (packages/plugins/plugin-assistant/src/components/Chat/Chat.tsx)
+│
+│ reads processor.messages + processor.streaming atoms,
+│ passes flat Message[] down to ChatThread
+▼
+ChatThread.tsx (packages/plugins/plugin-assistant/src/components/ChatThread/ChatThread.tsx)
+│
+│ MessageSyncer (sync.ts) compares current messages
+│ to last rendered set:
+│ - new finalized chunk → controller.append(delta)
+│ - changed earlier message → controller.setContent(full)
+│ blockToMarkdown serializes ContentBlocks → markdown,
+│ embedding tool calls as XML widget tags
+│ (e.g. <tool-call name="...">...</tool-call>)
+▼
+MarkdownStreamController.append / setContent
+▼
+MarkdownStream (packages/ui/react-ui-markdown/src/MarkdownStream/MarkdownStream.tsx)
+│
+│ CodeMirror editor with:
+│ - extendedMarkdown (parseMixed → xmlLanguage on HTMLBlock/Paragraph)
+│ - xmlTags (registry → React/native widget portals)
+│ - wire extension (buffers appended text, drips at typewriter rate,
+│ treats XML atomic ranges as indivisible units)
+▼
+Rendered DOM (markdown + portaled widgets for tool calls / reasoning / etc.)

package/src/components/ChatThread/MarkdownStream.stories.tsx

@@ -0,0 +1,281 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useEffect, useState } from 'react';
+
+import '@dxos/lit-ui';
+import { PublicKey } from '@dxos/keys';
+import { random } from '@dxos/random';
+import { Input, Toolbar } from '@dxos/react-ui';
+import { Panel } from '@dxos/react-ui';
+import {
+  MarkdownStream,
+  type MarkdownStreamController,
+  type MarkdownStreamProps,
+  textStream,
+} from '@dxos/react-ui-markdown';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ContentBlock } from '@dxos/types';
+import { keyToFallback } from '@dxos/util';
+
+import { translations } from '#translations';
+
+import { componentRegistry } from './registry';
+import REASONING from './testing/reasoning.md?raw';
+import THINKING from './testing/thinking.md?raw';
+import THREAD_1 from './testing/thread-1.md?raw';
+import THREAD_WIDGETS from './testing/thread-widgets.md?raw';
+
+random.seed(123);
+
+const userHue = keyToFallback(PublicKey.random()).hue;
+
+type TextStreamOptions = {
+  wordsPerChunk?: number;
+  chunkDelay?: number;
+  variance?: number;
+};
+
+const defaultStreamOptions: TextStreamOptions = {
+  wordsPerChunk: 5,
+  chunkDelay: 200,
+  variance: 0.5,
+};
+
+/** Matches self-closing tool call tags in assistant markdown fixtures (e.g. thinking.md). */
+const TOOL_CALL_MARKUP_REGEX = /<toolCall\s+id="([^"]+)"\s*\/>/g;
+
+const extractToolCallIdsFromMarkdown = (markdown: string): string[] =>
+  [...markdown.matchAll(TOOL_CALL_MARKUP_REGEX)].map((match) => match[1]);
+
+const SAMPLE_TOOL_NAMES = [
+  'get_project_rules',
+  'list_mailboxes',
+  'query_inbox',
+  'enable_blueprint',
+  'create_schema',
+  'create_project',
+  'retry_operation',
+] as const;
+
+const sampleCallAndResultBlocks = (toolCallId: string, index: number): ContentBlock.Any[] => {
+  const name = SAMPLE_TOOL_NAMES[index % SAMPLE_TOOL_NAMES.length];
+  const input = JSON.stringify({ step: index + 1, tool: name });
+  const result = JSON.stringify({ ok: true, detail: `Sample result for ${name}.` });
+  return [
+    { _tag: 'toolCall', toolCallId, name, input, providerExecuted: false },
+    { _tag: 'toolResult', toolCallId, name, result, providerExecuted: false },
+  ];
+};
+
+type DefaultStoryProps = MarkdownStreamProps & {
+  initialContent?: string;
+  streamOptions?: TextStreamOptions;
+  /**
+   * When true, after loading `initialContent`, finds `<toolCall id="..." />` ids via
+   * {@link TOOL_CALL_MARKUP_REGEX} and seeds each portal widget with paired toolCall + toolResult blocks.
+   */
+  seedToolWidgetsFromMarkdown?: boolean;
+};
+
+const DefaultStory = ({
+  initialContent,
+  content,
+  streamOptions = defaultStreamOptions,
+  debug: debugProp,
+  seedToolWidgetsFromMarkdown = false,
+  ...props
+}: DefaultStoryProps) => {
+  const [controller, setController] = useState<MarkdownStreamController | null>(null);
+  const [streaming, setStreaming] = useState(false);
+  const [debug, setDebug] = useState(debugProp);
+
+  useEffect(() => {
+    if (!controller || !initialContent) {
+      return;
+    }
+
+    let cancelled = false;
+    void (async () => {
+      await controller.append(initialContent);
+      if (cancelled || !seedToolWidgetsFromMarkdown) {
+        return;
+      }
+
+      const toolCallIds = extractToolCallIdsFromMarkdown(initialContent);
+      toolCallIds.forEach((toolCallId, index) => {
+        controller.updateWidget(toolCallId, {
+          blocks: sampleCallAndResultBlocks(toolCallId, index),
+        });
+      });
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [controller, initialContent, seedToolWidgetsFromMarkdown]);
+
+  useEffect(() => {
+    if (!controller || !streaming || !content) {
+      return;
+    }
+
+    let cancelled = false;
+    void (async () => {
+      for await (const chunk of textStream(content + '\n', streamOptions)) {
+        if (cancelled) {
+          break;
+        }
+
+        await controller.append(chunk);
+      }
+
+      setStreaming(false);
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [controller, content, streaming]);
+
+  const handleReset = useCallback(() => {
+    setStreaming(false);
+    void controller?.setContent('');
+  }, [controller]);
+
+  return (
+    <Panel.Root data-hue={userHue}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>
+          <Toolbar.IconButton
+            disabled={streaming}
+            icon='ph--play--regular'
+            iconOnly
+            label='Start'
+            onClick={() => setStreaming(true)}
+          />
+          <Toolbar.IconButton
+            disabled={!streaming}
+            icon='ph--stop--regular'
+            iconOnly
+            label='Stop'
+            onClick={() => setStreaming(false)}
+          />
+          <Toolbar.IconButton icon='ph--trash--regular' iconOnly label='Reset' onClick={handleReset} />
+          <Toolbar.Separator />
+          <Input.Root>
+            <Input.Label classNames='pr-1'>Debug</Input.Label>
+            <Input.Switch checked={debug} onCheckedChange={setDebug} />
+          </Input.Root>
+        </Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content>
+        <MarkdownStream {...props} debug={debug} ref={setController} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/MarkdownStream',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    registry: componentRegistry,
+    initialContent: THREAD_1,
+    options: {
+      autoScroll: true,
+    },
+  },
+};
+
+export const Streaming: Story = {
+  args: {
+    registry: componentRegistry,
+    content: THREAD_1,
+    options: {
+      autoScroll: true,
+      typewriter: true,
+      cursor: true,
+    },
+  },
+};
+
+export const Widgets: Story = {
+  args: {
+    registry: componentRegistry,
+    initialContent: THREAD_WIDGETS,
+    options: {
+      autoScroll: true,
+    },
+  },
+};
+
+export const Debug: Story = {
+  args: {
+    initialContent: THREAD_1,
+    registry: componentRegistry,
+    content: THREAD_1,
+    debug: true,
+  },
+};
+
+export const Thinking: Story = {
+  args: {
+    initialContent: THINKING,
+    registry: componentRegistry,
+    seedToolWidgetsFromMarkdown: true,
+    options: {
+      autoScroll: true,
+    },
+  },
+};
+
+/**
+ * Splits a fixture at the first `</prompt>` so the prompt can be pre-loaded as initialContent
+ * (matching production: user prompts are submitted whole and never streamed) while the assistant
+ * body is streamed. Keeps the streaming-tail XML scan focused on the tags it is meant for
+ * (`<reasoning>`, `<status>`) instead of accumulating widgets for an unclosed `<prompt>`.
+ */
+const splitPromptAndBody = (markdown: string): { prompt: string; body: string } => {
+  const closing = '</prompt>';
+  const idx = markdown.indexOf(closing);
+  if (idx === -1) {
+    return { prompt: '', body: markdown };
+  }
+  return { prompt: markdown.slice(0, idx + closing.length), body: markdown.slice(idx + closing.length) };
+};
+
+const REASONING_PARTS = splitPromptAndBody(REASONING);
+
+/**
+ * Streams a reasoning block whose body contains a numbered list — exercises the streaming-tail XML
+ * scan as `<reasoning>` opens, accumulates list-marker lines like `"1. "`, and finally closes. Use
+ * this to visually verify that the reasoning widget renders cleanly without duplicate opening tags
+ * (regression from the per-line bullet stripper that used to collapse `"1. "` to empty mid-stream).
+ */
+export const Reasoning: Story = {
+  args: {
+    registry: componentRegistry,
+    initialContent: REASONING_PARTS.prompt,
+    content: REASONING_PARTS.body,
+    options: {
+      autoScroll: true,
+      typewriter: true,
+      cursor: true,
+    },
+  },
+};

package/src/components/ChatThread/registry.tsx

@@ -2,14 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
+import React from 'react';
+
 import { log } from '@dxos/log';
 import { ContentBlock, type Message } from '@dxos/types';
 import { type XmlWidgetRegistry, getXmlTextChild } from '@dxos/ui-editor';
 
+import { type Assistant } from '../../types';
 import { type BlockRenderer, type MessageThreadContext } from './sync';
+import { applyToolBlockToWidgetState } from './tool-widget-state';
 import {
   FallbackWidget,
-  PromptWidget,
   ReasoningWidget,
   ReferenceWidget,
   SelectWidget,
@@ -17,21 +20,41 @@ import {
   StatsWidget,
   SummaryWidget,
   ToolWidget,
+  StatusWidget,
 } from './widgets';
 
 /**
  * Custom XML tags registry.
+ *
+ * NOTE: `<prompt>` has no widget — it is rendered via mark + line decorations
+ * (`xmlBlockDecoration`) in MarkdownStream so the prompt text remains part of the document
+ * and can be highlighted by `xmlFormatting`. It is still listed here so the markdown block
+ * parser (`xmlBlockParsers`) knows to keep `<prompt>...</prompt>` as a single HTMLBlock
+ * — otherwise an unregistered prompt opens a Paragraph that lazy-continues into the
+ * following lines and breaks parsing of subsequent multi-line tags (e.g. a `<reasoning>`
+ * block whose content contains an ordered list).
  */
 export const componentRegistry: XmlWidgetRegistry = {
   //
-  // DOM Widgets
+  // Block-only (no widget — see note above).
   //
 
   prompt: {
     block: true,
-    factory: ({ children }) => {
+  },
+
+  //
+  // DOM Widgets
+  //
+
+  synthetic: {
+    block: true,
+    factory: ({ children, range }) => {
       const text = getXmlTextChild(children);
-      return text ? new PromptWidget(text) : null;
+      // TODO(dmaretskyi): Synthetic blocks are "user"-turn messages generated by the system, i.e. and event from a trigger, an email-encoded to JSON, etc.
+      //                   They are meant to start agent, to process the event without looking like user-authored prompt.
+      //                   Create a new widget type for them.
+      return text ? new ReasoningWidget(text, range.from) : null;
     },
   },
   reasoning: {
@@ -72,6 +95,14 @@ export const componentRegistry: XmlWidgetRegistry = {
       return text ? new StatsWidget(text) : null;
     },
   },
+  status: {
+    block: true,
+    streaming: true,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children);
+      return text ? new StatusWidget(text) : null;
+    },
+  },
 
   //
   // React Widgets (portaled outside of the editor)
@@ -83,9 +114,12 @@ export const componentRegistry: XmlWidgetRegistry = {
   },
   toolCall: {
     block: true,
-    Component: ToolWidget,
+    Component: (props) => (
+      <div className='py-2'>
+        <ToolWidget {...props} />
+      </div>
+    ),
   },
-
   toolResult: {
     block: true,
     Component: FallbackWidget,
@@ -108,17 +142,51 @@ export const componentRegistry: XmlWidgetRegistry = {
 /**
  * Convert block to markdown.
  */
-export const blockToMarkdown: BlockRenderer = (
-  context: MessageThreadContext,
+export const blockToMarkdown: BlockRenderer = createBlockRenderer('normal');
+
+/**
+ * Create a {@link BlockRenderer} that filters blocks based on the chat view type.
+ *
+ * - `summary`: only user prompts.
+ * - `normal`: user prompts + assistant text + tool calls + summary/select/suggestion/reference + status. Hides reasoning.
+ * - `thinking`: same as normal plus reasoning.
+ * - `debug`: renders every block (raw fallbacks visible).
+ */
+export function createBlockRenderer(viewType: Assistant.ChatView | undefined): BlockRenderer {
+  return (context, message, block) => {
+    if (!isBlockVisible(viewType, message, block)) {
+      return;
+    }
+    let str = blockToMarkdownImpl(context, message, block);
+    if (str && !block.pending) {
+      // Use a blank line as the block separator so each rendered block parses as its own
+      // markdown block. A single newline lets CommonMark absorb a following `<prompt>` (an
+      // HTML type-7 tag, which can't interrupt an open paragraph) into the previous
+      // paragraph, rendering the prompt bubble inline next to the prior assistant text.
+      return (str += '\n');
+    }
+    return str;
+  };
+}
+
+const isBlockVisible = (
+  viewType: Assistant.ChatView | undefined,
   message: Message.Message,
   block: ContentBlock.Any,
-) => {
-  let str = blockToMarkdownImpl(context, message, block);
-  if (str && !block.pending) {
-    return (str += '\n');
+): boolean => {
+  switch (viewType) {
+    case 'debug':
+      return true;
+    case 'normal':
+      return block._tag !== 'reasoning';
+    case 'summary':
+      // Show only conversational text (user prompts + assistant replies); hide reasoning,
+      // tool calls, status, stats, and synthetic system messages.
+      return block._tag === 'text' && (block as ContentBlock.Text).disposition !== 'synthetic';
+    case 'thinking':
+    default:
+      return true;
   }
-
-  return str;
 };
 
 const blockToMarkdownImpl = (context: MessageThreadContext, message: Message.Message, block: ContentBlock.Any) => {
@@ -126,7 +194,11 @@ const blockToMarkdownImpl = (context: MessageThreadContext, message: Message.Mes
   switch (block._tag) {
     case 'text': {
       if (message.sender.role === 'user') {
-        return `<prompt>${block.text}</prompt>`;
+        if (block.disposition === 'synthetic') {
+          return renderXMLBlock('synthetic', { content: block.text, pending: block.pending });
+        } else {
+          return `\n<prompt>${block.text}</prompt>`;
+        }
       } else {
         const text = block.text.trim();
         if (text.length > 0) {
@@ -159,22 +231,18 @@ const blockToMarkdownImpl = (context: MessageThreadContext, message: Message.Mes
     }
 
     case 'toolCall': {
-      context.updateWidget<{ blocks: ContentBlock.Any[] }>(block.toolCallId, {
-        blocks: [block],
-      });
+      applyToolBlockToWidgetState(context, block);
       return `<toolCall id="${block.toolCallId}" />`;
     }
 
     case 'toolResult': {
       // TODO(dmaretskyi): the parameter could be undefined, perhaps tool blocks are not arriving in order.
-      context.updateWidget<{ blocks: ContentBlock.Any[] }>(block.toolCallId, ({ blocks = [] } = { blocks: [] }) => ({
-        blocks: [...blocks, block],
-      }));
+      applyToolBlockToWidgetState(context, block);
       break;
     }
 
     case 'stats': {
-      return renderXMLBlock('stats', { content: ContentBlock.createStatsMessage(block) });
+      return '';
     }
 
     case 'reasoning': {
@@ -189,6 +257,10 @@ const blockToMarkdownImpl = (context: MessageThreadContext, message: Message.Mes
       return renderXMLBlock('summary', { content: block.content, pending: block.pending });
     }
 
+    case 'status': {
+      return renderXMLBlock('status', { content: block.statusText, pending: block.pending });
+    }
+
     default: {
       // TODO(burdon): Needs stable ID.
       return `<json id="${message.id}">\n${JSON.stringify(block)}\n</json>`;
@@ -196,9 +268,19 @@ const blockToMarkdownImpl = (context: MessageThreadContext, message: Message.Mes
   }
 };
 
+/**
+ * Escape text embedded in generated XML so the mixed XML parser does not treat `&`, `<`, `>` as markup.
+ */
+const escapeXmlTextContent = (raw: string): string =>
+  raw.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
 const renderXMLBlock = (tag: string, opts: { content?: string; pending?: boolean; attributes?: string }) => {
-  // Replace paragraph breaks so that markdown parser does not split the content into multiple paragraphs.
-  const content = (opts.content ?? '').replace(/\n\n/g, ' ').trim();
+  // Replace paragraph breaks so that the markdown parser does not split the content into multiple paragraphs.
+  // NOTE: do not strip leading list-marker prefixes (`-`, `*`, `1. `, ...) per line — the streaming
+  // tag's range is replaced atomically by the XML widget so the inner markdown is never user-visible,
+  // and stripping can collapse a line to empty mid-stream (e.g. when only `1. ` has arrived), breaking
+  // the prefix-extension contract that `MessageSyncer` relies on for incremental appends.
+  const content = escapeXmlTextContent((opts.content ?? '').replace(/\n\n/g, ' ').trim());
 
   if (opts.pending) {
     return `<${tag}${opts.attributes ? ` ${opts.attributes}` : ''}>${content}`;