@dxos/plugin-assistant 0.7.5-labs.a8b535d

package/src/components/Toolbox/Toolbox.stories.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta } from '@storybook/react';
+import React from 'react';
+
+import { IntentPlugin, Capabilities, useCapabilities, SettingsPlugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { capabilities } from '@dxos/artifact-testing';
+import { ChessPlugin } from '@dxos/plugin-chess';
+import { ClientPlugin } from '@dxos/plugin-client';
+import { MapPlugin } from '@dxos/plugin-map';
+import { SpacePlugin } from '@dxos/plugin-space';
+import { TablePlugin } from '@dxos/plugin-table';
+import { withLayout, withSignals, withTheme } from '@dxos/storybook-utils';
+
+import { Toolbox, type ToolboxProps } from './Toolbox';
+import translations from '../../translations';
+
+const Render = (props: ToolboxProps) => {
+  const artifactDefinitions = useCapabilities(Capabilities.ArtifactDefinition);
+  return (
+    <Toolbox
+      {...props}
+      artifacts={artifactDefinitions}
+      classNames='w-[30rem] h-[15rem] rounded-md border border-separator py-1'
+    />
+  );
+};
+
+const meta: Meta<typeof Toolbox> = {
+  title: 'plugins/plugin-automation/Toolbox',
+  component: Toolbox,
+  render: Render,
+  decorators: [
+    withSignals,
+    withPluginManager({
+      plugins: [
+        ClientPlugin({
+          onClientInitialized: async (_, client) => {
+            await client.halo.createIdentity();
+          },
+        }),
+        SpacePlugin({ observability: false }),
+        SettingsPlugin(),
+        IntentPlugin(),
+        ChessPlugin(),
+        MapPlugin(),
+        TablePlugin(),
+      ],
+      capabilities,
+    }),
+    withTheme,
+    withLayout({ tooltips: true }),
+  ],
+  parameters: {
+    translations,
+    layout: 'centered',
+  },
+};
+
+export default meta;
+
+type Story = Meta<typeof Toolbox>;
+
+export const Default: Story = {};

package/src/components/Toolbox/Toolbox.tsx

@@ -0,0 +1,115 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useState, useEffect, Fragment, type FC } from 'react';
+
+import { Capabilities, useCapabilities } from '@dxos/app-framework';
+import { parseToolName, type ArtifactDefinition, type Tool } from '@dxos/artifact';
+import { FunctionType } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { Filter, type Space, useQuery } from '@dxos/react-client/echo';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import { createToolsFromService } from '../../tools';
+import { ServiceType } from '../../types';
+
+export type ToolboxProps = ThemedClassName<{
+  artifacts?: ArtifactDefinition[];
+  services?: { service: ServiceType; tools: Tool[] }[];
+  functions?: FunctionType[];
+  striped?: boolean;
+}>;
+
+export const Toolbox = ({ classNames, artifacts, functions, services, striped }: ToolboxProps) => {
+  return (
+    <div className={mx('flex flex-col overflow-y-auto box-content', classNames)}>
+      {artifacts && artifacts.length > 0 && (
+        <Section
+          title='Artifacts'
+          items={artifacts.map(({ name, description, tools }) => ({
+            name,
+            description,
+            subitems: tools.map(({ name, description }) => ({ name: `∙ ${parseToolName(name)}`, description })),
+          }))}
+        />
+      )}
+
+      {services && services.length > 0 && (
+        <Section
+          title='Services'
+          items={services.map(({ service: { serviceId, name, description }, tools }) => ({
+            name: name ?? serviceId,
+            description,
+            subitems: tools.map(({ name, description }) => ({ name: `∙ ${name}`, description })),
+          }))}
+        />
+      )}
+
+      {functions && functions.length > 0 && (
+        <Section title='Functions' items={functions.map(({ name, description }) => ({ name, description }))} />
+      )}
+    </div>
+  );
+};
+
+const Section: FC<{
+  title: string;
+  items: { name: string; description?: string; subitems?: { name: string; description?: string }[] }[];
+  striped?: boolean;
+}> = ({ title, items, striped }) => {
+  const stripeClassNames = 'odd:bg-neutral-50 dark:odd:bg-neutral-800';
+  const gridClassNames = 'grid grid-cols-[8rem_1fr]';
+  const subGridClassNames = mx('col-span-full grid grid-cols-subgrid text-xs px-2', striped && stripeClassNames);
+
+  return (
+    <div>
+      <h1 className='px-2 text-sm'>{title}</h1>
+      <div className={gridClassNames}>
+        {items.map(({ name, description, subitems }, i) => (
+          <Fragment key={i}>
+            {name && (
+              <div className={subGridClassNames}>
+                <div className='truncate text-primary-500'>{name}</div>
+                <div className='line-clamp-2'>{description}</div>
+              </div>
+            )}
+            {subitems?.map(({ name, description }, i) => (
+              <div key={i} className={mx(subGridClassNames, striped && stripeClassNames)}>
+                <div className='truncate'>{name}</div>
+                <div className='line-clamp-3 text-subdued'>{description}</div>
+              </div>
+            ))}
+          </Fragment>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export const ToolboxContainer = ({ classNames, space }: ThemedClassName<{ space?: Space }>) => {
+  // Plugin artifacts.
+  const artifactDefinitions = useCapabilities(Capabilities.ArtifactDefinition);
+
+  // Registered services.
+  const services = useQuery(space, Filter.schema(ServiceType));
+  const [serviceTools, setServiceTools] = useState<{ service: ServiceType; tools: Tool[] }[]>([]);
+  useEffect(() => {
+    log('creating service tools...', { services: services.length });
+    queueMicrotask(async () => {
+      const tools = await Promise.all(
+        services.map(async (service) => ({ service, tools: await createToolsFromService(service) })),
+      );
+
+      setServiceTools(tools);
+    });
+  }, [services]);
+
+  // Deployed functions.
+  const functions = useQuery(space, Filter.schema(FunctionType));
+
+  return (
+    <Toolbox classNames={classNames} artifacts={artifactDefinitions} services={serviceTools} functions={functions} />
+  );
+};

package/src/components/Toolbox/index.ts

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

package/src/components/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { lazy } from 'react';
+
+export * from './AssistantSettings';
+export * from './ServiceRegistry';
+export * from './TemplateEditor';
+export * from './Thread';
+export * from './Toolbox';
+
+export const AssistantDialog = lazy(() => import('./AssistantDialog'));
+export const ChatContainer = lazy(() => import('./ChatContainer'));
+export const TemplateContainer = lazy(() => import('./TemplateContainer'));

package/src/hooks/email.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { findObjectWithForeignKey } from '@dxos/echo-db';
+import { foreignKey } from '@dxos/echo-schema';
+import { log } from '@dxos/log';
+import { MailboxType } from '@dxos/plugin-inbox/types';
+import { MessageType } from '@dxos/plugin-space/types';
+import { type Space, Filter, create, makeRef } from '@dxos/react-client/echo';
+
+export const SOURCE_ID = 'hub.dxos.network/api/mailbox';
+
+export const handleEmail = async (space: Space, data: any) => {
+  const { messages } = data;
+
+  // Create mailbox if doesn't exist.
+  const { objects: mailboxes } = await space.db.query(Filter.schema(MailboxType)).run();
+  const mailbox = mailboxes[0] ?? space.db.add(create(MailboxType, { messages: [] }));
+
+  log.info('messages', { count: messages.length, existingMailbox: mailboxes.length > 0 });
+
+  const { objects } = await space.db.query(Filter.schema(MessageType)).run();
+  for (const message of messages) {
+    let object = findObjectWithForeignKey(objects, { source: SOURCE_ID, id: String(message.id) });
+    if (!object) {
+      object = space.db.add(
+        create(
+          MessageType,
+          {
+            sender: { email: message.from },
+            timestamp: new Date(message.created).toISOString(),
+            text: message.body,
+            properties: {
+              subject: message.subject,
+              to: [{ email: message.to }],
+            },
+          },
+          {
+            keys: [foreignKey(SOURCE_ID, String(message.id))],
+          },
+        ),
+      );
+      mailbox.messages?.push(makeRef(object));
+    }
+  }
+
+  return 200;
+};

package/src/hooks/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './processor';
+
+export * from './useChatProcessor';
+export * from './useLocalTriggerManager';
+export * from './useMessageQueue';
+export * from './useServices';
+export * from './useTextInputEvents';

package/src/hooks/invocation-handler.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { sleep } from '@dxos/async';
+import { getObjectCore, ResultFormat } from '@dxos/echo-db';
+import { type AnyObjectData } from '@dxos/echo-schema';
+import { FunctionType } from '@dxos/functions';
+import { type FunctionTrigger } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { DXN, LOCAL_SPACE_TAG } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { type Client, type Config } from '@dxos/react-client';
+import { type Space } from '@dxos/react-client/echo';
+
+const MAX_RETRIES = 3;
+const RETRY_DELAY = 1_000;
+
+const callFunction = async (funcUrl: string, trigger: any, data: any) => {
+  const body = { event: 'trigger', trigger, data };
+
+  let retryCount = 0;
+  while (retryCount < MAX_RETRIES) {
+    log.info('exec', { funcUrl, body, retryCount });
+    const response = await fetch(funcUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    const data = await response.text();
+    log.info('response', { status: response.status, body: data });
+    if (response.status === 409) {
+      retryCount++;
+      await sleep(RETRY_DELAY * Math.min(retryCount, 2));
+      continue;
+    }
+
+    return { status: response.status, data };
+  }
+  return { status: 500 };
+};
+
+export const invokeFunction = async (client: Client, space: Space, trigger: FunctionTrigger, data: any) => {
+  try {
+    invariant(trigger.spec);
+    invariant(trigger.function);
+
+    const script = await space.db.query({ id: trigger.function }, { format: ResultFormat.Plain }).first();
+    const { objects: functions } = await space.db
+      .query({ __typename: FunctionType.typename }, { format: ResultFormat.Plain })
+      .run();
+    const func = functions.find((fn) => referenceEquals(fn.source, trigger.function!)) as AnyObjectData | undefined;
+    const funcSlug = func?.__meta.keys.find((key) => key.source === USERFUNCTIONS_META_KEY)?.id;
+    if (!funcSlug) {
+      log.warn('function not deployed', { scriptId: script.id, name: script.name });
+      return 404;
+    }
+
+    const funcUrl = getFunctionUrl(client.config, funcSlug, space.id);
+    const triggerData: AnyObjectData = {
+      ...getObjectCore(trigger).toPlainObject(),
+      // TODO: Remove when functions can query by DXN.
+      promptId: trigger.meta?.prompt?.id,
+    };
+    // TODO: Remove when functions can add objects and easily modify collections (push, splice).
+    return (await callFunction(funcUrl, triggerData, data)).status;
+  } catch (err) {
+    return 400;
+  }
+};
+
+const USERFUNCTIONS_META_KEY = 'dxos.org/service/function';
+
+const getFunctionUrl = (config: Config, slug: string, spaceId?: string) => {
+  const baseUrl = new URL('functions/', config.values.runtime?.services?.edge?.url);
+
+  // Leading slashes cause the URL to be treated as an absolute path.
+  const relativeUrl = slug.replace(/^\//, '');
+  const url = new URL(`./${relativeUrl}`, baseUrl.toString());
+  spaceId && url.searchParams.set('spaceId', spaceId);
+  url.protocol = 'https';
+  return url.toString();
+};
+
+// TODO(dmaretskyi): Factor out.
+
+type ReferenceLike = { '/': string } | string;
+
+const referenceEquals = (a: ReferenceLike, b: ReferenceLike): boolean => {
+  const aDXN = toDXN(a);
+  const bDXN = toDXN(b);
+  return aDXN.toString() === bDXN.toString();
+};
+
+const toDXN = (ref: ReferenceLike): DXN => {
+  if (typeof ref === 'string') {
+    if (ref.startsWith('dxn:')) {
+      return DXN.parse(ref);
+    } else {
+      return new DXN(DXN.kind.ECHO, [LOCAL_SPACE_TAG, ref]);
+    }
+  }
+
+  invariant(typeof ref['/'] === 'string');
+  return DXN.parse(ref['/']);
+};

package/src/hooks/processor.test.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from 'vitest';
+
+import { ChatProcessor } from './processor';
+
+describe('ChatProcessor', () => {
+  it('should be instantiable', ({ expect }) => {
+    const client = {} as any; // TODO(burdon): Create mock.
+    const processor = new ChatProcessor(client);
+    expect(processor).toBeDefined();
+  });
+});

package/src/hooks/processor.ts

@@ -0,0 +1,228 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Signal, batch, computed, signal } from '@preact/signals-core';
+
+import { type PromiseIntentDispatcher } from '@dxos/app-framework';
+import { type Tool, Message, type MessageContentBlock } from '@dxos/artifact';
+import {
+  isToolUse,
+  runTools,
+  type GenerateRequest,
+  type GenerationStream,
+  MixedStreamParser,
+  DEFAULT_LLM_MODEL,
+  type AIService,
+} from '@dxos/assistant';
+import { createStatic } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { type Space } from '@dxos/react-client/echo';
+
+// TODO(burdon): Factor out.
+declare global {
+  interface ToolContextExtensions {
+    space?: Space;
+    dispatch?: PromiseIntentDispatcher;
+  }
+}
+
+type RequestOptions = {
+  history?: Message[];
+  onComplete?: (messages: Message[]) => void;
+};
+
+export type ChatProcessorOptions = Pick<GenerateRequest, 'model' | 'systemPrompt'>;
+
+const defaultOptions: ChatProcessorOptions = {
+  model: DEFAULT_LLM_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.
+ */
+export class ChatProcessor {
+  /** SSE stream parser. */
+  private readonly _parser = new MixedStreamParser();
+
+  /** Current streaming response. */
+  private _stream: GenerationStream | undefined;
+
+  /** Pending messages (incl. the current user request). */
+  private readonly _pending: Signal<Message[]> = signal([]);
+
+  /** Current streaming block (from the AI service). */
+  private readonly _block: Signal<MessageContentBlock | undefined> = signal(undefined);
+
+  /** Prior history from queue. */
+  private _history: Message[] = [];
+
+  /**
+   * Streaming state.
+   * @reactive
+   */
+  public readonly streaming: Signal<boolean> = computed(() => this._block.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<Message[]> = computed(() => {
+    const messages = [...this._pending.value];
+    if (this._block.value) {
+      const current = messages.pop();
+      invariant(current);
+      const { content, ...rest } = current;
+      const message = { ...rest, content: [...content, this._block.value] };
+      messages.push(message);
+    }
+
+    return messages;
+  });
+
+  constructor(
+    private readonly _service: AIService,
+    private _tools?: Tool[],
+    private readonly _extensions?: ToolContextExtensions,
+    private readonly _options: ChatProcessorOptions = defaultOptions,
+  ) {
+    // Message complete.
+    this._parser.message.on((message) => {
+      batch(() => {
+        this._pending.value = [...this._pending.value, message];
+        this._block.value = undefined;
+      });
+    });
+
+    // Streaming update (happens before message complete).
+    this._parser.update.on((block) => {
+      batch(() => {
+        this._block.value = block;
+      });
+    });
+  }
+
+  get tools() {
+    return this._tools;
+  }
+
+  /**
+   * Update tools.
+   */
+  setTools(tools: Tool[]) {
+    this._tools = tools;
+  }
+
+  /**
+   * Make GPT request.
+   */
+  async request(message: string, options: RequestOptions = {}): Promise<Message[]> {
+    batch(() => {
+      this._history = options.history ?? [];
+      this._pending.value = [
+        createStatic(Message, {
+          role: 'user',
+          content: [{ type: 'text', text: message }],
+        }),
+      ];
+      this._block.value = undefined;
+    });
+
+    await this._request();
+    options.onComplete?.(this._pending.value);
+    return this._reset();
+  }
+
+  /**
+   * Cancel pending requests.
+   * @returns Pending requests (incl. the request message).
+   */
+  async cancel(): Promise<Message[]> {
+    log.info('cancelling...');
+    this._stream?.abort();
+    return this._reset();
+  }
+
+  private async _reset(): Promise<Message[]> {
+    const messages = this._pending.value;
+    batch(() => {
+      this._history = [];
+      this._pending.value = [];
+      this._block.value = undefined;
+    });
+
+    return messages;
+  }
+
+  /**
+   * Generate a response from the AI service.
+   * Iterates over tool requests.
+   */
+  private async _request() {
+    try {
+      let more = false;
+      do {
+        log('request', {
+          pending: this._pending.value.length,
+          history: this._history.length,
+          tools: this._tools?.map((tool) => tool.name),
+        });
+
+        // Open request stream.
+        this._stream = await this._service.exec({
+          ...this._options,
+          // TODO(burdon): Rename messages or separate history/message.
+          history: [...this._history, ...this._pending.value],
+          tools: this._tools,
+        });
+
+        // Wait until complete.
+        await this._parser.parse(this._stream);
+        await this._stream.complete();
+
+        // Add messages.
+        log('response', { pending: this._pending.value });
+
+        // Resolve tool use locally.
+        more = false;
+        const message = this._pending.value.at(-1);
+        invariant(message);
+        if (isToolUse(message)) {
+          log('tool request...');
+          const response = await runTools({
+            message: this._pending.value.at(-1)!,
+            tools: this._tools ?? [],
+            extensions: this._extensions,
+          });
+
+          log('tool response', { response });
+          switch (response.type) {
+            case 'continue': {
+              this._pending.value = [...this._pending.value, response.message];
+              more = true;
+              break;
+            }
+          }
+        }
+      } while (more);
+
+      this.error.value = undefined;
+    } catch (err) {
+      log.catch(err);
+      this.error.value = new Error('AI service error', { cause: err });
+    } finally {
+      this._stream = undefined;
+    }
+  }
+}