@dxos/assistant 0.8.4-main.b97322e → 0.8.4-main.bcb3aa67d6

package/src/conversation/conversation.ts

@@ -2,95 +2,265 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type AiError, type AiLanguageModel, type AiTool, type AiToolkit } from '@effect/ai';
-import { Effect } from 'effect';
+import type * as Tool from '@effect/ai/Tool';
+import type * as Toolkit from '@effect/ai/Toolkit';
+import type { Registry } from '@effect-atom/atom-react';
+import * as Array from 'effect/Array';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
 
-import {
-  type ToolExecutionService,
-  type ToolResolverService,
-  type AiInputPreprocessingError,
-  type AiToolNotFoundError,
-} from '@dxos/ai';
-import { Event } from '@dxos/async';
+import { type ToolExecutionService, type ToolResolverService } from '@dxos/ai';
+import { type GenericToolkit } from '@dxos/ai';
+import { type Blueprint } from '@dxos/blueprints';
+import { Resource } from '@dxos/context';
 import { Obj } from '@dxos/echo';
 import { type Queue } from '@dxos/echo-db';
-import { DatabaseService } from '@dxos/functions';
-import { DataType } from '@dxos/schema';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { McpToolkit } from '@dxos/mcp-client';
+import { Message } from '@dxos/types';
+import * as Record from 'effect/Record';
 
-import { ContextBinder, type ContextBinding } from '../context';
-import type { AiAssistantError } from '../errors';
-import { AiSession } from '../session';
+import {
+  AiSession,
+  type AiSessionRunError,
+  type AiSessionRunRequirements,
+  type GenerationObserver,
+  createToolkit,
+  formatSystemPrompt,
+} from '../session';
 
-export interface ConversationRunOptions<Tools extends AiTool.Any> {
-  systemPrompt?: string;
-  prompt: string;
+import { AiContextBinder, AiContextService, type ContextBinding } from './context';
 
-  toolkit?: AiToolkit.AiToolkit<Tools>;
+export interface AiConversationRunProps<Tools extends Record<string, Tool.Any>> {
+  prompt: string;
+  system?: string;
+  observer?: GenerationObserver;
+  toolkit?: Toolkit.Toolkit<Tools>;
 }
 
-export type ConversationOptions = {
-  queue: Queue<DataType.Message | ContextBinding>;
+export type AiConversationOptions = {
+  queue: Queue<Message.Message | ContextBinding>;
+  registry?: Registry.Registry;
 };
 
+// TODO(dmaretskyi): Take from model characteristics. opus has 200k max tokens.
 /**
- * Persistent conversation state.
- * Context + history + artifacts.
- * Backed by a Queue.
+ * Summarization threshold in tokens.
  */
-export class Conversation {
-  private readonly _queue: Queue<DataType.Message | ContextBinding>;
-
-  /**
-   * Fired when the execution loop begins.
-   * This is called before the first message is sent.
-   */
-  public readonly onBegin = new Event<AiSession>();
+const SUMMARY_THRESHOLD = 80_000;
 
+/**
+ * Durable conversation state (initiated by users and agents) backed by a Queue.
+ * Executes tools based on AI responses and supports cancellation of in-progress requests.
+ */
+export class AiConversation extends Resource {
   /**
-   * Blueprints bound to the conversation.
+   * Blueprints and objects bound to the conversation.
    */
-  public readonly context: ContextBinder;
+  private readonly _binder: AiContextBinder;
+  private readonly _queue: Queue<Message.Message | ContextBinding>;
+  private readonly _toolkit?: Toolkit.Any;
 
-  constructor(options: ConversationOptions) {
+  public constructor(options: AiConversationOptions) {
+    super();
     this._queue = options.queue;
-    this.context = new ContextBinder(this._queue);
+    invariant(this._queue);
+    this._binder = new AiContextBinder({ queue: this._queue, registry: options.registry });
   }
 
-  async getHistory(): Promise<DataType.Message[]> {
-    const queueItems = await this._queue.queryObjects();
-    return queueItems.filter(Obj.instanceOf(DataType.Message));
+  protected override async _open(): Promise<void> {
+    await this._binder.open(this._ctx);
   }
 
-  run = <Tools extends AiTool.Any>(
-    options: ConversationRunOptions<Tools>,
-  ): Effect.Effect<
-    DataType.Message[],
-    AiAssistantError | AiInputPreprocessingError | AiError.AiError | AiToolNotFoundError,
-    AiLanguageModel.AiLanguageModel | ToolResolverService | ToolExecutionService | AiTool.ToHandler<Tools>
-  > =>
-    Effect.gen(this, function* () {
-      const session = new AiSession();
-      this.onBegin.emit(session);
+  public get queue() {
+    return this._queue;
+  }
 
+  public get context() {
+    return this._binder;
+  }
+
+  public get toolkit() {
+    return this._toolkit;
+  }
+
+  public async getHistory(): Promise<Message.Message[]> {
+    const queueItems = await this._queue.queryObjects(); // TODO(burdon): Update.
+    return queueItems.filter(Obj.instanceOf(Message.Message));
+  }
+
+  getTools(): Effect.Effect<Record<string, Tool.Any>, never, ToolExecutionService | ToolResolverService> {
+    return Effect.gen(this, function* () {
+      const blueprints = this.context.getBlueprints();
+      const tookit = yield* createToolkit({ toolkit: this._toolkit, blueprints });
+      return tookit.tools;
+    }).pipe(Effect.orDie);
+  }
+
+  /**
+   * Creates a new cancelable request effect.
+   */
+  public createRequest<Tools extends Record<string, Tool.Any> = {}>(
+    params: AiConversationRunProps<Tools>,
+  ): Effect.Effect<Message.Message[], AiSessionRunError, AiSessionRunRequirements | Tool.HandlersFor<Tools>> {
+    return Effect.gen(this, function* () {
       const history = yield* Effect.promise(() => this.getHistory());
-      const context = yield* Effect.promise(() => this.context.query());
-      const blueprints = yield* Effect.forEach(context.blueprints.values(), DatabaseService.loadRef);
+      const blueprints = this.context.getBlueprints();
+      const objects = this.context.getObjects();
 
-      const contextObjects = yield* Effect.forEach(context.objects.values(), DatabaseService.loadRef);
+      log('run', {
+        history: history.length,
+        blueprints: blueprints.length,
+        objects: objects.length,
+      });
 
-      const systemPrompt =
-        (options.systemPrompt ?? '') +
-        '\n\n' +
-        contextObjects.map((obj) => `<object>${Obj.getDXN(obj)}</object>`).join('\n');
+      const session = new AiSession({
+        summarizationThreshold: SUMMARY_THRESHOLD,
+        observer: params.observer,
+        onOutput: (message) => Effect.promise(() => this._queue.append([message])),
+      });
 
-      const messages = yield* session.run({
-        prompt: options.prompt,
+      yield* session.begin({
         history,
-        systemPrompt,
-        toolkit: options.toolkit,
         blueprints,
+        objects,
+        prompt: params.prompt,
+        system: params.system,
       });
-      yield* Effect.promise(() => this._queue.append(messages));
-      return messages;
-    }).pipe(Effect.withSpan('Conversation.run'));
+
+      // Turn loop: recompute toolkit and system prompt between turns to pick up dynamically enabled blueprints.
+      do {
+        const currentBlueprints = this.context.getBlueprints();
+        const mcps = yield* connectMcpServers(currentBlueprints);
+        const toolkit = yield* createToolkit({
+          toolkit: params.toolkit,
+          blueprints: currentBlueprints,
+          genericToolkits: mcps,
+        });
+        log('toolkit', { tools: Record.keys(toolkit.tools) });
+        const system = yield* formatSystemPrompt({
+          system: params.system,
+          blueprints: currentBlueprints,
+          objects: this.context.getObjects(),
+        }).pipe(Effect.orDie);
+
+        const { done } = yield* session.runAgentTurn({
+          system,
+          toolkit,
+        });
+
+        if (done) {
+          break;
+        }
+
+        yield* session.runTools({ toolkit });
+      } while (true);
+
+      log('result', {
+        messages: session.pending.length,
+        duration: session.duration,
+        toolCalls: session.toolCalls,
+      });
+
+      return [...session.pending];
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          Layer.succeed(AiContextService, {
+            binder: this.context,
+          }),
+          Layer.succeed(AiConversationService, this),
+        ),
+      ),
+    );
+  }
+}
+
+/**
+ * Gives access to the ai conversation.
+ */
+export class AiConversationService extends Context.Tag('@dxos/assistant/AiConversationService')<
+  AiConversationService,
+  AiConversation
+>() {
+  /**
+   * Create a new conversation layer from options.
+   */
+  static layer = (options: AiConversationOptions): Layer.Layer<AiConversationService | AiContextService> =>
+    aiContextFromConversation.pipe(
+      Layer.provideMerge(
+        Layer.scoped(
+          AiConversationService,
+          Effect.gen(function* () {
+            const conversation = yield* acquireReleaseResource(() => new AiConversation(options));
+            return conversation;
+          }),
+        ),
+      ),
+    );
+
+  /**
+   * Create a new conversation with a new queue.
+   */
+  static layerNewQueue = (
+    options?: Omit<AiConversationOptions, 'queue'>,
+  ): Layer.Layer<AiConversationService | AiContextService, never, QueueService> =>
+    Layer.unwrapScoped(
+      Effect.gen(function* () {
+        return AiConversationService.layer({
+          ...options,
+          queue: yield* QueueService.createQueue<Message.Message | ContextBinding>(),
+        });
+      }),
+    );
+
+  /**
+   * Run a prompt in the current conversation.
+   */
+  static run = <Tools extends Record<string, Tool.Any> = {}>(
+    params: AiConversationRunProps<Tools>,
+  ): Effect.Effect<
+    Message.Message[],
+    AiSessionRunError,
+    AiSessionRunRequirements | Tool.HandlersFor<Tools> | AiConversationService
+  > =>
+    Effect.gen(function* () {
+      const conversation = yield* AiConversationService;
+      return yield* conversation.createRequest(params);
+    });
 }
+
+const aiContextFromConversation = Layer.effect(
+  AiContextService,
+  Effect.gen(function* () {
+    const conversation = yield* AiConversationService;
+    return {
+      binder: conversation.context,
+    };
+  }),
+);
+
+const connectMcpServers = (
+  blueprints: readonly Blueprint.Blueprint[],
+): Effect.Effect<GenericToolkit.GenericToolkit[]> =>
+  pipe(
+    blueprints,
+    Array.flatMap((_) => _.mcpServers ?? []),
+    Effect.forEach(({ url, protocol }) =>
+      McpToolkit.make({ url, kind: protocol }).pipe(
+        // NOTE: Type-inference fails here without explicit void return.
+        Effect.tap((toolkit): void =>
+          log.info('Connected to MCP server', { url, tools: Object.keys(toolkit.toolkit.tools).length }),
+        ),
+        Effect.tapDefect((error) => Effect.sync(() => log.warn('Failed to connect to MCP server', { error }))),
+        Effect.either,
+      ),
+    ),
+    Effect.map(Array.filterMap((_) => Either.getRight(_))),
+  );

package/src/conversation/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './context';
 export * from './conversation';

package/src/diff.test.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { createDocAccessor } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { applyDiffs } from './diff';
+
+describe('diff', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  it('should apply diffs', async () => {
+    const { db } = await builder.createDatabase({ types: [Text.Text] });
+
+    const document = trim`
+      # Hello World
+      There'z a typo in this sentence.
+      And another oon here.
+      But not this one.
+    `;
+
+    const text = db.add(Text.make({ content: document }));
+    const accessor = createDocAccessor(text, ['content']);
+    const result = applyDiffs(accessor, [
+      `- There'z a typo in this sentence.`,
+      `+ There is a typo in this sentence.`,
+      `- And another oon here.`,
+      `+ And another one here.`,
+    ]);
+
+    expect(result).toBe(trim`
+      # Hello World
+      There is a typo in this sentence.
+      And another one here.
+      But not this one.
+    `);
+  });
+
+  it('should apply diffs that append content at the end', async () => {
+    const { db } = await builder.createDatabase({ types: [Text.Text] });
+
+    const document = '# Shopping list';
+
+    const text = db.add(Text.make({ content: document }));
+    const accessor = createDocAccessor(text, ['content']);
+    const result = applyDiffs(accessor, ['- # Shopping list', '+ # Shopping list\n- Milk']);
+
+    expect(result).toBe('# Shopping list\n- Milk');
+  });
+
+  it('should append text to an empty document', async () => {
+    const builder = new EchoTestBuilder();
+    const { db, graph } = await builder.createDatabase();
+    await graph.schemaRegistry.register([Text.Text]);
+
+    const text = db.add(Text.make({ content: '' }));
+    const accessor = createDocAccessor(text, ['content']);
+    const result = applyDiffs(accessor, ['+ # Shopping list']);
+
+    expect(result).toBe('# Shopping list');
+  });
+});

package/src/diff.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { next as A, type Doc } from '@automerge/automerge';
+
+import { DocAccessor, toCursorRange } from '@dxos/echo-db';
+import { log } from '@dxos/log';
+import { isNonNullable } from '@dxos/util';
+
+// Relevant info:
+// https://github.com/Minahil-official/GPT-4.1-Promting-Guide?tab=readme-ov-file#-apply-patch-tool-format-v4a-diff
+
+// TODO(burdon): Anthropic only.
+//  https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/text-editor-tool#example-str-replace-command
+//  AI_TOOL_NOT_FOUND: str_replace_based_edit_tool
+// 'str_replace_based_edit_tool',
+
+// TOOD(burdon): Support append to end (no "-").
+
+export type Diff = {
+  match: string;
+  replace: string;
+};
+
+/**
+ * Convert a list of diffs into a list of operations.
+ */
+export const reduceDiffs = (diffs: readonly string[]): Diff[] => {
+  return diffs.reduce<Diff[]>((acc, diff) => {
+    const current = acc[acc.length - 1];
+    const [op, ...rest] = diff.split(' ');
+    switch (op) {
+      case '-': {
+        if (current && !current.match) {
+          current.match += rest.join(' ');
+        } else {
+          acc.push({ match: rest.join(' '), replace: '' });
+        }
+        return acc;
+      }
+      case '+': {
+        if (current && !current.replace) {
+          current.replace += rest.join(' ');
+        } else {
+          acc.push({ match: '', replace: rest.join(' ') });
+        }
+        return acc;
+      }
+      default: {
+        throw new Error(`Invalid diff format: each line must start with "- " or "+ ", got: ${JSON.stringify(diff)}`);
+      }
+    }
+  }, []);
+};
+
+export const computeDiffsWithCursors = <T>(accessor: DocAccessor<T>, diffs: readonly string[]) => {
+  return reduceDiffs(diffs)
+    .map((diff) => {
+      const text = DocAccessor.getValue<string>(accessor);
+      const idx = text.indexOf(diff.match);
+      if (idx !== -1) {
+        return { cursor: toCursorRange(accessor, idx, idx + diff.match.length), text: diff.replace };
+      }
+    })
+    .filter(isNonNullable);
+};
+
+export const applyDiffs = <T>(
+  accessor: DocAccessor<T>,
+  diffs: readonly string[],
+  { errorOnNotFound = false }: { errorOnNotFound?: boolean } = {},
+): string => {
+  for (const diff of reduceDiffs(diffs)) {
+    accessor.handle.change((doc: Doc<T>) => {
+      const text = DocAccessor.getValue<string>(accessor);
+      const idx = text.indexOf(diff.match);
+      if (idx !== -1) {
+        // TODO(burdon): Replace smallest substring.
+        // NOTE: This only replaces the first match.
+        A.splice(doc, accessor.path as A.Prop[], idx, diff.match.length, diff.replace);
+      } else {
+        if (errorOnNotFound) {
+          throw new Error(`Diff not found: ${diff.match}`);
+        } else {
+          log.warn('diff not found', diff);
+        }
+      }
+    });
+  }
+
+  return DocAccessor.getValue<string>(accessor);
+};

package/src/errors.ts

@@ -4,7 +4,12 @@
 
 import { BaseError } from '@dxos/errors';
 
+/**
+ * Generic error from AI model.
+ */
+export class AiModelError extends BaseError.extend('AiModelError', 'AI model error') {}
+
 /**
  * Generic error for AI agent execution.
  */
-export class AiAssistantError extends BaseError.extend('AI_ASSISTANT_ERROR') {}
+export class AiAssistantError extends BaseError.extend('AiAssistantError', 'AI assistant error') {}