@dxos/plugin-assistant 0.8.4-main.72ec0f3 → 0.8.4-main.7996785055

package/src/capabilities/react-surface/react-surface.tsx

@@ -0,0 +1,158 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface, useSettingsState } from '@dxos/app-framework/ui';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Chat, Project } from '@dxos/assistant-toolkit';
+import { Blueprint, Prompt } from '@dxos/blueprints';
+import { getSpace } from '@dxos/client/echo';
+import { Sequence } from '@dxos/conductor';
+import { InvocationTraceContainer } from '@dxos/devtools';
+import { Obj } from '@dxos/echo';
+import { Panel } from '@dxos/react-ui';
+import { useActiveSpace } from '@dxos/plugin-space';
+
+import {
+  AssistantSettings,
+  BlueprintArticle,
+  ChatCompanion,
+  ChatContainer,
+  ChatDialog,
+  ProjectArticle,
+  ProjectSettings,
+  PromptArticle,
+  PromptList,
+  TracePanel,
+  TriggerStatus,
+} from '../../containers';
+import { ASSISTANT_DIALOG, meta } from '../../meta';
+import { type Assistant } from '../../types';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: `${meta.id}.plugin-settings`,
+        role: 'article',
+        filter: (data): data is { subject: AppCapabilities.Settings } =>
+          AppCapabilities.isSettings(data.subject) && data.subject.prefix === meta.id,
+        component: ({ data: { subject } }) => {
+          const { settings, updateSettings } = useSettingsState<Assistant.Settings>(subject.atom);
+          return <AssistantSettings settings={settings} onSettingsChange={updateSettings} />;
+        },
+      }),
+      Surface.create({
+        id: `${meta.id}.chat`,
+        role: 'article',
+        filter: (data): data is { attendableId: string; subject: Chat.Chat; variant: undefined } =>
+          typeof data.attendableId === 'string' &&
+          Obj.instanceOf(Chat.Chat, data.subject) &&
+          data.variant !== 'assistant-chat',
+        component: ({ data, role, ref }) => (
+          <ChatContainer role={role} subject={data.subject} attendableId={data.attendableId} ref={ref} />
+        ),
+      }),
+      Surface.create({
+        id: `${meta.id}.project`,
+        role: 'article',
+        filter: (data): data is { subject: Project.Project } => Obj.instanceOf(Project.Project, data.subject),
+        component: ({ data, role }) => <ProjectArticle role={role} subject={data.subject} />,
+      }),
+      Surface.create({
+        id: `${meta.id}.project.companion.settings`,
+        role: 'object-settings',
+        filter: (data): data is { subject: Project.Project } => Obj.instanceOf(Project.Project, data.subject),
+        component: ({ data }) => <ProjectSettings subject={data.subject} />,
+      }),
+      // TODO(wittjosiah): This is flashing when chat changes.
+      Surface.create({
+        id: `${meta.id}.companion-chat`,
+        role: 'article',
+        filter: (
+          data,
+        ): data is { subject: Chat.Chat | 'assistant-chat'; attendableId: string; companionTo: Obj.Unknown } =>
+          typeof data.attendableId === 'string' &&
+          Obj.isObject(data.companionTo) &&
+          (Obj.instanceOf(Chat.Chat, data.subject) || data.subject === 'assistant-chat'),
+        component: ({ data, role, ref }) => (
+          <ChatCompanion
+            role={role}
+            data={data}
+            // TODO(burdon): See comment in ChatCompanion.tsx
+            // data={data.subject}
+            // companionTo={data.companionTo}
+            // attendableId={data.attendableId}
+            ref={ref}
+          />
+        ),
+      }),
+      Surface.create({
+        id: `${meta.id}.companion-invocations`,
+        role: 'article',
+        filter: (data): data is { companionTo: Sequence } =>
+          (Obj.instanceOf(Sequence, data.companionTo) || Obj.instanceOf(Prompt.Prompt, data.companionTo)) &&
+          data.subject === 'invocations',
+        component: ({ data, role }) => {
+          const space = getSpace(data.companionTo);
+          const queueDxn = space?.properties.invocationTraceQueue?.dxn;
+          // TODO(wittjosiah): Support invocation filtering for prompts.
+          const target = Obj.instanceOf(Prompt.Prompt, data.companionTo) ? undefined : data.companionTo;
+          return (
+            <Panel.Root role={role} className='dx-document'>
+              <Panel.Content asChild>
+                <InvocationTraceContainer db={space?.db} queueDxn={queueDxn} target={target} detailAxis='block' />
+              </Panel.Content>
+            </Panel.Root>
+          );
+        },
+      }),
+      Surface.create({
+        id: `${meta.id}.blueprint`,
+        role: 'article',
+        filter: (data): data is { subject: Blueprint.Blueprint } => Obj.instanceOf(Blueprint.Blueprint, data.subject),
+        component: ({ data }) => <BlueprintArticle subject={data.subject} />,
+      }),
+      Surface.create({
+        id: `${meta.id}.prompt`,
+        role: 'article',
+        filter: (data): data is { subject: Prompt.Prompt } => Obj.instanceOf(Prompt.Prompt, data.subject),
+        component: ({ data }) => <PromptArticle subject={data.subject} />,
+      }),
+      Surface.create({
+        id: ASSISTANT_DIALOG,
+        role: 'dialog',
+        filter: (data): data is { props: { chat: Chat.Chat } } => data.component === ASSISTANT_DIALOG,
+        component: ({ data }) => <ChatDialog {...data.props} />,
+      }),
+      Surface.create({
+        id: `${meta.id}.trace`,
+        role: 'deck-companion--trace',
+        filter: (data): data is { subject: 'trace' } => data.subject === 'trace',
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <TracePanel space={space} />;
+        },
+      }),
+      Surface.create({
+        id: `${meta.id}.status`,
+        role: 'status-indicator',
+        component: () => <TriggerStatus />,
+      }),
+      Surface.create({
+        id: `${meta.id}.prompts`,
+        role: 'prompts',
+        filter: (data): data is { subject: Obj.Unknown } => Obj.isObject(data.subject),
+        component: ({ data }) => <PromptList subject={data.subject} />,
+      }),
+    ]),
+  ),
+);

package/src/capabilities/settings/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const Settings = Capability.lazy('Settings', () => import('./settings'));

package/src/capabilities/settings/settings.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '../../meta';
+import { Assistant, AssistantCapabilities } from '../../types';
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: Assistant.Settings,
+      defaultValue: () => ({}),
+    });
+
+    return [
+      Capability.contributes(AssistantCapabilities.Settings, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.id,
+        schema: Assistant.Settings,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/capabilities/state/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const AssistantState = Capability.lazy('AssistantState', () => import('./state'));

package/src/capabilities/state/state.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '../../meta';
+import { AssistantCapabilities } from '../../types';
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    // NOTE: This needs to be a chat object rather than a string id to avoid a query race.
+    // TODO(wittjosiah): Handle serialization and hydration for this so it can be cached.
+    const stateAtom = createKvsStore({
+      key: meta.id,
+      schema: AssistantCapabilities.StateSchema,
+      defaultValue: () => ({
+        currentChat: {},
+        pendingPrompts: {},
+      }),
+    });
+
+    return Capability.contributes(AssistantCapabilities.State, stateAtom);
+  }),
+);

package/src/capabilities/toolkit/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const Toolkit = Capability.lazy('Toolkit', () => import('./toolkit'));

package/src/capabilities/toolkit/toolkit.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { GenericToolkit } from '@dxos/ai';
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { WebSearchToolkit } from '@dxos/assistant-toolkit';
+
+export default Capability.makeModule(() =>
+  Effect.succeed([Capability.contributes(AppCapabilities.Toolkit, GenericToolkit.make(WebSearchToolkit, Layer.empty))]),
+);

package/src/components/Chat/Chat.tsx

@@ -10,23 +10,23 @@ import * as Array from 'effect/Array';
 import * as Option from 'effect/Option';
 import React, { type PropsWithChildren, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
+import { type Chat as ChatModule } from '@dxos/assistant-toolkit';
 import { Event } from '@dxos/async';
-import { Obj } from '@dxos/echo';
+import { type Database, Filter, Obj } from '@dxos/echo';
 import { useVoiceInput } from '@dxos/plugin-transcription';
-import { type Space, getSpace, useQueue } from '@dxos/react-client/echo';
+import { useQuery } from '@dxos/react-client/echo';
 import { useIdentity } from '@dxos/react-client/halo';
 import { Input, type ThemedClassName, useDynamicRef, useTranslation } from '@dxos/react-ui';
 import { ChatEditor, type ChatEditorController, type ChatEditorProps } from '@dxos/react-ui-chat';
 import { type MarkdownStreamController } from '@dxos/react-ui-components';
-import { MenuProvider, ToolbarMenu } from '@dxos/react-ui-menu';
-import { mx } from '@dxos/react-ui-theme';
+import { Menu, MenuRootProps } from '@dxos/react-ui-menu';
 import { Message } from '@dxos/types';
+import { composable, composableProps, mx } from '@dxos/ui-theme';
 import { isTruthy } from '@dxos/util';
 
 import { useChatToolbarActions } from '../../hooks';
 import { meta } from '../../meta';
 import { type AiChatProcessor } from '../../processor';
-import { type Assistant } from '../../types';
 import {
   ChatActions,
   type ChatActionsProps,
@@ -48,8 +48,8 @@ import { type ChatEvent } from './events';
 type ChatContextValue = {
   debug?: boolean;
   event: Event<ChatEvent>;
-  space?: Space;
-  chat?: Assistant.Chat;
+  db?: Database.Database;
+  chat?: ChatModule.Chat;
   messages: Message.Message[];
   processor: AiChatProcessor;
 };
@@ -61,7 +61,7 @@ export const [ChatContextProvider, useChatContext] = createContext<ChatContextVa
 //
 
 type ChatRootProps = PropsWithChildren<
-  Pick<ChatContextValue, 'space' | 'chat' | 'processor'> & {
+  Pick<ChatContextValue, 'db' | 'chat' | 'processor'> & {
     onEvent?: (event: ChatEvent) => void;
   }
 >;
@@ -73,11 +73,10 @@ const ChatRoot = ({ children, chat, processor, onEvent, ...props }: ChatRootProp
   const lastPrompt = useRef<string | undefined>(undefined);
 
   // Messages.
-  const queue = useQueue<Message.Message>(chat?.queue.dxn);
+  const storedMessages = useQuery(chat?.queue?.target, Filter.type(Message.Message));
   const messages = useMemo(() => {
-    const queueMessages = queue?.objects?.filter(Obj.instanceOf(Message.Message)) ?? [];
-    return Array.dedupeWith([...queueMessages, ...pending], ({ id: a }, { id: b }) => a === b);
-  }, [queue?.objects, pending]);
+    return Array.dedupeWith([...storedMessages, ...pending], ({ id: a }, { id: b }) => a === b);
+  }, [storedMessages, pending]);
 
   // Events.
   const event = useMemo(() => new Event<ChatEvent>(), []);
@@ -85,7 +84,26 @@ const ChatRoot = ({ children, chat, processor, onEvent, ...props }: ChatRootProp
     return event.on((ev) => {
       switch (ev.type) {
         case 'toggle-debug': {
-          setDebug((current) => !current);
+          setDebug((debug) => !debug);
+
+          // Dump state to console.
+          queueMicrotask(async () => {
+            const objects = processor.context.getObjects();
+            const blueprints = processor.context.getBlueprints();
+            const tools = await processor.getTools();
+            const system = await processor.getSystemPrompt();
+            // eslint-disable-next-line no-console
+            console.log('Chat processor state:', { objects, blueprints });
+            // eslint-disable-next-line no-console
+            console.log(`
+              ==== System Prompt ====
+              ${system}
+              ==== Tools ====
+              ${Object.values(tools)
+                .map((tool) => JSON.stringify(tool, null, 2))
+                .join('\n')}
+            `);
+          });
           break;
         }
 
@@ -120,13 +138,13 @@ const ChatRoot = ({ children, chat, processor, onEvent, ...props }: ChatRootProp
     });
   }, [event, processor, streaming, onEvent]);
 
-  const space = props.space ?? getSpace(chat);
+  const db = props.db ?? (chat && Obj.getDatabase(chat));
 
   return (
     <ChatContextProvider
       debug={debug}
       event={event}
-      space={space}
+      db={db}
       chat={chat}
       messages={messages}
       processor={processor}
@@ -143,20 +161,83 @@ ChatRoot.displayName = 'Chat.Root';
 // Viewport
 //
 
-type ChatViewportProps = ThemedClassName<PropsWithChildren>;
+const CHAT_VIEWPORT_NAME = 'Chat.Viewport';
 
-const ChatViewport = ({ classNames, children }: ChatViewportProps) => {
+type ChatViewportProps = {};
+
+const ChatViewport = composable<HTMLDivElement, ChatViewportProps>(({ children, ...props }, forwardedRef) => {
   return (
-    <div role='none' className={mx('flex flex-col bs-full is-full', classNames)}>
+    <div {...composableProps(props, { role: 'none', classNames: 'dx-expander flex flex-col' })} ref={forwardedRef}>
       {children}
     </div>
   );
+});
+
+ChatViewport.displayName = CHAT_VIEWPORT_NAME;
+
+//
+// Thread
+//
+
+const CHAT_THREAD_NAME = 'Chat.Thread';
+
+type ChatThreadProps = Omit<NaturalChatThreadProps, 'identity' | 'messages' | 'tools'>;
+
+const ChatThread = (props: ChatThreadProps) => {
+  const { debug, event, messages, processor } = useChatContext(CHAT_THREAD_NAME);
+  const identity = useIdentity();
+  const error = useAtomValue(processor.error).pipe(Option.getOrUndefined);
+
+  const controllerRef = useRef<MarkdownStreamController | null>(null);
+  useEffect(() => {
+    return event.on((event) => {
+      switch (event.type) {
+        case 'submit':
+        case 'scroll-to-bottom':
+          controllerRef.current?.scrollToBottom();
+          break;
+        case 'nav-previous':
+          controllerRef.current?.navigatePrevious();
+          break;
+        case 'nav-next':
+          controllerRef.current?.navigateNext();
+          break;
+      }
+    });
+  }, [event]);
+
+  const handleEvent = useCallback<NonNullable<NaturalChatThreadProps['onEvent']>>(
+    (ev) => {
+      event.emit(ev);
+    },
+    [event],
+  );
+
+  if (!identity) {
+    return null;
+  }
+
+  return (
+    <NaturalChatThread
+      {...props}
+      identity={identity}
+      messages={messages}
+      error={error}
+      debug={debug}
+      onEvent={handleEvent}
+      ref={controllerRef}
+    />
+  );
 };
 
+ChatThread.displayName = CHAT_THREAD_NAME;
+
 //
 // Prompt
 //
 
+const CHAT_PROMPT_NAME = 'Chat.Prompt';
+
 type ChatPromptProps = ThemedClassName<
   {
     outline?: boolean;
@@ -183,7 +264,7 @@ const ChatPrompt = ({
   onOnlineChange,
 }: ChatPromptProps) => {
   const { t } = useTranslation(meta.id);
-  const { space, processor, event } = useChatContext(ChatPrompt.displayName);
+  const { db, processor, event } = useChatContext(CHAT_PROMPT_NAME);
 
   const error = useAtomValue(processor.error).pipe(Option.getOrUndefined);
   const streaming = useAtomValue(processor.streaming);
@@ -282,9 +363,9 @@ const ChatPrompt = ({
     <div
       role='group'
       className={mx(
-        'flex flex-col is-full density-fine',
+        'flex flex-col w-full dx-density-fine',
         outline &&
-          'bg-groupSurface border border-subduedSeparator transition transition-border [&:has(.cm-content:focus)]:border-separator rounded',
+          'bg-group-surface border border-subdued-separator transition transition-border [&:has(.cm-content:focus)]:border-separator rounded-sm',
         classNames,
       )}
     >
@@ -294,17 +375,17 @@ const ChatPrompt = ({
           ref={editorRef}
           autoFocus
           lineWrapping
-          classNames='col-span-2 pbs-0.5'
+          classNames='col-span-2 pt-0.5'
           placeholder={placeholder ?? t('prompt placeholder')}
           extensions={extensions}
           onSubmit={handleSubmit}
         />
       </div>
 
-      {space && settings && (
+      {db && settings && (
         <div role='none' className='flex items-center overflow-hidden'>
           <ChatOptions
-            space={space}
+            db={db}
             blueprintRegistry={processor.blueprintRegistry}
             context={processor.context}
             preset={preset}
@@ -313,7 +394,7 @@ const ChatPrompt = ({
           />
 
           <div role='none' className='flex grow overflow-x-auto scrollbar-none'>
-            <ChatReferences space={space} context={processor.context} />
+            <ChatReferences db={db} context={processor.context} />
           </div>
 
           <ChatActions
@@ -327,7 +408,7 @@ const ChatPrompt = ({
             {online !== undefined && (
               <Input.Root>
                 <Input.Label srOnly>{t('online switch label')}</Input.Label>
-                <Input.Switch classNames='mli-2' checked={online} onCheckedChange={onOnlineChange} />
+                <Input.Switch classNames='mx-2' checked={online} onCheckedChange={onOnlineChange} />
               </Input.Root>
             )}
           </ChatActions>
@@ -337,84 +418,32 @@ const ChatPrompt = ({
   );
 };
 
-ChatPrompt.displayName = 'Chat.Prompt';
+ChatPrompt.displayName = CHAT_PROMPT_NAME;
 
 //
-// Thread
+// Toolbar
 //
 
-type ChatThreadProps = Omit<NaturalChatThreadProps, 'identity' | 'messages' | 'tools'>;
-
-const ChatThread = (props: ChatThreadProps) => {
-  const { debug, event, messages, processor } = useChatContext(ChatThread.displayName);
-  const identity = useIdentity();
-  const error = useAtomValue(processor.error).pipe(Option.getOrUndefined);
+const CHAT_TOOLBAR_NAME = 'Chat.Toolbar';
 
-  const controllerRef = useRef<MarkdownStreamController | null>(null);
-  useEffect(() => {
-    return event.on((event) => {
-      switch (event.type) {
-        case 'submit':
-        case 'scroll-to-bottom':
-          controllerRef.current?.scrollToBottom();
-          break;
-        case 'nav-previous':
-          controllerRef.current?.navigatePrevious();
-          break;
-        case 'nav-next':
-          controllerRef.current?.navigateNext();
-          break;
-      }
-    });
-  }, [event]);
-
-  const handleEvent = useCallback<NonNullable<NaturalChatThreadProps['onEvent']>>(
-    (ev) => {
-      event.emit(ev);
-    },
-    [event],
-  );
-
-  if (!identity) {
-    return null;
-  }
-
-  return (
-    <NaturalChatThread
-      {...props}
-      identity={identity}
-      messages={messages}
-      error={error}
-      debug={debug}
-      onEvent={handleEvent}
-      ref={controllerRef}
-    />
-  );
+type ChatToolbarProps = Pick<MenuRootProps, 'attendableId'> & {
+  companionTo?: Obj.Unknown;
 };
 
-ChatThread.displayName = 'Chat.Thread';
-
-//
-// Toolbar
-//
-
-type ChatToolbarProps = ThemedClassName<{ companionTo?: Obj.Any }>;
+const ChatToolbar = composable<HTMLDivElement, ChatToolbarProps>(
+  ({ attendableId, companionTo, ...props }, forwardedRef) => {
+    const { chat } = useChatContext(CHAT_TOOLBAR_NAME);
+    const menuActions = useChatToolbarActions({ chat, companionTo });
 
-const ChatToolbar = ({ classNames, companionTo }: ChatToolbarProps) => {
-  const { chat } = useChatContext(ChatToolbar.displayName);
-  const menu = useChatToolbarActions({ chat, companionTo });
+    return (
+      <Menu.Root {...menuActions} attendableId={attendableId}>
+        <Menu.Toolbar {...composableProps(props)} ref={forwardedRef} />
+      </Menu.Root>
+    );
+  },
+);
 
-  return (
-    <MenuProvider
-      {...menu}
-      attendableId={companionTo ? Obj.getDXN(companionTo).toString() : chat ? Obj.getDXN(chat).toString() : ''}
-    >
-      <ToolbarMenu classNames={classNames} textBlockWidth />
-    </MenuProvider>
-  );
-};
-
-ChatToolbar.displayName = 'Chat.Toolbar';
+ChatToolbar.displayName = CHAT_TOOLBAR_NAME;
 
 //
 // Chat
@@ -423,8 +452,8 @@ ChatToolbar.displayName = 'Chat.Toolbar';
 export const Chat = {
   Root: ChatRoot,
   Viewport: ChatViewport,
-  Prompt: ChatPrompt,
   Thread: ChatThread,
+  Prompt: ChatPrompt,
   Toolbar: ChatToolbar,
 };
 

package/src/components/Chat/events.ts

@@ -31,7 +31,7 @@ export type ChatEvent =
     }
   | {
       type: 'add';
-      object: Obj.Any;
+      object: Obj.Unknown;
     }
   //
   // UX