@dxos/plugin-assistant 0.13.0 → 0.14.0

package/src/chat-model/testing/harness.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import type * as Scope from 'effect/Scope';
+
+import { AiService, OpaqueToolkit } from '@dxos/ai';
+import type * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as Plugin from '@dxos/app-framework/Plugin';
+import * as PluginManager from '@dxos/app-framework/PluginManager';
+import { ProcessManager } from '@dxos/compute-runtime';
+import * as AgentService from '@dxos/compute/AgentService';
+import * as Credential from '@dxos/compute/Credential';
+import * as Operation from '@dxos/compute/Operation';
+import * as ServiceResolver from '@dxos/compute/ServiceResolver';
+import { Database, Registry } from '@dxos/echo';
+
+import { type SpaceServices } from '../chat-model.ts';
+
+type BaseSpaceServices = Exclude<SpaceServices, AgentService.AgentService>;
+
+/** The ambient services a chat model needs besides the agent service. */
+const pickBaseServices = Effect.map(Effect.context<BaseSpaceServices>(), (services) =>
+  Layer.succeedContext(
+    Context.pick(
+      Database.Service,
+      Credential.CredentialsService,
+      AiService.AiService,
+      Registry.Service,
+      OpaqueToolkit.OpaqueToolkitProvider,
+    )(services),
+  ),
+);
+
+/** The chat model's space layer over the ambient services, including the real agent service. */
+export const makeSpaceLayer: Effect.Effect<Layer.Layer<SpaceServices>, never, SpaceServices> = Effect.gen(function* () {
+  const base = yield* pickBaseServices;
+  const agentService = yield* AgentService.AgentService;
+  return Layer.mergeAll(base, Layer.succeed(AgentService.AgentService, agentService));
+});
+
+/** The chat model's space layer with a stub agent service, to script the trace stream directly. */
+export const makeStubSpaceLayer = (
+  agentService: AgentService.Service,
+): Effect.Effect<Layer.Layer<SpaceServices>, never, BaseSpaceServices> =>
+  Effect.map(pickBaseServices, (base) => Layer.mergeAll(base, Layer.succeed(AgentService.AgentService, agentService)));
+
+/**
+ * A sound {@link Capabilities.ProcessManagerRuntime} for tests: a `ManagedRuntime` over the
+ * assistant test layer's process services plus a bare `PluginManager` for the capability/plugin
+ * tags. Scoped so the runtime is disposed with the test.
+ */
+export const makeTestRuntime: Effect.Effect<
+  Capabilities.ProcessManagerRuntime,
+  never,
+  ProcessManager.Service | Operation.Service | ServiceResolver.ServiceResolver | Scope.Scope
+> = Effect.gen(function* () {
+  const services = yield* Effect.context<
+    ProcessManager.Service | Operation.Service | ServiceResolver.ServiceResolver
+  >();
+  const manager = PluginManager.make({
+    pluginLoader: (id: string) => Effect.die(new Error(`No plugins in test runtime: ${id}`)),
+    plugins: [],
+  });
+  const runtime: Capabilities.ProcessManagerRuntime = ManagedRuntime.make(
+    Layer.mergeAll(
+      Layer.succeedContext(services),
+      Layer.succeed(Capability.Service, manager.capabilities),
+      Layer.succeed(Plugin.Service, manager),
+    ),
+  );
+  yield* Effect.addFinalizer(() =>
+    Effect.promise(() => (runtime as ManagedRuntime.ManagedRuntime<never, never>).dispose()),
+  );
+  return runtime;
+});

package/src/{processor → chat-model}/thread.test.ts

@@ -578,7 +578,7 @@ const sortText = (messages: Message.Message[]) => text(Array.sort(messages, byAp
 
 const statusOf = (message: Message.Message) => getDelivery(message);
 
-/** A prompt as `AiChatProcessor.send` holds it, submitted while the feed held `known`. */
+/** A prompt as `ChatModel.send` holds it, submitted while the feed held `known`. */
 const outboxEntry = (text: string, known: readonly Message.Message[]): OutboxEntry => ({
   id: Obj.ID.random(),
   created: new Date(clock++).toISOString(),

package/src/components/Chat/Chat.tsx

@@ -35,6 +35,7 @@ import {
 import { ActionToolbar, type ActionToolbarProps, createMenuAction } from '@dxos/react-ui-menu';
 import { TaskList, TaskQuestion } from '@dxos/react-ui-task';
 import * as UiHooks from '@dxos/react-ui/Hooks';
+import * as Layout from '@dxos/react-ui/Layout';
 import * as Toast from '@dxos/react-ui/Toast';
 import * as Util from '@dxos/react-ui/Util';
 import { Message, Task } from '@dxos/types';
@@ -44,15 +45,15 @@ import { type ChatSwitcher, useChatToolbarActions, useDebug } from '#hooks';
 import { meta } from '#meta';
 import { AssistantOperation } from '#types';
 
-import { TaskSlashCommands } from '../../commands/index.ts';
 import {
   AiUsageQuotaError,
-  type ProcessorRequestContext,
-  getProcessorState,
+  type ChatRequestContext,
+  getChatModelState,
   projectAlarms,
   projectSelfWakes,
   resolveRewind,
-} from '../../processor/index.ts';
+} from '../../chat-model/index.ts';
+import { TaskSlashCommands } from '../../commands/index.ts';
 import {
   ChatStatus,
   DEFAULT_MAX_QUEUE,
@@ -78,7 +79,7 @@ import { SurfaceWidget } from './SurfaceWidget.tsx';
 //
 
 type ChatRootProps = PropsWithChildren<
-  Pick<ChatContextValue, 'chat' | 'processor' | 'debug'> & {
+  Pick<ChatContextValue, 'chat' | 'chatModel' | 'debug'> & {
     /** Fallback database when the chat is transient (not yet persisted). */
     db?: Database.Database;
     onEvent?: (event: ChatEvent) => void;
@@ -88,14 +89,14 @@ type ChatRootProps = PropsWithChildren<
      */
     onSubmit?: (text: string) => Promise<void> | void;
     /** Called at submit time to capture ephemeral request context (e.g. companion selection). */
-    getContext?: () => ProcessorRequestContext | undefined;
+    getContext?: () => ChatRequestContext | undefined;
   }
 >;
 
 const ChatRoot = ({
   children,
   chat,
-  processor,
+  chatModel,
   db: dbFallback,
   debug: debugProp,
   onEvent,
@@ -106,12 +107,12 @@ const ChatRoot = ({
   const [debug, setDebug] = useState(debugProp ?? false);
   // Slash commands run their operations through the same invoker the rest of the UI uses.
   const { invokePromise } = Hooks.useOperationInvoker();
-  const processorState = getProcessorState(processor);
-  const streaming = useAtomValue(processorState.streaming);
-  const active = useAtomValue(processorState.active);
+  const chatModelState = getChatModelState(chatModel);
+  const streaming = useAtomValue(chatModelState.streaming);
+  const active = useAtomValue(chatModelState.active);
   const requestTiming = useRequestTiming({ active });
   const lastPrompt = useRef<string | undefined>(undefined);
-  // A slash command runs outside the processor, so `streaming` does not cover it.
+  // A slash command runs outside the chat model, so `streaming` does not cover it.
   const commandPending = useRef(false);
   // Transient chats have no database of their own; fall back to the supplied space db so
   // the message query and context controls operate before the chat is persisted.
@@ -133,15 +134,15 @@ const ChatRoot = ({
     db,
     feed ? Query.select(Filter.type(Alarm.Alarm)).from(feed) : Query.select(Filter.nothing()),
   );
-  // The processor queries the feed and reconciles it with the streamed turn and the outbox.
-  const { messages, delivery, queued, tail } = useAtomValue(processorState.thread);
+  // The chat model queries the feed and reconciles it with the streamed turn and the outbox.
+  const { messages, delivery, queued, tail } = useAtomValue(chatModelState.thread);
   const alarms = useMemo(() => projectAlarms({ feedAlarms }), [feedAlarms]);
   const selfWakes = useMemo(() => projectSelfWakes({ feedAlarms, messages }), [feedAlarms, messages]);
 
-  const dump = useDebug({ processor });
+  const dump = useDebug({ chatModel });
 
-  // Surface processor failures (e.g., AI service unavailable) to subscribers via the event bus.
-  const error = useAtomValue(processorState.error);
+  // Surface chat model failures (e.g., AI service unavailable) to subscribers via the event bus.
+  const error = useAtomValue(chatModelState.error);
   useEffect(() => {
     if (Option.isSome(error)) {
       event.emit({ type: 'error', error: error.value });
@@ -188,7 +189,7 @@ const ChatRoot = ({
               void db.removeFeedItemsByIds(feed, [row.entryId]).catch((err) => log.catch(err));
             }
             if (row.outboxId) {
-              processor?.removePrompt(row.outboxId);
+              chatModel?.removePrompt(row.outboxId);
             }
           }
           break;
@@ -199,7 +200,7 @@ const ChatRoot = ({
     });
     // `feed`, `messages` and `delivery` are dependencies because the rewind and prompt branches read
     // them: without them the handler would keep resolving against whatever was mounted first.
-  }, [event, dump, onEvent, db, feed, messages, delivery, processor]);
+  }, [event, dump, onEvent, db, feed, messages, delivery, chatModel]);
 
   useEffect(() => {
     return event.on((ev) => {
@@ -222,7 +223,7 @@ const ChatRoot = ({
   }, [event, chat, invokePromise]);
 
   useEffect(() => {
-    if (!processor) {
+    if (!chatModel) {
       return;
     }
 
@@ -275,7 +276,7 @@ const ChatRoot = ({
                 if (result.followUp) {
                   // Some effects run on the supervisor loop (delegation spawns post-turn), so the
                   // command wakes the conversation with a short synthetic prompt.
-                  void processor.request({ message: result.followUp });
+                  void chatModel.request({ message: result.followUp });
                 }
               })()
                 .catch((error) => {
@@ -293,9 +294,9 @@ const ChatRoot = ({
             markWork('chat.submit');
             lastPrompt.current = ev.text;
             // Optimistic: the prompt is in the thread from this call on, before `onSubmit` persists a
-            // transient chat and before the agent acknowledges it. The processor requests it when the
+            // transient chat and before the agent acknowledges it. The chat model requests it when the
             // agent is idle and queues it behind a running turn otherwise.
-            processor.send({ message: text, context: getContext?.() }, { prepare: () => onSubmit?.(text) });
+            chatModel.send({ message: text, context: getContext?.() }, { prepare: () => onSubmit?.(text) });
           }
           break;
         }
@@ -307,8 +308,8 @@ const ChatRoot = ({
             // content is synthetic — nobody typed it.
             void Promise.resolve(onSubmit?.(text)).then(() =>
               active
-                ? processor.enqueue({ message: text, disposition: 'synthetic' })
-                : processor.request({ message: text, disposition: 'synthetic' }),
+                ? chatModel.enqueue({ message: text, disposition: 'synthetic' })
+                : chatModel.request({ message: text, disposition: 'synthetic' }),
             );
           }
           break;
@@ -316,13 +317,13 @@ const ChatRoot = ({
 
         case 'retry': {
           if (!streaming) {
-            void processor.retry();
+            void chatModel.retry();
           }
           break;
         }
 
         case 'cancel': {
-          void processor.cancel();
+          void chatModel.cancel();
           if (streaming) {
             if (lastPrompt.current) {
               event.emit({ type: 'update-prompt', text: lastPrompt.current });
@@ -332,7 +333,7 @@ const ChatRoot = ({
         }
       }
     });
-  }, [event, processor, streaming, active, queued, onSubmit, getContext, invokePromise, chat, db, feed]);
+  }, [event, chatModel, streaming, active, queued, onSubmit, getContext, invokePromise, chat, db, feed]);
 
   // An inline surface (connector prompt, plugin prompt) reports its completed flow as a synthetic
   // turn, so the agent resumes without the report reading as something the user typed.
@@ -344,8 +345,9 @@ const ChatRoot = ({
       event={event}
       db={db}
       chat={chat}
-      processor={processor}
+      chatModel={chatModel}
       queueSize={queued}
+      started={messages.length > 0 || queued > 0}
       setController={setController}
       setVisibleRange={setVisibleRange}
       {...props}
@@ -537,7 +539,7 @@ type ChatThreadProps = Util.ThemedClassName<{
 
 const ChatThread = ({ classNames, viewType, tailLines, userHue: userHueProp, onViewUsage }: ChatThreadProps) => {
   const { t } = UiHooks.useTranslation(meta.profile.key);
-  const { chat, db, debug, event, processor, setController, setVisibleRange } = useChatContext(CHAT_THREAD_NAME);
+  const { chat, db, debug, event, chatModel, setController, setVisibleRange } = useChatContext(CHAT_THREAD_NAME);
   const { messages, tail } = useChatThreadContext(CHAT_THREAD_NAME);
   const identity = useIdentity();
   // Embedded objects resolve against the chat's database (the fallback one while it is transient).
@@ -565,7 +567,7 @@ const ChatThread = ({ classNames, viewType, tailLines, userHue: userHueProp, onV
   // arrive as updates on one identity, and the window is told — the old `MessageSyncer`'s cursor
   // and range table have no equivalent left.
   const model = useFeedModel(messages, { stops: 'prompt' });
-  const streaming = useAtomValue(getProcessorState(processor).streaming);
+  const streaming = useAtomValue(getChatModelState(chatModel).streaming);
   useEffect(() => {
     // The answer streams above any prompts still waiting for the agent, which end the thread.
     const last = messages[messages.length - 1 - tail];
@@ -717,7 +719,10 @@ ChatOutline.displayName = CHAT_OUTLINE_NAME;
 
 const CHAT_PROMPT_NAME = 'Chat.Prompt';
 
-type ChatPromptProps = Omit<NaturalChatPromptProps, 'chat' | 'db' | 'processor' | 'event' | 'tasksVisible'> & {
+type ChatPromptProps = Omit<
+  NaturalChatPromptProps,
+  'chat' | 'db' | 'chatModel' | 'event' | 'tasksVisible' | 'started'
+> & {
   /** Whether the checklist is disclosed on mount. */
   defaultTasksVisible?: boolean;
 };
@@ -734,7 +739,7 @@ type ChatPromptProps = Omit<NaturalChatPromptProps, 'chat' | 'db' | 'processor'
  * event rather than being wrapped in a `Collapsible.Trigger` it cannot reach.
  */
 const ChatPrompt = ({ classNames, defaultTasksVisible = false, ...props }: ChatPromptProps) => {
-  const { chat, db, processor, event, queueSize } = useChatContext(CHAT_PROMPT_NAME);
+  const { chat, db, chatModel, event, queueSize, started } = useChatContext(CHAT_PROMPT_NAME);
 
   // A chat with no checklist at all has nothing to disclose, so the toggle is withheld rather than
   // shown pointing at nothing — `ChatActions` renders it only when `tasksVisible` is defined.
@@ -774,9 +779,10 @@ const ChatPrompt = ({ classNames, defaultTasksVisible = false, ...props }: ChatP
         classNames={[tasksVisible && 'rounded-t-none', classNames]}
         db={db}
         chat={chat}
-        processor={processor}
+        chatModel={chatModel}
         event={event}
         queueSize={queueSize}
+        started={started}
         tasksVisible={hasTasks ? tasksVisible : undefined}
       />
     </Collapsible.Root>
@@ -939,7 +945,7 @@ const ChatTaskQuestions = ({ tasks }: { tasks: readonly Task.Task[] }) => {
   }
 
   return (
-    <div className='flex flex-col gap-2 p-2' data-testid='chat.taskQuestions'>
+    <Layout.Flex column gap='sm' classNames='p-2' data-testid='chat.taskQuestions'>
       {threads.map(({ task, thread }) => (
         <TaskQuestion
           key={thread.question.id}
@@ -947,7 +953,7 @@ const ChatTaskQuestions = ({ tasks }: { tasks: readonly Task.Task[] }) => {
           onAnswer={(answer) => handleAnswer(task, thread.question.id, answer)}
         />
       ))}
-    </div>
+    </Layout.Flex>
   );
 };
 
@@ -960,14 +966,14 @@ ChatTaskQuestions.displayName = 'Chat.TaskQuestions';
 const CHAT_ACTIVITY_NAME = 'Chat.Activity';
 
 /**
- * The activity line bound to the chat's processor and the chat's pending alarms: what the agent is
+ * The activity line bound to the chat's chat model and the chat's pending alarms: what the agent is
  * doing, for as long as it is doing anything. The line itself takes resolved values, so it lives
  * beside the prompt with the rest of the presentational parts and only the binding is here.
  */
 const ChatActivity = ({ classNames }: Util.ThemedClassName) => {
-  const { processor } = useChatContext(CHAT_ACTIVITY_NAME);
+  const { chatModel } = useChatContext(CHAT_ACTIVITY_NAME);
   const { alarms } = useChatThreadContext(CHAT_ACTIVITY_NAME);
-  const activity = useAtomValue(getProcessorState(processor).activity);
+  const activity = useAtomValue(getChatModelState(chatModel).activity);
 
   // Earliest pending alarm: the agent wakes at the first one, so a later one says nothing about the
   // wait in front of the reader.

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

@@ -12,7 +12,7 @@ import * as Toast from '@dxos/react-ui/Toast';
 import { meta as pluginMeta } from '#meta';
 import { translations } from '#translations';
 
-import { AiUsageQuotaError, parseError } from '../../processor/index.ts';
+import { AiUsageQuotaError, parseError } from '../../chat-model/index.ts';
 
 type FailureToastProps = {
   /**

package/src/components/Chat/context.ts

@@ -11,7 +11,7 @@ import { type ChatThreadController } from '@dxos/react-ui-assistant';
 import { type MessageRange } from '@dxos/react-ui-feed';
 import { type Message } from '@dxos/types';
 
-import { type AiChatProcessor } from '../../processor/index.ts';
+import { type ChatModel } from '../../chat-model/index.ts';
 import { type ChatEvent } from './events.ts';
 
 /**
@@ -36,8 +36,10 @@ export type ChatContextValue = {
   event: Event<ChatEvent>;
   db?: Database.Database;
   chat?: Chat.Chat;
-  /** Undefined while the processor is still opening; the chat renders from the feed meanwhile. */
-  processor?: AiChatProcessor;
+  /** Undefined while the chat model is still opening; the chat renders from the feed meanwhile. */
+  chatModel?: ChatModel;
+  /** Whether the conversation has begun; a boolean, so it changes once rather than per message. */
+  started: boolean;
   /** How many prompts wait behind the running turn; a count, so it changes per enqueue rather than per block. */
   queueSize: number;
   setController: (controller: ChatThreadController | null) => void;

package/src/components/ChatPrompt/ChatActions.tsx

@@ -37,7 +37,7 @@ export type ChatActionsProps = Util.ThemedClassName<
     customActions?: Atom.Atom<ActionGraphProps>;
     processing?: boolean;
     debug?: boolean;
-    /** Whether the prompt holds text and the processor would accept it; drives the send control's enablement. */
+    /** Whether the prompt holds text and the chat model would accept it; drives the send control's enablement. */
     canSend?: boolean;
     /** Whether the checklist beside the prompt is shown; the toggle renders only when provided. */
     tasksVisible?: boolean;

package/src/components/ChatPrompt/ChatMcpErrors.tsx

@@ -12,23 +12,23 @@ import type * as Util from '@dxos/react-ui/Util';
 
 import { meta } from '#meta';
 
-import { type AiChatProcessor } from '../../processor/index.ts';
+import { type ChatModel } from '../../chat-model/index.ts';
 
 export type ChatMcpErrorsProps = Util.ThemedClassName<{
-  processor: AiChatProcessor;
+  chatModel: ChatModel;
 }>;
 
 /**
  * Inline banner that lists MCP servers that failed to connect during the most recent request.
  * The chat itself keeps working without these servers — this just lets the user see what was dropped.
  */
-export const ChatMcpErrors = ({ classNames, processor }: ChatMcpErrorsProps) => {
+export const ChatMcpErrors = ({ classNames, chatModel }: ChatMcpErrorsProps) => {
   const { t } = Hooks.useTranslation(meta.profile.key);
-  const errors = useAtomValue(processor.mcpErrors);
+  const errors = useAtomValue(chatModel.mcpErrors);
 
   const handleDismiss = useCallback(() => {
-    processor.dismissMcpErrors();
-  }, [processor]);
+    chatModel.dismissMcpErrors();
+  }, [chatModel]);
 
   if (errors.length === 0) {
     return null;

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

@@ -7,6 +7,7 @@ import * as Effect from 'effect/Effect';
 import * as Atom from 'effect/reactivity/Atom';
 import React, { useState } from 'react';
 
+import { SessionConfig } from '@dxos/ai';
 import * as Capability from '@dxos/app-framework/Capability';
 import { withPluginManager } from '@dxos/app-framework/testing';
 import { capabilities } from '@dxos/assistant-toolkit/testing';
@@ -29,6 +30,19 @@ import { type Assistant, AssistantCapabilities } from '#types';
 
 import { ChatOptions, type ChatOptionsProps, ObjectsPanel } from './ChatOptions.tsx';
 
+/** Stands in for an agent another plugin registers: listed in the picker, never run by the story. */
+const stubAgent = (
+  id: string,
+  label: string,
+  availability: AssistantCapabilities.AgentAvailability,
+): AssistantCapabilities.Agent => ({
+  id,
+  label,
+  icon: id === SessionConfig.COMPOSER_HARNESS ? 'ph--sparkle--regular' : 'px--anthropic--regular',
+  availability: Atom.make(availability).pipe(Atom.keepAlive),
+  makeTurnProducer: () => Effect.succeed({ runTurn: () => Effect.succeed([]), getSkills: () => [] }),
+});
+
 const presets = [
   {
     id: 'edge-claude-sonnet',
@@ -44,9 +58,9 @@ const presets = [
   },
 ];
 
-type StoryArgs = Pick<ChatOptionsProps, 'presets'>;
+type StoryArgs = Pick<ChatOptionsProps, 'presets' | 'started'>;
 
-const DefaultStory = ({ presets }: StoryArgs) => {
+const DefaultStory = ({ presets, started }: StoryArgs) => {
   const [space] = useSpaces();
   const [feed] = useQuery(space?.db, Filter.type(Feed.Feed));
   const [chat] = useQuery(space?.db, Filter.type(Chat.Chat));
@@ -63,6 +77,7 @@ const DefaultStory = ({ presets }: StoryArgs) => {
       db={space.db}
       context={binder}
       registry={registry}
+      started={started}
       presets={presets}
       preset={preset}
       onPresetChange={setPreset}
@@ -72,7 +87,6 @@ const DefaultStory = ({ presets }: StoryArgs) => {
 
 const meta = {
   title: 'plugins/plugin-assistant/components/ChatOptions',
-  component: ChatOptions as any,
   render: DefaultStory,
   decorators: [
     withTheme(),
@@ -107,6 +121,18 @@ const meta = {
         ...capabilities,
         // The Models tab's online switch reads the assistant settings; without them it would suspend forever.
         Capability.contribute(AssistantCapabilities.Settings, Atom.make<Assistant.Settings>({}).pipe(Atom.keepAlive)),
+        Capability.contribute(
+          AssistantCapabilities.Agent,
+          stubAgent(SessionConfig.COMPOSER_HARNESS, 'Composer', { available: true }),
+        ),
+        Capability.contribute(
+          AssistantCapabilities.Agent,
+          stubAgent('claude-code', 'Claude Code', { available: false, reason: 'needs the Composer desktop app' }),
+        ),
+        Capability.contribute(
+          AssistantCapabilities.Agent,
+          stubAgent('claude-code-edge', 'Claude Code (cloud)', { available: true }),
+        ),
       ],
     }),
   ],
@@ -126,6 +152,14 @@ export const Default: Story = {
   },
 };
 
+/** A chat that has begun shows its agent but no longer offers the others. */
+export const Started: Story = {
+  args: {
+    presets,
+    started: true,
+  },
+};
+
 export const _ObjectsPanel: Story = {
   render: () => {
     const [space] = useSpaces();