@dxos/assistant 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -82,26 +82,26 @@
   "dependencies": {
     "@automerge/automerge": "3.5.0",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/ai": "0.13.0",
-    "@dxos/compute": "0.13.0",
-    "@dxos/compute-runtime": "0.13.0",
-    "@dxos/context": "0.13.0",
-    "@dxos/debug": "0.13.0",
-    "@dxos/echo": "0.13.0",
-    "@dxos/echo-client": "0.13.0",
-    "@dxos/echo-doc": "0.13.0",
-    "@dxos/echo-protocol": "0.13.0",
-    "@dxos/effect": "0.13.0",
-    "@dxos/errors": "0.13.0",
-    "@dxos/invariant": "0.13.0",
-    "@dxos/keys": "0.13.0",
-    "@dxos/log": "0.13.0",
-    "@dxos/mcp-client": "0.13.0",
-    "@dxos/node-std": "0.13.0",
-    "@dxos/protocols": "0.13.0",
-    "@dxos/schema": "0.13.0",
-    "@dxos/types": "0.13.0",
-    "@dxos/util": "0.13.0"
+    "@dxos/ai": "0.14.0",
+    "@dxos/compute": "0.14.0",
+    "@dxos/compute-runtime": "0.14.0",
+    "@dxos/context": "0.14.0",
+    "@dxos/debug": "0.14.0",
+    "@dxos/echo": "0.14.0",
+    "@dxos/echo-client": "0.14.0",
+    "@dxos/echo-doc": "0.14.0",
+    "@dxos/echo-protocol": "0.14.0",
+    "@dxos/effect": "0.14.0",
+    "@dxos/errors": "0.14.0",
+    "@dxos/invariant": "0.14.0",
+    "@dxos/keys": "0.14.0",
+    "@dxos/log": "0.14.0",
+    "@dxos/mcp-client": "0.14.0",
+    "@dxos/node-std": "0.14.0",
+    "@dxos/protocols": "0.14.0",
+    "@dxos/schema": "0.14.0",
+    "@dxos/types": "0.14.0",
+    "@dxos/util": "0.14.0"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "^2.11.0",

package/src/session/AiContext.test.ts

@@ -81,6 +81,60 @@ describe('AiContext.Binder', () => {
       .pipe(Effect.runPromise);
   });
 
+  test('a holding binder writes its bindings only when flushed', async ({ expect }) => {
+    await Effect.gen(function* () {
+      const feed = Feed.make();
+      const runtime = yield* Effect.context<Database.Service>();
+      const a = yield* Database.add(Obj.make(TypeA, {}));
+      const b = yield* Database.add(Obj.make(TypeB, {}));
+
+      const binder = new AiContext.Binder({ feed, runtime, hold: true });
+      yield* Effect.promise(() => binder.open());
+      yield* Effect.promise(() => binder.bind({ objects: [Ref.make(a), Ref.make(b)] }));
+      yield* Effect.promise(() => binder.unbind({ objects: [Ref.make(b)] }));
+      const held = binder.getObjects();
+
+      yield* Database.add(feed);
+      const beforeFlush = yield* Feed.query(feed, Query.type(AiContext.Binding)).run;
+      yield* Effect.promise(() => binder.flush());
+      yield* Effect.promise(() => binder.close());
+
+      const reader = new AiContext.Binder({ feed, runtime });
+      yield* Effect.promise(() => reader.open());
+      const reopened = reader.getObjects();
+      yield* Effect.promise(() => reader.close());
+
+      expect(held.map((obj) => Obj.getURI(obj))).toEqual([Obj.getURI(a)]);
+      expect(beforeFlush).toHaveLength(0);
+      expect(reopened.map((obj) => Obj.getURI(obj))).toEqual([Obj.getURI(a)]);
+    })
+      .pipe(Effect.provide(TestLayer))
+      .pipe(Effect.runPromise);
+  });
+
+  test('a holding binder resolves a registry skill bound by URI', async ({ expect }) => {
+    const registered = Skill.make({ key: 'org.dxos.skill.registered', name: 'Registered' });
+    await Effect.gen(function* () {
+      const runtime = yield* Effect.context<Database.Service>();
+
+      const binder = new AiContext.Binder({ feed: Feed.make(), runtime, hold: true });
+      yield* Effect.promise(() => binder.open());
+      yield* Effect.promise(() =>
+        binder.bind({ skills: [Ref.fromURI(Skill.registryURI('org.dxos.skill.registered'))] }),
+      );
+      const skills = binder.getSkills();
+      yield* Effect.promise(() => binder.close());
+
+      expect(skills.map((skill) => Skill.getKey(skill))).toEqual(['org.dxos.skill.registered']);
+    })
+      .pipe(
+        Effect.provide(
+          TestDatabaseLayer({ types: [Feed.Feed, TypeA, TypeB, Skill.Skill, Text.Text], registry: [registered] }),
+        ),
+      )
+      .pipe(Effect.runPromise);
+  });
+
   // Run between agent turns: a rejected re-read used to fail the whole agent process.
   test('a sync whose query fails keeps the current bindings', async ({ expect }) => {
     await Effect.gen(function* () {

package/src/session/AiContext.ts

@@ -18,7 +18,7 @@ import { Resource } from '@dxos/context';
 import { Database, DXN, Feed, Obj, Query, type QueryResult, Ref, Type } from '@dxos/echo';
 import * as AtomEx from '@dxos/effect/AtomEx';
 import * as RuntimeProvider from '@dxos/effect/RuntimeProvider';
-import { assertArgument } from '@dxos/invariant';
+import { assertArgument, invariant } from '@dxos/invariant';
 import { EID, type URI } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { ComplexSet, isNonNullable } from '@dxos/util';
@@ -81,18 +81,20 @@ export type BinderOptions = {
   runtime: Context.Context<Database.Service>;
   /** @effect/atom-react Registry for reactive state management. */
   registry?: AtomRegistry.AtomRegistry;
+  /** Holds bindings in memory until {@link Binder.flush}, so the feed need not be stored yet (a draft conversation). */
+  hold?: boolean;
 };
 
 /**
  * Manages bindings of skills and objects to a conversation.
  */
-// TODO(burdon): Context should manage ephemeral state of bindings until prompt is issued?
 export class Binder extends Resource {
   private readonly _skills = Atom.make<Skill.Skill[]>([]).pipe(Atom.keepAlive);
   private readonly _objects = Atom.make<Obj.Unknown[]>([]).pipe(Atom.keepAlive);
   private readonly _registry: AtomRegistry.AtomRegistry;
   private readonly _feed: Feed.Feed;
   private readonly _runtime: Context.Context<Database.Service>;
+  private readonly _hold: boolean;
 
   #bindingsQuery: QueryResult.QueryResult<Binding> | undefined;
 
@@ -105,6 +107,11 @@ export class Binder extends Resource {
    */
   #bound = { skills: new Set<URI.URI>(), objects: new Set<URI.URI>() };
 
+  #pending?: Binding[];
+
+  /** Bumped by each held write, so only the latest resolution of the held bindings lands. */
+  #heldGeneration = 0;
+
   constructor(options: BinderOptions) {
     super();
     assertArgument(options.feed, 'options.feed', 'Feed is required');
@@ -112,6 +119,7 @@ export class Binder extends Resource {
     this._feed = options.feed;
     this._runtime = options.runtime;
     this._registry = options.registry ?? AtomEx.makeRegistry();
+    this._hold = options.hold ?? false;
   }
 
   /**
@@ -157,6 +165,36 @@ export class Binder extends Resource {
   }
 
   protected override async _open(): Promise<void> {
+    if (this._hold) {
+      this.#pending = [];
+      return;
+    }
+    await this._follow();
+  }
+
+  /**
+   * Writes a holding binder's bindings to its feed, which the caller has stored, as one binding. Later
+   * writes go straight to the feed, which the binder does not follow.
+   */
+  async flush(): Promise<void> {
+    const held = this.#pending;
+    if (!held) {
+      return;
+    }
+    invariant(Obj.getDatabase(this._feed), 'The feed must be stored before its bindings are flushed.');
+    this.#pending = undefined;
+    const { skills, objects } = this._reduce(held);
+    if (skills.size > 0 || objects.size > 0) {
+      await this._append(
+        Obj.make(Binding, {
+          skills: { added: [...skills], removed: [] },
+          objects: { added: [...objects], removed: [] },
+        }),
+      );
+    }
+  }
+
+  private async _follow(): Promise<void> {
     const bindingsQuery = await RuntimeProvider.runPromise(Effect.succeed(this._runtime))(
       Feed.query(this._feed, Query.type(Binding)),
     );
@@ -284,21 +322,18 @@ export class Binder extends Resource {
     this._registry.set(this._objects, nextObjects);
 
     log('bind', { skills: addedSkills.length, objects: addedObjects.length });
-    await RuntimeProvider.runPromise(Effect.succeed(this._runtime))(
-      Feed.append(this._feed, [
-        Obj.make(Binding, {
-          skills: {
-            added: addedSkills,
-            removed: [],
-          },
-          objects: {
-            added: addedObjects,
-            removed: [],
-          },
-        }),
-      ]),
+    await this._write(
+      Obj.make(Binding, {
+        skills: {
+          added: addedSkills,
+          removed: [],
+        },
+        objects: {
+          added: addedObjects,
+          removed: [],
+        },
+      }),
     );
-    countBindingWrite(this._feed);
   }
 
   async unbind({ skills, objects }: BindingProps): Promise<void> {
@@ -310,38 +345,70 @@ export class Binder extends Resource {
     (objects ?? []).forEach((ref) => this.#bound.objects.delete(refKey(ref.uri)));
 
     // Immediately update atom state so removals are reflected before the queue round-trips.
-    const removedSkillDxns = (skills ?? []).map((ref) => ref.uri);
-    const removedObjectDxns = (objects ?? []).map((ref) => ref.uri);
-    if (removedSkillDxns.length > 0) {
+    const removedSkillKeys = new Set((skills ?? []).map((ref) => refKey(ref.uri)));
+    const removedObjectKeys = new Set((objects ?? []).map((ref) => refKey(ref.uri)));
+    if (removedSkillKeys.size > 0) {
       const current = this._registry.get(this._skills);
       this._registry.set(
         this._skills,
-        current.filter((obj) => !removedSkillDxns.some((uri) => Obj.getURI(obj) === uri)),
+        current.filter((obj) => !removedSkillKeys.has(refKey(Obj.getURI(obj)))),
       );
     }
-    if (removedObjectDxns.length > 0) {
+    if (removedObjectKeys.size > 0) {
       const current = this._registry.get(this._objects);
       this._registry.set(
         this._objects,
-        current.filter((obj) => !removedObjectDxns.some((uri) => Obj.getURI(obj) === uri)),
+        current.filter((obj) => !removedObjectKeys.has(refKey(Obj.getURI(obj)))),
       );
     }
 
     log('unbind', { skills: skills?.length, objects: objects?.length });
-    await RuntimeProvider.runPromise(Effect.succeed(this._runtime))(
-      Feed.append(this._feed, [
-        Obj.make(Binding, {
-          skills: {
-            added: [],
-            removed: skills ?? [],
-          },
-          objects: {
-            added: [],
-            removed: objects ?? [],
-          },
-        }),
-      ]),
+    await this._write(
+      Obj.make(Binding, {
+        skills: {
+          added: [],
+          removed: skills ?? [],
+        },
+        objects: {
+          added: [],
+          removed: objects ?? [],
+        },
+      }),
     );
+  }
+
+  private async _write(binding: Binding): Promise<void> {
+    if (this.#pending) {
+      this.#pending.push(binding);
+      await this._resolveHeld(this.#pending);
+      return;
+    }
+    await this._append(binding);
+  }
+
+  /**
+   * Sets the atoms from the held bindings. Their refs have no feed query to hydrate them, so each is
+   * resolved against the database, which also spans the registry.
+   */
+  private async _resolveHeld(held: Binding[]): Promise<void> {
+    const generation = ++this.#heldGeneration;
+    const { db } = Context.get(this._runtime, Database.Service);
+    const { skills, objects } = this._reduce(held);
+    const hydrate = <T extends Obj.Unknown>(refs: Iterable<Ref.Ref<T>>): Ref.Ref<T>[] =>
+      [...refs].map((ref) => (ref.isAvailable ? ref : db.makeRef<T>(ref.uri)));
+    const [resolvedSkills, resolvedObjects] = await Promise.all([
+      this._resolve(hydrate(skills), this._registry.get(this._skills)),
+      this._resolve(hydrate(objects), this._registry.get(this._objects)),
+    ]);
+    if (generation !== this.#heldGeneration) {
+      return;
+    }
+    this._registry.set(this._skills, resolvedSkills);
+    this._registry.set(this._objects, resolvedObjects);
+  }
+
+  private async _append(binding: Binding): Promise<void> {
+    await RuntimeProvider.runPromise(Effect.succeed(this._runtime))(Feed.append(this._feed, [binding]));
     countBindingWrite(this._feed);
   }
 

package/src/session/SkillHooks.ts

@@ -26,6 +26,7 @@ export type HookPhase = 'begin-request' | 'end-request';
 export type HookInvoker<R> = (
   operation: Operation.Definition.Any,
   input: Record<string, unknown>,
+  hook: Skill.Hook,
 ) => Effect.Effect<void, never, R>;
 
 /**
@@ -61,7 +62,7 @@ export const runHooks = <R>({
           const operation = Operation.deserialize(record);
           // Hooks carry no event payload (the spec is a bare tag), so the input template is passed
           // through verbatim — the hook's operation reads any conversation state it needs itself.
-          yield* invoke(operation, { ...hook.input });
+          yield* invoke(operation, { ...hook.input }, hook);
         }).pipe(
           Effect.catchCause((cause) =>
             // Meta key rather than `Skill.getKey`: a space-authored skill has none, and an error

package/src/types/Agent.ts

@@ -7,6 +7,7 @@
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
+import type * as AgentService from '@dxos/compute/AgentService';
 import * as Instructions from '@dxos/compute/Instructions';
 import * as Skill from '@dxos/compute/Skill';
 import { Annotation, Database, DXN, type Error as EchoError, Feed, Filter, Obj, Ref, Type } from '@dxos/echo';
@@ -127,6 +128,20 @@ export const loadForChat = (chat: Chat.Chat): Effect.Effect<Agent | undefined> =
     return parent && Obj.instanceOf(Agent, parent) ? parent : undefined;
   });
 
+/**
+ * Where a chat's turns run: as its `remote` flag says, else on EDGE for an agent's chat, since its chats share
+ * the agent's one brain, which only EDGE holds. An explicit `remote: false` keeps an agent's chats local, for
+ * a runtime with no EDGE to reach (a story or test), where every chat shares the client's brain instead.
+ */
+export const chatLocation = (chat: Chat.Chat): AgentService.AgentLocation =>
+  (chat.remote ?? isAgentChat(chat)) ? 'edge' : 'local';
+
+/** Whether the chat runs as an agent (the agent parents it); synchronous, like {@link loadForChat}. */
+export const isAgentChat = (chat: Chat.Chat): boolean => {
+  const parent = Obj.getParent(chat);
+  return parent !== undefined && Obj.instanceOf(Agent, parent);
+};
+
 export type MakeProps = Omit<Obj.MakeProps<typeof Agent>, 'instructions'> & {
   instructions: string;
   skills?: Ref.Ref<Skill.Skill>[];