@dxos/plugin-assistant 0.8.4-main.fd6878d → 0.9.0

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

@@ -0,0 +1,290 @@
+//
+// 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,
+  ReasoningWidget,
+  ReferenceWidget,
+  SelectWidget,
+  SuggestionWidget,
+  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 = {
+  //
+  // Block-only (no widget — see note above).
+  //
+
+  prompt: {
+    block: true,
+  },
+
+  //
+  // DOM Widgets
+  //
+
+  synthetic: {
+    block: true,
+    factory: ({ children, range }) => {
+      const text = getXmlTextChild(children);
+      // 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: {
+    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 }) => {
+      const text = getXmlTextChild(children);
+      return text ? new StatusWidget(text) : null;
+    },
+  },
+
+  //
+  // React Widgets (portaled outside of the editor)
+  //
+
+  summary: {
+    block: true,
+    Component: SummaryWidget,
+  },
+  toolCall: {
+    block: true,
+    Component: (props) => (
+      <div 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 = 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,
+): 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;
+  }
+};
+
+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') {
+        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) {
+          return text;
+        }
+      }
+      break;
+    }
+
+    case 'reference': {
+      if (block.pending) {
+        return;
+      }
+      const dxn = block.reference.uri;
+      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;');
+
+const renderXMLBlock = (tag: string, opts: { content?: string; pending?: boolean; attributes?: string }) => {
+  // 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}`;
+  } else {
+    return `<${tag}${opts.attributes ? ` ${opts.attributes}` : ''}>${content}</${tag}>`;
+  }
+};