@dxos/plugin-assistant 0.8.3-staging.0fa589b → 0.8.4-main.1da679c

package/src/execution-graph/execution-graph.ts

@@ -0,0 +1,211 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { AgentStatus } from '@dxos/ai';
+import { Obj, type Ref } from '@dxos/echo';
+import { MESSAGE_PROPERTY_TOOL_CALL_ID } from '@dxos/functions';
+import { type ObjectId } from '@dxos/keys';
+import { LogLevel } from '@dxos/log';
+import { type Commit } from '@dxos/react-ui-components';
+import { ContentBlock, DataType } from '@dxos/schema';
+import { isNotFalsy } from '@dxos/util';
+
+// TODO(burdon): Move to assistant.
+
+// TODO(burdon): Add colors?
+enum IconType {
+  // General status.
+  SUCCESS = 'ph--check-circle--regular',
+  WARNING = 'ph--warning-circle--regular',
+  ERROR = 'ph--x-circle--regular',
+  FLAG = 'ph--flag--regular',
+  ROCKET = 'ph--rocket--regular',
+  TIMER = 'ph--timer--regular',
+
+  // Interactions.
+  USER = 'ph--user--regular',
+  USER_INTERACTION = 'ph--user-sound--regular',
+  AGENT = 'ph--robot--regular',
+  THINKING = 'ph--brain--regular',
+  LINK = 'ph--link--regular',
+  TOOL = 'ph--wrench--regular',
+}
+
+/**
+ * Models the execution graph based on a stream of events.
+ */
+export class ExecutionGraph {
+  // TODO(dmaretskyi): Evolve the internal state to support chats, functions, circuit workflows, etc.
+  private _commits: Commit[] = [];
+  private _branchNames = new Set<string>();
+
+  /**
+   * Adds events to the graph.
+   */
+  addEvents(events: Obj.Any[]) {
+    for (const event of events) {
+      if (Obj.instanceOf(DataType.Message, event)) {
+        const messageCommits = messageToCommit(event);
+        this._commits.push(...messageCommits);
+        messageCommits.map((c) => c.branch).forEach((branch) => this._branchNames.add(branch));
+      } else if (Obj.instanceOf(AgentStatus, event)) {
+        const branch = getBranchName({ parentMessage: event.parentMessage, toolCallId: event.toolCallId });
+        this._branchNames.add(branch);
+        this._commits.push({
+          id: event.id,
+          branch,
+          message: event.message,
+          icon: IconType.FLAG,
+          parents:
+            event.parentMessage && event.toolCallId
+              ? [getToolCallId(event.parentMessage, event.toolCallId)]
+              : undefined, // TODO(burdon): Fix.
+        });
+      }
+    }
+  }
+
+  /**
+   * Returns the current state of the graph.
+   */
+  getGraph(lastRequest = false): { branches: string[]; commits: Commit[] } {
+    const idx = lastRequest ? this._commits.findLastIndex((c) => c.tags?.includes('user')) : -1;
+    const commits = idx === -1 ? this._commits : this._commits.slice(idx);
+
+    return {
+      branches: Array.from(this._branchNames),
+      commits: commits,
+    };
+  }
+}
+
+// TODO(burdon): Pass in AiToolProvider.
+const messageToCommit = (message: DataType.Message): Commit[] => {
+  return message.blocks
+    .map((block, idx) => {
+      const branch = getMessageBranch(message);
+      const parent = getParentId(message);
+      const parents = parent ? [parent] : [];
+      switch (block._tag) {
+        case 'text':
+          if (!block.text.trim().length) {
+            return null;
+          }
+          return {
+            id: getGenericBlockId(message.id, idx),
+            branch,
+            parents,
+            ...(message.sender.role === 'user'
+              ? {
+                  icon: IconType.USER,
+                  tags: ['user'],
+                  message: 'Processing request...',
+                }
+              : {
+                  icon: IconType.AGENT,
+                  message: `Response (${block.text.split(' ').length} words)`,
+                }),
+          } satisfies Commit;
+        case 'toolCall':
+          return {
+            id: getToolCallId(message.id, block.toolCallId),
+            branch,
+            parents,
+            icon: IconType.TOOL,
+            level: LogLevel.INFO,
+            // TODO(burdon): Lookup tool name/description?
+            message: `Calling tool (${block.name})`,
+          } satisfies Commit;
+        case 'toolResult':
+          return {
+            id: getToolResultId(message.id, block.toolCallId),
+            branch,
+            parents,
+            icon: block.error ? IconType.ERROR : IconType.SUCCESS,
+            level: block.error ? LogLevel.ERROR : LogLevel.INFO,
+            message: block.error ? 'Tool error: ' + block.error : 'Tool call succeeded',
+          } satisfies Commit;
+        case 'summary':
+          return {
+            id: getGenericBlockId(message.id, idx),
+            branch,
+            parents,
+            icon: IconType.ROCKET,
+            level: LogLevel.INFO,
+            message: ContentBlock.createSummaryMessage(block),
+          } satisfies Commit;
+        case 'status':
+          return {
+            id: getGenericBlockId(message.id, idx),
+            branch,
+            parents,
+            message: block.statusText,
+            level: LogLevel.INFO,
+            icon: IconType.FLAG,
+          } satisfies Commit;
+        case 'reasoning':
+          return {
+            id: getGenericBlockId(message.id, idx),
+            branch,
+            parents,
+            message: block.reasoningText ?? 'Thinking...',
+            icon: IconType.THINKING,
+          } satisfies Commit;
+        case 'reference':
+          return {
+            id: getGenericBlockId(message.id, idx),
+            branch,
+            parents,
+            icon: IconType.LINK,
+            message: stringifyRef(block.reference),
+          } satisfies Commit;
+        default:
+          return null;
+      }
+    })
+    .filter(isNotFalsy);
+};
+
+const getToolCallId = (messageId: ObjectId, toolCallId: string) => `${messageId}_toolCall_${toolCallId}`;
+
+const getToolResultId = (messageId: ObjectId, toolCallId: string) => `${messageId}_toolResult_${toolCallId}`;
+
+const getGenericBlockId = (messageId: ObjectId, idx: number) => `${messageId}_block_${idx}`;
+
+const getBranchName = (options: { parentMessage?: ObjectId; toolCallId?: string }) => {
+  if (options.parentMessage && options.toolCallId) {
+    return `${options.parentMessage}_${options.toolCallId}`;
+  } else if (options.parentMessage) {
+    return options.parentMessage;
+  } else {
+    return 'main';
+  }
+};
+
+const getMessageBranch = (message: DataType.Message) => {
+  return getBranchName({
+    parentMessage: message.parentMessage,
+    toolCallId: message.properties?.[MESSAGE_PROPERTY_TOOL_CALL_ID],
+  });
+};
+
+const getParentId = (message: DataType.Message) => {
+  if (message.parentMessage && message.properties?.[MESSAGE_PROPERTY_TOOL_CALL_ID]) {
+    return getToolCallId(message.parentMessage, message.properties[MESSAGE_PROPERTY_TOOL_CALL_ID]);
+  } else {
+    return undefined;
+  }
+};
+
+const stringifyRef = (ref: Ref.Any) => {
+  if (ref.target) {
+    return stringifyObject(ref.target);
+  }
+
+  return ref.dxn.asEchoDXN()?.echoId ?? ref.dxn.asQueueDXN()?.objectId ?? '';
+};
+
+const stringifyObject = (obj: Obj.Any) => {
+  return Obj.getLabel(obj) ?? Obj.getTypename(obj) ?? obj.id;
+};

package/src/execution-graph/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './execution-graph';

package/src/functions/analysis.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect, Schema } from 'effect';
+
+import { defineFunction } from '@dxos/functions';
+import { log } from '@dxos/log';
+
+export default defineFunction({
+  name: 'dxos.org/function/assistant-analysis',
+  description: 'Enter analysis analysis mode.',
+  inputSchema: Schema.Struct({
+    enable: Schema.Boolean.annotations({ description: 'Enable or disable analysis mode.' }),
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ context, data: { enable } }) {
+    log.info('analysis mode', { space: context.space?.id, enable });
+  }),
+});

package/src/functions/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as analysis } from './analysis';
+export { default as list } from './list';
+export { default as load } from './load';

package/src/functions/list.ts

@@ -0,0 +1,46 @@
+//
+// 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 } }) {
+    // TODO(wittjosiah): Typename query is not working for dynamic schemas.
+    const [schema] = yield* DatabaseService.runSchemaQuery({ typename });
+    const filter = schema ? Filter.type(schema) : Filter.typename(typename);
+
+    const { objects } = yield* DatabaseService.runQuery(Query.select(filter));
+    const results = objects.map((object) => ({
+      dxn: Obj.getDXN(object).toString(),
+      label: Obj.getLabel(object),
+    }));
+
+    return { results };
+  }),
+});

package/src/functions/load.ts

@@ -0,0 +1,42 @@
+//
+// 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';
+
+// 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/index.ts

@@ -2,10 +2,14 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './processor';
-
+export * from './useBlueprintRegistry';
 export * from './useChatProcessor';
-export * from './useMessageQueue';
-export * from './useServices';
-export * from './useTextInputEvents';
-export * from './useContextProvider';
+export * from './useChatServices';
+export * from './useContextBinder';
+export * from './useContextObjects';
+export * from './useExecutionGraph';
+export * from './useFlush';
+export * from './useItemTypes';
+export * from './useOnline';
+export * from './usePresets';
+export * from './useReferencesProvider';

package/src/hooks/useBlueprintRegistry.ts

@@ -0,0 +1,80 @@
+//
+// 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]);
+};
+
+export const useBlueprints = ({ blueprintRegistry }: { blueprintRegistry?: Blueprint.Registry }) =>
+  useMemo(() => blueprintRegistry?.query() ?? [], [blueprintRegistry]);
+
+/**
+ * Create reactive map of active blueprints (by key).
+ */
+export const useActiveBlueprints = ({ context }: { context?: AiContextBinder }) => {
+  const [active, setActive] = useState<Map<string, Blueprint.Blueprint>>(new Map());
+
+  useSignalEffect(() => {
+    const refs = [...(context?.blueprints.value ?? [])];
+    const blueprints = refs.map((ref) => ref.target).filter(isNonNullable);
+    setActive(new Map(blueprints.map((blueprint) => [blueprint.key, blueprint])));
+  });
+
+  return active;
+};
+
+// TODO(burdon): Move logic into binder.
+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,66 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-rx/rx-react';
+import { type Runtime } from 'effect';
+import { useContext, useMemo } from 'react';
+
+import { AiConversation } from '@dxos/assistant';
+import { type Blueprint } from '@dxos/blueprints';
+import { log } from '@dxos/log';
+import { type Queue } from '@dxos/react-client/echo';
+
+import { AiChatProcessor, type AiChatServices, type AiServicePreset } from '../processor';
+import { type Assistant } from '../types';
+
+export type UseChatProcessorProps = {
+  chat?: Assistant.Chat;
+  preset?: AiServicePreset;
+  services?: () => Promise<Runtime.Runtime<AiChatServices>>;
+  blueprintRegistry?: Blueprint.Registry;
+  settings?: Assistant.Settings;
+};
+
+/**
+ * Configure and create AiChatProcessor.
+ */
+export const useChatProcessor = ({
+  chat,
+  preset,
+  services,
+  blueprintRegistry,
+  settings,
+}: UseChatProcessorProps): AiChatProcessor | undefined => {
+  const observableRegistry = useContext(RegistryContext);
+
+  // Create conversation from chat queue.
+  const conversation = useMemo(() => {
+    if (!chat?.queue.target) {
+      return;
+    }
+
+    return new AiConversation({ queue: chat.queue.target as Queue<any> });
+  }, [chat?.queue.target]);
+
+  // Create processor.
+  const processor = useMemo(() => {
+    if (!services || !conversation) {
+      return undefined;
+    }
+
+    log('creating processor', {
+      preset,
+      model: preset?.model,
+      settings,
+    });
+
+    return new AiChatProcessor(conversation, services, {
+      observableRegistry,
+      blueprintRegistry,
+      model: preset?.model,
+    });
+  }, [services, conversation, blueprintRegistry, preset]);
+
+  return processor;
+};

package/src/hooks/useChatServices.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect, type Runtime } from 'effect';
+import { useMemo } from 'react';
+
+import { useCapability } from '@dxos/app-framework';
+import { type Space } from '@dxos/client/echo';
+import { TracingService } from '@dxos/functions';
+import { AutomationCapabilities } from '@dxos/plugin-automation';
+import { useClient } from '@dxos/react-client';
+
+import { type AiChatServices } from '../processor';
+import { type Assistant } from '../types';
+
+export type UseChatServicesProps = {
+  space?: Space;
+  chat?: Assistant.Chat;
+};
+
+/**
+ * Construct service layer.
+ */
+// TODO(dmaretskyi): Better return type.
+export const useChatServices = ({
+  space,
+  chat,
+}: UseChatServicesProps): (() => Promise<Runtime.Runtime<AiChatServices>>) | undefined => {
+  const client = useClient();
+  space ??= client.spaces.default;
+
+  const computeRuntimeResolver = useCapability(AutomationCapabilities.ComputeRuntime);
+
+  return useMemo(() => {
+    const runtime = computeRuntimeResolver.getRuntime(space.id);
+    return () =>
+      runtime.runPromise(
+        Effect.gen(function* () {
+          return yield* Effect.runtime<AiChatServices>().pipe(
+            Effect.provide(
+              chat?.traceQueue?.target ? TracingService.layerQueue(chat.traceQueue?.target) : TracingService.layerNoop,
+            ),
+          );
+        }),
+      );
+  }, [space, chat?.traceQueue?.target]);
+};

package/src/hooks/useContextBinder.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { AiContextBinder } from '@dxos/assistant';
+
+import { type Assistant } from '../types';
+
+export const useContextBinder = (chat: Assistant.Chat | undefined): AiContextBinder | undefined => {
+  const binder = useMemo(() => {
+    const queue = chat?.queue.target;
+    return queue && new AiContextBinder(queue);
+  }, [chat]);
+
+  return binder;
+};

package/src/hooks/useContextObjects.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCallback } from 'react';
+
+import { type AiContextBinder } from '@dxos/assistant';
+import { type DXN, type Obj, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { type Space } from '@dxos/react-client/echo';
+import { isNonNullable } from '@dxos/util';
+
+export type UseContextObjects = {
+  objects: Obj.Any[];
+  onUpdateObject: (dxn: DXN, checked: boolean) => Promise<void>;
+};
+
+/**
+ * Create reactive map of active object references (by DXN string).
+ */
+export const useContextObjects = ({
+  space,
+  context,
+}: {
+  space?: Space;
+  context?: AiContextBinder;
+}): UseContextObjects => {
+  const objects = context?.objects.value.map((ref) => ref.target).filter(isNonNullable) ?? [];
+
+  const handleUpdateObject = useCallback<UseContextObjects['onUpdateObject']>(
+    async (dxn: DXN, checked: boolean) => {
+      if (!space || !context) {
+        return;
+      }
+
+      // Load the object by DXN/id from the current space.
+      const id = dxn.asEchoDXN();
+      const object = id && (await space.db.getObjectById(id.echoId));
+      if (!object) {
+        log.warn('Object not found', { dxn, id });
+        return;
+      }
+
+      const ref = Ref.fromDXN(dxn);
+      if (checked) {
+        await context.bind({ objects: [ref] });
+      } else {
+        await context.unbind({ objects: [ref] });
+      }
+    },
+    [space, context],
+  );
+
+  return {
+    objects,
+    onUpdateObject: handleUpdateObject,
+  };
+};

package/src/hooks/useExecutionGraph.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type Queue } from '@dxos/client/echo';
+import { Obj } from '@dxos/echo';
+import { useQueue } from '@dxos/react-client/echo';
+
+import { ExecutionGraph } from '../execution-graph';
+
+export const useExecutionGraph = (queueRef?: Queue, lastRequest = false) => {
+  const queue = useQueue(queueRef?.dxn);
+  return useMemo(() => {
+    const graph = new ExecutionGraph();
+    graph.addEvents(queue?.objects.filter(Obj.isObject) ?? []);
+    return graph.getGraph(lastRequest);
+  }, [queue?.objects, lastRequest]);
+};

package/src/hooks/useFlush.ts

@@ -0,0 +1,35 @@
+//
+// 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 };
+};