@dxos/plugin-assistant 0.13.0 → 0.14.0

package/src/containers/ChatDialog/ChatDialog.tsx

@@ -14,7 +14,7 @@ import { ChatDialog as NaturalChatDialog } from '@dxos/react-ui-chat';
 import * as UiHooks from '@dxos/react-ui/Hooks';
 
 import { Chat, type ChatRootProps } from '#components';
-import { useChatProcessor, useChatServices, usePresets } from '#hooks';
+import { useChatModel, useChatServices, usePresets } from '#hooks';
 import { meta } from '#meta';
 import { AssistantCapabilities } from '#types';
 
@@ -30,7 +30,7 @@ export const ChatDialog = ({ chat }: ChatDialogProps) => {
   const runtime = useChatServices({ id: db?.spaceId });
   const { preset, ...chatProps } = usePresets(settings, chat);
   const registry = useRegistry();
-  const processor = useChatProcessor({ chat, preset, runtime, registry, settings });
+  const chatModel = useChatModel({ db, chat, preset, runtime, registry, settings });
   // Subscribe via `useObject` so the thread re-renders when ChatOptions changes the view type.
   const [chatViewType] = useObject(chat, 'viewType');
 
@@ -50,12 +50,12 @@ export const ChatDialog = ({ chat }: ChatDialogProps) => {
     }
   }, []);
 
-  if (!chat || !processor) {
+  if (!chat || !chatModel) {
     return null;
   }
 
   return (
-    <Chat.Root chat={chat} processor={processor} onEvent={handleEvent}>
+    <Chat.Root chat={chat} chatModel={chatModel} onEvent={handleEvent}>
       <NaturalChatDialog.Root open={open} expanded={expanded} onOpenChange={setOpen}>
         <NaturalChatDialog.Header title={t('assistant-dialog.title')} />
         <NaturalChatDialog.Content>

package/src/containers/SpaceHomePrompt/SpaceHomePrompt.tsx

@@ -2,90 +2,59 @@
 // Copyright 2026 DXOS.org
 //
 
-import React, { useEffect, useMemo, useState } from 'react';
+import * as Effect from 'effect/Effect';
+import type * as AtomRegistry from 'effect/reactivity/AtomRegistry';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 
 import * as Capabilities from '@dxos/app-framework/Capabilities';
 import * as Hooks from '@dxos/app-framework/Hooks';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
 import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
-import type * as Chat from '@dxos/assistant/Chat';
+import { AiContext } from '@dxos/assistant';
+import * as Chat from '@dxos/assistant/Chat';
 import { Event } from '@dxos/async';
+import { Database, Feed, Ref } from '@dxos/echo';
+import * as EffectEx from '@dxos/effect/EffectEx';
+import { log } from '@dxos/log';
 import { type Space, useRegistry } from '@dxos/react-client/echo';
 import * as UiHooks from '@dxos/react-ui/Hooks';
 
 import { type ChatEvent, ChatPrompt } from '#components';
-import { useChatProcessor, useChatServices, usePresets } from '#hooks';
+import { usePresets } from '#hooks';
 import { meta } from '#meta';
-import { AssistantCapabilities, AssistantOperation } from '#types';
+import { AssistantCapabilities } from '#types';
 
 import { getChatPath } from '../../paths.ts';
+import { bindChatDefaults, contributesPluginManager } from '../../util/default-skills.ts';
 
 type SpaceScopedProps = {
   space?: Space;
 };
 
-/**
- * Home article pinned-bottom contributor: the assistant prompt. Backed by an ephemeral in-memory
- * chat whose sole responsibility is to collect the user's text, context bindings, and preset
- * choice, then on submit: persist the chat to the space, queue the text as a pending prompt, and
- * navigate to it. AI generation runs in the opened chat view — the processor here exists only to
- * back the context-binder UI.
- */
 export const SpaceHomePrompt = ({ space }: SpaceScopedProps) => {
   const { t } = UiHooks.useTranslation(meta.profile.key);
-  const { invokePromise } = Hooks.useOperationInvoker();
 
   const registry = useRegistry();
   const atomRegistry = Hooks.useCapability(Capabilities.AtomRegistry);
-  const stateAtom = Hooks.useCapability(AssistantCapabilities.State);
-  const runtime = useChatServices({ id: space?.id });
   const settings = Hooks.useAtomCapability(AssistantCapabilities.Settings);
+  const pluginManager = contributesPluginManager(Hooks.useCapabilities(AppCapabilities.SkillDefinition));
 
-  // In-memory backing chat (not yet added to the space). `nonce` forces a fresh chat after submit.
-  const [chat, setChat] = useState<Chat.Chat>();
-  const [nonce, setNonce] = useState(0);
-  const { preset, ...presetProps } = usePresets(settings, chat);
-  useEffect(() => {
+  const [draftGeneration, setDraftGeneration] = useState(0);
+  const draft = useMemo(() => {
     if (!space) {
-      setChat(undefined);
-      return;
+      return undefined;
     }
-    let cancelled = false;
-    void invokePromise(AssistantOperation.CreateChat, {}, { spaceId: space.db.spaceId }).then((result) => {
-      if (!cancelled) {
-        setChat(result.data?.object);
-      }
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [space, nonce, invokePromise]);
-
-  const processor = useChatProcessor({ db: space?.db, chat, preset, runtime, registry });
-
-  const event = useMemo(() => new Event<ChatEvent>(), []);
-  useEffect(() => {
-    return event.on((ev) => {
-      if (ev.type !== 'submit') {
-        return;
-      }
-      const text = ev.text.trim();
-      if (!space || !chat || text.length === 0) {
-        return;
-      }
+    const feed = Feed.make();
+    return { feed, chat: Chat.make({ feed: Ref.make(feed) }) };
+  }, [space, draftGeneration]);
+  const chat = draft?.chat;
+  const context = useDraftContext({ db: space?.db, draft, registry: atomRegistry, pluginManager });
+  const { preset, ...presetProps } = usePresets(settings, chat);
 
-      // Persist the in-memory chat, queue the prompt, and open the chat (which submits it).
-      space.db.add(chat);
-      const chatPath = getChatPath(space.db.spaceId, chat.id);
-      atomRegistry.update(stateAtom, (current) => ({
-        ...current,
-        pendingPrompts: { ...current.pendingPrompts, [chatPath]: text },
-      }));
-      void invokePromise(LayoutOperation.Open, { subject: [chatPath] });
-      setNonce((current) => current + 1);
-    });
-  }, [event, space, chat, atomRegistry, stateAtom, invokePromise]);
+  const startNewDraft = useCallback(() => setDraftGeneration((current) => current + 1), []);
+  const event = useDraftSend({ space, draft, context, onSent: startNewDraft });
 
-  if (!processor || !chat || !space) {
+  if (!space) {
     return null;
   }
 
@@ -95,7 +64,8 @@ export const SpaceHomePrompt = ({ space }: SpaceScopedProps) => {
       outline
       chat={chat}
       db={space.db}
-      processor={processor}
+      context={context}
+      registry={registry}
       event={event}
       preset={preset?.id}
       placeholder={t('space-home.prompt.placeholder')}
@@ -104,3 +74,86 @@ export const SpaceHomePrompt = ({ space }: SpaceScopedProps) => {
 };
 
 SpaceHomePrompt.displayName = 'SpaceHomePrompt';
+
+type UseDraftSendProps = {
+  space?: Space;
+  draft?: { feed: Feed.Feed; chat: Chat.Chat };
+  context?: AiContext.Binder;
+  onSent: () => void;
+};
+
+/** Stores the draft's chat and bindings, then opens it; a failed send removes what it stored and restores the text. */
+const useDraftSend = ({ space, draft, context, onSent }: UseDraftSendProps) => {
+  const { invokePromise } = Hooks.useOperationInvoker();
+  const atomRegistry = Hooks.useCapability(Capabilities.AtomRegistry);
+  const stateAtom = Hooks.useCapability(AssistantCapabilities.State);
+  const event = useMemo(() => new Event<ChatEvent>(), []);
+  useEffect(() => {
+    return event.on((ev) => {
+      if (ev.type !== 'submit') {
+        return;
+      }
+      const text = ev.text.trim();
+      if (!space || !draft || !context || text.length === 0) {
+        return;
+      }
+
+      const { feed, chat } = draft;
+      space.db.add(feed);
+      space.db.add(chat);
+      const chatPath = getChatPath(space.db.spaceId, chat.id);
+      onSent();
+      void context
+        .flush()
+        .then(() => {
+          atomRegistry.update(stateAtom, (current) => ({
+            ...current,
+            pendingPrompts: { ...current.pendingPrompts, [chatPath]: text },
+          }));
+          void invokePromise(LayoutOperation.Open, { subject: [chatPath] });
+        })
+        .catch((err) => {
+          log.catch(err);
+          space.db.remove(chat);
+          space.db.remove(feed);
+          event.emit({ type: 'update-prompt', text });
+        });
+    });
+  }, [event, space, draft, context, atomRegistry, stateAtom, invokePromise, onSent]);
+  return event;
+};
+
+type UseDraftContextProps = {
+  db?: Database.Database;
+  draft?: { feed: Feed.Feed; chat: Chat.Chat };
+  registry: AtomRegistry.AtomRegistry;
+  pluginManager: boolean;
+};
+
+const useDraftContext = ({ db, draft, registry, pluginManager }: UseDraftContextProps) => {
+  const [context, setContext] = useState<AiContext.Binder>();
+  UiHooks.useAsyncEffect(
+    async (controller) => {
+      if (!db || !draft) {
+        return;
+      }
+      const runtime = await EffectEx.runAndForwardErrors(
+        Effect.context<Database.Service>().pipe(Effect.provide(Database.layer(db))),
+      );
+      const binder = new AiContext.Binder({ feed: draft.feed, runtime, registry, hold: true });
+      await binder.open();
+      await bindChatDefaults(binder, { chat: draft.chat, pluginManager });
+      if (controller.signal.aborted) {
+        void binder.close();
+        return;
+      }
+      setContext(binder);
+      return () => {
+        setContext(undefined);
+        void binder.close();
+      };
+    },
+    [db, draft, registry, pluginManager],
+  );
+  return context;
+};

package/src/hooks/index.ts

@@ -5,7 +5,7 @@
 
 export * from './useSkillRegistry.ts';
 export * from './useChatKeymap.ts';
-export * from './useChatProcessor.ts';
+export * from './useChatModel.ts';
 export * from './useChatServices.ts';
 export * from './useChatToolbarActions.ts';
 export * from './useContextBinder.ts';
@@ -21,4 +21,4 @@ export * from './useHomeSuggestions.ts';
 export * from './useProcessEphemeralStatus.ts';
 export * from './useSessionTimeline.ts';
 
-export { type AiChatProcessor } from '../processor/index.ts';
+export { type ChatModel } from '../chat-model/index.ts';

package/src/hooks/{useChatProcessor.ts → useChatModel.ts}

@@ -23,23 +23,23 @@ import * as UiHooks from '@dxos/react-ui/Hooks';
 
 import { Assistant } from '#types';
 
-import { AiChatProcessor, type AiServicePreset } from '../processor/index.ts';
+import { type AiServicePreset, ChatModel } from '../chat-model/index.ts';
 
-export type UseChatProcessorProps = {
+export type UseChatModelProps = {
   db?: Database.Database;
   chat?: Chat.Chat;
   preset?: AiServicePreset;
   runtime?: Capabilities.ProcessManagerRuntime;
   registry?: Registry.Registry;
   settings?: Assistant.Settings;
-  /** Attributes the prompts submitted through this processor to a person (see `AiChatProcessorOptions.sender`). */
+  /** Attributes the prompts submitted through this chat model to a person (see `ChatModelOptions.sender`). */
   sender?: AgentService.PromptSender;
 };
 
 /**
- * Configure and create AiChatProcessor.
+ * Configure and create ChatModel.
  */
-export const useChatProcessor = ({
+export const useChatModel = ({
   db,
   chat,
   preset,
@@ -47,7 +47,7 @@ export const useChatProcessor = ({
   registry,
   settings,
   sender,
-}: UseChatProcessorProps): AiChatProcessor | undefined => {
+}: UseChatModelProps): ChatModel | undefined => {
   const observableRegistry = useContext(RegistryContext);
 
   // Reactive subscription — re-renders when the feed ref resolves. Direct `.target` reads are not reactive.
@@ -79,11 +79,12 @@ export const useChatProcessor = ({
   }, [db, chat, feed]);
 
   const serviceResolver = Hooks.useCapability(Capabilities.ServiceResolver);
-  // Primitives rather than the object, so an inline `sender` literal does not rebuild the processor each render.
+  // Primitives rather than the object, so an inline `sender` literal does not rebuild the chat model each render.
   const senderName = sender?.name;
   const senderDid = sender?.identityDid;
+  const reportStruggles = settings?.reportStruggles ?? false;
 
-  const processor = useMemo(() => {
+  const chatModel = useMemo(() => {
     if (!runtime || !session || !chat || !feed || !db) {
       return undefined;
     }
@@ -98,8 +99,8 @@ export const useChatProcessor = ({
       OpaqueToolkit.OpaqueToolkitProvider,
     ).pipe(Layer.provide(Layer.succeed(ServiceResolver.ServiceResolver, serviceResolver)));
 
-    log('creating processor', { preset, model: preset?.model, settings });
-    return new AiChatProcessor(session, runtime, feed, spaceLayer, {
+    log('creating chat model', { preset, model: preset?.model, settings });
+    return new ChatModel(session, runtime, feed, spaceLayer, {
       chat: chat ? Ref.make(chat) : undefined,
       observableRegistry,
       registry,
@@ -110,13 +111,14 @@ export const useChatProcessor = ({
         senderName || senderDid
           ? { ...(senderName ? { name: senderName } : {}), ...(senderDid ? { identityDid: senderDid } : {}) }
           : undefined,
+      reportStruggles,
     });
-  }, [runtime, session, registry, preset, chat, feed, db?.spaceId, senderName, senderDid]);
+  }, [runtime, session, registry, preset, chat, feed, db?.spaceId, senderName, senderDid, reportStruggles]);
 
-  // A remount (e.g. the user navigated to another page mid-turn) gets a fresh processor whose
+  // A remount (e.g. the user navigated to another page mid-turn) gets a fresh chat model whose
   // active/streaming state starts empty, while the agent process for the feed keeps running;
   // adopting it restores the running indicator and the streamed blocks.
-  useEffect(() => processor?.adopt(), [processor]);
+  useEffect(() => chatModel?.adopt(), [chatModel]);
 
-  return processor;
+  return chatModel;
 };

package/src/hooks/useDebug.ts

@@ -6,23 +6,23 @@ import { useCallback } from 'react';
 
 import { trim } from '@dxos/util';
 
-import { type AiChatProcessor } from '../processor/index.ts';
+import { type ChatModel } from '../chat-model/index.ts';
 
 /**
  * Returns an async callback that logs the chat's current context, system prompt,
  * and resolved tools to the browser console under a collapsible group.
  * Used by the chat's debug-toggle event handler.
  */
-export const useDebug = ({ processor }: { processor?: AiChatProcessor }) => {
+export const useDebug = ({ chatModel }: { chatModel?: ChatModel }) => {
   return useCallback(async () => {
-    if (!processor) {
+    if (!chatModel) {
       return;
     }
 
-    const objects = processor.context.getObjects();
-    const skills = processor.context.getSkills();
-    const system = await processor.getSystemPrompt();
-    const tools = (await processor.getTools()) ?? {};
+    const objects = chatModel.context.getObjects();
+    const skills = chatModel.context.getSkills();
+    const system = await chatModel.getSystemPrompt();
+    const tools = (await chatModel.getTools()) ?? {};
     console.group('Chat', { objects, skills });
     try {
       console.log(trim`
@@ -38,5 +38,5 @@ export const useDebug = ({ processor }: { processor?: AiChatProcessor }) => {
     } finally {
       console.groupEnd();
     }
-  }, [processor]);
+  }, [chatModel]);
 };

package/src/hooks/useHomeSuggestions.ts

@@ -9,7 +9,7 @@ import { type Space } from '@dxos/react-client/echo';
 import * as UiHooks from '@dxos/react-ui/Hooks';
 
 import { meta } from '#meta';
-import { AssistantOperation } from '#types';
+import { AssistantCapabilities, AssistantOperation } from '#types';
 
 const FALLBACK_SUGGESTION_KEYS = [
   'space-home.suggestion-magazine.label',
@@ -17,31 +17,36 @@ const FALLBACK_SUGGESTION_KEYS = [
 ] as const;
 
 /**
- * Returns starter prompts for the space Home page. Returns undefined while the request is in flight
- * so the section stays hidden until settled. On success yields generated prompts; on empty result or
- * error falls back to the hardcoded defaults.
+ * Returns starter prompts for the space Home page: the space's cached prompts at once, then the
+ * operation's answer once it settles (generated prompts, or the hardcoded defaults on an empty result
+ * or error). Undefined while nothing is cached and the request is in flight.
  */
 export const useHomeSuggestions = (space?: Space): readonly string[] | undefined => {
   const { t } = UiHooks.useTranslation(meta.profile.key);
   const { invokePromise } = Hooks.useOperationInvoker();
+  const cache = Hooks.useOptionalAtomCapability(AssistantCapabilities.HomeSuggestionsCache);
   const fallbacks = useMemo(() => FALLBACK_SUGGESTION_KEYS.map((key) => t(key)), [t]);
-  const [suggestions, setSuggestions] = useState<readonly string[] | undefined>(undefined);
+  const [settled, setSettled] = useState<{ spaceId: string; prompts: readonly string[] }>();
 
   UiHooks.useAsyncEffect(
     async (controller) => {
-      setSuggestions(undefined);
       if (!space) {
         return;
       }
-      const result = await invokePromise(AssistantOperation.GenerateHomeSuggestions, {}, { spaceId: space.db.spaceId });
+      const spaceId = space.db.spaceId;
+      const result = await invokePromise(AssistantOperation.GenerateHomeSuggestions, {}, { spaceId });
       if (controller.signal.aborted) {
         return;
       }
       const prompts = result.data?.prompts;
-      setSuggestions(prompts && prompts.length > 0 ? prompts : fallbacks);
+      setSettled({ spaceId, prompts: prompts && prompts.length > 0 ? prompts : fallbacks });
     },
     [space, invokePromise],
   );
 
-  return suggestions;
+  const spaceId = space?.db.spaceId;
+  if (!spaceId) {
+    return undefined;
+  }
+  return settled?.spaceId === spaceId ? settled.prompts : cache?.[spaceId]?.prompts;
 };

package/src/hooks/usePresets.ts

@@ -24,7 +24,7 @@ import {
   presetsForProvider,
   providerForModel,
   resolveProvider,
-} from '../processor/index.ts';
+} from '../chat-model/index.ts';
 
 export type UsePresets = {
   preset: AiServicePreset | undefined;
@@ -38,7 +38,7 @@ export type UsePresets = {
 export const usePresets = (settings: Assistant.Settings, chat?: Chat.Chat): UsePresets => {
   const { t } = UiHooks.useTranslation(meta.profile.key);
   // Subscribed rather than read: the picker has to follow a selection made on another mount of the
-  // same chat, and the stamp the processor writes before the first request.
+  // same chat, and the stamp the chat model writes before the first request.
   const [session] = useObject(chat, 'session');
   const chatModel = session?.model;
 

package/src/hooks/useProcessEphemeralStatus.ts

@@ -60,7 +60,7 @@ const resolveSubscribePids = (agentPid: Process.ID, processes: readonly Process.
 const attachActiveHandle = (
   processManager: ProcessManager.Manager,
   pid: Process.ID,
-): Effect.Effect<Process.Handle<any, any, never> | undefined> =>
+): Effect.Effect<Process.Process<any, any, never> | undefined> =>
   Effect.gen(function* () {
     const maxAttempts = 15;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {

package/src/hooks/useSelectionContext.ts

@@ -10,7 +10,7 @@ import { Obj } from '@dxos/echo';
 import * as AttentionCapabilities from '@dxos/plugin-attention/AttentionCapabilities';
 import { Selection } from '@dxos/react-ui-attention/types';
 
-import { type ProcessorRequestContext } from '../processor/index.ts';
+import { type ChatRequestContext } from '../chat-model/index.ts';
 
 /** Resolve `object`'s selection to text via the AnchorResolver contributed for its typename. */
 export const getSelectionContext = ({
@@ -21,7 +21,7 @@ export const getSelectionContext = ({
   object: Obj.Unknown;
   selection: Selection.Selection | undefined;
   resolvers: readonly AppCapabilities.AnchorResolver[];
-}): ProcessorRequestContext | undefined => {
+}): ChatRequestContext | undefined => {
   const typename = Obj.getTypename(object);
   const resolver = typename ? resolvers.find((candidate) => candidate.key === typename) : undefined;
   if (!resolver) {
@@ -55,9 +55,7 @@ export const getSelectionContext = ({
 };
 
 /** Submit-time provider of the companion object's current selection as request context. */
-export const useSelectionContext = (
-  companionTo: Obj.Unknown | undefined,
-): (() => ProcessorRequestContext | undefined) => {
+export const useSelectionContext = (companionTo: Obj.Unknown | undefined): (() => ChatRequestContext | undefined) => {
   // getAll-style lookup: absent capabilities yield empty arrays so non-companion chats stay inert.
   const [viewState] = Hooks.useCapabilities(AttentionCapabilities.ViewState);
   const resolvers = Hooks.useCapabilities(AppCapabilities.AnchorResolver);