@dxos/assistant-toolkit 0.10.0 → 0.11.1

package/src/skills/database/operations/context-add.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AiContext } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Feed, Obj, Query, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EID, EntityId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { ContextAdd } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('ContextAdd', () => {
+  it.effect(
+    'context-add: binds the object to the conversation',
+    Effect.fnUntraced(
+      function* (_) {
+        const feed = yield* Database.add(Feed.make());
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Context Corp' }));
+        yield* Database.flush();
+
+        yield* Operation.invoke(ContextAdd, { obj: Ref.make(organization) }).pipe(
+          Effect.provide(Operation.withInvocationOptions({ conversation: Obj.getURI(feed) })),
+        );
+
+        const bindings = yield* Feed.query(feed, Query.type(AiContext.Binding)).run;
+        const added = bindings.flatMap((binding) => entityIds(binding.objects.added));
+        expect(added).toContain(organization.id);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});
+
+// Compare by entity id: a same-space ref stores a local EID (`echo:/<id>`) while `Obj.getURI`
+// returns the fully-qualified form (`echo://<space>/<id>`).
+const entityIds = (refs: readonly Ref.Ref<Obj.Unknown>[]): (string | undefined)[] =>
+  refs.map((ref) => EID.getEntityId(EID.parse(ref.uri)));

package/src/skills/database/operations/context-remove.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AiContext } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Feed, Obj, Query, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EID, EntityId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { ContextAdd, ContextRemove } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('ContextRemove', () => {
+  it.effect(
+    'context-remove: unbinds the object from the conversation',
+    Effect.fnUntraced(
+      function* (_) {
+        const feed = yield* Database.add(Feed.make());
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Remove Context Corp' }));
+        yield* Database.flush();
+
+        const conversation = Operation.withInvocationOptions({ conversation: Obj.getURI(feed) });
+        yield* Operation.invoke(ContextAdd, { obj: Ref.make(organization) }).pipe(Effect.provide(conversation));
+        yield* Operation.invoke(ContextRemove, { obj: Ref.make(organization) }).pipe(Effect.provide(conversation));
+
+        const bindings = yield* Feed.query(feed, Query.type(AiContext.Binding)).run;
+        const removed = bindings.flatMap((binding) => entityIds(binding.objects.removed));
+        expect(removed).toContain(organization.id);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});
+
+// Compare by entity id: a same-space ref stores a local EID (`echo:/<id>`) while `Obj.getURI`
+// returns the fully-qualified form (`echo://<space>/<id>`).
+const entityIds = (refs: readonly Ref.Ref<Obj.Unknown>[]): (string | undefined)[] =>
+  refs.map((ref) => EID.getEntityId(EID.parse(ref.uri)));

package/src/skills/database/operations/definitions.ts

@@ -53,7 +53,7 @@ export const Query = Operation.make({
 
       <example description="Emails from specific mailboxes">
         {
-          "in": [{"/" : "echo:/YYYYYY"}, {"/" : "echo:/XXXXXXX"}],
+          "in": [{"/" : "echo:///YYYYYY"}, {"/" : "echo:///XXXXXXX"}],
           "typename": "org.dxos.type.email",
           "includeContent": true,
           "limit": 20
@@ -132,15 +132,26 @@ export const ObjectCreate = Operation.make({
     name: 'Create object',
     icon: 'ph--plus--regular',
     description: trim`
-      Creates a new object and adds it to the current space.
+      Creates a new object of any type and adds it to the current space.
+      When a type has its own create tool (e.g. the markdown skill creates documents), prefer that
+      tool — it builds the object's owned parts correctly. Use this one for types that have none.
       Get the schema from the schema-list tool and ensure that the data matches the corresponding schema.
       References are provided in the following format: { "/": "echo:..." }.
-      Reference examples: { "/": "echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "echo://<space id>/01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
+      Reference examples: { "/": "echo:///01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "echo://<space id>/01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
     `,
   },
   input: Schema.Struct({
-    typename: Schema.String,
-    data: Schema.Any,
+    typename: Schema.String.annotations({
+      description: 'The typename of the object to create.',
+      examples: ['dxn:org.dxos.type.person'],
+    }),
+    properties: Schema.Record({ key: Schema.String, value: Schema.Any }),
+    attach: Schema.optional(Schema.Boolean).annotations({
+      description: trim`
+        Attach the object to the space root collection so it appears in the navigation tree.
+        Set for top-level objects; leave unset for subordinate objects referenced by others.
+      `,
+    }),
   }),
   output: Schema.Unknown,
   services: [Database.Service],
@@ -154,7 +165,7 @@ export const ObjectUpdate = Operation.make({
     description: trim`
       Updates the object properties.
       References are provided in the following format: { "/": "echo:..." }.
-      Reference examples: { "/": "echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "echo://<space id>/01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
+      Reference examples: { "/": "echo:///01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "echo://<space id>/01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
     `,
   },
   input: Schema.Struct({
@@ -196,7 +207,12 @@ export const SchemaAdd = Operation.make({
     typename: Schema.String.annotations({
       description: 'The typename of the schema in the format of "com.example.type.type".',
     }),
-    jsonSchema: Schema.Any,
+    // Typed as a record so the tool parameter advertises `type: object` to the LLM, forcing it to
+    // emit the JSON Schema as an object rather than a JSON-encoded string (which an unconstrained
+    // `Schema.Any` parameter would allow, breaking `makeObjectFromJsonSchema`).
+    jsonSchema: Schema.Record({ key: Schema.String, value: Schema.Any }).annotations({
+      description: 'The JSON Schema (draft-07) object describing the fields of the new type.',
+    }),
   }),
   output: Schema.Void,
   services: [Database.Service],

package/src/skills/database/operations/load.test.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Organization, Person } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { Load } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('Load', () => {
+  it.effect(
+    'load: returns one entry per requested ref',
+    Effect.fnUntraced(
+      function* (_) {
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        const person = yield* Database.add(Obj.make(Person.Person, { fullName: 'John Connor' }));
+        yield* Database.flush();
+
+        const loaded = yield* Operation.invoke(Load, { refs: [Ref.make(organization), Ref.make(person)] });
+
+        const rows = yield* Schema.decodeUnknown(Schema.Array(Schema.Struct({ id: Schema.String })))(loaded);
+        expect(rows.map((row) => row.id)).toEqual([organization.id, person.id]);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/skills/database/operations/object-create.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { AppAnnotation } from '@dxos/app-toolkit';
+import { WithProperties } from '@dxos/app-toolkit/testing';
+import { SpaceProperties } from '@dxos/client-protocol';
+import { Operation } from '@dxos/compute';
+import { Annotation, Collection, Database, Obj, Query, Type } from '@dxos/echo';
+import { EncodedReference } from '@dxos/echo-protocol';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Organization, Person } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { ObjectCreate } from './definitions';
+
+const loadRootCollection = Effect.gen(function* () {
+  const [properties] = yield* Database.query(Query.type(SpaceProperties)).run;
+  const collectionRef = Annotation.get(properties, AppAnnotation.RootCollectionAnnotation).pipe(Option.getOrThrow);
+  return yield* Database.load(collectionRef);
+});
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('ObjectCreate', () => {
+  it.effect(
+    'object-create: creates an object with the declared properties',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* Operation.invoke(ObjectCreate, {
+          typename: Type.getTypename(Organization.Organization),
+          properties: { name: 'Cyberdyne Systems' },
+        });
+
+        const organizations = yield* Database.query(Query.type(Organization.Organization)).run;
+        expect(organizations).toHaveLength(1);
+        expect(organizations[0].name).toBe('Cyberdyne Systems');
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'object-create: resolves an encoded reference into a live ref',
+    Effect.fnUntraced(
+      function* (_) {
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        yield* Database.flush();
+
+        yield* Operation.invoke(ObjectCreate, {
+          typename: Type.getTypename(Person.Person),
+          properties: {
+            fullName: 'John Doe',
+            // The model emits references in this wire form; the handler decodes it to a ref.
+            organization: EncodedReference.fromURI(Obj.getURI(organization)),
+          },
+        });
+
+        const people = yield* Database.query(Query.type(Person.Person)).run;
+        expect(people).toHaveLength(1);
+        expect(people[0].organization?.target).toBe(organization);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'object-create: default leaves the root collection untouched',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* Operation.invoke(ObjectCreate, {
+          typename: Type.getTypename(Collection.Collection),
+          properties: { name: 'Unattached', objects: [] },
+        });
+
+        const collection = yield* loadRootCollection;
+        expect(collection.objects).toHaveLength(0);
+      },
+      WithProperties,
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'object-create: attach files the object in the space root collection',
+    Effect.fnUntraced(
+      function* (_) {
+        // A collection is always collection-eligible; non-eligible types (no
+        // `CollectionItemAnnotation`) are filed under navtree type nodes instead and skip the root.
+        yield* Operation.invoke(ObjectCreate, {
+          typename: Type.getTypename(Collection.Collection),
+          properties: { name: 'Projects', objects: [] },
+          attach: true,
+        });
+
+        const collection = yield* loadRootCollection;
+        const created = (yield* Database.query(Query.type(Collection.Collection)).run).find(
+          (candidate) => candidate !== collection && candidate.name === 'Projects',
+        );
+        expect(created).toBeDefined();
+        expect(collection.objects.map((ref) => ref.target)).toContain(created);
+      },
+      WithProperties,
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/skills/database/operations/object-create.ts

@@ -4,6 +4,9 @@
 
 import * as Effect from 'effect/Effect';
 
+// Narrow subpath: the app-toolkit barrel drags `@dxos/client` (→ protobufjs), which the workerd
+// bundle guard (env-tests) forbids for assistant-toolkit.
+import { CollectionModel } from '@dxos/app-toolkit/types';
 import { Operation } from '@dxos/compute';
 import { Database, Entity, Filter, Obj, Query, Scope, Type } from '@dxos/echo';
 import { EncodedReference } from '@dxos/echo-protocol';
@@ -14,7 +17,7 @@ import { ObjectCreate } from './definitions';
 
 export default ObjectCreate.pipe(
   Operation.withHandler(
-    Effect.fn(function* ({ typename, data }) {
+    Effect.fn(function* ({ typename, properties, attach }) {
       const { db } = yield* Database.Service;
       const types = yield* Database.query(Query.select(Filter.type(Type.Type)).from(Scope.space(), Scope.registry()))
         .run;
@@ -26,7 +29,7 @@ export default ObjectCreate.pipe(
       const object = db.add(
         Obj.make(
           schema,
-          deepMapValues(data, (value, recurse) => {
+          deepMapValues(properties, (value, recurse) => {
             if (EncodedReference.isEncodedReference(value)) {
               return db.makeRef(EncodedReference.toURI(value));
             }
@@ -34,6 +37,14 @@ export default ObjectCreate.pipe(
           }),
         ),
       );
+
+      if (attach) {
+        // Same best-effort attach as `markdown.create`: the object is already persisted, so swallow
+        // only the transient race where concurrent agents materialize the root collection.
+        yield* CollectionModel.add({ object }).pipe(Effect.catchTag('EntityNotFoundError', () => Effect.void));
+        yield* Database.flush();
+      }
+
       return Entity.toJSON(object);
     }),
   ),

package/src/skills/database/operations/object-delete.test.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Obj, Query, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { ObjectDelete } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('ObjectDelete', () => {
+  it.effect(
+    'object-delete: removes the object from the database',
+    Effect.fnUntraced(
+      function* (_) {
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Doomed Corp' }));
+        yield* Database.flush();
+
+        yield* Operation.invoke(ObjectDelete, { obj: Ref.make(organization) });
+        yield* Database.flush();
+
+        const organizations = yield* Database.query(Query.type(Organization.Organization)).run;
+        expect(organizations).toHaveLength(0);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/skills/database/operations/object-update.test.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { ObjectUpdate } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('ObjectUpdate', () => {
+  it.effect(
+    'object-update: writes the given properties onto the object',
+    Effect.fnUntraced(
+      function* (_) {
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Before' }));
+        yield* Database.flush();
+
+        yield* Operation.invoke(ObjectUpdate, {
+          obj: Ref.make(organization),
+          properties: { name: 'After', description: 'Now with a description.' },
+        });
+
+        expect(organization.name).toBe('After');
+        expect(organization.description).toBe('Now with a description.');
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/skills/database/operations/query.test.ts

@@ -0,0 +1,128 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+import { Database, Feed, Obj, Ref, Type } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Organization, Person } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { Query as QueryOperation } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('Query', () => {
+  it.effect(
+    'query: finds objects by typename',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* Database.add(Obj.make(Organization.Organization, { name: 'Acme Corp' }));
+        yield* Database.add(Obj.make(Organization.Organization, { name: 'Globex Industries' }));
+        yield* Database.add(Obj.make(Person.Person, { fullName: 'John Connor' }));
+        yield* Database.flush();
+
+        const results = yield* Operation.invoke(QueryOperation, {
+          typename: Type.getTypename(Organization.Organization),
+          limit: 20,
+        });
+
+        expect((yield* rows(results)).map((row) => row.label).sort()).toEqual(['Acme Corp', 'Globex Industries']);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'query: the in param scopes results to the given feed',
+    Effect.fnUntraced(
+      function* (_) {
+        const inbox1 = Feed.make({ name: 'inbox-1' });
+        yield* Database.add(inbox1);
+        yield* Feed.append(inbox1, [Obj.make(Organization.Organization, { name: 'Email Corp Alpha' })]);
+
+        const inbox2 = Feed.make({ name: 'inbox-2' });
+        yield* Database.add(inbox2);
+        yield* Feed.append(inbox2, [Obj.make(Organization.Organization, { name: 'Email Corp Beta' })]);
+        yield* Database.flush();
+
+        const results = yield* Operation.invoke(QueryOperation, {
+          typename: Type.getTypename(Organization.Organization),
+          in: [Ref.make(inbox1)],
+          includeQueues: true,
+          limit: 20,
+        });
+
+        expect((yield* rows(results)).map((row) => row.label)).toEqual(['Email Corp Alpha']);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'query operation: includeQueues via invokeFunction',
+    Effect.fnUntraced(
+      function* (_) {
+        const feed = Feed.make();
+        yield* Database.add(feed);
+        yield* Feed.append(feed, [
+          Obj.make(Organization.Organization, {
+            name: 'Invoke Op Lot Co',
+            description: 'Feed-only mock email op-search-token-7f3a2c91 reservation line.',
+          }),
+        ]);
+        yield* Database.flush();
+
+        const noQueues = yield* Operation.invoke(QueryOperation, {
+          text: 'op-search-token-7f3a2c91',
+          includeQueues: false,
+          limit: 20,
+        });
+        expect(noQueues).toHaveLength(0);
+
+        const withQueues = yield* Operation.invoke(QueryOperation, {
+          text: 'op-search-token-7f3a2c91',
+          includeQueues: true,
+          limit: 20,
+        });
+        expect(withQueues.length).toBeGreaterThanOrEqual(1);
+        expect(
+          (yield* rows(withQueues)).some(
+            (row) =>
+              row.typename === Type.getTypename(Organization.Organization) &&
+              String(row.label ?? '').includes('Invoke Op Lot'),
+          ),
+        ).toBe(true);
+
+        const byTypename = yield* Operation.invoke(QueryOperation, {
+          typename: Type.getTypename(Organization.Organization),
+          includeQueues: true,
+          limit: 20,
+        });
+        expect(byTypename.length).toBeGreaterThanOrEqual(1);
+        expect(
+          (yield* rows(byTypename)).some(
+            (row) =>
+              row.typename === Type.getTypename(Organization.Organization) &&
+              String(row.label ?? '').includes('Invoke Op Lot'),
+          ),
+        ).toBe(true);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});
+
+// The operation's output is `Schema.Unknown`; decode rather than cast.
+const rows = (results: readonly unknown[]) =>
+  Schema.decodeUnknown(
+    Schema.Array(Schema.Struct({ typename: Schema.optional(Schema.String), label: Schema.optional(Schema.String) })),
+  )(results);

package/src/skills/database/operations/relation-create.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Obj, Query, Ref, Relation, Type } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Employer, Organization, Person } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { RelationCreate } from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('RelationCreate', () => {
+  it.effect(
+    'relation-create: links source to target and stores the properties',
+    Effect.fnUntraced(
+      function* (_) {
+        const person = yield* Database.add(Obj.make(Person.Person, { fullName: 'John Connor' }));
+        const organization = yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        yield* Database.flush();
+
+        yield* Operation.invoke(RelationCreate, {
+          typename: Type.getTypename(Employer.Employer),
+          source: Ref.make(person),
+          target: Ref.make(organization),
+          properties: { role: 'Engineer' },
+        });
+
+        const relations = yield* Database.query(Query.type(Employer.Employer)).run;
+        expect(relations).toHaveLength(1);
+        expect(relations[0].role).toBe('Engineer');
+        // Endpoints, not just the properties: a swapped source/target would otherwise pass.
+        expect(Relation.getSource(relations[0]).id).toBe(person.id);
+        expect(Relation.getTarget(relations[0]).id).toBe(organization.id);
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});