@dxos/plugin-assistant 0.8.4-main.406dc2a → 0.8.4-main.4668b7de9b

package/src/components/ChatThread/ChatThread.tsx

@@ -2,75 +2,100 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, {
-  type CSSProperties,
-  forwardRef,
-  useCallback,
-  useEffect,
-  useImperativeHandle,
-  useMemo,
-  useState,
-} from 'react';
+import React, { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { PublicKey } from '@dxos/keys';
 import { type Identity } from '@dxos/react-client/halo';
-import { type ThemedClassName } from '@dxos/react-ui';
-import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-components';
-import { mx } from '@dxos/react-ui-theme';
-import { type DataType } from '@dxos/schema';
+import { type ThemedClassName, setRef } from '@dxos/react-ui';
+import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-markdown';
+import { type Message } from '@dxos/types';
 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';
 
-export type ChatThreadController = Pick<MarkdownStreamController, 'setContext' | 'scrollToBottom'>;
+const defaultOptions: MarkdownStreamProps['options'] = {
+  autoScroll: true,
+  cursor: false,
+  fader: false,
+  typewriter: true,
+};
 
 export type ChatThreadProps = ThemedClassName<
   {
     identity?: Identity;
-    messages?: DataType.Message[];
+    messages?: Message.Message[];
     error?: Error;
-    overscroll?: number;
+    viewType?: Assistant.ChatView;
     onEvent?: (event: ChatEvent) => void;
-  } & Pick<MarkdownStreamProps, 'cursor' | 'fadeIn' | 'overscroll'>
+  } & Pick<MarkdownStreamProps, 'options' | 'debug' | 'extensions' | 'footer'>
 >;
 
-export const ChatThread = forwardRef<ChatThreadController | null, ChatThreadProps>(
+export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThreadProps>(
   (
-    { classNames, identity, messages = [], error, cursor = false, fadeIn = true, overscroll, onEvent },
+    {
+      classNames,
+      identity,
+      messages = [],
+      error,
+      options = defaultOptions,
+      footer,
+      debug = false,
+      extensions,
+      viewType,
+      onEvent,
+    },
     forwardedRef,
   ) => {
-    const userHue = useMemo(() => {
-      return identity?.profile?.data?.hue || keyToFallback(identity?.identityKey ?? PublicKey.random()).hue;
-    }, [identity]);
-
-    // Expose controller.
     const [controller, setController] = useState<MarkdownStreamController | null>(null);
-    useImperativeHandle(forwardedRef, () => (controller ? controller : (null as any)), [controller]);
+    const handleMarkdownStreamRef = useCallback(
+      (instance: MarkdownStreamController | null) => {
+        setController(instance);
+        setRef(forwardedRef, instance);
+      },
+      [forwardedRef],
+    );
 
-    // Show error.
+    const userHue = useMemo(
+      () => identity?.profile?.data?.hue || keyToFallback(identity?.identityKey ?? PublicKey.random()).hue,
+      [identity],
+    );
+
+    // Jump to the bottom instantly when the thread first mounts (e.g. opening the companion);
+    // smooth-scroll only on subsequent error changes.
+    const initializedRef = useRef(false);
     useEffect(() => {
-      controller?.scrollToBottom();
+      if (!controller) {
+        // MarkdownStream is keyed by viewType; switching views replaces the controller. Reset so
+        // the first scroll for the new controller is instant rather than animated.
+        initializedRef.current = false;
+        return;
+      }
+      controller.scrollToBottom(initializedRef.current ? 'smooth' : 'instant');
+      initializedRef.current = true;
     }, [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(() => {
-      syncer?.sync(messages);
-    }, [syncer, messages]);
+      if (!syncer) {
+        return;
+      }
+
+      if (syncer.update(messages)) {
+        controller?.scrollToBottom('instant');
+      }
+    }, [controller, syncer, messages]);
 
-    // Event handler.
+    // Event adapter.
     const handleEvent = useCallback<NonNullable<MarkdownStreamProps['onEvent']>>(
-      (ev) => {
-        switch (ev.type) {
+      ({ type, value }) => {
+        switch (type) {
           case 'submit': {
-            ev.value &&
-              onEvent?.({
-                type: 'submit',
-                text: ev.value,
-              });
+            value && onEvent?.({ type, text: value });
             break;
           }
         }
@@ -79,17 +104,17 @@ export const ChatThread = forwardRef<ChatThreadController | null, ChatThreadProp
     );
 
     return (
-      <div
-        className={mx('flex bs-full is-full justify-center overflow-hidden', classNames)}
-        style={{ '--user-fill': `var(--dx-${userHue}Fill)` } as CSSProperties}
-      >
+      <div data-hue={userHue} className='contents'>
         <MarkdownStream
-          ref={setController}
+          key={viewType}
+          classNames={classNames}
           registry={componentRegistry}
-          cursor={cursor}
-          fadeIn={fadeIn}
-          overscroll={overscroll}
+          options={options}
+          debug={debug}
+          extensions={extensions}
+          footer={footer}
           onEvent={handleEvent}
+          ref={handleMarkdownStreamRef}
         />
       </div>
     );

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/Link.tsx

@@ -5,21 +5,21 @@
 import React, { useMemo } from 'react';
 
 import { type Space } from '@dxos/client/echo';
-import { Obj } from '@dxos/echo';
-import { type DXN } from '@dxos/keys';
+import { Entity } from '@dxos/echo';
+import { type URI } from '@dxos/keys';
 import { DxAnchor } from '@dxos/lit-ui/react';
 
 export type ObjectLinkProps = {
   space: Space;
-  dxn: DXN;
+  dxn: URI.URI;
 };
 
 export const ObjectLink = ({ space, dxn }: ObjectLinkProps) => {
-  const ref = useMemo(() => space.db.ref(dxn), [space, dxn.toString()]);
+  const ref = useMemo(() => space.db.makeRef(dxn), [space, dxn]);
 
-  const title = Obj.getLabel(ref.target) ?? ref.target?.id ?? ref.dxn.toString();
+  const title = (ref.target && Entity.getLabel(ref.target)) ?? ref.target?.id ?? ref.uri;
   return (
-    <DxAnchor rootclassname='dx-tag--anchor' refid={dxn.toString()}>
+    <DxAnchor rootclassname='dx-tag--anchor' dxn={dxn}>
       {title}
     </DxAnchor>
   );

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,
+    },
+  },
+};