@dxos/plugin-assistant 0.8.4-main.3c1ae3b → 0.8.4-main.3fbcb4aa9b

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

@@ -6,38 +6,37 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 import * as Fiber from 'effect/Fiber';
 import * as Layer from 'effect/Layer';
-import React, { type CSSProperties, useEffect, useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useState } from 'react';
 
+import { withPluginManager } from '@dxos/app-framework/testing';
 import { Database } from '@dxos/echo';
+import { runAndForwardErrors } from '@dxos/effect';
 import { ContextQueueService } from '@dxos/functions';
-import { faker } from '@dxos/random';
-import { useQueue, useSpace } from '@dxos/react-client/echo';
-import { withClientProvider } from '@dxos/react-client/testing';
-import { Popover } from '@dxos/react-ui';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import { MarkdownStream } from '@dxos/react-ui-components';
-import { EditorPreviewProvider, useEditorPreview } from '@dxos/react-ui-editor';
-import { Card } from '@dxos/react-ui-stack';
-import { render } from '@dxos/storybook-utils';
-import { type Message, Organization, Person } from '@dxos/types';
-
-import { createMessageGenerator } from '../../testing';
-import { translations } from '../../translations';
+import { ClientPlugin } from '@dxos/plugin-client/plugin';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { PreviewPlugin } from '@dxos/plugin-preview/testing';
+import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { type Queue, useSpaces } from '@dxos/react-client/echo';
+import { EditorPreviewProvider } from '@dxos/react-ui-editor';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Message, Organization, Person } from '@dxos/types';
+
+import { createMessageGenerator } from '#testing';
+import { translations } from '#translations';
 
 import { ChatThread, type ChatThreadProps } from './ChatThread';
-import { componentRegistry } from './registry';
-import TEXT from './testing/thread.md?raw';
 
-faker.seed(1);
+random.seed(1);
 
 type MessageGenerator = Effect.Effect<void, never, Database.Service | ContextQueueService>;
 
-type StoryProps = { generator?: MessageGenerator[]; delay?: number; wait?: boolean } & ChatThreadProps;
+type DefaultStoryProps = { generator?: MessageGenerator[]; delay?: number; wait?: boolean } & ChatThreadProps;
 
-const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: StoryProps) => {
-  const space = useSpace();
-  const queueDxn = useMemo(() => space?.queues.create().dxn, [space]);
-  const queue = useQueue<Message.Message>(queueDxn);
+const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: DefaultStoryProps) => {
+  const [space] = useSpaces();
+  const queue = useMemo<Queue<Message.Message> | undefined>(() => space?.queues.create(), [space]);
+  const messages = useQueueMessages(queue);
   const [done, setDone] = useState(false);
 
   // Generate messages.
@@ -54,67 +53,75 @@ const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: StoryProps)
             yield* Effect.sleep(delay);
           }
         }
+
         setDone(true);
-      }).pipe(Effect.provide(Layer.mergeAll(Database.Service.layer(space.db), ContextQueueService.layer(queue)))),
+      }).pipe(Effect.provide(Layer.mergeAll(Database.layer(space.db), ContextQueueService.layer(queue)))),
     );
 
     return () => {
-      void Effect.runPromise(Fiber.interrupt(fiber));
+      void runAndForwardErrors(Fiber.interrupt(fiber));
     };
-  }, [space, queue, generator]);
+  }, [space, queue, generator, delay]);
 
   if (wait && !done) {
-    return null;
+    return <Loading data={{ wait, done }} />;
   }
 
   return (
-    <EditorPreviewProvider onLookup={async ({ label, ref }) => ({ label, text: ref })}>
-      <ChatThread {...props} messages={queue?.objects} />
-      <PreviewCard />
+    <EditorPreviewProvider onLookup={async ({ dxn, label }) => ({ label, text: dxn })}>
+      <ChatThread {...props} messages={messages} />
     </EditorPreviewProvider>
   );
 };
 
-const PreviewCard = () => {
-  const { target } = useEditorPreview('PreviewCard');
+const useQueueMessages = (queue?: Queue<Message.Message>) => {
+  const [messages, setMessages] = useState<Message.Message[]>([]);
 
-  return (
-    <Popover.Portal>
-      <Popover.Content onOpenAutoFocus={(event) => event.preventDefault()}>
-        <Popover.Viewport>
-          <Card.SurfaceRoot role='card--popover'>
-            <Card.Heading>{target?.label}</Card.Heading>
-            {target && <Card.Text classNames='truncate line-clamp-3'>{target.text}</Card.Text>}
-          </Card.SurfaceRoot>
-        </Popover.Viewport>
-        <Popover.Arrow />
-      </Popover.Content>
-    </Popover.Portal>
-  );
+  useEffect(() => {
+    if (!queue) {
+      setMessages([]);
+      return;
+    }
+
+    const update = () => setMessages([...queue.objects]);
+    update();
+    return queue.subscribe(update);
+  }, [queue]);
+
+  return messages;
 };
 
 const meta = {
-  title: 'plugins/plugin-assistant/ChatThread',
+  title: 'plugins/plugin-assistant/components/ChatThread',
   component: ChatThread,
-  render: render(DefaultStory),
+  render: DefaultStory,
   decorators: [
-    withTheme,
-    withLayout({ container: 'column' }),
-    withClientProvider({
-      createIdentity: true,
-      createSpace: true,
-      types: [Organization.Organization, Person.Person],
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        StorybookPlugin({}),
+        PreviewPlugin(),
+        ClientPlugin({
+          types: [Organization.Organization, Person.Person],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              yield* initializeIdentity(client);
+            }),
+        }),
+      ],
     }),
   ],
   parameters: {
     layout: 'fullscreen',
     translations,
   },
-} satisfies Meta<StoryProps>;
+} satisfies Meta<DefaultStoryProps>;
 
 export default meta;
 
-type Story = StoryObj<StoryProps>;
+type Story = StoryObj<DefaultStoryProps>;
 
 export const Default: Story = {
   args: {
@@ -126,24 +133,11 @@ export const Default: Story = {
 export const Delayed: Story = {
   args: {
     generator: createMessageGenerator(),
-    delay: 1_000,
-    fadeIn: true,
-    cursor: false,
+    delay: 500,
+    options: {
+      autoScroll: true,
+      typewriter: true,
+      cursor: true,
+    },
   },
 };
-
-export const Raw: Story = {
-  render: () => (
-    <div className='contents' style={{ '--user-fill': 'var(--dx-amberFill)' } as CSSProperties}>
-      <MarkdownStream content={TEXT} />
-    </div>
-  ),
-};
-
-export const Static: Story = {
-  render: () => (
-    <div className='contents' style={{ '--user-fill': 'var(--dx-amberFill)' } as CSSProperties}>
-      <MarkdownStream content={TEXT} registry={componentRegistry} />
-    </div>
-  ),
-};

package/src/components/ChatThread/ChatThread.tsx

@@ -2,38 +2,61 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type CSSProperties, forwardRef, useCallback, useEffect, useMemo } 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, useForwardedRef } from '@dxos/react-ui';
-import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-components';
-import { mx } from '@dxos/react-ui-theme';
+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';
 
+const defaultOptions: MarkdownStreamProps['options'] = {
+  autoScroll: true,
+  cursor: false,
+  fader: false,
+  typewriter: true,
+};
+
 export type ChatThreadProps = ThemedClassName<
   {
     identity?: Identity;
     messages?: Message.Message[];
     error?: Error;
+    viewType?: Assistant.ChatView;
     onEvent?: (event: ChatEvent) => void;
-  } & Pick<MarkdownStreamProps, 'cursor' | 'fadeIn' | 'debug'>
+  } & Pick<MarkdownStreamProps, 'options' | 'debug' | 'extensions' | 'footer'>
 >;
 
-// TODO(burdon): Memo thread position.
-export const ChatThread = forwardRef<MarkdownStreamController, ChatThreadProps>(
+export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThreadProps>(
   (
-    { classNames, identity, messages = [], error, cursor = false, fadeIn = true, debug = false, onEvent },
+    {
+      classNames,
+      identity,
+      messages = [],
+      error,
+      options = defaultOptions,
+      footer,
+      debug = false,
+      extensions,
+      viewType,
+      onEvent,
+    },
     forwardedRef,
   ) => {
-    const controllerRef = useForwardedRef(forwardedRef);
-    const controller = controllerRef.current;
+    const [controller, setController] = useState<MarkdownStreamController | null>(null);
+    const handleMarkdownStreamRef = useCallback(
+      (instance: MarkdownStreamController | null) => {
+        setController(instance);
+        setRef(forwardedRef, instance);
+      },
+      [forwardedRef],
+    );
 
     const userHue = useMemo(
       () => identity?.profile?.data?.hue || keyToFallback(identity?.identityKey ?? PublicKey.random()).hue,
@@ -46,13 +69,17 @@ export const ChatThread = forwardRef<MarkdownStreamController, ChatThreadProps>(
     }, [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');
       }
-    }, [syncer, messages]);
+    }, [controller, syncer, messages]);
 
     // Event adapter.
     const handleEvent = useCallback<NonNullable<MarkdownStreamProps['onEvent']>>(
@@ -68,18 +95,17 @@ export const ChatThread = forwardRef<MarkdownStreamController, ChatThreadProps>(
     );
 
     return (
-      <div
-        role='none'
-        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={controllerRef}
+          key={viewType}
+          classNames={classNames}
           registry={componentRegistry}
-          cursor={cursor}
-          fadeIn={fadeIn}
+          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,7 +5,7 @@
 import React, { useMemo } from 'react';
 
 import { type Space } from '@dxos/client/echo';
-import { Obj } from '@dxos/echo';
+import { Entity } from '@dxos/echo';
 import { type DXN } from '@dxos/keys';
 import { DxAnchor } from '@dxos/lit-ui/react';
 
@@ -17,9 +17,9 @@ export type ObjectLinkProps = {
 export const ObjectLink = ({ space, dxn }: ObjectLinkProps) => {
   const ref = useMemo(() => space.db.makeRef(dxn), [space, dxn.toString()]);
 
-  const title = (ref.target && Obj.getLabel(ref.target)) ?? ref.target?.id ?? ref.dxn.toString();
+  const title = (ref.target && Entity.getLabel(ref.target)) ?? ref.target?.id ?? ref.dxn.toString();
   return (
-    <DxAnchor rootclassname='dx-tag--anchor' refid={dxn.toString()}>
+    <DxAnchor rootclassname='dx-tag--anchor' dxn={dxn.toString()}>
       {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,
+    },
+  },
+};