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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-main.b97322e",
+  "version": "0.8.4-main.dedc0f3",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,51 +10,68 @@
   "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": {
-    "@effect/ai": "0.23.0",
-    "@effect/ai-anthropic": "^0.13.0",
-    "@effect/platform": "^0.89.0",
-    "@effect/platform-node": "^0.92.0",
+    "@automerge/automerge": "3.1.1",
+    "@effect/ai": "0.25.2",
+    "@effect/ai-anthropic": "^0.16.1",
+    "@effect/platform": "^0.90.2",
+    "@effect/platform-node": "^0.95.0",
     "@preact/signals-core": "^1.9.0",
     "@xenova/transformers": "^2.17.2",
     "chalk": "^4.1.0",
-    "exa-js": "^1.5.12",
     "handlebars": "4.7.8",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/ai": "0.8.4-main.b97322e",
-    "@dxos/async": "0.8.4-main.b97322e",
-    "@dxos/context": "0.8.4-main.b97322e",
-    "@dxos/blueprints": "0.8.4-main.b97322e",
-    "@dxos/debug": "0.8.4-main.b97322e",
-    "@dxos/echo": "0.8.4-main.b97322e",
-    "@dxos/echo-db": "0.8.4-main.b97322e",
-    "@dxos/effect": "0.8.4-main.b97322e",
-    "@dxos/echo-schema": "0.8.4-main.b97322e",
-    "@dxos/errors": "0.8.4-main.b97322e",
-    "@dxos/functions": "0.8.4-main.b97322e",
-    "@dxos/invariant": "0.8.4-main.b97322e",
-    "@dxos/graph": "0.8.4-main.b97322e",
-    "@dxos/keys": "0.8.4-main.b97322e",
-    "@dxos/log": "0.8.4-main.b97322e",
-    "@dxos/live-object": "0.8.4-main.b97322e",
-    "@dxos/node-std": "0.8.4-main.b97322e",
-    "@dxos/schema": "0.8.4-main.b97322e",
-    "@dxos/util": "0.8.4-main.b97322e",
-    "@dxos/echo-protocol": "0.8.4-main.b97322e"
+    "@dxos/ai": "0.8.4-main.dedc0f3",
+    "@dxos/blueprints": "0.8.4-main.dedc0f3",
+    "@dxos/context": "0.8.4-main.dedc0f3",
+    "@dxos/async": "0.8.4-main.dedc0f3",
+    "@dxos/debug": "0.8.4-main.dedc0f3",
+    "@dxos/echo-db": "0.8.4-main.dedc0f3",
+    "@dxos/echo-protocol": "0.8.4-main.dedc0f3",
+    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
+    "@dxos/errors": "0.8.4-main.dedc0f3",
+    "@dxos/functions": "0.8.4-main.dedc0f3",
+    "@dxos/effect": "0.8.4-main.dedc0f3",
+    "@dxos/graph": "0.8.4-main.dedc0f3",
+    "@dxos/keys": "0.8.4-main.dedc0f3",
+    "@dxos/echo": "0.8.4-main.dedc0f3",
+    "@dxos/log": "0.8.4-main.dedc0f3",
+    "@dxos/node-std": "0.8.4-main.dedc0f3",
+    "@dxos/schema": "0.8.4-main.dedc0f3",
+    "@dxos/invariant": "0.8.4-main.dedc0f3",
+    "@dxos/util": "0.8.4-main.dedc0f3",
+    "@dxos/live-object": "0.8.4-main.dedc0f3"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "effect": "3.17.0",
+    "effect": "3.17.7",
     "inquirer": "^12.0.0"
   },
   "peerDependencies": {
@@ -65,6 +82,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,95 +2,122 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type AiError, type AiLanguageModel, type AiTool, type AiToolkit } from '@effect/ai';
-import { Effect } from 'effect';
+import { type AiTool, type AiToolkit } from '@effect/ai';
+import { Array, Effect, Option } from 'effect';
 
-import {
-  type ToolExecutionService,
-  type ToolResolverService,
-  type AiInputPreprocessingError,
-  type AiToolNotFoundError,
-} from '@dxos/ai';
-import { Event } from '@dxos/async';
 import { Obj } from '@dxos/echo';
 import { type Queue } from '@dxos/echo-db';
 import { DatabaseService } from '@dxos/functions';
+import { log } from '@dxos/log';
 import { DataType } from '@dxos/schema';
 
-import { ContextBinder, type ContextBinding } from '../context';
-import type { AiAssistantError } from '../errors';
-import { AiSession } from '../session';
+import {
+  AiSession,
+  type AiSessionRunError,
+  type AiSessionRunRequirements,
+  type GenerationObserver,
+  createToolkit,
+} 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 type AiConversationRunRequirements<Tools extends AiTool.Any> =
+  | AiSessionRunRequirements
+  | AiTool.ToHandler<Tools>;
+
+export interface AiConversationRunParams {
+  prompt: string;
+  system?: string;
+  observer?: GenerationObserver;
 }
 
-export type ConversationOptions = {
+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 {
+export class AiConversation {
+  /**
+   * Message and binding queue.
+   */
   private readonly _queue: Queue<DataType.Message | ContextBinding>;
 
   /**
-   * Fired when the execution loop begins.
-   * This is called before the first message is sent.
+   * Blueprints bound to the conversation.
    */
-  public readonly onBegin = new Event<AiSession>();
+  private readonly _context: AiContextBinder;
 
   /**
-   * Blueprints bound to the conversation.
+   * Toolkit from the current session request.
    */
-  public readonly context: ContextBinder;
+  private _toolkit: AiToolkit.ToHandler<AiTool.Any> | undefined;
 
-  constructor(options: ConversationOptions) {
+  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;
+  }
+
+  public get toolkit() {
+    return this._toolkit;
   }
 
-  async getHistory(): Promise<DataType.Message[]> {
+  public async getHistory(): Promise<DataType.Message[]> {
     const queueItems = await this._queue.queryObjects();
     return queueItems.filter(Obj.instanceOf(DataType.Message));
   }
 
-  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* () {
+  /**
+   * Creates a new cancelable request effect.
+   */
+  createRequest<Tools extends AiTool.Any>(
+    params: AiConversationRunParams,
+  ): Effect.Effect<DataType.Message[], AiSessionRunError, AiConversationRunRequirements<Tools>> {
+    return Effect.gen(this, function* () {
       const session = new AiSession();
-      this.onBegin.emit(session);
-
       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.loadRef);
+      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<Tools>({ 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,
+      });
 
-      const contextObjects = yield* Effect.forEach(context.objects.values(), DatabaseService.loadRef);
+      // Process request.
+      const messages = yield* session.run<Tools>({ history, blueprints, objects, toolkit, ...params }).pipe(
+        Effect.provideService(AiContextService, {
+          binder: this.context,
+        }),
+      );
 
-      const systemPrompt =
-        (options.systemPrompt ?? '') +
-        '\n\n' +
-        contextObjects.map((obj) => `<object>${Obj.getDXN(obj)}</object>`).join('\n');
+      log('result', { messages: messages.length, duration: Date.now() - start });
 
-      const messages = yield* session.run({
-        prompt: options.prompt,
-        history,
-        systemPrompt,
-        toolkit: options.toolkit,
-        blueprints,
-      });
+      // Append to queue.
       yield* Effect.promise(() => this._queue.append(messages));
       return messages;
-    }).pipe(Effect.withSpan('Conversation.run'));
+    }).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

@@ -8,3 +8,8 @@ import { BaseError } from '@dxos/errors';
  * Generic error for AI agent execution.
  */
 export class AiAssistantError extends BaseError.extend('AI_ASSISTANT_ERROR') {}
+
+/**
+ * Parsed error from the anthropic API.
+ */
+export class AnthropicError extends BaseError.extend('ANTHROPIC_ERROR') {}

package/src/extraction/extraction-llm-function/extraction-llm-function.test.ts

@@ -11,7 +11,8 @@ import { createTestData } from '@dxos/schema/testing';
 import { range } from '@dxos/util';
 
 import { processTranscriptMessage } from '../extraction';
-import { extractionAnthropicFn } from './extraction-llm-function';
+
+import { extractionAnthropicFunction } from './extraction-llm-function';
 
 // TODO(burdon): Rewrite test.
 describe.skip('LLM EntityExtraction', () => {
@@ -32,7 +33,7 @@ describe.skip('LLM EntityExtraction', () => {
           message,
           objects: [...documents, ...Object.values(contacts)],
         },
-        function: extractionAnthropicFn,
+        function: extractionAnthropicFunction,
         executor,
       });
       log.info('output', enhancedMessage);
@@ -41,8 +42,8 @@ describe.skip('LLM EntityExtraction', () => {
 
   test('computational irreducibility', async () => {
     const { transcriptWoflram, documents, contacts } = createTestData();
-
     log.info('context', { documents, contacts });
+
     const message = transcriptWoflram[0];
     log.info('input', message);
 
@@ -53,9 +54,10 @@ describe.skip('LLM EntityExtraction', () => {
             message,
             objects: [...documents, ...Object.values(contacts)],
           },
-          function: extractionAnthropicFn,
+          function: extractionAnthropicFunction,
           executor,
         });
+
         log.info('output', { message: enhancedMessage.blocks[0], timeElapsed });
       }),
     );
@@ -63,20 +65,19 @@ describe.skip('LLM EntityExtraction', () => {
 
   test('org and document linking', async () => {
     const { transcriptJosiah, documents, contacts, organizations } = createTestData();
-
     log.info('context', { contacts, organizations, documents });
 
     for (const message of transcriptJosiah) {
       log.info('input', message);
-
       const { message: enhancedMessage } = await processTranscriptMessage({
         input: {
           message,
           objects: [...documents, ...Object.values(contacts), ...Object.values(organizations)],
         },
-        function: extractionAnthropicFn,
+        function: extractionAnthropicFunction,
         executor,
       });
+
       log.info('output', enhancedMessage);
     }
   });