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

package/src/capabilities/migrations.ts

@@ -1,28 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-
-import { Capability } from '@dxos/app-framework';
-import { Chat } from '@dxos/assistant-toolkit';
-import { Migration } from '@dxos/echo';
-import { ClientCapabilities } from '@dxos/plugin-client';
-
-const identityTransform = async (from: any) => ({ ...from });
-const noopCallback = async () => {};
-
-const migrations = [
-  Migration.define({
-    from: Chat.LegacyCompanionTo,
-    to: Chat.CompanionTo,
-    transform: identityTransform,
-    onMigration: noopCallback,
-  }),
-];
-
-export default Capability.makeModule(
-  Effect.fnUntraced(function* () {
-    return Capability.contributes(ClientCapabilities.Migration, migrations);
-  }),
-);

package/src/capabilities/navigation-resolver.ts

@@ -1,20 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-
-import { Capability } from '@dxos/app-framework';
-import { AppCapabilities, Paths, TypeSection } from '@dxos/app-toolkit';
-import { Chat } from '@dxos/assistant-toolkit';
-
-export default Capability.makeModule(
-  Effect.fnUntraced(function* () {
-    return [
-      Capability.contributes(
-        AppCapabilities.NavigationPathResolver,
-        TypeSection.createTypeSectionPathResolver(Chat.Chat, { groupId: Paths.GroupSegments.ai }),
-      ),
-    ];
-  }),
-);

package/src/capabilities/react-surface.tsx

@@ -1,177 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-import React, { type ComponentProps, useEffect } from 'react';
-
-import { Capabilities, Capability } from '@dxos/app-framework';
-import { Surface, useSettingsState } from '@dxos/app-framework/ui';
-import { AppSurface, useActiveSpace } from '@dxos/app-toolkit/ui';
-import { Agent, Chat, Plan } from '@dxos/assistant-toolkit';
-import { getSpace } from '@dxos/client/echo';
-import { Instructions } from '@dxos/compute';
-import { Sequence } from '@dxos/conductor';
-import { InvocationTraceContainer } from '@dxos/devtools';
-import { Feed, Obj } from '@dxos/echo';
-import { log } from '@dxos/log';
-import { SpaceHomeContent, SpaceHomePinBottom } from '@dxos/plugin-space';
-import { Panel } from '@dxos/react-ui';
-import { Position } from '@dxos/util';
-
-import {
-  AgentArticle,
-  AgentProperties,
-  AssistantSettings,
-  ChatArticle,
-  ChatCompanion,
-  ChatDialog,
-  IntegrationPrompt,
-  PlanArticle,
-  SpaceHomePrompt,
-  SpaceHomeSuggestions,
-  TracePanel,
-  TriggerStatus,
-} from '#containers';
-import { ASSISTANT_COMPANION_VARIANT, ASSISTANT_DIALOG, meta } from '#meta';
-import { type Assistant, ChatSurface } from '#types';
-
-export default Capability.makeModule(() =>
-  Effect.succeed(
-    Capability.contributes(Capabilities.ReactSurface, [
-      Surface.create({
-        id: 'pluginSettings',
-        filter: AppSurface.settings(AppSurface.Article, meta.profile.key),
-        component: ({ data: { subject } }) => {
-          const { settings, updateSettings } = useSettingsState<Assistant.Settings>(subject.atom);
-          return <AssistantSettings settings={settings} onSettingsChange={updateSettings} />;
-        },
-      }),
-      Surface.create({
-        id: 'spaceHomePrompt',
-        filter: Surface.makeFilter(SpaceHomePinBottom),
-        component: ({ data }) => <SpaceHomePrompt space={data.space} />,
-      }),
-      Surface.create({
-        id: 'spaceHomeSuggestions',
-        filter: Surface.makeFilter(SpaceHomeContent),
-        position: Position.last,
-        component: ({ data }) => <SpaceHomeSuggestions space={data.space} />,
-      }),
-      Surface.create({
-        id: 'chat',
-        filter: AppSurface.object(
-          AppSurface.Article,
-          Chat.Chat,
-          (data) => data.variant !== ASSISTANT_COMPANION_VARIANT,
-        ),
-        component: ({ data, role, ref }) => {
-          return <ChatArticle role={role} subject={data.subject} attendableId={data.attendableId} ref={ref} />;
-        },
-      }),
-      Surface.create({
-        id: 'agent',
-        filter: AppSurface.object(AppSurface.Article, Agent.Agent),
-        component: ({ data, role }) => (
-          <AgentArticle role={role} subject={data.subject} attendableId={data.attendableId} />
-        ),
-      }),
-      Surface.create({
-        id: 'objectProperties',
-        filter: AppSurface.object(AppSurface.ObjectProperties, Agent.Agent),
-        component: ({ data }) => <AgentProperties subject={data.subject} />,
-      }),
-      Surface.create({
-        id: 'companionChat',
-        filter: Surface.makeFilter(
-          AppSurface.Article,
-          (data) =>
-            Obj.isObject(data.companionTo) && (Obj.instanceOf(Chat.Chat, data.subject) || data.subject === null),
-        ),
-        component: ({ data: { subject, attendableId, companionTo }, role, ref }) => (
-          <ChatCompanion
-            role={role}
-            subject={subject}
-            attendableId={attendableId}
-            companionTo={companionTo}
-            ref={ref}
-          />
-        ),
-      }),
-      Surface.create({
-        id: 'companionInvocations',
-        filter: AppSurface.allOf(
-          AppSurface.literal(AppSurface.Article, 'invocations'),
-          AppSurface.oneOf(
-            AppSurface.companion(AppSurface.Article, Sequence.Sequence),
-            AppSurface.companion(AppSurface.Article, Instructions.Instructions),
-          ),
-        ),
-        component: ({ data, role }) => {
-          const space = getSpace(data.companionTo);
-          const feed = space?.properties.invocationTraceFeed?.target;
-          const feedDXN = feed ? Feed.getQueueUri(feed) : undefined;
-          // TODO(wittjosiah): Support invocation filtering for prompts.
-          const target = Obj.instanceOf(Instructions.Instructions, data.companionTo) ? undefined : data.companionTo;
-
-          return (
-            <Panel.Root role={role} className='dx-document'>
-              <Panel.Content>
-                <InvocationTraceContainer db={space?.db} feedDXN={feedDXN} target={target} detailAxis='block' />
-              </Panel.Content>
-            </Panel.Root>
-          );
-        },
-      }),
-      Surface.create({
-        id: 'plan',
-        filter: AppSurface.object(AppSurface.Article, Plan.Plan),
-        component: ({ data, role }) => (
-          <PlanArticle role={role} subject={data.subject} attendableId={data.attendableId} />
-        ),
-      }),
-      Surface.create({
-        id: ASSISTANT_DIALOG,
-        filter: AppSurface.component<ComponentProps<typeof ChatDialog>>(AppSurface.Dialog, ASSISTANT_DIALOG),
-        component: ({ data }) => <ChatDialog {...data.props} />,
-      }),
-      Surface.create({
-        id: 'trace',
-        filter: Surface.makeFilter(AppSurface.deckCompanion('trace')),
-        component: () => {
-          const space = useActiveSpace();
-          useEffect(() => {
-            log('trace panel surface', { hasSpace: Boolean(space), spaceId: space?.id });
-          }, [space?.id]);
-
-          if (!space) {
-            return null;
-          }
-
-          return <TracePanel space={space} />;
-        },
-      }),
-      Surface.create({
-        id: 'integrationPrompt',
-        filter: Surface.makeFilter(ChatSurface, (data) => data.role === 'integration-prompt'),
-        component: ({ data }) => {
-          // `data.data` is model-supplied JSON (untyped); narrow `service` before use.
-          const service = typeof data.data?.service === 'string' ? data.data.service : undefined;
-          return <IntegrationPrompt service={service} />;
-        },
-      }),
-      Surface.create({
-        id: 'triggerStatus',
-        filter: Surface.makeFilter(AppSurface.StatusIndicator),
-        component: () => {
-          const space = useActiveSpace();
-          if (!space) {
-            return null;
-          }
-
-          return <TriggerStatus role='status-indicator' space={space} />;
-        },
-      }),
-    ]),
-  ),
-);

package/src/components/ChatPrompt/ChatStatusIndicator.tsx

@@ -1,42 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React, { useEffect, useState } from 'react';
-
-import { type ThemedClassName, Tooltip, useTimeout } from '@dxos/react-ui';
-import { Spinner, type SpinnerProps } from '@dxos/react-ui-components';
-import { mx } from '@dxos/ui-theme';
-
-const period = 3_000;
-
-export type ChatStatusIndicatorProps = ThemedClassName<
-  {
-    preset?: string;
-    processing?: boolean;
-    error?: Error;
-  } & Pick<SpinnerProps, 'size' | 'onClick'>
->;
-
-export const ChatStatusIndicator = ({ classNames, preset, processing, error, ...props }: ChatStatusIndicatorProps) => {
-  const [init, setInit] = useState(false);
-  useEffect(() => setInit(false), [preset]);
-  useTimeout(
-    async () => {
-      setInit(true);
-    },
-    period / 2,
-    [preset],
-  );
-
-  return (
-    <div className={mx('relative flex', classNames)}>
-      <Spinner duration={period} state={!init ? 'flash' : error ? 'error' : processing ? 'spin' : 'pulse'} {...props} />
-      {error && (
-        <Tooltip.Trigger asChild content={error.message}>
-          <div className='absolute inset-0' />
-        </Tooltip.Trigger>
-      )}
-    </div>
-  );
-};

package/src/components/ChatThread/DEBUG.md

@@ -1,64 +0,0 @@
-# Dataflow from AI to Codemirror
-
-AiSession (packages/core/assistant/src/conversation/session.ts)
-│
-│ emits ephemeral Trace events containing
-│ PartialBlock { messageId, role, block: ContentBlock.Any }
-│ via AgentService.Session.subscribeEphemeral(): Stream<Trace.Message>
-▼
-AiChatProcessor (packages/plugins/plugin-assistant/src/processor/processor.ts)
-│
-│ Stream.runForEach → if Trace.isOfType(PartialBlock) →
-│ #handleEphemeralMessage(event.data)
-│ → upserts Message.Message into #streaming atom
-│ → finalizes into #messages atom on complete block
-▼
-Chat.tsx (packages/plugins/plugin-assistant/src/components/Chat/Chat.tsx)
-│
-│ reads processor.messages + processor.streaming atoms,
-│ passes flat Message[] down to ChatThread
-▼
-ChatThread.tsx (packages/plugins/plugin-assistant/src/components/ChatThread/ChatThread.tsx)
-│
-│ MessageSyncer (sync.ts) compares current messages
-│ to last rendered set:
-│ - new finalized chunk → controller.append(delta)
-│ - changed earlier message → controller.setContent(full)
-│ blockToMarkdown serializes ContentBlocks → markdown,
-│ embedding tool calls as XML widget tags
-│ (e.g. <tool-call name="...">...</tool-call>)
-▼
-MarkdownStreamController.append / setContent
-▼
-MarkdownStream (packages/ui/react-ui-markdown/src/MarkdownStream/MarkdownStream.tsx)
-│
-│ CodeMirror editor with:
-│ - extendedMarkdown (parseMixed → xmlLanguage on HTMLBlock/Paragraph)
-│ - xmlTags (registry → React/native widget portals)
-│ - wire extension (buffers appended text, drips at typewriter rate,
-│ treats XML atomic ranges as indivisible units)
-▼
-Rendered DOM (markdown + portaled widgets for tool calls / reasoning / etc.)
-
----
-
-# Ephemeral status subscriptions (TaskList / debug panel)
-
-ProcessHandle.pushEphemeral → subscribeEphemeral(): Stream<Trace.Message>
-│
-│ UI hooks fork a collector fiber from the stream inside useEffect
-▼
-useProcessEphemeralStatus (TaskList delegated rows)
-EphemeralDebugModule (storybook debug panel)
-│
-│ **Must use Effect.forkDaemon**, not Effect.fork, when the parent is
-│ `runtime.runPromise(Effect.forEach(subscribe))` — forEach returns as soon as
-│ each subscribe forks, closing the scope and interrupting scoped forks before
-│ live events arrive. forkDaemon survives until explicit Fiber.interrupt on dispose.
-│
-│ Same pattern as ProcessOperationInvoker.fiberFromProcess (output collector).
-▼
-resolveEphemeralStatusUpdate → TaskList activity line
-
-**Contrast:** processor.ts uses Effect.fork because its parent Effect.gen continues
-through submitPrompt + waitForCompletion, keeping the scope open for the whole turn.

package/src/containers/PlanArticle/PlanArticle.tsx

@@ -1,37 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import React from 'react';
-
-import { type AppSurface } from '@dxos/app-toolkit/ui';
-import { type Plan } from '@dxos/assistant-toolkit';
-import { getSpace } from '@dxos/client/echo';
-import { Panel, ScrollArea, Toolbar } from '@dxos/react-ui';
-import { useAttention } from '@dxos/react-ui-attention';
-
-import { TaskList } from '#components';
-import { useTraceMessages } from '#hooks';
-
-export type PlanArticleProps = AppSurface.ObjectArticleProps<Plan.Plan>;
-
-export const PlanArticle = ({ role, attendableId, subject }: PlanArticleProps) => {
-  const { hasAttention } = useAttention(attendableId);
-  const space = getSpace(subject);
-  const traceMessages = useTraceMessages(space);
-
-  return (
-    <Panel.Root role={role} classNames='dx-document'>
-      <Panel.Toolbar asChild>
-        <Toolbar.Root disabled={!hasAttention} />
-      </Panel.Toolbar>
-      <Panel.Content asChild>
-        <ScrollArea.Root orientation='vertical'>
-          <ScrollArea.Viewport>
-            <TaskList plan={subject} space={space} traceMessages={traceMessages} />
-          </ScrollArea.Viewport>
-        </ScrollArea.Root>
-      </Panel.Content>
-    </Panel.Root>
-  );
-};

package/src/containers/PlanArticle/index.ts

@@ -1,5 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-export { PlanArticle as default } from './PlanArticle';

package/src/hooks/useFlush.ts

@@ -1,35 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useCallback, useRef, useState } from 'react';
-
-import { type Space } from '@dxos/client/echo';
-
-export const useFlush = (space?: Space) => {
-  const [state, setState] = useState<'idle' | 'flushing' | 'flushed'>('idle');
-  const resetTimer = useRef<NodeJS.Timeout | null>(null);
-
-  const handleFlush = useCallback(() => {
-    if (!space) {
-      return;
-    }
-
-    queueMicrotask(async () => {
-      if (resetTimer.current) {
-        clearTimeout(resetTimer.current);
-      }
-
-      setState('flushing');
-      await space.db.flush();
-      setState('flushed');
-
-      resetTimer.current = setTimeout(() => {
-        setState('idle');
-        resetTimer.current = null;
-      }, 1_000);
-    });
-  }, [space]);
-
-  return { state, handleFlush };
-};

package/src/operations/resolve-navigation-targets.ts

@@ -1,44 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-
-import { Capability } from '@dxos/app-framework';
-import { AppCapabilities, AppSpace } from '@dxos/app-toolkit';
-import { Operation } from '@dxos/compute';
-import { Database, EID } from '@dxos/echo';
-import { ClientCapabilities } from '@dxos/plugin-client';
-
-import { AssistantOperation } from '#types';
-
-const handler: Operation.WithHandler<typeof AssistantOperation.ResolveNavigationTargets> =
-  AssistantOperation.ResolveNavigationTargets.pipe(
-    Operation.withHandler(
-      Effect.fn(function* ({ query }) {
-        const capabilities = yield* Capability.Service;
-        const client = yield* Capability.get(ClientCapabilities.Client).pipe(
-          Effect.catchAll(() => Effect.succeed(undefined)),
-        );
-
-        // Object resolvers read the space database to derive a navigation path, but the agent tool
-        // runtime does not bind Database.Service. Derive it from the queried object URI's space (or
-        // the active space for space-less URIs) so resolution works for object URIs.
-        const eid = query?.uri ? EID.tryParse(query.uri) : undefined;
-        const spaceId = eid ? EID.getSpaceId(eid) : undefined;
-        const space = client
-          ? ((spaceId ? client.spaces.get(spaceId) : undefined) ?? AppSpace.getActiveSpace(client, capabilities))
-          : undefined;
-
-        // Delegate to contributed resolvers.
-        const resolvers = capabilities.getAll(AppCapabilities.NavigationTargetResolver);
-        const resolve = Effect.forEach(resolvers, (resolver) =>
-          resolver(query).pipe(Effect.catchAll(() => Effect.succeed([]))),
-        );
-        const results = yield* space ? resolve.pipe(Effect.provide(Database.layer(space.db))) : resolve;
-        return { targets: results.flat() };
-      }),
-    ),
-  );
-
-export default handler;