@dxos/plugin-assistant 0.8.3 → 0.8.4-main.5acf9ea

package/src/hooks/chat-processor.ts

@@ -0,0 +1,314 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Signal, batch, computed, signal } from '@preact/signals-core';
+import { Effect, type Layer } from 'effect';
+
+import { AiService, DEFAULT_EDGE_MODEL, type ExecutableTool, type GenerateRequest } from '@dxos/ai';
+import { type PromiseIntentDispatcher } from '@dxos/app-framework';
+import { type AiSession, ArtifactDiffResolver, type ContextBinder, type Conversation } from '@dxos/assistant';
+import { type ArtifactDefinition, type Blueprint } from '@dxos/blueprints';
+import { Context } from '@dxos/context';
+import { Obj } from '@dxos/echo';
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+import { Filter, type Space, getVersion } from '@dxos/react-client/echo';
+import { DataType } from '@dxos/schema';
+
+import type { ChatServices } from './useChatServices';
+
+// TODO(burdon): Factor out.
+declare global {
+  interface ToolContextExtensions {
+    space?: Space;
+    dispatch?: PromiseIntentDispatcher;
+  }
+}
+
+type RequestOptions = {
+  // Empty for now.
+};
+
+export type ChatProcessorOptions = {
+  // TODO(burdon): Change to AiToolkit.
+  tools?: readonly ExecutableTool[];
+  blueprintRegistry?: Blueprint.Registry;
+
+  // TODO(dmaretskyi): Remove.
+  artifacts?: readonly ArtifactDefinition[];
+  extensions?: ToolContextExtensions;
+  // TODO(burdon): Remove systemPrompt -- should come from blueprint.
+} & Pick<GenerateRequest, 'model' | 'systemPrompt'>;
+
+const defaultOptions: Partial<ChatProcessorOptions> = {
+  model: DEFAULT_EDGE_MODEL,
+  systemPrompt: 'you are a helpful assistant',
+};
+
+/**
+ * Handles interactions with the AI service.
+ * Maintains a queue of messages and handles streaming responses from the AI service.
+ * Executes tools based on AI responses.
+ * Supports cancellation of in-progress requests.
+ */
+// TODO(burdon): Rename ChatContext?
+export class ChatProcessor {
+  /**
+   * Pending messages (incl. the current user request).
+   * @reactive
+   */
+  private readonly _pending: Signal<DataType.Message[]> = signal([]);
+
+  /**
+   * Current streaming message (from the AI service).
+   * @reactive
+   */
+  private readonly _streaming: Signal<DataType.Message | undefined> = signal(undefined);
+
+  /**
+   * Streaming state.
+   * @reactive
+   */
+  public readonly streaming: Signal<boolean> = computed(() => this._streaming.value !== undefined);
+
+  /**
+   * Last error.
+   * @reactive
+   */
+  public readonly error: Signal<Error | undefined> = signal(undefined);
+
+  /**
+   * Array of Messages (incl. the current message being streamed).
+   * @reactive
+   */
+  public readonly messages: Signal<DataType.Message[]> = computed(() => {
+    const messages = [...this._pending.value];
+    if (this._streaming.value) {
+      // TODO(dmaretskyi): Replace with Obj.clone.
+      // NOTE: We have to clone the message here so that react will re-render.
+      messages.push(Obj.make(DataType.Message, this._streaming.value));
+    }
+
+    return messages;
+  });
+
+  // TODO(burdon): Replace with Toolkit.
+  private _tools?: ExecutableTool[];
+
+  /** Current session. */
+  private _session: AiSession | undefined = undefined;
+
+  constructor(
+    // TODO(dmaretskyi): Replace this with effect's ManagedRuntime wrapping this layer.
+    private readonly _services: Layer.Layer<ChatServices>,
+    private readonly _conversation: Conversation,
+    private readonly _options: ChatProcessorOptions = defaultOptions,
+  ) {
+    this._tools = [...(_options.tools ?? [])];
+  }
+
+  get conversation() {
+    return this._conversation;
+  }
+
+  get context(): ContextBinder {
+    return this._conversation.context;
+  }
+
+  get blueprintRegistry() {
+    return this._options.blueprintRegistry;
+  }
+
+  get tools() {
+    return this._tools;
+  }
+
+  /**
+   * @deprecated Replace with blueprints
+   */
+  setTools(tools: ExecutableTool[]): void {
+    this._tools = tools;
+  }
+
+  /**
+   * Make GPT request.
+   */
+  async request(message: string, options: RequestOptions = {}): Promise<DataType.Message[]> {
+    await using ctx = Context.default(); // Auto-disposed at the end of this block.
+
+    this._conversation.onBegin.on(ctx, (session) => {
+      log.info('onBegin', { session, isDisposed: ctx.disposed });
+
+      this._session = session;
+      ctx.onDispose(() => {
+        log.info('onDispose', { session, isDisposed: ctx.disposed });
+        if (this._session === session) {
+          this._session = undefined;
+        }
+      });
+
+      // User message.
+      session.userMessage.on((message) => {
+        log.info('userMessage', { message });
+        this._pending.value = [...this._pending.value, message];
+      });
+
+      // Message complete.
+      session.message.on((message) => {
+        batch(() => {
+          this._pending.value = [...this._pending.value, message];
+          this._streaming.value = undefined;
+        });
+      });
+
+      // Streaming update (happens before message complete).
+      session.update.on((block) => {
+        batch(() => {
+          if (!this._streaming.value) {
+            // TODO(burdon): Hack to create temp message; better for session to send initial partial object?
+            this._streaming.value = Obj.make(DataType.Message, {
+              created: new Date().toISOString(),
+              sender: { role: 'assistant' },
+              blocks: [block],
+            });
+          } else if (this._streaming.value.blocks.at(-1)?.pending === true) {
+            this._streaming.value.blocks[this._streaming.value.blocks.length - 1] = block;
+          } else {
+            this._streaming.value.blocks.push(block);
+          }
+        });
+      });
+
+      session.block.on((block) => {
+        if (!this._streaming.value) {
+          // TODO(burdon): Hack to create temp message; better for session to send initial partial object?
+          this._streaming.value = Obj.make(DataType.Message, {
+            created: new Date().toISOString(),
+            sender: { role: 'assistant' },
+            blocks: [block],
+          });
+        } else if (this._streaming.value.blocks.at(-1)?.pending === true) {
+          this._streaming.value.blocks[this._streaming.value.blocks.length - 1] = block;
+        } else {
+          this._streaming.value.blocks.push(block);
+        }
+      });
+
+      // TODO(dmaretskyi): Handle tool status reports.
+      // session.toolStatusReport.on(({ message, status }) => {
+      //   const msg = this._pending.peek().find((m) => m.id === message.id);
+      //   const toolUse = msg?.content.find((block) => block.type === 'tool_use');
+      //   if (!toolUse) {
+      //     return;
+      //   }
+
+      //   const block = msg?.content.find(
+      //     (block): block is ToolUseContentBlock => block.type === 'tool_use' && block.id === toolUse.id,
+      //   );
+      //   if (block) {
+      //     this._pending.value = this._pending.value.map((m) => {
+      //       if (m.id === message.id) {
+      //         return {
+      //           ...m,
+      //           content: m.content.map((block) =>
+      //             block.type === 'tool_use' && block.id === toolUse.id ? { ...block, currentStatus: status } : block,
+      //           ),
+      //         };
+      //       }
+
+      //       return m;
+      //     });
+      //   } else {
+      //     log.warn('no block for status report');
+      //   }
+      // });
+    });
+
+    try {
+      const messages = await runAndForwardErrors(
+        this._conversation
+          .run({
+            prompt: message,
+            // TODO(burdon): Construct from blueprints?
+            systemPrompt: this._options.systemPrompt,
+          })
+          .pipe(
+            //
+            Effect.provide(AiService.model(this._options.model ?? DEFAULT_EDGE_MODEL)),
+            // TODO(dmaretskyi): Move ArtifactDiffResolver upstream.
+            Effect.provideService(ArtifactDiffResolver, this._artifactDiffResolver),
+            Effect.provide(this._services),
+            Effect.tapErrorCause((cause) => {
+              log.error('error', { cause });
+              return Effect.void;
+            }),
+          ),
+      );
+
+      log('completed', { messages });
+    } catch (err) {
+      log.catch(err);
+      if (err instanceof Error && err.message.includes('Overloaded')) {
+        this.error.value = new AiServiceOverloadedError('AI service overloaded', { cause: err });
+      } else {
+        this.error.value = new Error('AI service error', { cause: err });
+      }
+    }
+
+    return this._reset();
+  }
+
+  /**
+   * Cancel pending requests.
+   * @returns Pending requests (incl. the request message).
+   */
+  async cancel(): Promise<DataType.Message[]> {
+    log.info('cancelling...');
+
+    // TODO(dmaretskyi): Conversation should handle aborting.
+    this._session?.abort();
+    return this._reset();
+  }
+
+  private async _reset(): Promise<DataType.Message[]> {
+    const messages = this._pending.value;
+    batch(() => {
+      this._pending.value = [];
+      this._streaming.value = undefined;
+    });
+
+    return messages;
+  }
+
+  private _artifactDiffResolver: ArtifactDiffResolver.Service = {
+    resolve: async (artifacts) => {
+      const space = this._options.extensions?.space;
+      if (!space) {
+        return new Map();
+      }
+
+      const versions = new Map();
+      await Promise.all(
+        artifacts.map(async (artifact) => {
+          const {
+            objects: [object],
+          } = await space.db.query(Filter.ids(artifact.id)).run();
+          if (!object) {
+            return;
+          }
+          versions.set(artifact.id, {
+            version: getVersion(object),
+            diff: `Current state: ${JSON.stringify(object)}`,
+          });
+        }),
+      );
+      return versions;
+    },
+  };
+}
+
+// TODO(wittjosiah): Move to ai-service-client.
+export class AiServiceOverloadedError extends Error {
+  code = 'AI_SERVICE_OVERLOADED';
+}

package/src/hooks/index.ts

@@ -2,10 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './processor';
+export * from './chat-processor';
+export * from './presets';
 
+export * from './useBlueprints';
 export * from './useChatProcessor';
-export * from './useMessageQueue';
-export * from './useServices';
-export * from './useTextInputEvents';
-export * from './useContextProvider';
+export * from './useChatServices';
+export * from './useReferencesProvider';

package/src/hooks/presets.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { type LLMModel } from '@dxos/ai';
+
+const ModelProviders = ['dxos-local', 'dxos-remote', 'lm-studio'] as const;
+
+const ModelProvider = Schema.Literal(...ModelProviders);
+type ModelProvider = Schema.Schema.Type<typeof ModelProvider>;
+
+export type AiServicePreset = {
+  id: string;
+  provider: ModelProvider;
+  model: LLMModel;
+  label?: string;
+};
+
+const createModelLabel = (model: LLMModel) => {
+  const parts = model.split('/');
+  return parts[parts.length - 1];
+};
+
+// TODO(burdon): Users should be able to create and edit presets.
+export const AiServicePresets: AiServicePreset[] = [
+  {
+    provider: 'dxos-remote' as const,
+    model: '@anthropic/claude-3-5-haiku-20241022' as const,
+  },
+  {
+    provider: 'dxos-remote' as const,
+    model: '@anthropic/claude-opus-4-0' as const,
+  },
+  {
+    provider: 'lm-studio' as const,
+    model: '@google/gemma-3-12b' as const,
+  },
+  {
+    provider: 'lm-studio' as const,
+    model: '@mlx-community/llama-3.2-3b-instruct' as const,
+  },
+].map(
+  ({ model, provider }, i) =>
+    ({
+      id: `preset-${i}`,
+      provider,
+      model,
+      label: createModelLabel(model),
+    }) satisfies AiServicePreset,
+);

package/src/hooks/useBlueprints.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { effect } from '@preact/signals-react';
+import { useCallback, useEffect, useState } from 'react';
+
+import { type ContextBinder } from '@dxos/assistant';
+import { Blueprint } from '@dxos/blueprints';
+import { type Space } from '@dxos/client/echo';
+import { Obj, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { isNonNullable } from '@dxos/util';
+
+export type UpdateCallback = (key: string, active: boolean) => void;
+
+/**
+ * Get collection of active blueprints based on the context.
+ */
+export const useBlueprints = (
+  space: Space,
+  context: ContextBinder,
+  blueprintRegistry?: Blueprint.Registry,
+): [Blueprint.Blueprint[], UpdateCallback] => {
+  const [blueprints, setBlueprints] = useState<Blueprint.Blueprint[]>([]);
+  useEffect(() => {
+    let t: NodeJS.Timeout;
+    effect(() => {
+      const refs = [...(context.blueprints.value ?? [])];
+      t = setTimeout(async () => {
+        const blueprints = (await Ref.Array.loadAll(refs)).filter(isNonNullable);
+        setBlueprints(blueprints);
+      });
+    });
+
+    return () => clearTimeout(t);
+  }, [context]);
+
+  const handleUpdate = useCallback<UpdateCallback>(
+    (key: string, active: boolean) => {
+      log.info('update', { key, active });
+      if (active) {
+        // TODO(burdon): Check if already in space.
+        const blueprint = blueprintRegistry?.getByKey(key);
+        if (blueprint) {
+          // TODO(dmaretskyi): This should be done by Obj.clone.
+          const { id: _id, ...data } = blueprint;
+          const obj = space.db.add(Obj.make(Blueprint.Blueprint, data));
+          void context.bind({ blueprints: [Ref.make(obj)] });
+        }
+      }
+    },
+    [space, context],
+  );
+
+  return [blueprints, handleUpdate] as const;
+};

package/src/hooks/useChatProcessor.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Layer } from 'effect';
+import { useEffect, useMemo, useState } from 'react';
+
+import { type ExecutableTool } from '@dxos/ai';
+import { Capabilities, useCapabilities, useIntentDispatcher } from '@dxos/app-framework';
+import { Conversation, createSystemPrompt } from '@dxos/assistant';
+import { type ArtifactDefinition, type AssociatedArtifact, type Blueprint } from '@dxos/blueprints';
+import { FunctionType } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { useConfig } from '@dxos/react-client';
+import { Filter, fullyQualifiedId, type Queue, type Space, useQuery } from '@dxos/react-client/echo';
+import { isNonNullable } from '@dxos/util';
+
+import { type AiServicePreset, ChatProcessor, type ChatServices } from '../hooks';
+import { convertFunctionToTool, createToolsFromService } from '../tools';
+import { type Assistant, ServiceType } from '../types';
+
+type UseChatProcessorProps = {
+  preset?: AiServicePreset;
+  space?: Space;
+  chat?: Assistant.Chat;
+
+  // TODO(burdon): Move into layer?
+  services?: Layer.Layer<ChatServices>;
+  blueprintRegistry?: Blueprint.Registry;
+  // TODO(burdon): Not currently used.
+  settings?: Assistant.Settings;
+
+  /** @deprecated */
+  instructions?: string;
+  /** @deprecated */
+  artifact?: AssociatedArtifact;
+  /** @deprecated */
+  noPluginArtifacts?: boolean;
+};
+
+/**
+ * Configure and create ChatProcessor.
+ */
+export const useChatProcessor = ({
+  preset,
+  space,
+  chat,
+  services,
+  blueprintRegistry,
+  settings,
+  instructions,
+  artifact,
+  noPluginArtifacts,
+}: UseChatProcessorProps): ChatProcessor | undefined => {
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+  const globalTools = useCapabilities(Capabilities.Tools);
+
+  // TODO(burdon): Spec artifacts.
+  let artifacts: readonly ArtifactDefinition[] = useCapabilities(Capabilities.ArtifactDefinition);
+  if (noPluginArtifacts) {
+    artifacts = Stable.array;
+  }
+
+  // Services.
+  const remoteServices = useQuery(space, Filter.type(ServiceType));
+  const [serviceTools, setServiceTools] = useState<ExecutableTool[]>([]);
+  useEffect(() => {
+    log('creating service tools...');
+    queueMicrotask(async () => {
+      const tools = await Promise.all(remoteServices.map((service) => createToolsFromService(service)));
+      setServiceTools(tools.flat());
+    });
+  }, [remoteServices]);
+
+  // Tools and context.
+  const config = useConfig();
+  const functions = useQuery(space, Filter.type(FunctionType));
+  const chatId = useMemo(() => (chat ? fullyQualifiedId(chat) : undefined), [chat]);
+  const [tools, extensions] = useMemo(() => {
+    log('creating tools...');
+    const tools: ExecutableTool[] = [
+      ...globalTools.flat(),
+      ...serviceTools,
+      ...functions
+        .map((fn) => convertFunctionToTool(fn, config.values.runtime?.services?.edge?.url ?? '', space?.id))
+        .filter(isNonNullable),
+    ];
+    const extensions = { space, dispatch, pivotId: chatId };
+    return [tools, extensions];
+  }, [dispatch, globalTools, space, chatId, serviceTools, functions]);
+
+  // TODO(burdon): Create from template.
+  const systemPrompt = useMemo(
+    () =>
+      createSystemPrompt({
+        artifacts: artifacts.map((definition) => `${definition.name}\n${definition.instructions}`),
+        artifact,
+        instructions,
+      }),
+    [artifacts, artifact, instructions],
+  );
+
+  const conversation = useMemo(() => {
+    if (!chat?.queue.target) {
+      return;
+    }
+
+    return new Conversation({ queue: chat.queue.target as Queue<any> });
+  }, [chat?.queue.target]);
+
+  // Create processor.
+  // TODO(burdon): Updated on each query update above; should just update current processor?
+  const processor = useMemo(() => {
+    if (!services || !conversation) {
+      return undefined;
+    }
+
+    log.info('creating processor', {
+      preset,
+      artifacts: artifacts.length,
+      systemPrompt: systemPrompt.length,
+      model: preset?.model,
+      settings,
+    });
+
+    return new ChatProcessor(services, conversation, {
+      tools,
+      extensions,
+      blueprintRegistry,
+      artifacts,
+      systemPrompt,
+      model: preset?.model,
+    });
+  }, [services, conversation, tools, blueprintRegistry, artifacts, extensions, systemPrompt, preset]);
+
+  return processor;
+};
+
+// TODO(dmaretskyi): Extract.
+export const Stable = Object.freeze({
+  array: [] as readonly never[],
+  object: {} as {},
+});

package/src/hooks/useChatServices.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Layer } from 'effect';
+import { useMemo } from 'react';
+import { useDeepCompareMemoize } from 'use-deep-compare-effect';
+
+import { type AiService, type ToolExecutionService, type ToolResolverService } from '@dxos/ai';
+import { Capabilities, useCapabilities } from '@dxos/app-framework';
+import { makeToolExecutionServiceFromFunctions, makeToolResolverFromFunctions } from '@dxos/assistant';
+import { type Space } from '@dxos/client/echo';
+import {
+  ComputeEventLogger,
+  CredentialsService,
+  DatabaseService,
+  LocalFunctionExecutionService,
+  QueueService,
+  RemoteFunctionExecutionService,
+  TracingService,
+} from '@dxos/functions';
+
+import { AssistantCapabilities } from '../capability-definitions';
+
+export * from '@dxos/assistant';
+
+// TODO(burdon): Deconstruct into separate layers?
+export type ChatServices =
+  | AiService
+  | CredentialsService
+  | DatabaseService
+  | QueueService
+  | RemoteFunctionExecutionService
+  | ToolResolverService
+  | ToolExecutionService
+  | TracingService;
+
+export type UseChatServicesProps = {
+  space?: Space;
+};
+
+/**
+ * Construct service layer.
+ */
+export const useChatServices = ({ space }: UseChatServicesProps): Layer.Layer<ChatServices> | undefined => {
+  const aiServiceLayer =
+    useCapabilities(AssistantCapabilities.AiServiceLayer).at(0) ?? Layer.die('AiService not found');
+  const functions = useCapabilities(Capabilities.Functions).flat();
+
+  return useMemo(() => {
+    return Layer.mergeAll(
+      aiServiceLayer,
+      makeToolResolverFromFunctions(functions),
+      makeToolExecutionServiceFromFunctions(functions),
+
+      CredentialsService.configuredLayer([]),
+      space ? DatabaseService.makeLayer(space.db) : DatabaseService.notAvailable,
+      space ? QueueService.makeLayer(space.queues) : QueueService.notAvailable,
+
+      ComputeEventLogger.layerFromTracing,
+    ).pipe(
+      Layer.provideMerge(TracingService.layerNoop),
+      Layer.provideMerge(LocalFunctionExecutionService.layer),
+      Layer.provideMerge(RemoteFunctionExecutionService.mockLayer),
+    );
+  }, [space, useDeepCompareMemoize(functions.map((f) => f.name))]);
+};