@dxos/assistant 0.8.4-main.84f28bd → 0.8.4-main.a4bbb77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-main.84f28bd",
+  "version": "0.8.4-main.a4bbb77",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,43 +10,69 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./extraction": {
+      "source": "./src/extraction/index.ts",
+      "types": "./dist/types/src/extraction/index.d.ts",
+      "browser": "./dist/lib/browser/extraction/index.mjs",
+      "node": "./dist/lib/node-esm/extraction/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "types": [
+        "dist/types/src/types/index.d.ts"
+      ],
+      "extraction": [
+        "dist/types/src/extraction/index.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.9.0",
+    "@automerge/automerge": "3.1.2",
+    "@effect/ai": "0.29.1",
+    "@effect/ai-anthropic": "^0.19.2",
+    "@effect/experimental": "0.56.0",
+    "@effect/platform": "^0.92.1",
+    "@effect/platform-node": "^0.98.3",
+    "@preact/signals-core": "^1.12.1",
     "@xenova/transformers": "^2.17.2",
     "chalk": "^4.1.0",
-    "exa-js": "^1.5.12",
-    "@dxos/ai": "0.8.4-main.84f28bd",
-    "@dxos/artifact": "0.8.4-main.84f28bd",
-    "@dxos/async": "0.8.4-main.84f28bd",
-    "@dxos/debug": "0.8.4-main.84f28bd",
-    "@dxos/echo": "0.8.4-main.84f28bd",
-    "@dxos/context": "0.8.4-main.84f28bd",
-    "@dxos/echo-db": "0.8.4-main.84f28bd",
-    "@dxos/echo-protocol": "0.8.4-main.84f28bd",
-    "@dxos/echo-schema": "0.8.4-main.84f28bd",
-    "@dxos/effect": "0.8.4-main.84f28bd",
-    "@dxos/functions": "0.8.4-main.84f28bd",
-    "@dxos/graph": "0.8.4-main.84f28bd",
-    "@dxos/invariant": "0.8.4-main.84f28bd",
-    "@dxos/keys": "0.8.4-main.84f28bd",
-    "@dxos/live-object": "0.8.4-main.84f28bd",
-    "@dxos/log": "0.8.4-main.84f28bd",
-    "@dxos/node-std": "0.8.4-main.84f28bd",
-    "@dxos/schema": "0.8.4-main.84f28bd",
-    "@dxos/util": "0.8.4-main.84f28bd"
+    "handlebars": "4.7.8",
+    "lodash.defaultsdeep": "^4.6.1",
+    "@dxos/ai": "0.8.4-main.a4bbb77",
+    "@dxos/async": "0.8.4-main.a4bbb77",
+    "@dxos/blueprints": "0.8.4-main.a4bbb77",
+    "@dxos/context": "0.8.4-main.a4bbb77",
+    "@dxos/debug": "0.8.4-main.a4bbb77",
+    "@dxos/echo": "0.8.4-main.a4bbb77",
+    "@dxos/echo-schema": "0.8.4-main.a4bbb77",
+    "@dxos/effect": "0.8.4-main.a4bbb77",
+    "@dxos/echo-db": "0.8.4-main.a4bbb77",
+    "@dxos/errors": "0.8.4-main.a4bbb77",
+    "@dxos/echo-protocol": "0.8.4-main.a4bbb77",
+    "@dxos/graph": "0.8.4-main.a4bbb77",
+    "@dxos/invariant": "0.8.4-main.a4bbb77",
+    "@dxos/functions": "0.8.4-main.a4bbb77",
+    "@dxos/keys": "0.8.4-main.a4bbb77",
+    "@dxos/live-object": "0.8.4-main.a4bbb77",
+    "@dxos/log": "0.8.4-main.a4bbb77",
+    "@dxos/node-std": "0.8.4-main.a4bbb77",
+    "@dxos/schema": "0.8.4-main.a4bbb77",
+    "@dxos/util": "0.8.4-main.a4bbb77"
   },
   "devDependencies": {
-    "effect": "3.16.13",
+    "@types/lodash.defaultsdeep": "^4.6.6",
+    "effect": "3.18.3",
     "inquirer": "^12.0.0"
   },
   "peerDependencies": {
@@ -57,6 +83,6 @@
   },
   "beast": {},
   "scripts": {
-    "run:chat": "tsx ./bin/chat.ts"
+    "run:chat": "vite-node ./bin/chat.ts"
   }
 }

package/src/conversation/context.ts

@@ -0,0 +1,154 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ReadonlySignal, computed } from '@preact/signals-core';
+import { Context, Schema } from 'effect';
+import { Array, pipe } from 'effect';
+
+import { Blueprint } from '@dxos/blueprints';
+import { DXN, Obj, type Ref, type Relation, Type } from '@dxos/echo';
+import { type Queue } from '@dxos/echo-db';
+import { ComplexSet } from '@dxos/util';
+
+/**
+ * Thread message that binds or unbinds contextual objects to a conversation.
+ */
+// TODO(burdon): Move to @dxos/schema ContentBlock?
+export const ContextBinding = Schema.Struct({
+  blueprints: Schema.Struct({
+    added: Schema.Array(Type.Ref(Blueprint.Blueprint)),
+    removed: Schema.Array(Type.Ref(Blueprint.Blueprint)),
+  }),
+
+  // TODO(burdon): Type.Expando => Type.Obj (or Obj.Any?)
+  objects: Schema.Struct({
+    added: Schema.Array(Type.Ref(Type.Expando)),
+    removed: Schema.Array(Type.Ref(Type.Expando)),
+  }),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/ContextBinding',
+    version: '0.1.0',
+  }),
+);
+
+export interface ContextBinding extends Schema.Schema.Type<typeof ContextBinding> {}
+
+export type BindingProps = Partial<{
+  blueprints: Ref.Ref<Blueprint.Blueprint>[];
+  objects: Ref.Ref<Type.Expando>[];
+}>;
+
+export class Bindings {
+  readonly blueprints = new ComplexSet<Ref.Ref<Blueprint.Blueprint>>((ref) => ref.dxn.toString());
+  // TODO(burdon): Some DXNs have the Space prefix so only compare the object ID.
+  readonly objects = new ComplexSet<Ref.Ref<Type.Expando>>((ref) => ref.dxn.asEchoDXN()?.echoId);
+
+  toJSON() {
+    return {
+      blueprints: Array.fromIterable(this.blueprints).map((ref) => ref.dxn.toString()),
+      objects: Array.fromIterable(this.objects).map((ref) => ref.dxn.toString()),
+    };
+  }
+}
+
+/**
+ * Manages bindings of blueprints and objects to a conversation.
+ */
+// TODO(burdon): Context should manage ephemeral state of bindings until prompt is issued?
+export class AiContextBinder {
+  /**
+   * Reactive query of all bindings.
+   */
+  // TODO(burdon): Cache value?
+  readonly bindings: ReadonlySignal<Bindings> = computed(() => this._reduce(this._queue.objects));
+
+  readonly blueprints: ReadonlySignal<Ref.Ref<Blueprint.Blueprint>[]> = computed(() => [
+    ...this.bindings.value.blueprints,
+  ]);
+
+  readonly objects: ReadonlySignal<Ref.Ref<Type.Expando>[]> = computed(() => [...this.bindings.value.objects]);
+
+  constructor(private readonly _queue: Queue) {}
+
+  /**
+   * Asynchronous query of all bindings.
+   */
+  async query(): Promise<Bindings> {
+    const queueItems = await this._queue.queryObjects();
+    return this._reduce(queueItems);
+  }
+
+  // TODO(burdon): Pass in Blueprint obj (from registry?) and create reference.
+  async bind(props: BindingProps): Promise<void> {
+    if (!props.blueprints?.length && !props.objects?.length) {
+      return;
+    }
+
+    const blueprints =
+      props.blueprints?.filter((ref) => !this.blueprints.peek().find((b) => b.dxn.toString() === ref.dxn.toString())) ??
+      [];
+    const objects =
+      props.objects?.filter((ref) => !this.objects.peek().find((o) => o.dxn.toString() === ref.dxn.toString())) ?? [];
+
+    await this._queue.append([
+      Obj.make(ContextBinding, {
+        blueprints: {
+          added: blueprints,
+          removed: [],
+        },
+        objects: {
+          added: objects,
+          removed: [],
+        },
+      }),
+    ]);
+  }
+
+  async unbind(props: BindingProps): Promise<void> {
+    if (!props.blueprints?.length && !props.objects?.length) {
+      return;
+    }
+
+    await this._queue.append([
+      Obj.make(ContextBinding, {
+        blueprints: {
+          added: [],
+          removed: props.blueprints ?? [],
+        },
+        objects: {
+          added: [],
+          removed: props.objects ?? [],
+        },
+      }),
+    ]);
+  }
+
+  private _reduce(items: (Obj.Any | Relation.Any)[]): Bindings {
+    return pipe(
+      items,
+      Array.filter(Obj.instanceOf(ContextBinding)),
+      Array.reduce(new Bindings(), (context, item) => {
+        item.blueprints.removed.forEach((ref) => context.blueprints.delete(ref));
+        item.blueprints.added.forEach((ref) => context.blueprints.add(ref));
+        item.objects.removed.forEach((ref) => {
+          for (const obj of context.objects) {
+            if (DXN.equalsEchoId(obj.dxn, ref.dxn)) {
+              context.objects.delete(obj);
+            }
+          }
+        });
+        item.objects.added.forEach((ref) => context.objects.add(ref));
+        return context;
+      }),
+    );
+  }
+}
+
+export class AiContextService extends Context.Tag('@dxos/assistant/AiContextService')<
+  AiContextService,
+  {
+    binder: AiContextBinder;
+  }
+>() {}

package/src/conversation/conversation.ts

@@ -2,102 +2,118 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Message, type ExecutableTool } from '@dxos/ai';
-import { type ArtifactDefinition } from '@dxos/artifact';
-import { Event } from '@dxos/async';
-import { Obj, Ref } from '@dxos/echo';
+import { type Toolkit } from '@effect/ai';
+import { Array, Effect, Option } from 'effect';
+
+import { Obj } from '@dxos/echo';
 import { type Queue } from '@dxos/echo-db';
-import { AiService, ToolResolverService, type ServiceContainer } from '@dxos/functions';
+import { DatabaseService } from '@dxos/functions';
 import { log } from '@dxos/log';
-import { isNonNullable } from '@dxos/util';
-
-import { ContextBinder, type ContextBinding } from '../context';
-import { AISession, type SessionRunOptions } from '../session';
-
-export interface ConversationRunOptions {
-  systemPrompt?: string;
-  prompt: string;
+import { DataType } from '@dxos/schema';
 
-  tools?: ExecutableTool[];
-  artifacts?: ArtifactDefinition[];
-  extensions?: ToolContextExtensions;
-  generationOptions?: SessionRunOptions['generationOptions'];
+import {
+  AiSession,
+  type AiSessionRunError,
+  type AiSessionRunRequirements,
+  type GenerationObserver,
+  createToolkit,
+} from '../session';
 
-  /** @depreacated Should be managed by the conversation. */
-  requiredArtifactIds?: string[];
+import { AiContextBinder, AiContextService, type ContextBinding } from './context';
 
-  // TODO(dmaretskyi): Move into conversation.
-  artifactDiffResolver?: SessionRunOptions['artifactDiffResolver'];
+export interface AiConversationRunParams {
+  prompt: string;
+  system?: string;
+  observer?: GenerationObserver;
 }
 
-export type ConversationOptions = {
-  serviceContainer: ServiceContainer;
-  queue: Queue<Message | ContextBinding>;
+export type AiConversationOptions = {
+  queue: Queue<DataType.Message | ContextBinding>;
 };
 
 /**
- * Persistent conversation state.
- * Context + history + artifacts.
- * Backed by a Queue.
+ * 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 Conversation {
-  private readonly _serviceContainer: ServiceContainer;
-  private readonly _queue: Queue<Message | ContextBinding>;
-
+export class AiConversation {
   /**
-   * Fired when the execution loop begins.
-   * This is called before the first message is sent.
+   * Message and binding queue.
    */
-  public readonly onBegin = new Event<AISession>();
+  private readonly _queue: Queue<DataType.Message | ContextBinding>;
 
   /**
    * Blueprints bound to the conversation.
    */
-  public readonly context: ContextBinder;
+  private readonly _context: AiContextBinder;
 
-  constructor(options: ConversationOptions) {
-    this._serviceContainer = options.serviceContainer;
+  /**
+   * Toolkit from the current session request.
+   */
+  private _toolkit: Toolkit.WithHandler<any> | undefined;
+
+  public constructor(options: AiConversationOptions) {
     this._queue = options.queue;
-    this.context = new ContextBinder(this._queue);
+    this._context = new AiContextBinder(this._queue);
+  }
+
+  public get context() {
+    return this._context;
   }
 
-  async run(options: ConversationRunOptions): Promise<Message[]> {
-    const session = new AISession({ operationModel: 'configured' });
-    this.onBegin.emit(session);
-
-    const history = await this.getHistory();
-    const context = await this.context.query();
-    const blueprints = (await Ref.Array.loadAll([...context.blueprints])).filter(isNonNullable);
-    if (blueprints.length > 1) {
-      log.warn('multiple blueprints are not yet supported');
-    }
-
-    const messages = await session.run({
-      history,
-      prompt: options.prompt,
-      systemPrompt: (options.systemPrompt ?? '') + (blueprints.at(0)?.instructions ?? ''),
-
-      // TODO(dmaretskyi): Artifacts come from the blueprint?
-      artifacts: options.artifacts ?? [],
-      tools: blueprints.at(0)?.tools ?? [],
-      executableTools: options.tools,
-      requiredArtifactIds: options.requiredArtifactIds,
-      client: this._serviceContainer.getService(AiService).client,
-      toolResolver: this._serviceContainer.getService(ToolResolverService).toolResolver,
-      extensions: {
-        serviceContainer: this._serviceContainer,
-        ...options.extensions,
-      },
-      generationOptions: options.generationOptions,
-    });
-
-    await this._queue.append(messages);
-
-    return messages;
+  public get toolkit() {
+    return this._toolkit;
   }
 
-  async getHistory(): Promise<Message[]> {
+  public async getHistory(): Promise<DataType.Message[]> {
     const queueItems = await this._queue.queryObjects();
-    return queueItems.filter(Obj.instanceOf(Message));
+    return queueItems.filter(Obj.instanceOf(DataType.Message));
+  }
+
+  /**
+   * Creates a new cancelable request effect.
+   */
+  createRequest(
+    params: AiConversationRunParams,
+  ): Effect.Effect<DataType.Message[], AiSessionRunError, AiSessionRunRequirements> {
+    return Effect.gen(this, function* () {
+      const session = new AiSession();
+      const history = yield* Effect.promise(() => this.getHistory());
+
+      // Get context objects.
+      const context = yield* Effect.promise(() => this.context.query());
+      const blueprints = yield* Effect.forEach(context.blueprints.values(), DatabaseService.loadOption).pipe(
+        Effect.map(Array.filter(Option.isSome)),
+        Effect.map(Array.map((option) => option.value)),
+      );
+      const objects = yield* Effect.forEach(context.objects.values(), DatabaseService.loadOption).pipe(
+        Effect.map(Array.filter(Option.isSome)),
+        Effect.map(Array.map((option) => option.value)),
+      );
+
+      // Create toolkit.
+      const toolkit = yield* createToolkit({ blueprints });
+      this._toolkit = toolkit;
+
+      const start = Date.now();
+      log('run', {
+        history: history.length,
+        blueprints: blueprints.length,
+        objects: objects.length,
+        tools: this._toolkit?.tools.length ?? 0,
+      });
+
+      // Process request.
+      const messages = yield* session.run({ history, blueprints, objects, toolkit, ...params }).pipe(
+        Effect.provideService(AiContextService, {
+          binder: this.context,
+        }),
+      );
+
+      log('result', { messages: messages.length, duration: Date.now() - start });
+
+      // Append to queue.
+      yield* Effect.promise(() => this._queue.append(messages));
+      return messages;
+    }).pipe(Effect.withSpan('AiConversation.request'));
   }
 }

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,43 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from 'vitest';
+
+import { createDocAccessor } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { DataType } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { applyDiffs } from './diff';
+
+describe('diff', () => {
+  it('should apply diffs', async () => {
+    const builder = new EchoTestBuilder();
+    const { db, graph } = await builder.createDatabase();
+    graph.schemaRegistry.addSchema([DataType.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(DataType.makeText(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.
+    `);
+  });
+});

package/src/diff.ts

@@ -0,0 +1,79 @@
+//
+// 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
+
+// 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;
+      }
+    }
+
+    return acc;
+  }, []);
+};
+
+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[]): 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 {
+        log.warn('diff not found', diff);
+      }
+    });
+  }
+
+  return DocAccessor.getValue<string>(accessor);
+};

package/src/errors.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError } from '@dxos/errors';
+
+/**
+ * Generic error from AI model.
+ */
+export class AiModelError extends BaseError.extend('AI_MODEL_ERROR', 'AI model error') {}
+
+/**
+ * Generic error for AI agent execution.
+ */
+export class AiAssistantError extends BaseError.extend('AI_ASSISTANT_ERROR', 'AI assistant error') {}