@dxos/assistant 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/package.json

@@ -1,62 +1,93 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-main.f9ba587",
+  "version": "0.8.4-main.fcfe5033a5",
   "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,
   "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"
+      "default": "./dist/lib/neutral/index.mjs"
+    },
+    "./extraction": {
+      "source": "./src/extraction/index.ts",
+      "types": "./dist/types/src/extraction/index.d.ts",
+      "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",
+  "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.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",
-    "chalk": "^4.1.0",
-    "exa-js": "^1.5.12",
-    "@dxos/ai": "0.8.4-main.f9ba587",
-    "@dxos/artifact": "0.8.4-main.f9ba587",
-    "@dxos/async": "0.8.4-main.f9ba587",
-    "@dxos/context": "0.8.4-main.f9ba587",
-    "@dxos/debug": "0.8.4-main.f9ba587",
-    "@dxos/echo-db": "0.8.4-main.f9ba587",
-    "@dxos/echo-protocol": "0.8.4-main.f9ba587",
-    "@dxos/echo-schema": "0.8.4-main.f9ba587",
-    "@dxos/effect": "0.8.4-main.f9ba587",
-    "@dxos/graph": "0.8.4-main.f9ba587",
-    "@dxos/functions": "0.8.4-main.f9ba587",
-    "@dxos/echo": "0.8.4-main.f9ba587",
-    "@dxos/invariant": "0.8.4-main.f9ba587",
-    "@dxos/live-object": "0.8.4-main.f9ba587",
-    "@dxos/keys": "0.8.4-main.f9ba587",
-    "@dxos/log": "0.8.4-main.f9ba587",
-    "@dxos/schema": "0.8.4-main.f9ba587",
-    "@dxos/node-std": "0.8.4-main.f9ba587",
-    "@dxos/util": "0.8.4-main.f9ba587"
+    "lodash.defaultsdeep": "^4.6.1",
+    "@dxos/async": "0.8.4-main.fcfe5033a5",
+    "@dxos/ai": "0.8.4-main.fcfe5033a5",
+    "@dxos/blueprints": "0.8.4-main.fcfe5033a5",
+    "@dxos/debug": "0.8.4-main.fcfe5033a5",
+    "@dxos/echo": "0.8.4-main.fcfe5033a5",
+    "@dxos/echo-db": "0.8.4-main.fcfe5033a5",
+    "@dxos/echo-protocol": "0.8.4-main.fcfe5033a5",
+    "@dxos/effect": "0.8.4-main.fcfe5033a5",
+    "@dxos/errors": "0.8.4-main.fcfe5033a5",
+    "@dxos/functions": "0.8.4-main.fcfe5033a5",
+    "@dxos/functions-runtime": "0.8.4-main.fcfe5033a5",
+    "@dxos/graph": "0.8.4-main.fcfe5033a5",
+    "@dxos/invariant": "0.8.4-main.fcfe5033a5",
+    "@dxos/keys": "0.8.4-main.fcfe5033a5",
+    "@dxos/log": "0.8.4-main.fcfe5033a5",
+    "@dxos/mcp-client": "0.8.4-main.fcfe5033a5",
+    "@dxos/node-std": "0.8.4-main.fcfe5033a5",
+    "@dxos/util": "0.8.4-main.fcfe5033a5",
+    "@dxos/context": "0.8.4-main.fcfe5033a5",
+    "@dxos/schema": "0.8.4-main.fcfe5033a5",
+    "@dxos/operation": "0.8.4-main.fcfe5033a5",
+    "@dxos/types": "0.8.4-main.fcfe5033a5"
   },
   "devDependencies": {
-    "effect": "3.16.13",
-    "inquirer": "^12.0.0"
+    "@types/lodash.defaultsdeep": "^4.6.6",
+    "effect": "3.20.0"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "beast": {},
   "scripts": {
-    "run:chat": "tsx ./bin/chat.ts"
+    "run:chat": "vite-node ./bin/chat.ts"
   }
 }

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

@@ -0,0 +1,403 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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, 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.
+ */
+// TODO(burdon): Move to @dxos/schema ContentBlock?
+export const ContextBinding = Schema.Struct({
+  blueprints: Schema.Struct({
+    added: Schema.Array(Ref.Ref(Blueprint.Blueprint)),
+    removed: Schema.Array(Ref.Ref(Blueprint.Blueprint)),
+  }),
+
+  objects: Schema.Struct({
+    added: Schema.Array(Ref.Ref(Obj.Unknown)),
+    removed: Schema.Array(Ref.Ref(Obj.Unknown)),
+  }),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.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<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<Obj.Unknown>>((ref) => ref.dxn.asEchoDXN()?.echoId);
+
+  toJSON() {
+    return {
+      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();
+  }
+
+  /**
+   * Returns the blueprints atom for subscription.
+   */
+  get blueprints(): Atom.Atom<Blueprint.Blueprint[]> {
+    return this._blueprints;
+  }
+
+  /**
+   * Returns the objects atom for subscription.
+   */
+  get objects(): Atom.Atom<Obj.Unknown[]> {
+    return this._objects;
+  }
+
+  /**
+   * Gets the current blueprints value.
+   */
+  getBlueprints(): Blueprint.Blueprint[] {
+    return this._registry.get(this._blueprints);
+  }
+
+  /**
+   * Gets the current objects value.
+   */
+  getObjects(): Obj.Unknown[] {
+    return this._registry.get(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)));
+  }
+
+  /**
+   * 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> {
+    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);
+      }),
+    );
+  }
+
+  /**
+   * Re-reads bindings from the feed to pick up changes made by other processes.
+   */
+  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, []);
+  }
+
+  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 Runtime.runPromise(this._runtime)(
+      Feed.append(this._feed, [
+        Obj.make(ContextBinding, {
+          blueprints: {
+            added: addedBlueprints,
+            removed: [],
+          },
+          objects: {
+            added: addedObjects,
+            removed: [],
+          },
+        }),
+      ]),
+    );
+  }
+
+  async unbind({ blueprints, objects }: BindingProps): Promise<void> {
+    if (!blueprints?.length && !objects?.length) {
+      return;
+    }
+
+    // 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 ?? [],
+          },
+        }),
+      ]),
+    );
+  }
+
+  /**
+   * 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,
+      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);
+            }
+          }
+        });
+
+        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')<
+  AiContextService,
+  {
+    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));
+    });
+  };
+}

package/src/conversation/index.ts

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

package/src/conversation/session.test.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import { describe, expect } from 'vitest';
+
+import { Blueprint } from '@dxos/blueprints';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { TestDatabaseLayer } from '@dxos/functions-runtime/testing';
+
+import { ContextBinding } from './context';
+import { AiSession } from './session';
+
+describe('AiSession', () => {
+  const TestLayer = TestDatabaseLayer({
+    types: [Blueprint.Blueprint, ContextBinding],
+  });
+
+  it.effect('loads blueprints on open', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+
+      // Create feed.
+      const feed = db.add(Feed.make());
+
+      // Create blueprint.
+      const blueprint = db.add(
+        Blueprint.make({
+          key: 'example.com/blueprint/Test',
+          name: 'Test Blueprint',
+        }),
+      );
+
+      // Add blueprint to feed via binding.
+      yield* Feed.append(feed, [
+        Obj.make(ContextBinding, {
+          blueprints: {
+            added: [Ref.make(blueprint)],
+            removed: [],
+          },
+          objects: {
+            added: [],
+            removed: [],
+          },
+        }),
+      ]);
+
+      const runtime = yield* Effect.runtime<Feed.FeedService>();
+      const session = new AiSession({ feed, runtime });
+      yield* Effect.promise(() => session.open());
+
+      expect(session.context.getBlueprints()).toHaveLength(1);
+      expect(session.context.getObjects()).toHaveLength(0);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+});