@dxos/plugin-assistant 0.8.3-staging.0fa589b → 0.8.4-main.28f8d3d

package/src/functions/list.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect, Schema } from 'effect';
+
+import { Filter, Obj, Query } from '@dxos/echo';
+import { DatabaseService, defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+// TODO(burdon): Factor out to space plugin.
+export default defineFunction({
+  name: 'dxos.org/function/assistant/list',
+  description:
+    // TODO(wittjosiah): Find a better way to prompt for looking up typenames before querying with them.
+    trim`
+      Lists the objects of the given type.
+      Check the list-schemas tool for available types before calling this function.
+    `,
+  inputSchema: Schema.Struct({
+    typename: Schema.String.annotations({
+      description: 'The typename of the objects to list.',
+    }),
+  }),
+  outputSchema: Schema.Struct({
+    results: Schema.Array(
+      Schema.Struct({
+        dxn: Schema.String.annotations({ description: 'The DXN of the object.' }),
+        label: Schema.optional(Schema.String.annotations({ description: 'The label of the object.' })),
+      }),
+    ),
+  }),
+  handler: Effect.fn(function* ({ data: { typename } }) {
+    const { objects } = yield* DatabaseService.runQuery(Query.select(Filter.typename(typename)));
+    const results = objects.map((object) => ({
+      dxn: Obj.getDXN(object).toString(),
+      label: Obj.getLabel(object),
+    }));
+
+    return { results };
+  }),
+});

package/src/functions/load.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect, Option, Schema, pipe } from 'effect';
+
+import { ArtifactId } from '@dxos/assistant';
+import { Obj } from '@dxos/echo';
+import { DatabaseService, defineFunction } from '@dxos/functions';
+import { log } from '@dxos/log';
+
+// TODO(burdon): Common error handling.
+// TODO(burdon): Factor out to space plugin.
+export default defineFunction({
+  name: 'dxos.org/function/assistant/load',
+  description: 'Loads the object.',
+  inputSchema: Schema.Struct({
+    id: ArtifactId.annotations({
+      description: 'The ID of the object.',
+    }),
+    typename: Schema.String.annotations({
+      description: 'The typename of the object.',
+    }),
+  }),
+  outputSchema: Schema.Struct({
+    // TODO(wittjosiah): Type.Obj.Any | Type.Relation.Any
+    object: Schema.Any,
+  }),
+  handler: Effect.fn(function* ({ data: { id, typename } }) {
+    const object = yield* DatabaseService.resolve(ArtifactId.toDXN(id));
+    return yield* pipe(
+      Option.fromNullable(object),
+      Option.flatMap((object) => (Obj.getTypename(object) === typename ? Option.some(object) : Option.none())),
+      Option.match({
+        onNone: () => Effect.fail('Object not found.'),
+        onSome: (object) => {
+          log.info('object', { object });
+          return Effect.succeed({ object });
+        },
+      }),
+    );
+  }),
+});

package/src/hooks/chat-processor.ts

@@ -0,0 +1,260 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Registry, Result, Rx } from '@effect-rx/rx-react';
+import { Effect, type Layer, Option, Stream, pipe } from 'effect';
+
+import { AiService, DEFAULT_EDGE_MODEL, type ModelName, type ModelRegistry } from '@dxos/ai';
+import { type PromiseIntentDispatcher } from '@dxos/app-framework';
+import {
+  type AiConversation,
+  type AiConversationRunParams,
+  AiSession,
+  ArtifactDiffResolver,
+  createSystemPrompt,
+} from '@dxos/assistant';
+import { 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 { type ContentBlock, DataType } from '@dxos/schema';
+
+import { AiServiceOverloadedError } from './errors';
+import { type AiChatServices } from './useChatServices';
+
+// TODO(burdon): Is this still used?
+declare global {
+  interface ToolContextExtensions {
+    space?: Space;
+    dispatch?: PromiseIntentDispatcher;
+  }
+}
+
+export type AiRequestOptions = {
+  // Empty for now.
+};
+
+export type AiChatProcessorOptions = {
+  model?: ModelName;
+  modelRegistry?: ModelRegistry;
+  blueprintRegistry?: Blueprint.Registry;
+  observableRegistry?: Registry.Registry;
+  extensions?: ToolContextExtensions;
+} & Pick<AiConversationRunParams<any>, 'system'>;
+
+const defaultOptions: Partial<AiChatProcessorOptions> = {
+  model: DEFAULT_EDGE_MODEL,
+};
+
+/**
+ * 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.
+ */
+export class AiChatProcessor {
+  /**
+   * Last error.
+   */
+  // TODO(wittjosiah): Error should come from the message stream.
+  readonly error = Rx.make<Option.Option<Error>>(Option.none());
+
+  /** Rx registry. */
+  private readonly _observableRegistry: Registry.Registry;
+
+  /** Current session. */
+  private readonly _session = Rx.make<Option.Option<AiSession>>(Option.none());
+
+  /**
+   * Current streaming message (from the AI service).
+   */
+  private readonly _streaming: Rx.Rx<Result.Result<Option.Option<DataType.Message>, Error>> = Rx.make((get) => {
+    return pipe(
+      get(this._session),
+      Option.map((session) => Stream.fromQueue(session.blockQueue)),
+      Option.getOrElse(() => Stream.make()),
+      Stream.scan<Option.Option<DataType.Message>, Option.Option<ContentBlock.Any>>(Option.none(), (acc, blockOption) =>
+        Option.flatMap(blockOption, (block) =>
+          acc.pipe(
+            Option.match({
+              onNone: () => [block],
+              onSome: (message) => [...message.blocks.filter((b) => !b.pending), block],
+            }),
+            Option.some,
+            Option.map((blocks) =>
+              Obj.make(DataType.Message, {
+                created: new Date().toISOString(),
+                sender: { role: 'assistant' },
+                blocks,
+              }),
+            ),
+          ),
+        ),
+      ),
+    );
+  });
+
+  /**
+   * Streaming state.
+   */
+  readonly streaming: Rx.Rx<boolean> = Rx.make((get) => {
+    return pipe(
+      get(this._streaming),
+      Result.map((streaming) => Option.isSome(streaming)),
+      Result.getOrElse(() => false),
+    );
+  });
+
+  /**
+   * Pending messages (incl. the current user request).
+   */
+  private readonly _pending: Rx.Rx<Result.Result<DataType.Message[], Error>> = Rx.make((get) => {
+    // TODO(wittjosiah): For some reason using Option.map here loses reactivity.
+    const session = get(this._session);
+    return Option.isSome(session)
+      ? pipe(
+          session.value.messageQueue,
+          Stream.fromQueue,
+          Stream.scan<DataType.Message[], DataType.Message>([], (acc, message) => [...acc, message]),
+        )
+      : Stream.make();
+  });
+
+  /**
+   * Array of Messages (incl. the current message being streamed).
+   */
+  readonly messages: Rx.Rx<Result.Result<DataType.Message[], Error>> = Rx.make((get) => {
+    const streaming = get(this._streaming);
+    return Result.map(get(this._pending), (pending) =>
+      Result.match(streaming, {
+        onInitial: () => pending,
+        onSuccess: (streaming) =>
+          Option.match(streaming.value, {
+            onNone: () => pending,
+            onSome: (message) => [...pending, message],
+          }),
+        onFailure: () => pending,
+      }),
+    );
+  });
+
+  constructor(
+    // TODO(dmaretskyi): Replace this with effect's ManagedRuntime wrapping this layer.
+    private readonly _services: Layer.Layer<AiChatServices>,
+    private readonly _conversation: AiConversation,
+    private readonly _options: AiChatProcessorOptions = defaultOptions,
+  ) {
+    // Initialize registries and defaults before using in other logic.
+    this._observableRegistry = this._options.observableRegistry ?? Registry.make();
+    if (this._options.model && !this._options.system) {
+      const capabilities = this._options.modelRegistry?.getCapabilities(this._options.model) ?? {};
+      this._options.system = createSystemPrompt(capabilities);
+    }
+  }
+
+  get context() {
+    return this._conversation.context;
+  }
+
+  get conversation() {
+    return this._conversation;
+  }
+
+  get blueprintRegistry() {
+    return this._options.blueprintRegistry;
+  }
+
+  /**
+   * Make GPT request.
+   */
+  async request(message: string, _options: AiRequestOptions = {}): Promise<void> {
+    await using ctx = Context.default(); // Auto-disposed at the end of this block.
+
+    const session = new AiSession();
+    this._observableRegistry.set(this._session, Option.some(session));
+
+    ctx.onDispose(() => {
+      log.info('onDispose', { session, isDisposed: ctx.disposed });
+      Option.match(this._observableRegistry.get(this._session), {
+        onSome: (s) => {
+          if (s === session) {
+            this._observableRegistry.set(this._session, Option.none());
+          }
+        },
+        onNone: () => {},
+      });
+    });
+
+    try {
+      const messages = await runAndForwardErrors(
+        this._conversation
+          .run({
+            session,
+            prompt: message,
+            system: this._options.system,
+          })
+          .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._observableRegistry.set(
+          this.error,
+          Option.some(new AiServiceOverloadedError('AI service overloaded', { cause: err })),
+        );
+      } else {
+        this._observableRegistry.set(this.error, Option.some(new Error('AI service error', { cause: err })));
+      }
+    }
+  }
+
+  /**
+   * Cancel pending requests.
+   */
+  async cancel(): Promise<void> {
+    log.info('cancelling...');
+
+    // TODO(dmaretskyi): Abort using Fiber.interrupt.
+  }
+
+  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;
+    },
+  };
+}

package/src/hooks/errors.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Move to ai-service-client.
+export class AiServiceOverloadedError extends Error {
+  code = 'AI_SERVICE_OVERLOADED';
+}

package/src/hooks/index.ts

@@ -2,10 +2,14 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './processor';
+export * from './chat-processor';
+export * from './errors';
+export * from './presets';
 
+export * from './useBlueprintRegistry';
 export * from './useChatProcessor';
-export * from './useMessageQueue';
-export * from './useServices';
-export * from './useTextInputEvents';
-export * from './useContextProvider';
+export * from './useChatServices';
+export * from './useOnline';
+export * from './usePresets';
+export * from './useReferencesProvider';
+export * from './useResolveRef';

package/src/hooks/presets.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { type ModelName } 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: ModelName;
+  label?: string;
+};
+
+const createModelLabel = (model: ModelName) => {
+  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-opus-4-0' as const,
+  },
+  {
+    provider: 'dxos-remote' as const,
+    model: '@anthropic/claude-3-5-haiku-20241022' 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,
+  },
+  { model: 'deepseek-r1:latest' as const, provider: 'dxos-local' as const },
+].map(
+  ({ model, provider }, i) =>
+    ({
+      id: `preset-${i}`,
+      provider,
+      model,
+      label: createModelLabel(model),
+    }) satisfies AiServicePreset,
+);

package/src/hooks/useBlueprintRegistry.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useSignalEffect } from '@preact/signals-react';
+import { useCallback, useMemo, useState } from 'react';
+
+import { Capabilities, useCapabilities } from '@dxos/app-framework';
+import { type AiContextBinder } from '@dxos/assistant';
+import { Blueprint } from '@dxos/blueprints';
+import { type Space } from '@dxos/client/echo';
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { isNonNullable } from '@dxos/util';
+
+/**
+ * Provide a registry of blueprints from plugins.
+ */
+// TODO(burdon): Reconcile with eventual public registry.
+export const useBlueprintRegistry = () => {
+  const blueprints = useCapabilities(Capabilities.BlueprintDefinition);
+  return useMemo(() => new Blueprint.Registry(blueprints), [blueprints]);
+};
+
+/**
+ * Create reactive map of active blueprints (by key).
+ */
+export const useBlueprints = ({ context }: { context?: AiContextBinder }) => {
+  const [active, setActive] = useState<Map<string, Blueprint.Blueprint>>(new Map());
+  useSignalEffect(() => {
+    const refs = [...(context?.blueprints.value ?? [])];
+    const t = setTimeout(async () => {
+      const blueprints = (await Ref.Array.loadAll(refs)).filter(isNonNullable);
+      setActive(new Map(blueprints.map((blueprint) => [blueprint.key, blueprint])));
+    });
+
+    return () => clearTimeout(t);
+  });
+
+  return active;
+};
+
+// TODO(burdon): Context should manage ephemeral state of bindings until prompt is issued?
+export const useBlueprintHandlers = ({
+  space,
+  context,
+  blueprintRegistry,
+}: {
+  space: Space;
+  context?: AiContextBinder;
+  blueprintRegistry?: Blueprint.Registry;
+}) => {
+  const onUpdateBlueprint = useCallback(
+    async (key: string, checked: boolean) => {
+      if (!context || !blueprintRegistry) {
+        return;
+      }
+
+      // Find existing cloned blueprint.
+      const { objects } = await space.db.query(Filter.type(Blueprint.Blueprint)).run();
+      let storedBlueprint = objects.find((blueprint) => blueprint.key === key);
+      if (checked) {
+        if (!storedBlueprint) {
+          const blueprint = blueprintRegistry.getByKey(key);
+          if (!blueprint) {
+            return;
+          }
+          // NOTE: Possible race condition with other peers.
+          storedBlueprint = space.db.add(Obj.clone(blueprint));
+        }
+        await context.bind({ blueprints: [Ref.make(storedBlueprint)] });
+      } else if (storedBlueprint) {
+        await context.unbind({ blueprints: [Ref.make(storedBlueprint)] });
+      }
+    },
+    [space, context, blueprintRegistry],
+  );
+
+  return { onUpdateBlueprint };
+};

package/src/hooks/useChatProcessor.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-rx/rx-react';
+import { type Layer } from 'effect';
+import { useContext, useMemo } from 'react';
+
+import { useIntentDispatcher } from '@dxos/app-framework';
+import { AiConversation } from '@dxos/assistant';
+import { type Blueprint } from '@dxos/blueprints';
+import { log } from '@dxos/log';
+import { type Queue, type Space, fullyQualifiedId } from '@dxos/react-client/echo';
+
+import { AiChatProcessor, type AiChatServices, type AiServicePreset } from '../hooks';
+import { type Assistant } from '../types';
+
+export type UseChatProcessorProps = {
+  space?: Space;
+  chat?: Assistant.Chat;
+  preset?: AiServicePreset;
+  services?: Layer.Layer<AiChatServices>;
+  blueprintRegistry?: Blueprint.Registry;
+  settings?: Assistant.Settings;
+};
+
+/**
+ * Configure and create AiChatProcessor.
+ */
+export const useChatProcessor = ({
+  space,
+  chat,
+  preset,
+  services,
+  blueprintRegistry,
+  settings,
+}: UseChatProcessorProps): AiChatProcessor | undefined => {
+  const observableRegistry = useContext(RegistryContext);
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+
+  // Tools and context.
+  const chatId = useMemo(() => (chat ? fullyQualifiedId(chat) : undefined), [chat]);
+  const extensions = useMemo(() => ({ space, dispatch, pivotId: chatId }), [dispatch, space, chatId]);
+
+  const conversation = useMemo(() => {
+    if (!chat?.queue.target) {
+      return;
+    }
+
+    return new AiConversation({ 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('creating processor', {
+      preset,
+      model: preset?.model,
+      settings,
+    });
+
+    return new AiChatProcessor(services, conversation, {
+      extensions,
+      blueprintRegistry,
+      observableRegistry,
+      model: preset?.model,
+    });
+  }, [services, conversation, blueprintRegistry, extensions, 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,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AiTool, AiToolkit } from '@effect/ai';
+import { Layer } from 'effect';
+import { useMemo } from 'react';
+
+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 '../capabilities';
+
+// TODO(burdon): Deconstruct into separate layers?
+export type AiChatServices =
+  | AiService.AiService
+  | CredentialsService
+  | DatabaseService
+  | QueueService
+  | RemoteFunctionExecutionService
+  | ToolResolverService
+  | ToolExecutionService
+  | TracingService;
+
+export type UseChatServicesProps = {
+  space?: Space;
+};
+
+/**
+ * Construct service layer.
+ */
+export const useChatServices = ({ space }: UseChatServicesProps): Layer.Layer<AiChatServices> | undefined => {
+  const serviceLayer = useCapabilities(AssistantCapabilities.AiServiceLayer).at(0) ?? Layer.die('AiService not found');
+  const functions = useCapabilities(Capabilities.Functions);
+  const toolkits = useCapabilities(Capabilities.Toolkit);
+  const handlers = useCapabilities(Capabilities.ToolkitHandler);
+
+  return useMemo(() => {
+    const allFunctions = functions.flat();
+    // TODO(wittjosiah): Don't cast.
+    const toolkit = AiToolkit.merge(...toolkits) as AiToolkit.Any as AiToolkit.AiToolkit<AiTool.Any>;
+    const handlersLayer = Layer.mergeAll(Layer.empty, ...handlers);
+    return Layer.mergeAll(
+      serviceLayer,
+      makeToolResolverFromFunctions(allFunctions, toolkit),
+      makeToolExecutionServiceFromFunctions(allFunctions, toolkit, handlersLayer),
+      CredentialsService.layerFromDatabase(),
+      ComputeEventLogger.layerFromTracing,
+    ).pipe(
+      Layer.provideMerge(
+        Layer.mergeAll(
+          space ? DatabaseService.layer(space.db) : DatabaseService.notAvailable,
+          space ? QueueService.layer(space.queues) : QueueService.notAvailable,
+          TracingService.layerNoop,
+          LocalFunctionExecutionService.layer,
+          RemoteFunctionExecutionService.mockLayer,
+        ),
+      ),
+    );
+  }, [space, functions, toolkits, handlers]);
+};

package/src/hooks/useOnline.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Dispatch, type SetStateAction, useState } from 'react';
+
+export const useOnline = (): [boolean, Dispatch<SetStateAction<boolean>>] => {
+  const [online, setOnline] = useState(true);
+  return [online, setOnline];
+};