@dxos/plugin-assistant 0.8.4-main.c85a9c8dae → 0.8.4-main.dfabb4ec29

package/src/components/ChatThread/sync.ts

@@ -3,15 +3,31 @@
 //
 
 import { type DXN } from '@dxos/echo';
-import { log } from '@dxos/log';
-import { type MarkdownStreamController } from '@dxos/react-ui-components';
+import { type MarkdownStreamController } from '@dxos/react-ui-markdown';
 import { type ContentBlock, type Message } from '@dxos/types';
 import { type StateDispatch, type XmlWidgetStateManager } from '@dxos/ui-editor';
 
+import { rehydrateToolWidgetsFromMessages } from './tool-widget-state';
+
 /**
  * Update document.
  */
-export type TextModel = Pick<MarkdownStreamController, 'view' | 'reset' | 'append' | 'updateWidget'>;
+export type TextModel = Pick<MarkdownStreamController, 'length' | 'setContent' | 'append' | 'updateWidget'>;
+
+/**
+ * Renders a block to markdown.
+ *
+ * Contract: for any block whose lifetime spans multiple invocations (i.e. a streaming block
+ * with `pending: true` whose content grows over time, transitioning to `pending: false`), the
+ * sequence of returned strings must be monotonically extending — each subsequent value must be
+ * a string-extension of the previous. The {@link MessageSyncer} relies on this invariant to
+ * compute appendable deltas without diffing.
+ */
+export type BlockRenderer = (
+  context: MessageThreadContext,
+  message: Message.Message,
+  block: ContentBlock.Any,
+) => string | undefined;
 
 /**
  * Thread context passed to renderer.
@@ -23,138 +39,112 @@ export class MessageThreadContext implements Pick<MarkdownStreamController, 'upd
     this._widgetState?.updateWidget(id, value);
   }
 
-  // TODO(burdon): Resolve from hypergraph.
+  // TODO(burdon): Resolve name from hypergraph.
   getObjectLabel(_id: DXN) {
     return 'Object';
   }
 }
 
-/**
- * Renders a block to markdown.
- */
-export type BlockRenderer = (
-  context: MessageThreadContext,
-  message: Message.Message,
-  block: ContentBlock.Any,
-) => string | undefined;
-
 /**
  * Syncs messages with the editor.
+ *
+ * Reflects the AI streaming contract:
+ * - Messages and their blocks are appended in order.
+ * - Only the last block in `messages` may be `pending`; all earlier blocks are finalized.
+ * - The renderer's output for a streaming block grows monotonically (see {@link BlockRenderer}).
+ * - The document is read-only outside this syncer.
+ *
+ * Under those rules the syncer needs only:
+ * - `_completed`: the flat-block index past which everything has been fully appended.
+ * - `_trailing`: chars of the in-flight block (at index `_completed`) already appended.
+ * - `_threadId`: identity sentinel; if `messages[0]?.id` changes, the document is replaced.
  */
 export class MessageSyncer {
-  private _initialMessageId?: string;
-  private _currentMessageIndex = 0;
-  private _currentBlockIndex = 0;
-  private _currentBlockContent?: string;
+  private _threadId?: string;
+  private _completed = 0;
+  private _trailing = 0;
 
   private readonly _context: MessageThreadContext;
 
   constructor(
-    private readonly _model: TextModel,
-    private readonly _blockRenderer: BlockRenderer,
+    private readonly _document: TextModel,
+    private readonly _renderer: BlockRenderer,
   ) {
-    this._context = new MessageThreadContext(this._model);
+    this._context = new MessageThreadContext(this._document);
   }
 
   get context() {
     return this._context;
   }
 
-  reset() {
-    log('reset');
-    this._initialMessageId = undefined;
-    this._currentMessageIndex = 0;
-    this._currentBlockIndex = 0;
-    this._currentBlockContent = undefined;
-    void this._model.reset('');
+  /**
+   * Replace the document with the rendering of `messages`. Use on mount, on thread switch,
+   * and from {@link update} when it detects an identity change in `messages[0]`.
+   */
+  reset(messages: Message.Message[] = []): void {
+    this._threadId = messages[0]?.id;
+    this._completed = 0;
+    this._trailing = 0;
+    const buffer = this._walk(messages);
+    // Match the pre-rewrite behaviour: rendering from a steady state (initial mount with
+    // non-empty messages, or thread switch) lands the entire content via `setContent` — which
+    // uses `wireBypass`, so the editor jumps straight to the final text and `update()` returns
+    // `true` so the caller can scroll to the bottom. Live streaming partials that arrive
+    // *after* this initial render flow through `update()`'s incremental path → `_document.append`
+    // → wire's drip filter, preserving the char-by-char typewriter for incoming text.
+    void this._document.setContent(buffer).then(() => {
+      rehydrateToolWidgetsFromMessages(this._context, messages);
+    });
   }
 
   /**
-   * Syncs messages with the editor.
+   * Stream the suffix of the rendered messages into the document.
+   * Returns `true` if the document was replaced (initial mount or thread switch), `false`
+   * if the call was a streaming append (or a no-op).
    */
-  append(messages: Message.Message[], flush = false): boolean {
-    // TODO(dmaretskyi): MarkdownStream currently does not support streaming XML tags, so we need to remove pending non-text blocks.
-    messages = messages.map((message) => ({
-      ...message,
-      blocks: message.blocks.filter((block) => !block.pending || block._tag === 'text'),
-    }));
-
-    // Check if new set of messages.
-    if (this._initialMessageId !== messages[0]?.id) {
-      this.reset();
-      this._initialMessageId = messages[0]?.id;
-    }
-
-    if (flush && this._model.view?.state.doc.length === 0) {
-      const buffer: string[] = [];
-      this.process(messages, (content) => {
-        buffer.push(content);
-      });
-
-      const content = buffer.join('');
-      this._model.view?.dispatch({
-        changes: [
-          {
-            from: 0,
-            to: this._model.view?.state.doc.length ?? 0,
-            insert: content,
-          },
-        ],
-        selection: { anchor: content.length },
-      });
-
+  update(messages: Message.Message[]): boolean {
+    if (messages[0]?.id !== this._threadId) {
+      this.reset(messages);
       return true;
-    } else {
-      this.process(messages, (content) => {
-        void this._model.append(content);
-      });
-
-      return false;
     }
+    const buffer = this._walk(messages);
+    if (buffer.length > 0) {
+      void this._document.append(buffer);
+    }
+    return false;
   }
 
-  private process(messages: Message.Message[], append: (content: string) => void) {
-    // console.log('sync', {
-    //   doc: this._model.view?.state.doc.length,
-    //   messages: messages.map((message) => message.blocks.length),
-    //   currentMessageIndex: this._currentMessageIndex,
-    //   currentBlockIndex: this._currentBlockIndex,
-    //   currentBlockContent: this._currentBlockContent,
-    // });
-
-    let i = this._currentMessageIndex;
-    for (const message of messages.slice(this._currentMessageIndex)) {
-      if (i > this._currentMessageIndex) {
-        this._currentBlockIndex = 0;
-      }
-
-      this._currentMessageIndex = i;
-      let j = this._currentBlockIndex;
-      for (const block of message.blocks.slice(this._currentBlockIndex)) {
-        this._currentBlockIndex = j;
-        const currentBlockContent = this._blockRenderer(this._context, message, block);
-        if (currentBlockContent) {
-          let content: string = '';
-          if (this._currentBlockContent && currentBlockContent.startsWith(this._currentBlockContent)) {
-            content = currentBlockContent.slice(this._currentBlockContent.length);
-          } else {
-            content = currentBlockContent;
-          }
-
-          // console.log('append', { message: i, block: j, content });
-          this._currentBlockContent = currentBlockContent;
-          append(content);
+  /**
+   * Walk flat blocks starting at `_completed`, advancing the cursors and returning the chars
+   * to append. Blocks before `_completed` are skipped — their renderer is never re-invoked,
+   * which preserves single-shot side effects (e.g. tool widget state mutation).
+   */
+  _walk(messages: Message.Message[]): string {
+    let buffer = '';
+    let index = 0;
+    outer: for (const message of messages) {
+      for (const block of message.blocks) {
+        if (index < this._completed) {
+          index++;
+          continue;
+        }
+        const rendered = this._renderer(this._context, message, block) ?? '';
+        if (rendered.length > this._trailing) {
+          buffer += rendered.slice(this._trailing);
         }
-
         if (block.pending) {
-          return;
-        } else {
-          this._currentBlockContent = undefined;
-          this._currentBlockIndex++;
+          // Stay on this block; record how far we've appended so the next call can resume.
+          // `Math.max`-style guard against a non-monotonic renderer output without shrinking the doc.
+          if (rendered.length > this._trailing) {
+            this._trailing = rendered.length;
+          }
+          break outer;
         }
-        j++;
+        this._completed = index + 1;
+        this._trailing = 0;
+        index++;
       }
-      i++;
     }
+    return buffer;
   }
 }

package/src/components/ChatThread/testing/reasoning.md

@@ -0,0 +1,25 @@
+<prompt>How should I structure a CLI tool with subcommands?</prompt>
+
+<reasoning>
+The user is asking about CLI subcommand structure. Let me think through what they likely care about:
+
+1. Discoverability — every subcommand needs help text and a flat top-level listing.
+2. Composability — subcommands should be invokable individually for scripting.
+3. Shared concerns — auth, config, logging should not be duplicated per command.
+
+A few patterns worth considering:
+
+- A single binary that dispatches to subcommand handlers (like `git`, `kubectl`).
+- A plugin model where subcommands live in separate binaries on the PATH (like `git-foo`).
+- A library that each subcommand wraps as a thin executable.
+
+The plugin model wins for very large surfaces but adds packaging cost. For a tool with under ~30 subcommands the dispatcher pattern stays clearer.
+</reasoning>
+
+For a CLI with a moderate set of subcommands, the dispatcher pattern is usually the right default:
+
+1. One binary, one entry point.
+2. Subcommands registered as handlers off a shared root.
+3. Cross-cutting concerns (auth, config, logging) wired in at the root and inherited.
+
+If you grow past ~30 subcommands or want third-party extensions, switch to a plugin model where binaries named `<tool>-<subcommand>` are discovered on the `PATH`.

package/src/components/ChatThread/testing/thinking.md

@@ -0,0 +1,21 @@
+<prompt>create a project to track what I order online based on my emails, dont asak me questions</prompt>
+<reasoning>The user wants me to create a project that tracks their online orders based on emails. They don't want me to ask questions - just go ahead and create it. Let me first get the project rules and query for available mailboxes/inboxes.</reasoning>
+<status>Getting the project rules and finding your mailboxes to set this up...</status>
+<toolCall id="toolu_01QJcUw8RZDyemLdvMe8nSGZ" />
+<toolCall id="toolu_01JJZrCc17JqV5r36aR9wcaj" />
+<toolCall id="toolu_012r3VQFxvWZ9UmKxMNiJP48" />
+<reasoning>The mailbox query failed. Let me try a different approach to find mailboxes. Let me also enable the inbox blueprint to find mailboxes, and create the Order schema first. Let me first search for mailboxes with a different query approach.</reasoning>
+<status>Looking for your mailboxes...</status>
+<toolCall id="toolu_01P4ekwYwYJfxUnGFPHNhcCu" />
+<toolCall id="toolu_017NHbtinMDcjmwqN6vLaNQp" />
+<reasoning>I found the mailbox with DXN `dxn:echo:B6ON2Y6HN4KLJWZD75VUUDCUQ552ERQSG:01KNHKXSWWCBZX6TCPMF1M0PDE`. Now I need to: 1. Create an Order schema for tracking online orders 2. Create the project with the right blueprints and subscriptions Let me first create the Order schema, then create the project.</reasoning>
+<status>Found your mailbox. Now creating an Order schema and setting up the project...</status>
+<toolCall id="toolu_01Gk4RcfdB4ttzsVN9mnatWn" />
+<status>Order schema created. Now creating the project...</status>
+<toolCall id="toolu_01QmJcua6jmRx15wnxo5bkNQ" />
+<reasoning>The service isn't available. Let me try again.</reasoning>
+<status>Encountered a temporary service issue. Retrying...</status>
+<toolCall id="toolu_01X4CVxXuBjgW2JESGUEsm6f" />
+<reasoning>The service seems to be temporarily unavailable. Let me try once more.</reasoning>
+<toolCall id="toolu_01S9vi1pMnwqUuxNpe5FU731" />
+Got the project created. Let me know if you need anything else.

package/src/components/ChatThread/testing/thread-1.md

@@ -0,0 +1,30 @@
+<prompt>What is markdown?</prompt>
+
+<reasoning>
+The user is asking me to think deeply about what markdown is.
+
+But given the context of our conversation - we've been trying to scrape slab data from a website - I think they might be hinting at something specific.
+</reasoning>
+
+### Markdown
+
+Markdown is a lightweight markup language used to format plain text in a simple and readable way.
+
+It allows you to create structured documents using conventions for headings, lists, emphasis (bold/italic), links, images, code, blockquotes, tables, and horizontal rules.
+
+Markdown documents look like this
+
+```
+# Markdown
+
+This is a plain text.
+```
+
+Composer supports extended components via XML tags.
+
+<summary>
+The user asked about Markdown.
+
+We responded with a summary.
+
+</summary>

package/src/components/ChatThread/testing/{thread.md → thread-2.md}

@@ -35,3 +35,22 @@ What kind of information are you looking to organize? This will help me suggest
 
 <summary>OK (1 tool uses · 4.28k tokens · 11.1s)</summary>
 <summary>OK (4.30k tokens · 1.6s)</summary>
+
+<reasoning>Based on the rules, this is similar to the "Parcel tracking" example. I should: 1. First create an Order schema 2. Query for mailboxes to subscribe to 3. Query for available blueprints 4. Create the project Let me first ask a couple of qualifying questions, then proceed. Actually, the example is pretty clear - let me set things up. But first let me check for mailboxes and blueprints. Let me query for mailboxes and blueprints in parallel.</reasoning>
+
+<reasoning>I found a mailbox at `dxn:echo:B6ON2Y6HN4KLJWZD75VUUDCUQ552ERQSG:01KNHKXSWWCBZX6TCPMF1M0PDE`. Now I have everything I need to create the CRM project. The project should:
+
+1. Subscribe to the mailbox
+2. Use database, web-search, and browser blueprints
+3. Extract People and Organizations from emails
+4. Research contacts on the web
+5. Save to database avoiding duplicates
+6. Now I'm building the project structure to tie all these components together.</reasoning>
+
+<reasoning>I found the mailbox. Now I have all the information I need to create the CRM project. Let me create it with the appropriate blueprints and subscription to the mailbox. The project should:
+
+- Subscribe to the mailbox
+- On every email, extract People and Organizations
+- Save them to the database (checking for duplicates first)
+- Run web searches to enrich contact/org data
+- Blueprints needed: database, web-search, browser</reasoning>

package/src/components/ChatThread/testing/thread-widgets.md

@@ -0,0 +1,79 @@
+<prompt>Analyze this codebase and suggest improvements.</prompt>
+
+<reasoning>
+The user wants a comprehensive analysis of their codebase. I should examine the project structure, identify key patterns, and look for areas that could be improved. Let me start by reviewing the main source files and dependencies.
+</reasoning>
+
+I'll start by examining the project structure and key files.
+
+<toolCall id="toolu_01ABC123analyze" />
+
+<summary>Analyzed 42 files across 8 packages. Found 3 areas for improvement.</summary>
+
+Here's what I found after reviewing the codebase:
+
+## Architecture
+
+The project follows a modular plugin architecture with clear separation of concerns. Each plugin manages its own state and communicates through a shared event bus.
+
+## Suggested Improvements
+
+1. **Type Safety** — Several utility functions use `any` types that could be narrowed. This would catch bugs at compile time rather than runtime.
+
+2. **Error Handling** — The API layer could benefit from structured error types using discriminated unions instead of thrown exceptions.
+
+3. **Performance** — The subscription handlers in the data layer create new closures on every update. Memoizing these would reduce GC pressure.
+
+<reference ref="dxn:echo:@:123e4567-e89b-12d3-a456-426614174000">ProjectConfig</reference>
+
+Would you like me to dive deeper into any of these areas?
+
+<select>
+<option>Improve type safety</option>
+<option>Refactor error handling</option>
+<option>Optimize performance</option>
+</select>
+
+<suggestion>Show me the specific files that need type improvements</suggestion>
+
+<suggestion>Generate a refactoring plan as a document</suggestion>
+
+<stats>3 tool uses · 12.4k tokens · 18.2s</stats>
+
+<prompt>Improve type safety</prompt>
+
+<reasoning>
+The user chose to focus on type safety improvements. I should identify the specific files and patterns where `any` types are used unnecessarily and propose concrete fixes with before/after examples.
+</reasoning>
+
+Let me find all the locations where type safety can be improved.
+
+<toolCall id="toolu_01DEF456typescan" />
+
+<summary>Scanned 42 files. Found 17 instances of unnecessary `any` usage across 6 modules.</summary>
+
+Here are the key changes I recommend:
+
+### `src/utils/transform.ts`
+
+The `transform` function currently accepts `any` for its input parameter. We can use a generic constraint instead:
+
+```typescript
+// Before
+const transform = (input: any) => { ... }
+
+// After
+const transform = <T extends Record<string, unknown>>(input: T) => { ... }
+```
+
+### `src/handlers/events.ts`
+
+The event handler map uses `any` for callback types. A mapped type would preserve type information:
+
+```typescript
+type EventHandlers = {
+  [K in keyof EventMap]: (event: EventMap[K]) => void;
+};
+```
+
+<stats>1 tool use · 8.7k tokens · 12.1s</stats>

package/src/components/ChatThread/tool-widget-state.test.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { createMessage } from '#testing';
+
+import { rehydrateToolWidgetsFromMessages } from './tool-widget-state';
+
+describe('rehydrateToolWidgetsFromMessages', () => {
+  test('replays toolCall then toolResult in order', () => {
+    const calls: Array<{ id: string; kind: 'object' | 'function' }> = [];
+    const sink = {
+      updateWidget: (id: string, value: unknown) => {
+        calls.push({ id, kind: typeof value === 'function' ? 'function' : 'object' });
+      },
+    };
+
+    const messages = [
+      createMessage('assistant', [
+        { _tag: 'toolCall', toolCallId: 't1', name: 'foo', input: '{}', providerExecuted: false },
+        { _tag: 'toolResult', toolCallId: 't1', name: 'foo', result: '{}', providerExecuted: false },
+      ]),
+    ];
+
+    rehydrateToolWidgetsFromMessages(sink, messages);
+
+    expect(calls).toEqual([
+      { id: 't1', kind: 'object' },
+      { id: 't1', kind: 'function' },
+    ]);
+  });
+});

package/src/components/ChatThread/tool-widget-state.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type ContentBlock, type Message } from '@dxos/types';
+import { type StateDispatch } from '@dxos/ui-editor';
+
+/**
+ * Minimal surface used to push tool call / result blocks into {@link MarkdownStreamController} widget state.
+ */
+export type ToolWidgetStateSink = {
+  updateWidget<T>(id: string, value: StateDispatch<T>): void;
+};
+
+/**
+ * Mirrors tool-related branches of {@link blockToMarkdown} so widget props stay in sync with message blocks.
+ */
+export const applyToolBlockToWidgetState = (context: ToolWidgetStateSink, block: ContentBlock.Any): void => {
+  switch (block._tag) {
+    case 'toolCall': {
+      context.updateWidget<{ blocks: ContentBlock.Any[] }>(block.toolCallId, {
+        blocks: [block],
+      });
+      break;
+    }
+    case 'toolResult': {
+      context.updateWidget<{ blocks: ContentBlock.Any[] }>(block.toolCallId, ({ blocks = [] } = { blocks: [] }) => ({
+        blocks: [...blocks, block],
+      }));
+      break;
+    }
+    default: {
+      break;
+    }
+  }
+};
+
+/**
+ * Re-applies tool widget state after a full document replace (e.g. {@link MarkdownStreamController.setContent}),
+ * which clears accumulated widget props via `xmlTagResetEffect`.
+ */
+export const rehydrateToolWidgetsFromMessages = (context: ToolWidgetStateSink, messages: Message.Message[]): void => {
+  for (const message of messages) {
+    for (const block of message.blocks) {
+      applyToolBlockToWidgetState(context, block);
+    }
+  }
+};

package/src/components/ChatThread/widgets/FallbackWidget.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { TogglePanel } from '@dxos/react-ui-components';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { type XmlWidgetProps } from '@dxos/ui-editor';
+
+import { type MessageThreadContext } from '../sync';
+
+export const FallbackWidget = ({ _tag, ...props }: XmlWidgetProps<MessageThreadContext>) => {
+  return (
+    <TogglePanel.Root>
+      <TogglePanel.Header classNames='bg-group-surface'>{_tag}</TogglePanel.Header>
+      <TogglePanel.Content classNames='bg-modal-surface'>
+        <TogglePanel.Viewport>
+          <JsonHighlighter classNames='p-2! text-sm' data={props} />
+        </TogglePanel.Viewport>
+      </TogglePanel.Content>
+    </TogglePanel.Root>
+  );
+};
+
+FallbackWidget.displayName = 'Fallback';

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

@@ -0,0 +1,68 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useRef } from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { ReasoningWidget } from './ReasoningWidget';
+
+export type DefaultStoryProps = {
+  text: string;
+};
+
+// TODO(burdon): Generalize factory for DOM widgets.
+const DefaultStory = ({ text }: DefaultStoryProps) => {
+  const hostRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) {
+      return;
+    }
+
+    host.replaceChildren();
+    const widget = new ReasoningWidget(text, 0);
+    const dom = widget.toDOM();
+    host.appendChild(dom);
+    widget.updateDOM(dom);
+    return () => {
+      widget.destroy(dom);
+      host.replaceChildren();
+    };
+  }, [text]);
+
+  return <div ref={hostRef} />;
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/ChatWidgets/ReasoningWidget',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    text: 'The user is asking about nested flex layouts and overflow. I should mention min-height 0 and grid track sizing.',
+  },
+};
+
+export const LongText: Story = {
+  args: {
+    text: [
+      'Step 1: Identify the scroll container and ensure it participates in a definite height chain.',
+      'Step 2: Apply min-h-0 to flex children that should shrink and scroll.',
+      'Step 3: Prefer overflow-y-auto on the leaf viewport, not on every ancestor.',
+      'Step 4: Use min-h-0 on the scroll container to ensure it participates in a definite height chain.',
+      'Step 5: Use min-w-0 on the scroll container to ensure it participates in a definite width chain.',
+    ].join('\n\n'),
+  },
+};