@dxos/assistant 0.8.4-main.ead640a → 0.8.4-main.ef1bc66f44

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-main.ead640a",
+  "version": "0.8.4-main.ef1bc66f44",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "info@dxos.org",
   "sideEffects": true,
@@ -12,14 +16,17 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "default": "./dist/lib/neutral/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"
+      "default": "./dist/lib/neutral/extraction/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
+      "default": "./dist/lib/neutral/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -38,39 +45,41 @@
     "src"
   ],
   "dependencies": {
-    "@automerge/automerge": "3.1.2",
-    "@effect/ai": "0.29.1",
-    "@effect/experimental": "0.56.0",
-    "@effect/platform": "^0.92.1",
-    "@preact/signals-core": "^1.12.1",
+    "@automerge/automerge": "3.2.3",
+    "@effect-atom/atom": "^0.5.1",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/ai": "0.33.2",
+    "@effect/experimental": "0.58.0",
+    "@effect/platform": "0.94.4",
     "@xenova/transformers": "^2.17.2",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/ai": "0.8.4-main.ead640a",
-    "@dxos/async": "0.8.4-main.ead640a",
-    "@dxos/blueprints": "0.8.4-main.ead640a",
-    "@dxos/debug": "0.8.4-main.ead640a",
-    "@dxos/echo": "0.8.4-main.ead640a",
-    "@dxos/echo-db": "0.8.4-main.ead640a",
-    "@dxos/echo-protocol": "0.8.4-main.ead640a",
-    "@dxos/effect": "0.8.4-main.ead640a",
-    "@dxos/errors": "0.8.4-main.ead640a",
-    "@dxos/graph": "0.8.4-main.ead640a",
-    "@dxos/functions": "0.8.4-main.ead640a",
-    "@dxos/invariant": "0.8.4-main.ead640a",
-    "@dxos/keys": "0.8.4-main.ead640a",
-    "@dxos/live-object": "0.8.4-main.ead640a",
-    "@dxos/log": "0.8.4-main.ead640a",
-    "@dxos/node-std": "0.8.4-main.ead640a",
-    "@dxos/context": "0.8.4-main.ead640a",
-    "@dxos/schema": "0.8.4-main.ead640a",
-    "@dxos/util": "0.8.4-main.ead640a"
+    "@dxos/async": "0.8.4-main.ef1bc66f44",
+    "@dxos/blueprints": "0.8.4-main.ef1bc66f44",
+    "@dxos/ai": "0.8.4-main.ef1bc66f44",
+    "@dxos/context": "0.8.4-main.ef1bc66f44",
+    "@dxos/debug": "0.8.4-main.ef1bc66f44",
+    "@dxos/echo": "0.8.4-main.ef1bc66f44",
+    "@dxos/echo-db": "0.8.4-main.ef1bc66f44",
+    "@dxos/echo-protocol": "0.8.4-main.ef1bc66f44",
+    "@dxos/effect": "0.8.4-main.ef1bc66f44",
+    "@dxos/errors": "0.8.4-main.ef1bc66f44",
+    "@dxos/functions-runtime": "0.8.4-main.ef1bc66f44",
+    "@dxos/graph": "0.8.4-main.ef1bc66f44",
+    "@dxos/functions": "0.8.4-main.ef1bc66f44",
+    "@dxos/invariant": "0.8.4-main.ef1bc66f44",
+    "@dxos/keys": "0.8.4-main.ef1bc66f44",
+    "@dxos/log": "0.8.4-main.ef1bc66f44",
+    "@dxos/node-std": "0.8.4-main.ef1bc66f44",
+    "@dxos/schema": "0.8.4-main.ef1bc66f44",
+    "@dxos/types": "0.8.4-main.ef1bc66f44",
+    "@dxos/util": "0.8.4-main.ef1bc66f44"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "effect": "3.18.3"
+    "effect": "3.19.16"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.19.16"
   },
   "publishConfig": {
     "access": "public"

package/src/conversation/context.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, it } from 'vitest';
+
+import { Obj, Ref, Type } from '@dxos/echo';
+import { type Queue } from '@dxos/echo-db';
+
+import { AiContextBinder } from './context';
+
+// TODO(burdon): Create mock queue?
+const createMockQueue = (): Queue =>
+  ({
+    query: () =>
+      ({
+        subscribe: () => ({ unsubscribe: () => {} }),
+        results: [],
+      }) as any,
+    append: async () => {
+      return [] as any;
+    },
+  }) as any;
+
+describe('AiContextBinder', () => {
+  it('should handle bind with Ref', async () => {
+    const queue = createMockQueue();
+    const binder = new AiContextBinder({ queue });
+
+    const TestSchema = Schema.Struct({}).pipe(
+      Type.object({
+        typename: 'dxos.org/type/Example',
+        version: '0.1.0',
+      }),
+    );
+
+    const obj = Obj.make(TestSchema, {});
+    const ref = Ref.make(obj);
+
+    await binder.bind({
+      blueprints: [],
+      objects: [ref],
+    });
+  });
+});

package/src/conversation/context.ts

@@ -2,18 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type ReadonlySignal, computed } from '@preact/signals-core';
-import * as Array from 'effect/Array';
+import { Atom, Registry } from '@effect-atom/atom-react';
+import * as EArray from 'effect/Array';
 import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 import * as Schema from 'effect/Schema';
 
 import { Blueprint } from '@dxos/blueprints';
 import { Resource } from '@dxos/context';
-import { DXN, Filter, Obj, Query, type Ref, type Relation, Type } from '@dxos/echo';
+import { DXN, Obj, Query, type Ref, Type } from '@dxos/echo';
 import { type Queue } from '@dxos/echo-db';
-import { invariant } from '@dxos/invariant';
-import { ComplexSet } from '@dxos/util';
+import { assertArgument } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { ComplexSet, isTruthy } from '@dxos/util';
 
 /**
  * Thread message that binds or unbinds contextual objects to a conversation.
@@ -25,13 +27,12 @@ export const ContextBinding = Schema.Struct({
     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)),
+    added: Schema.Array(Type.Ref(Type.Obj)),
+    removed: Schema.Array(Type.Ref(Type.Obj)),
   }),
 }).pipe(
-  Type.Obj({
+  Type.object({
     typename: 'dxos.org/type/ContextBinding',
     version: '0.1.0',
   }),
@@ -41,141 +42,260 @@ export interface ContextBinding extends Schema.Schema.Type<typeof ContextBinding
 
 export type BindingProps = Partial<{
   blueprints: Ref.Ref<Blueprint.Blueprint>[];
-  objects: Ref.Ref<Type.Expando>[];
+  objects: Ref.Ref<Obj.Unknown>[];
 }>;
 
 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);
+  readonly objects = new ComplexSet<Ref.Ref<Obj.Unknown>>((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()),
+      blueprints: EArray.fromIterable(this.blueprints).map((ref) => ref.dxn.toString()),
+      objects: EArray.fromIterable(this.objects).map((ref) => ref.dxn.toString()),
     };
   }
 }
 
+export type AiContextBinderOptions = {
+  queue: Queue;
+  registry?: Registry.Registry;
+};
+
 /**
  * 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 extends Resource {
-  /**
-   * Reactive query of all bindings.
-   */
-  // TODO(burdon): Cache value?
-  private _bindings?: ReadonlySignal<Bindings>;
-  private _blueprints?: ReadonlySignal<Ref.Ref<Blueprint.Blueprint>[]>;
-  private _objects?: ReadonlySignal<Ref.Ref<Type.Expando>[]>;
+  private readonly _blueprints = Atom.make<Blueprint.Blueprint[]>([]).pipe(Atom.keepAlive);
+  private readonly _objects = Atom.make<Obj.Unknown[]>([]).pipe(Atom.keepAlive);
+  private readonly _registry: Registry.Registry;
+  private readonly _queue: Queue;
 
-  constructor(private readonly _queue: Queue) {
+  constructor(options: AiContextBinderOptions) {
     super();
+    assertArgument(options.queue, 'options.queue', 'Queue is required');
+    this._queue = options.queue;
+    this._registry = options.registry ?? Registry.make();
   }
 
-  get bindings() {
-    invariant(this._bindings, 'AiContextBinder not open');
-    return this._bindings;
-  }
-
-  get blueprints() {
-    invariant(this._blueprints, 'AiContextBinder not open');
+  /**
+   * Returns the blueprints atom for subscription.
+   */
+  get blueprints(): Atom.Atom<Blueprint.Blueprint[]> {
     return this._blueprints;
   }
 
-  get objects() {
-    invariant(this._objects, 'AiContextBinder not open');
+  /**
+   * Returns the objects atom for subscription.
+   */
+  get objects(): Atom.Atom<Obj.Unknown[]> {
     return this._objects;
   }
 
-  // TODO(wittjosiah): Use parent context?
-  protected override async _open(): Promise<void> {
-    const query = this._queue.query(Query.select(Filter.everything()));
-    this._ctx.onDispose(query.subscribe(() => {}));
-    this._bindings = computed(() => this._reduce(query.objects));
-    this._blueprints = computed(() => [...this.bindings.value.blueprints]);
-    this._objects = computed(() => [...this.bindings.value.objects]);
+  /**
+   * Gets the current blueprints value.
+   */
+  getBlueprints(): Blueprint.Blueprint[] {
+    return this._registry.get(this._blueprints);
   }
 
-  protected override async _close(): Promise<void> {
-    this._bindings = undefined;
-    this._blueprints = undefined;
-    this._objects = undefined;
+  /**
+   * Gets the current objects value.
+   */
+  getObjects(): Obj.Unknown[] {
+    return this._registry.get(this._objects);
   }
 
   /**
-   * Asynchronous query of all bindings.
+   * Subscribe to changes in blueprints.
    */
-  async query(): Promise<Bindings> {
-    const { objects } = await this._queue.query(Query.select(Filter.everything())).run();
-    return this._reduce(objects);
+  subscribeBlueprints(cb: (blueprints: Blueprint.Blueprint[]) => void): () => void {
+    return this._registry.subscribe(this._blueprints, () => cb(this._registry.get(this._blueprints)));
   }
 
-  // TODO(burdon): Pass in Blueprint obj (from registry?) and create reference.
-  async bind(props: BindingProps): Promise<void> {
-    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())) ?? [];
+  /**
+   * Subscribe to changes in objects.
+   */
+  subscribeObjects(cb: (objects: Obj.Unknown[]) => void): () => void {
+    return this._registry.subscribe(this._objects, () => cb(this._registry.get(this._objects)));
+  }
+
+  protected override async _open(): Promise<void> {
+    const query = this._queue.query(Query.type(ContextBinding));
+
+    // Process initial state before returning.
+    const initialResults = await query.run();
+    await this._updateBindings(initialResults);
+
+    // Subscribe to future changes.
+    this._ctx.onDispose(
+      query.subscribe(async () => {
+        await this._updateBindings(query.results);
+      }),
+    );
+  }
 
-    if (!blueprints.length && !objects.length) {
+  private async _updateBindings(items: ContextBinding[]): Promise<void> {
+    // Skip update if no items - preserve existing state set by bind().
+    if (items.length === 0) {
       return;
     }
 
+    const bindings = this._reduce(items);
+
+    // Resolve references (loading them first if needed).
+    const currentBlueprints = this._registry.get(this._blueprints);
+    const currentObjects = this._registry.get(this._objects);
+    const newBlueprints = await this._resolve(bindings.blueprints, currentBlueprints);
+    const newObjects = await this._resolve(bindings.objects, currentObjects);
+
+    // Atomic updates - subscribers notified automatically.
+    this._registry.set(this._blueprints, newBlueprints);
+    this._registry.set(this._objects, newObjects);
+
+    log('updated bindings', {
+      blueprints: newBlueprints.length,
+      objects: newObjects.length,
+    });
+  }
+
+  protected override async _close(): Promise<void> {
+    // Reset atoms to empty state.
+    this._registry.set(this._blueprints, []);
+    this._registry.set(this._objects, []);
+  }
+
+  async bind({ blueprints, objects }: BindingProps): Promise<void> {
+    const currentBlueprints = this._registry.get(this._blueprints);
+    const currentObjects = this._registry.get(this._objects);
+
+    const { added: addedBlueprints, next: nextBlueprints } = this._processBindings(blueprints, currentBlueprints);
+    const { added: addedObjects, next: nextObjects } = this._processBindings(objects, currentObjects);
+    if (!addedBlueprints.length && !addedObjects.length) {
+      return;
+    }
+
+    // Atomic updates - subscribers notified automatically.
+    this._registry.set(this._blueprints, nextBlueprints);
+    this._registry.set(this._objects, nextObjects);
+
+    log('bind', { blueprints: addedBlueprints.length, objects: addedObjects.length });
     await this._queue.append([
       Obj.make(ContextBinding, {
         blueprints: {
-          added: blueprints,
+          added: addedBlueprints,
           removed: [],
         },
         objects: {
-          added: objects,
+          added: addedObjects,
           removed: [],
         },
       }),
     ]);
   }
 
-  async unbind(props: BindingProps): Promise<void> {
-    if (!props.blueprints?.length && !props.objects?.length) {
+  async unbind({ blueprints, objects }: BindingProps): Promise<void> {
+    if (!blueprints?.length && !objects?.length) {
       return;
     }
 
+    log('unbind', { blueprints: blueprints?.length, objects: objects?.length });
     await this._queue.append([
       Obj.make(ContextBinding, {
         blueprints: {
           added: [],
-          removed: props.blueprints ?? [],
+          removed: blueprints ?? [],
         },
         objects: {
           added: [],
-          removed: props.objects ?? [],
+          removed: objects ?? [],
         },
       }),
     ]);
   }
 
-  private _reduce(items: (Obj.Any | Relation.Any)[]): Bindings {
+  /**
+   * Process bindings to filter duplicates and determine next state.
+   */
+  private _processBindings<T extends Obj.Unknown>(
+    refs: Ref.Ref<T>[] | undefined,
+    current: T[],
+  ): { added: Ref.Ref<T>[]; next: T[] } {
+    const next = [...current];
+    const added: Ref.Ref<T>[] = [];
+    if (!refs?.length) {
+      return { added, next };
+    }
+
+    const seen = new Set(current.map((obj) => Obj.getDXN(obj).toString()));
+    for (const ref of refs) {
+      const dxn = ref.dxn.toString();
+      if (!seen.has(dxn)) {
+        seen.add(dxn);
+        added.push(ref);
+
+        // Only resolve target if available (has target or resolver).
+        if (ref.isAvailable) {
+          const target = ref.target;
+          if (target) {
+            next.push(target);
+          }
+        }
+      }
+    }
+
+    return { added, next };
+  }
+
+  /**
+   * Reduce results into sets of blueprints and objects.
+   */
+  private _reduce(items: ContextBinding[]): Bindings {
     return Function.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) => {
+      EArray.reduce(new Bindings(), (context, { blueprints, objects }) => {
+        blueprints.added.forEach((ref) => context.blueprints.add(ref));
+        blueprints.removed.forEach((ref) => context.blueprints.delete(ref));
+
+        objects.added.forEach((ref) => context.objects.add(ref));
+        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;
       }),
     );
   }
+
+  /**
+   * Resolve references to objects, loading them first if needed and falling back to existing objects.
+   */
+  private async _resolve<T>(refs: Iterable<Ref.Ref<T>>, current: T[]): Promise<T[]> {
+    const refArray = [...refs];
+
+    // Load all refs that need loading.
+    await Promise.all(refArray.map((ref) => ref.load()));
+
+    return refArray
+      .map((ref) => {
+        let target: T | undefined;
+        // Only resolve target if available (has target or resolver).
+        if (ref.isAvailable) {
+          target = ref.target;
+        }
+
+        // Fallback to existing object.
+        return target ?? current.find((obj) => Obj.getDXN(obj as any).toString() === ref.dxn.toString());
+      })
+      .filter(isTruthy);
+  }
 }
 
 export class AiContextService extends Context.Tag('@dxos/assistant/AiContextService')<
@@ -183,4 +303,28 @@ export class AiContextService extends Context.Tag('@dxos/assistant/AiContextServ
   {
     binder: AiContextBinder;
   }
->() {}
+>() {
+  static bindContext = ({ blueprints, objects }: BindingProps): Effect.Effect<void, never, AiContextService> =>
+    Effect.gen(function* () {
+      const { binder } = yield* AiContextService;
+      yield* Effect.promise(() => binder.bind({ blueprints, objects }));
+    });
+
+  static findObjects = <T extends Type.Entity.Any>(
+    type: T,
+  ): Effect.Effect<Schema.Schema.Type<T>[], never, AiContextService> => {
+    return Effect.gen(function* () {
+      const { binder } = yield* AiContextService;
+      return binder.getObjects().filter(Obj.instanceOf(type));
+    });
+  };
+
+  /**
+   * Glorified type cast until we figure out function service typing.
+   * For context, the AiContextService is provided to functions called from tool calls, but it's not implemented in types yet.
+   * @deprecated
+   */
+  static fixFunctionHandlerType = <A, E, R>(
+    eff: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E, Exclude<R, AiContextService>> => eff as any;
+}

package/src/conversation/conversation.test.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import { afterEach, beforeEach, describe, expect } from 'vitest';
+
+import { Blueprint } from '@dxos/blueprints';
+import { Obj, Ref } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+
+import { ContextBinding } from './context';
+import { AiConversation } from './conversation';
+
+describe('AiConversation', () => {
+  let builder: EchoTestBuilder;
+
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  it.effect('loads blueprints on open', () =>
+    Effect.gen(function* () {
+      const peer = yield* Effect.promise(() => builder.createPeer({ types: [Blueprint.Blueprint, ContextBinding] }));
+      const db = yield* Effect.promise(() => peer.createDatabase());
+      const queues = peer.client.constructQueueFactory(db.spaceId);
+      const queue = queues.create<ContextBinding>();
+
+      // Create blueprint.
+      const blueprint = db.add(
+        Blueprint.make({
+          key: 'example.com/blueprint/Test',
+          name: 'Test Blueprint',
+        }),
+      );
+
+      // Add blueprint to queue via binding.
+      yield* Effect.promise(() =>
+        queue.append([
+          Obj.make(ContextBinding, {
+            blueprints: {
+              added: [Ref.make(blueprint)],
+              removed: [],
+            },
+            objects: {
+              added: [],
+              removed: [],
+            },
+          }),
+        ]),
+      );
+
+      const conversation = new AiConversation({ queue });
+      yield* Effect.promise(() => conversation.open());
+
+      expect(conversation.context.getBlueprints()).toHaveLength(1);
+      expect(conversation.context.getObjects()).toHaveLength(0);
+    }),
+  );
+});