@dxos/assistant 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-main.72ec0f3",
+  "version": "0.8.4-main.74a063c4e0",
   "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,41 +45,43 @@
     "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.72ec0f3",
-    "@dxos/async": "0.8.4-main.72ec0f3",
-    "@dxos/blueprints": "0.8.4-main.72ec0f3",
-    "@dxos/debug": "0.8.4-main.72ec0f3",
-    "@dxos/echo-db": "0.8.4-main.72ec0f3",
-    "@dxos/echo": "0.8.4-main.72ec0f3",
-    "@dxos/context": "0.8.4-main.72ec0f3",
-    "@dxos/echo-protocol": "0.8.4-main.72ec0f3",
-    "@dxos/effect": "0.8.4-main.72ec0f3",
-    "@dxos/errors": "0.8.4-main.72ec0f3",
-    "@dxos/functions-runtime": "0.8.4-main.72ec0f3",
-    "@dxos/keys": "0.8.4-main.72ec0f3",
-    "@dxos/graph": "0.8.4-main.72ec0f3",
-    "@dxos/live-object": "0.8.4-main.72ec0f3",
-    "@dxos/log": "0.8.4-main.72ec0f3",
-    "@dxos/node-std": "0.8.4-main.72ec0f3",
-    "@dxos/functions": "0.8.4-main.72ec0f3",
-    "@dxos/schema": "0.8.4-main.72ec0f3",
-    "@dxos/invariant": "0.8.4-main.72ec0f3",
-    "@dxos/types": "0.8.4-main.72ec0f3",
-    "@dxos/util": "0.8.4-main.72ec0f3"
+    "@dxos/ai": "0.8.4-main.74a063c4e0",
+    "@dxos/async": "0.8.4-main.74a063c4e0",
+    "@dxos/blueprints": "0.8.4-main.74a063c4e0",
+    "@dxos/echo": "0.8.4-main.74a063c4e0",
+    "@dxos/echo-db": "0.8.4-main.74a063c4e0",
+    "@dxos/debug": "0.8.4-main.74a063c4e0",
+    "@dxos/echo-protocol": "0.8.4-main.74a063c4e0",
+    "@dxos/effect": "0.8.4-main.74a063c4e0",
+    "@dxos/functions": "0.8.4-main.74a063c4e0",
+    "@dxos/functions-runtime": "0.8.4-main.74a063c4e0",
+    "@dxos/errors": "0.8.4-main.74a063c4e0",
+    "@dxos/context": "0.8.4-main.74a063c4e0",
+    "@dxos/keys": "0.8.4-main.74a063c4e0",
+    "@dxos/invariant": "0.8.4-main.74a063c4e0",
+    "@dxos/log": "0.8.4-main.74a063c4e0",
+    "@dxos/mcp-client": "0.8.4-main.74a063c4e0",
+    "@dxos/operation": "0.8.4-main.74a063c4e0",
+    "@dxos/types": "0.8.4-main.74a063c4e0",
+    "@dxos/schema": "0.8.4-main.74a063c4e0",
+    "@dxos/util": "0.8.4-main.74a063c4e0",
+    "@dxos/node-std": "0.8.4-main.74a063c4e0",
+    "@dxos/graph": "0.8.4-main.74a063c4e0"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "effect": "3.18.3"
+    "effect": "3.20.0"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/conversation/context.test.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Runtime from 'effect/Runtime';
+import * as Schema from 'effect/Schema';
+import { describe, it } from 'vitest';
+
+import { Feed, Obj, Ref, Type } from '@dxos/echo';
+
+import { AiContextBinder } from './context';
+
+const createMockFeedRuntime = (): Runtime.Runtime<Feed.FeedService> => {
+  const mockFeedService: Context.Tag.Service<Feed.FeedService> = {
+    append: async () => {},
+    remove: async () => {},
+    query: () =>
+      ({
+        subscribe: () => () => {},
+        results: [],
+        run: async () => [],
+      }) as any,
+  };
+  const layer = Layer.succeed(Feed.FeedService, mockFeedService);
+  return Effect.runSync(Effect.runtime<Feed.FeedService>().pipe(Effect.provide(layer)));
+};
+
+describe('AiContextBinder', () => {
+  it('should handle bind with Ref', async () => {
+    const feed = Feed.make();
+    const runtime = createMockFeedRuntime();
+    const binder = new AiContextBinder({ feed, runtime });
+
+    const TestSchema = Schema.Struct({}).pipe(
+      Type.object({
+        typename: 'org.dxos.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 Runtime from 'effect/Runtime';
 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 { type Queue } from '@dxos/echo-db';
-import { invariant } from '@dxos/invariant';
-import { ComplexSet } from '@dxos/util';
+import { DXN, Feed, Obj, type QueryResult, Query, Ref, Type } from '@dxos/echo';
+import { assertArgument } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { ComplexSet, isNonNullable } from '@dxos/util';
 
 /**
  * Thread message that binds or unbinds contextual objects to a conversation.
@@ -21,18 +23,17 @@ import { ComplexSet } from '@dxos/util';
 // 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)),
+    added: Schema.Array(Ref.Ref(Blueprint.Blueprint)),
+    removed: Schema.Array(Ref.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(Ref.Ref(Obj.Unknown)),
+    removed: Schema.Array(Ref.Ref(Obj.Unknown)),
   }),
 }).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/ContextBinding',
+  Type.object({
+    typename: 'org.dxos.type.contextBinding',
     version: '0.1.0',
   }),
 );
@@ -41,141 +42,342 @@ 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 = {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Feed.FeedService>;
+  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 {
+  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 _feed: Feed.Feed;
+  private readonly _runtime: Runtime.Runtime<Feed.FeedService>;
+  #bindingsQuery: QueryResult.QueryResult<ContextBinding> | undefined;
+
+  constructor(options: AiContextBinderOptions) {
+    super();
+    assertArgument(options.feed, 'options.feed', 'Feed is required');
+    assertArgument(options.runtime, 'options.runtime', 'Feed runtime is required');
+    this._feed = options.feed;
+    this._runtime = options.runtime;
+    this._registry = options.registry ?? Registry.make();
+  }
+
   /**
-   * Reactive query of all bindings.
+   * Returns the blueprints atom for subscription.
    */
-  // TODO(burdon): Cache value?
-  private _bindings?: ReadonlySignal<Bindings>;
-  private _blueprints?: ReadonlySignal<Ref.Ref<Blueprint.Blueprint>[]>;
-  private _objects?: ReadonlySignal<Ref.Ref<Type.Expando>[]>;
+  get blueprints(): Atom.Atom<Blueprint.Blueprint[]> {
+    return this._blueprints;
+  }
 
-  constructor(private readonly _queue: Queue) {
-    super();
+  /**
+   * Returns the objects atom for subscription.
+   */
+  get objects(): Atom.Atom<Obj.Unknown[]> {
+    return this._objects;
   }
 
-  get bindings() {
-    invariant(this._bindings, 'AiContextBinder not open');
-    return this._bindings;
+  /**
+   * Gets the current blueprints value.
+   */
+  getBlueprints(): Blueprint.Blueprint[] {
+    return this._registry.get(this._blueprints);
   }
 
-  get blueprints() {
-    invariant(this._blueprints, 'AiContextBinder not open');
-    return this._blueprints;
+  /**
+   * Gets the current objects value.
+   */
+  getObjects(): Obj.Unknown[] {
+    return this._registry.get(this._objects);
   }
 
-  get objects() {
-    invariant(this._objects, 'AiContextBinder not open');
-    return this._objects;
+  /**
+   * Subscribe to changes in blueprints.
+   */
+  subscribeBlueprints(cb: (blueprints: Blueprint.Blueprint[]) => void): () => void {
+    return this._registry.subscribe(this._blueprints, () => cb(this._registry.get(this._blueprints)));
   }
 
-  // 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]);
+  /**
+   * 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 _close(): Promise<void> {
-    this._bindings = undefined;
-    this._blueprints = undefined;
-    this._objects = undefined;
+  protected override async _open(): Promise<void> {
+    this.#bindingsQuery = await Runtime.runPromise(this._runtime)(Feed.query(this._feed, Query.type(ContextBinding)));
+
+    // Process initial state before returning.
+    const initialResults = await this.#bindingsQuery.run();
+    await this._updateBindings(initialResults);
+
+    // Subscribe to future changes.
+    this._ctx.onDispose(
+      this.#bindingsQuery.subscribe(async () => {
+        await this._updateBindings(this.#bindingsQuery!.results);
+      }),
+    );
   }
 
   /**
-   * Asynchronous query of all bindings.
+   * Re-reads bindings from the feed to pick up changes made by other processes.
    */
-  async query(): Promise<Bindings> {
-    const { objects } = await this._queue.query(Query.select(Filter.everything())).run();
-    return this._reduce(objects);
+  async sync(): Promise<void> {
+    if (this.#bindingsQuery) {
+      const results = await this.#bindingsQuery.run();
+      log('sync', { bindingItems: results.length });
+      await this._updateBindings(results);
+      log('sync complete', {
+        blueprints: this._registry.get(this._blueprints).length,
+        blueprintKeys: this._registry.get(this._blueprints).map((bp) => (bp as any).key),
+      });
+    }
+  }
+
+  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);
+
+    log('_updateBindings', {
+      items: items.length,
+      blueprintRefs: [...bindings.blueprints].map((ref) => ({ dxn: ref.dxn.toString(), available: ref.isAvailable })),
+    });
+
+    // Resolve references (loading them first if needed).
+    const currentBlueprints = this._registry.get(this._blueprints);
+    const currentObjects = this._registry.get(this._objects);
+    const resolvedBlueprints = await this._resolve(bindings.blueprints, currentBlueprints);
+    const resolvedObjects = await this._resolve(bindings.objects, currentObjects);
+
+    log('_updateBindings resolved', {
+      resolvedBlueprints: resolvedBlueprints.length,
+      resolvedBlueprintKeys: resolvedBlueprints.map((bp) => (bp as any).key),
+    });
+
+    // Filter current state to only items still in the reduced binding set,
+    // then merge in newly resolved items. This ensures unbind events are respected.
+    const reducedBlueprintDxns = new ComplexSet<DXN>(
+      DXN.hash,
+      [...bindings.blueprints].map((ref) => ref.dxn),
+    );
+    const reducedObjectDxns = new ComplexSet<DXN>(
+      DXN.hash,
+      [...bindings.objects].map((ref) => ref.dxn),
+    );
+    const filteredBlueprints = currentBlueprints.filter((obj) => reducedBlueprintDxns.has(Obj.getDXN(obj)));
+    const filteredObjects = currentObjects.filter((obj) => reducedObjectDxns.has(Obj.getDXN(obj)));
+    const mergedBlueprints = this._mergeInto(filteredBlueprints, resolvedBlueprints);
+    const mergedObjects = this._mergeInto(filteredObjects, resolvedObjects);
+
+    this._registry.set(this._blueprints, mergedBlueprints);
+    this._registry.set(this._objects, mergedObjects);
+
+    log('updated bindings', {
+      blueprints: mergedBlueprints.length,
+      objects: mergedObjects.length,
+    });
+  }
+
+  protected override async _close(): Promise<void> {
+    // Reset atoms to empty state.
+    this._registry.set(this._blueprints, []);
+    this._registry.set(this._objects, []);
   }
 
-  // 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())) ?? [];
+  async bind({ blueprints, objects }: BindingProps): Promise<void> {
+    const currentBlueprints = this._registry.get(this._blueprints);
+    const currentObjects = this._registry.get(this._objects);
 
-    if (!blueprints.length && !objects.length) {
+    const { added: addedBlueprints, next: nextBlueprints } = this._processBindings(blueprints, currentBlueprints);
+    const { added: addedObjects, next: nextObjects } = this._processBindings(objects, currentObjects);
+    if (!addedBlueprints.length && !addedObjects.length) {
       return;
     }
 
-    await this._queue.append([
-      Obj.make(ContextBinding, {
-        blueprints: {
-          added: blueprints,
-          removed: [],
-        },
-        objects: {
-          added: objects,
-          removed: [],
-        },
-      }),
-    ]);
+    // 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 Runtime.runPromise(this._runtime)(
+      Feed.append(this._feed, [
+        Obj.make(ContextBinding, {
+          blueprints: {
+            added: addedBlueprints,
+            removed: [],
+          },
+          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;
     }
 
-    await this._queue.append([
-      Obj.make(ContextBinding, {
-        blueprints: {
-          added: [],
-          removed: props.blueprints ?? [],
-        },
-        objects: {
-          added: [],
-          removed: props.objects ?? [],
-        },
-      }),
-    ]);
+    // Immediately update atom state so removals are reflected before the queue round-trips.
+    const removedBlueprintDxns = (blueprints ?? []).map((ref) => ref.dxn);
+    const removedObjectDxns = (objects ?? []).map((ref) => ref.dxn);
+    if (removedBlueprintDxns.length > 0) {
+      const current = this._registry.get(this._blueprints);
+      this._registry.set(
+        this._blueprints,
+        current.filter((obj) => !removedBlueprintDxns.some((dxn) => DXN.equalsEchoId(Obj.getDXN(obj), dxn))),
+      );
+    }
+    if (removedObjectDxns.length > 0) {
+      const current = this._registry.get(this._objects);
+      this._registry.set(
+        this._objects,
+        current.filter((obj) => !removedObjectDxns.some((dxn) => DXN.equalsEchoId(Obj.getDXN(obj), dxn))),
+      );
+    }
+
+    log('unbind', { blueprints: blueprints?.length, objects: objects?.length });
+    await Runtime.runPromise(this._runtime)(
+      Feed.append(this._feed, [
+        Obj.make(ContextBinding, {
+          blueprints: {
+            added: [],
+            removed: blueprints ?? [],
+          },
+          objects: {
+            added: [],
+            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;
       }),
     );
   }
+
+  /**
+   * Merge resolved items into the current set, adding only items not already present (by DXN).
+   */
+  private _mergeInto<T extends Obj.Unknown>(current: T[], resolved: T[]): T[] {
+    const seen = new Set(current.map((obj) => Obj.getDXN(obj).toString()));
+    const merged = [...current];
+    for (const obj of resolved) {
+      const dxn = Obj.getDXN(obj).toString();
+      if (!seen.has(dxn)) {
+        seen.add(dxn);
+        merged.push(obj);
+      }
+    }
+    return merged;
+  }
+
+  /**
+   * Resolve references to objects, loading them first if needed and falling back to existing objects.
+   */
+  private async _resolve<T extends Obj.Unknown>(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.tryLoad()));
+
+    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(isNonNullable);
+  }
 }
 
 export class AiContextService extends Context.Tag('@dxos/assistant/AiContextService')<
@@ -183,4 +385,19 @@ 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.AnyEntity>(
+    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));
+    });
+  };
+}