@dxos/plugin-assistant 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/components/Chat/Chat.stories.tsx

@@ -0,0 +1,94 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { Button, Toast, useTranslation } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+
+import { AiUsageQuotaError, parseError } from '../../processor';
+
+type FailureToastProps = {
+  /**
+   * Raw failure exactly as it reaches {@link parseError}. The agent runs in a separate process and its
+   * failure cause is rendered to a string before it returns, so production typically surfaces a string
+   * here (not a typed error); the scenarios below mirror that.
+   */
+  rawError: unknown;
+};
+
+/**
+ * Renders the failure toast that `Chat.Thread` shows when a request fails: the title comes from the
+ * `ai-service-error.label` translation and the description is the message produced by {@link parseError}.
+ * Driving the real {@link parseError} keeps the displayed text identical to production for each failure
+ * class. The toast is held open (controlled) so it can be reviewed; production auto-dismisses after 20s.
+ */
+const FailureToast = ({ rawError }: FailureToastProps) => {
+  const { t } = useTranslation(pluginMeta.profile.key);
+  const [open, setOpen] = useState(true);
+  const error = parseError(rawError);
+  const action = error instanceof AiUsageQuotaError ? error.action : undefined;
+
+  return (
+    <Toast.Provider>
+      <Toast.Viewport />
+      {/* Long, 32-bit-safe duration keeps the toast up for review; larger values overflow setTimeout and fire immediately. */}
+      <Toast.Root type='foreground' open={open} duration={24 * 60 * 60 * 1000} onOpenChange={setOpen}>
+        <Toast.Title icon='ph--warning--regular' onClose={() => setOpen(false)}>
+          {t('ai-service-error.label')}
+        </Toast.Title>
+        <Toast.Description>{error.message}</Toast.Description>
+        {action && (
+          <Toast.Actions>
+            <Toast.Action altText={t(action.labelKey)} asChild>
+              <Button onClick={() => setOpen(false)}>{t(action.labelKey)}</Button>
+            </Toast.Action>
+          </Toast.Actions>
+        )}
+      </Toast.Root>
+    </Toast.Provider>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/Chat',
+  render: FailureToast,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: { translations },
+} satisfies Meta<typeof FailureToast>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The over-quota (HTTP 429) failure — the case this story exists for. EDGE rejects the request and
+ * `@effect/ai` surfaces an `HttpResponseError` whose message embeds the 429 status; the agent process
+ * stringifies it before it reaches the chat. Previously this fell through to "An unexpected error
+ * occurred."; it is now mapped to the actionable usage-limit message.
+ */
+export const QuotaExceeded: Story = {
+  args: {
+    rawError:
+      'HttpResponseError: StatusCode: An HTTP response error occurred. (429 POST https://edge.dxos.workers.dev/ai/v1/messages)\nResponse Body: {"error":{"message":"You have exceeded your usage quota."}}',
+  },
+};
+
+/** A configured model that the service does not recognize — the model name is surfaced to the user. */
+export const ModelUnavailable: Story = {
+  args: {
+    rawError: "UnknownError: ChatCompletionsClient.streamText: model 'gemma3:27b' not found",
+  },
+};
+
+/** Any unrecognized failure falls back to a generic message rather than leaking implementation detail. */
+export const UnexpectedError: Story = {
+  args: {
+    rawError: 'something unexpected blew up',
+  },
+};

package/src/components/Chat/Chat.tsx

@@ -2,24 +2,27 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Atom } from '@effect-atom/atom';
 import { useAtomValue } from '@effect-atom/atom-react';
 import * as Array from 'effect/Array';
 import * as Option from 'effect/Option';
 import React, { type PropsWithChildren, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { Agent, Plan } from '@dxos/assistant-toolkit';
+import { Plan } from '@dxos/assistant-toolkit';
 import { Event } from '@dxos/async';
-import { type Database, type Feed, Filter, Obj, Query } from '@dxos/echo';
-import { useQuery } from '@dxos/react-client/echo';
+import { getSpace } from '@dxos/client/echo';
+import { type Database, Filter, Obj, Query } from '@dxos/echo';
+import { useObject, useQuery } from '@dxos/react-client/echo';
 import { useIdentity } from '@dxos/react-client/halo';
-import { Toast, composable, composableProps, useTranslation } from '@dxos/react-ui';
+import { Button, Toast, composable, composableProps, useTranslation } from '@dxos/react-ui';
 import { type MarkdownStreamController } from '@dxos/react-ui-markdown';
 import { Menu, MenuRootProps } from '@dxos/react-ui-menu';
 import { Message } from '@dxos/types';
 
-import { useChatKeymapExtensions, useChatToolbarActions, useDebug } from '#hooks';
+import { useChatKeymapExtensions, useChatToolbarActions, useDebug, useTraceMessages } from '#hooks';
 import { meta } from '#meta';
 
+import { AiUsageQuotaError } from '../../processor';
 import {
   ChatStatus,
   ChatPrompt as NaturalChatPrompt,
@@ -36,7 +39,6 @@ import { type ChatEvent } from './events';
 
 type ChatRootProps = PropsWithChildren<
   Pick<ChatContextValue, 'chat' | 'processor'> & {
-    feed?: Feed.Feed;
     /** Fallback database when the chat is transient (not yet persisted). */
     db?: Database.Database;
     onEvent?: (event: ChatEvent) => void;
@@ -48,7 +50,7 @@ type ChatRootProps = PropsWithChildren<
   }
 >;
 
-const ChatRoot = ({ children, chat, feed, processor, db: dbFallback, onEvent, onSubmit, ...props }: ChatRootProps) => {
+const ChatRoot = ({ children, chat, processor, db: dbFallback, onEvent, onSubmit, ...props }: ChatRootProps) => {
   const [debug, setDebug] = useState(false);
   const streaming = useAtomValue(processor.streaming);
   const active = useAtomValue(processor.active);
@@ -58,6 +60,10 @@ const ChatRoot = ({ children, chat, feed, processor, db: dbFallback, onEvent, on
   // the message query and context controls operate before the chat is persisted.
   const db = (chat && Obj.getDatabase(chat)) || dbFallback;
 
+  // Reactive subscription — re-renders when the feed ref resolves. Direct `.target` reads are not reactive.
+  const [feedSnapshot] = useObject(chat?.feed);
+  const feed = Obj.getReactiveOrUndefined(feedSnapshot);
+
   // Event sink.
   const event = useMemo(() => new Event<ChatEvent>(), []);
 
@@ -212,15 +218,20 @@ ChatContent.displayName = CHAT_CONTENT_NAME;
 
 const CHAT_THREAD_NAME = 'Chat.Thread';
 
-type ChatThreadProps = Omit<NaturalChatThreadProps, 'identity' | 'messages' | 'tools'>;
+type ChatThreadProps = Omit<NaturalChatThreadProps, 'identity' | 'messages' | 'tools'> & {
+  /** Invoked from the over-quota error toast to open the usage dashboard. */
+  onViewUsage?: () => void;
+};
 
-const ChatThread = ({ viewType, debug: debugProp, ...props }: ChatThreadProps) => {
-  const { t } = useTranslation(meta.id);
+const ChatThread = ({ viewType, debug: debugProp, onViewUsage, ...props }: ChatThreadProps) => {
+  const { t } = useTranslation(meta.profile.key);
   const { debug, event, messages, processor } = useChatContext(CHAT_THREAD_NAME);
   const extensions = useChatKeymapExtensions({ event });
   const identity = useIdentity();
   const error = useAtomValue(processor.error).pipe(Option.getOrUndefined);
   const [toastError, setToastError] = useState<Error | undefined>(undefined);
+  // The toast renders whatever action the error declares (data-driven) rather than branching on type.
+  const toastAction = toastError instanceof AiUsageQuotaError ? toastError.action : undefined;
   const debugView = viewType === 'debug';
 
   const controllerRef = useRef<MarkdownStreamController | null>(null);
@@ -279,6 +290,20 @@ const ChatThread = ({ viewType, debug: debugProp, ...props }: ChatThreadProps) =
           {t('ai-service-error.label')}
         </Toast.Title>
         <Toast.Description>{toastError?.message}</Toast.Description>
+        {toastAction && onViewUsage && (
+          <Toast.Actions>
+            <Toast.Action altText={t(toastAction.labelKey)} asChild>
+              <Button
+                onClick={() => {
+                  setToastError(undefined);
+                  onViewUsage();
+                }}
+              >
+                {t(toastAction.labelKey)}
+              </Button>
+            </Toast.Action>
+          </Toast.Actions>
+        )}
       </Toast.Root>
     </>
   );
@@ -313,14 +338,40 @@ type ChatTaskListProps = {
 
 const ChatTaskList = composable<HTMLDivElement, ChatTaskListProps>(({ plan: planProp, ...props }, forwardedRef) => {
   const { chat } = useChatContext(CHAT_TASK_LIST_NAME);
-  const parent = chat ? Obj.getParent(chat) : undefined;
-  const agent = parent && Obj.instanceOf(Agent.Agent, parent) ? parent : undefined;
-  const plan = planProp ?? agent?.plan.target;
-  if (!plan) {
+
+  const plan = useAtomValue(
+    useMemo(
+      () =>
+        Atom.make(
+          (get) =>
+            planProp ??
+            Option.fromNullable(chat).pipe(
+              Option.map((_) => get(Obj.atom(_))),
+              Option.flatMapNullable((_) => _?.plan?.atom),
+              Option.map(get),
+              Option.getOrUndefined,
+            ),
+        ),
+      [chat, planProp],
+    ),
+  );
+  const space = chat ? getSpace(chat) : undefined;
+  const traceMessages = useTraceMessages(space);
+  const conversationId = chat?.feed?.target?.id;
+  if (!plan || !(plan.tasks?.length ?? 0)) {
     return null;
   }
 
-  return <TaskList {...props} plan={plan} ref={forwardedRef} />;
+  return (
+    <TaskList
+      {...props}
+      plan={plan}
+      space={space}
+      traceMessages={traceMessages}
+      conversationId={conversationId}
+      ref={forwardedRef}
+    />
+  );
 });
 
 ChatTaskList.displayName = CHAT_TASK_LIST_NAME;
@@ -339,4 +390,4 @@ export const Chat = {
   TaskList: ChatTaskList,
 };
 
-export type { ChatRootProps, ChatToolbarProps, ChatContentProps, ChatPromptProps, ChatThreadProps, ChatEvent };
+export type { ChatContentProps, ChatEvent, ChatPromptProps, ChatRootProps, ChatThreadProps, ChatToolbarProps };

package/src/components/Chat/events.ts

@@ -61,10 +61,4 @@ export type ChatEvent =
     }
   | {
       type: 'thread-close';
-    }
-  | {
-      type: 'record-start';
-    }
-  | {
-      type: 'record-stop';
     };

package/src/components/ChatPrompt/ChatActions.tsx

@@ -2,9 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type PropsWithChildren } from 'react';
+import React, { type PropsWithChildren, useCallback, useEffect, useState } from 'react';
 
-import { IconButton, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { useOptionalAtomCapabilityState, useOptionalCapabilities } from '@dxos/app-framework/ui';
+import { type Settings, TranscriptionCapabilities } from '@dxos/plugin-transcription';
+import { DropdownMenu, Icon, IconButton, MicButton, type ThemedClassName, useTranslation } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 
 import { meta } from '#meta';
@@ -13,43 +15,188 @@ import { type ChatEvent } from '../Chat/events';
 
 export type ChatActionsProps = ThemedClassName<
   PropsWithChildren<{
+    docId?: string;
     microphone?: boolean;
-    recording?: boolean;
     processing?: boolean;
     debug?: boolean;
     onEvent?: (event: ChatEvent) => void;
   }>
 >;
 
+type AudioInputDevice = {
+  deviceId: string;
+  label: string;
+};
+
 export const ChatActions = ({
   classNames,
   children,
+  docId,
   microphone,
-  recording,
   processing,
   debug,
   onEvent,
 }: ChatActionsProps) => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
+  // Voice input is optional: the transcription plugin contributes these capabilities. Tolerate its
+  // absence so the chat prompt still renders (e.g. in stories that do not load the plugin).
+  const transcriptionAvailable = useOptionalCapabilities(TranscriptionCapabilities.RecordingSession).length > 0;
+  const [session, setSession] = useOptionalAtomCapabilityState(TranscriptionCapabilities.RecordingSession);
+  const [settings, setSettings] = useOptionalAtomCapabilityState(TranscriptionCapabilities.Settings);
+
+  const recording = !!session?.recording && session.id === docId;
+  const recordMode: Settings.RecordMode = settings?.recordMode ?? 'toggle';
+  const entityExtraction = settings?.entityExtraction !== false;
+  const selectedDeviceId = settings?.audioDeviceId ?? '';
+
+  const [devices, setDevices] = useState<AudioInputDevice[]>([]);
+  useEffect(() => {
+    // Only touch media APIs when the recording controls are actually shown.
+    if (!microphone || !transcriptionAvailable || !navigator.mediaDevices?.enumerateDevices) {
+      return;
+    }
+    let cancelled = false;
+    const refresh = async () => {
+      const all = await navigator.mediaDevices.enumerateDevices();
+      if (cancelled) {
+        return;
+      }
+      // Labels are blank until microphone permission is granted; fall back to an ordinal name.
+      setDevices(
+        all
+          .filter((device) => device.kind === 'audioinput' && device.deviceId)
+          .map((device, index) => ({
+            deviceId: device.deviceId,
+            label: device.label || `Microphone ${index + 1}`,
+          })),
+      );
+    };
+    void refresh();
+    navigator.mediaDevices.addEventListener('devicechange', refresh);
+    return () => {
+      cancelled = true;
+      navigator.mediaDevices.removeEventListener('devicechange', refresh);
+    };
+  }, [microphone, transcriptionAvailable]);
+
+  const handleToggle = useCallback(() => {
+    if (!docId) {
+      return;
+    }
+    setSession((current) => (current?.recording && current.id === docId ? null : { id: docId, recording: true }));
+  }, [setSession, docId]);
+
+  const handlePressStart = useCallback(() => {
+    if (!docId) {
+      return;
+    }
+    setSession(() => ({ id: docId, recording: true }));
+  }, [setSession, docId]);
+
+  const handlePressEnd = useCallback(() => {
+    setSession((current) => (current?.id === docId ? null : current));
+  }, [setSession, docId]);
+
+  const handleRecordModeChange = useCallback(
+    (mode: Settings.RecordMode) => setSettings((current) => ({ ...current, recordMode: mode })),
+    [setSettings],
+  );
+
+  const handleEntityExtractionChange = useCallback(
+    (value: boolean) => setSettings((current) => ({ ...current, entityExtraction: value })),
+    [setSettings],
+  );
+
+  const handleSelectDevice = useCallback(
+    (deviceId: string) => setSettings((current) => ({ ...current, audioDeviceId: deviceId || undefined })),
+    [setSettings],
+  );
+
+  const recordLabel = recording
+    ? t('stop-recording.label')
+    : recordMode === 'hold'
+      ? t('hold-to-record.label')
+      : t('start-recording.label');
 
   return (
     <div className={mx('flex items-center', classNames)}>
       {children}
 
-      {microphone && (
-        <IconButton
-          disabled={!processing}
-          classNames={mx(recording && 'bg-primary-500')}
-          variant='ghost'
-          icon='ph--microphone--regular'
-          iconOnly
-          noTooltip
-          label={t('microphone.button')}
-          onMouseDown={() => onEvent?.({ type: 'record-start' })}
-          onMouseUp={() => onEvent?.({ type: 'record-stop' })}
-          onTouchStart={() => onEvent?.({ type: 'record-start' })}
-          onTouchEnd={() => onEvent?.({ type: 'record-stop' })}
-        />
+      {microphone && docId && transcriptionAvailable && (
+        <>
+          <MicButton
+            iconOnly
+            variant='ghost'
+            label={recordLabel}
+            recording={recording}
+            mode={recordMode}
+            onToggle={handleToggle}
+            onPressStart={handlePressStart}
+            onPressEnd={handlePressEnd}
+            data-testid='assistant.record'
+          />
+          <DropdownMenu.Root>
+            <DropdownMenu.Trigger asChild>
+              <IconButton
+                icon='ph--caret-down--regular'
+                iconOnly
+                label={t('recording-options.label')}
+                variant='ghost'
+                classNames='w-4'
+                data-testid='assistant.record.options'
+              />
+            </DropdownMenu.Trigger>
+            <DropdownMenu.Portal>
+              <DropdownMenu.Content>
+                <DropdownMenu.Viewport>
+                  <DropdownMenu.GroupLabel>{t('record-mode.label')}</DropdownMenu.GroupLabel>
+                  <SettingsSelectableItem
+                    label={t('record-mode.toggle.label')}
+                    selected={recordMode === 'toggle'}
+                    onSelect={() => handleRecordModeChange('toggle')}
+                  />
+                  <SettingsSelectableItem
+                    label={t('record-mode.hold.label')}
+                    selected={recordMode === 'hold'}
+                    onSelect={() => handleRecordModeChange('hold')}
+                  />
+
+                  <DropdownMenu.Separator />
+
+                  <DropdownMenu.GroupLabel>{t('audio-device.label')}</DropdownMenu.GroupLabel>
+                  <SettingsSelectableItem
+                    label={t('audio-device.default.label')}
+                    selected={selectedDeviceId === ''}
+                    onSelect={() => handleSelectDevice('')}
+                  />
+                  {devices.map((device) => (
+                    <SettingsSelectableItem
+                      key={device.deviceId}
+                      label={device.label}
+                      selected={selectedDeviceId === device.deviceId}
+                      onSelect={() => handleSelectDevice(device.deviceId)}
+                    />
+                  ))}
+
+                  <DropdownMenu.Separator />
+
+                  <DropdownMenu.CheckboxItem
+                    checked={entityExtraction}
+                    onCheckedChange={handleEntityExtractionChange}
+                    classNames='gap-2'
+                    data-testid='assistant.entity-extraction'
+                  >
+                    <span className='grow truncate'>{t('settings.entity-extraction.label')}</span>
+                    <DropdownMenu.ItemIndicator asChild>
+                      <Icon icon='ph--check--regular' size={4} />
+                    </DropdownMenu.ItemIndicator>
+                  </DropdownMenu.CheckboxItem>
+                </DropdownMenu.Viewport>
+                <DropdownMenu.Arrow />
+              </DropdownMenu.Content>
+            </DropdownMenu.Portal>
+          </DropdownMenu.Root>
+        </>
       )}
 
       {debug && (
@@ -68,8 +215,26 @@ export const ChatActions = ({
         icon='ph--x--regular'
         iconOnly
         label={t('cancel-processing.button')}
-        onClick={() => onEvent?.({ type: 'cancel' })}
+        onClick={() => {
+          onEvent?.({ type: 'cancel' });
+        }}
       />
     </div>
   );
 };
+
+type SettingsSelectableItemProps = {
+  label: string;
+  selected: boolean;
+  onSelect: () => void;
+};
+
+// The design system's `DropdownMenu.RadioItem` renders a plain item (no radio semantics), so
+// single-select is modelled with a plain item and an explicit trailing check. `onSelect` (not
+// `onClick`) so keyboard activation works.
+const SettingsSelectableItem = ({ label, selected, onSelect }: SettingsSelectableItemProps) => (
+  <DropdownMenu.Item classNames='gap-2' role='menuitemradio' aria-checked={selected} onSelect={onSelect}>
+    <span className='grow truncate'>{label}</span>
+    {selected && <Icon icon='ph--check--regular' size={4} />}
+  </DropdownMenu.Item>
+);

package/src/components/ChatPrompt/ChatMcpErrors.tsx

@@ -20,7 +20,7 @@ export type ChatMcpErrorsProps = ThemedClassName<{
  * The chat itself keeps working without these servers — this just lets the user see what was dropped.
  */
 export const ChatMcpErrors = ({ classNames, processor }: ChatMcpErrorsProps) => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
   const errors = useAtomValue(processor.mcpErrors);
 
   const handleDismiss = useCallback(() => {

package/src/components/ChatPrompt/ChatOptions.stories.tsx

@@ -23,7 +23,7 @@ import { Organization, Person } from '@dxos/types';
 import { useContextBinder } from '#hooks';
 import { translations } from '#translations';
 
-import { ChatOptions, ObjectsPanel, type ChatOptionsProps } from './ChatOptions';
+import { ChatOptions, type ChatOptionsProps, ObjectsPanel } from './ChatOptions';
 
 const presets = [
   {
@@ -40,9 +40,9 @@ const presets = [
   },
 ];
 
-type DefaultStoryProps = Pick<ChatOptionsProps, 'presets'>;
+type StoryArgs = Pick<ChatOptionsProps, 'presets'>;
 
-const DefaultStory = ({ presets }: DefaultStoryProps) => {
+const DefaultStory = ({ presets }: StoryArgs) => {
   const [space] = useSpaces();
   const [feed] = useQuery(space?.db, Filter.type(Feed.Feed));
   const [chat] = useQuery(space?.db, Filter.type(Chat.Chat));