@dxos/plugin-assistant 0.8.4-main.f5c0578 → 0.8.4-main.fcfe5033a5

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

@@ -0,0 +1,243 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useEffect, useState, type CSSProperties } 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-components';
+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 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 style={{ '--user-fill': `var(--color-${userHue}-fill)` } as CSSProperties}>
+      <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,
+      wire: 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,
+    },
+  },
+};

package/src/components/ChatThread/registry.tsx

@@ -0,0 +1,238 @@
+//
+// 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 BlockRenderer, type MessageThreadContext } from './sync';
+import { applyToolBlockToWidgetState } from './tool-widget-state';
+import {
+  FallbackWidget,
+  PromptWidget,
+  ReasoningWidget,
+  ReferenceWidget,
+  SelectWidget,
+  SuggestionWidget,
+  StatsWidget,
+  SummaryWidget,
+  ToolWidget,
+  StatusWidget,
+} from './widgets';
+
+/**
+ * Custom XML tags registry.
+ */
+export const componentRegistry: XmlWidgetRegistry = {
+  //
+  // DOM Widgets
+  //
+
+  prompt: {
+    block: true,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children);
+      return text ? new PromptWidget(text) : null;
+    },
+  },
+  reasoning: {
+    block: true,
+    streaming: true,
+    factory: ({ children, range }) => {
+      const text = getXmlTextChild(children);
+      return text ? new ReasoningWidget(text, range.from) : null;
+    },
+  },
+  reference: {
+    block: false,
+    factory: ({ children, ref }) => {
+      const text = getXmlTextChild(children);
+      return text && ref ? new ReferenceWidget(text, ref) : null;
+    },
+  },
+  select: {
+    block: true,
+    factory: ({ children }) => {
+      const options = children
+        ?.map((option: any) => option._tag === 'option' && getXmlTextChild(option.children))
+        .filter(Boolean);
+      return options?.length ? new SelectWidget(options) : null;
+    },
+  },
+  suggestion: {
+    block: true,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children);
+      return text ? new SuggestionWidget(text) : null;
+    },
+  },
+  stats: {
+    block: true,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children);
+      return text ? new StatsWidget(text) : null;
+    },
+  },
+  status: {
+    block: true,
+    streaming: true,
+    factory: ({ children, range }) => {
+      const text = getXmlTextChild(children);
+      return text ? new StatusWidget(text, range.from) : null;
+    },
+  },
+
+  //
+  // React Widgets (portaled outside of the editor)
+  //
+
+  summary: {
+    block: true,
+    Component: SummaryWidget,
+  },
+  toolCall: {
+    block: true,
+    Component: (props) => (
+      <div role='none' className='py-2'>
+        <ToolWidget {...props} />
+      </div>
+    ),
+  },
+  toolResult: {
+    block: true,
+    Component: FallbackWidget,
+  },
+  toolkit: {
+    block: true,
+    Component: FallbackWidget,
+  },
+
+  //
+  // Fallback
+  //
+
+  json: {
+    block: true,
+    Component: FallbackWidget,
+  },
+};
+
+/**
+ * Convert block to markdown.
+ */
+export const blockToMarkdown: BlockRenderer = (
+  context: MessageThreadContext,
+  message: Message.Message,
+  block: ContentBlock.Any,
+) => {
+  let str = blockToMarkdownImpl(context, message, block);
+  if (str && !block.pending) {
+    return (str += '\n');
+  }
+
+  return str;
+};
+
+const blockToMarkdownImpl = (context: MessageThreadContext, message: Message.Message, block: ContentBlock.Any) => {
+  log('blockToMarkdown', { block: JSON.stringify(block) });
+  switch (block._tag) {
+    case 'text': {
+      if (message.sender.role === 'user') {
+        return `<prompt>${block.text}</prompt>`;
+      } else {
+        const text = block.text.trim();
+        if (text.length > 0) {
+          return text;
+        }
+      }
+      break;
+    }
+
+    case 'reference': {
+      if (block.pending) {
+        return;
+      }
+      const dxn = block.reference.dxn;
+      return `<reference ref="${dxn.toString()}">${context.getObjectLabel(dxn)}</reference>`;
+    }
+
+    case 'suggestion': {
+      if (block.pending) {
+        return;
+      }
+      return `<suggestion>${block.text}</suggestion>`;
+    }
+
+    case 'select': {
+      if (block.pending || block.options.length === 0) {
+        return;
+      }
+      return `<select>${block.options.map((option) => `<option>${option}</option>`).join('')}</select>`;
+    }
+
+    case 'toolCall': {
+      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.
+      applyToolBlockToWidgetState(context, block);
+      break;
+    }
+
+    case 'stats': {
+      return '';
+    }
+
+    case 'reasoning': {
+      let text = block.reasoningText ?? block.redactedText;
+      if (!text) {
+        return;
+      }
+      return renderXMLBlock('reasoning', { content: text, pending: block.pending });
+    }
+
+    case 'summary': {
+      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>`;
+    }
+  }
+};
+
+/**
+ * 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;');
+
+/**
+ * Strip actual list-marker prefixes without removing meaningful leading content.
+ */
+const stripBulletLikeLinePrefixes = (raw: string): string =>
+  raw
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^\s*(?:[-*+•]|\d+[.)]\s)/, ''))
+    .join('\n');
+
+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 = escapeXmlTextContent(stripBulletLikeLinePrefixes((opts.content ?? '').replace(/\n\n/g, ' ').trim()));
+
+  if (opts.pending) {
+    return `<${tag}${opts.attributes ? ` ${opts.attributes}` : ''}>${content}`;
+  } else {
+    return `<${tag}${opts.attributes ? ` ${opts.attributes}` : ''}>${content}</${tag}>`;
+  }
+};

package/src/components/ChatThread/sync.test.ts

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorView } from '@codemirror/view';
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Obj } from '@dxos/echo';
+import { type Mutable } from '@dxos/echo/internal';
+import { type ContentBlock } from '@dxos/types';
+
+import { createMessage } from '#testing';
+
+import { blockToMarkdown } from './registry';
+import { MessageSyncer, type TextModel } from './sync';
+
+class TestDocument implements TextModel {
+  private readonly _view = new EditorView({ extensions: [] });
+
+  get length() {
+    return this._view.state.doc.length;
+  }
+
+  get content() {
+    return this._view.state.doc.toString();
+  }
+
+  async setContent(text: string) {
+    this._view.dispatch({
+      changes: { from: 0, to: this._view.state.doc.length, insert: text },
+    });
+  }
+
+  async append(text: string) {
+    this._view.dispatch({
+      changes: { from: this._view.state.doc.length, insert: text },
+    });
+  }
+
+  updateWidget(_id: string, _value: any) {}
+}
+
+describe('reducers', () => {
+  it.effect(
+    'basic sync',
+    Effect.fn(function* ({ expect }) {
+      const doc = new TestDocument();
+      const syncer = new MessageSyncer(doc, blockToMarkdown);
+
+      const messages = [
+        createMessage('user', [{ _tag: 'text', text: 'Hello' }]),
+        createMessage('assistant', [{ _tag: 'text', text: 'Hi there!' }]),
+      ];
+
+      syncer.append(messages);
+      expect(doc.content).toEqual(['<prompt>Hello</prompt>', 'Hi there!', ''].join('\n'));
+
+      Obj.change(messages[1], (obj) => {
+        obj.blocks.push({ _tag: 'text', text: 'How can I help?' });
+      });
+      syncer.append(messages);
+      expect(doc.content).toEqual(['<prompt>Hello</prompt>', 'Hi there!', 'How can I help?', ''].join('\n'));
+    }),
+  );
+
+  it.effect(
+    'sync with partial updates',
+    Effect.fn(function* ({ expect }) {
+      const doc = new TestDocument();
+      const syncer = new MessageSyncer(doc, blockToMarkdown);
+
+      const messages = [
+        createMessage('user', [{ _tag: 'text', text: 'Hello' }]),
+        createMessage('assistant', [{ _tag: 'text', text: 'Hi there!', pending: true }]),
+      ];
+
+      syncer.append(messages);
+      expect(doc.content).toEqual(['<prompt>Hello</prompt>', 'Hi there!'].join('\n'));
+
+      Obj.change(messages[1], (obj) => {
+        const block = obj.blocks[0] as Mutable<ContentBlock.Text>;
+        block.text = 'Hi there! How are you?';
+        block.pending = false;
+      });
+      syncer.append(messages);
+
+      Obj.change(messages[1], (obj) => {
+        obj.blocks.push({ _tag: 'text', text: 'How can I help?' });
+      });
+      syncer.append(messages);
+      expect(doc.content).toEqual(
+        ['<prompt>Hello</prompt>', 'Hi there! How are you?', 'How can I help?', ''].join('\n'),
+      );
+    }),
+  );
+});