@dxos/assistant-toolkit 0.8.4-main.e8ec1fe → 0.8.4-main.fcfe5033a5

package/src/blueprints/database/functions/definitions.ts

@@ -0,0 +1,318 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Database, Obj, Ref, Relation, Tag } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+export const Query = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.query',
+    name: 'Query',
+    description: trim`
+      Query for objects in ECHO.
+      Use this tool when searching for information in the space (both automerge and queues).
+      Currently, two types of queries are supported:
+        - Full-text search - terms may appear anywhere in the object.
+        - Type-based search - objects of a specific type.
+      You can use them together, for example, to search for objects of a specific type that match a full-text query.
+      Important: Whem querying by typename, make sure to list the schema first, to get the exact typename.
+
+      Omit both typename and text to search for all objects.
+
+      <output_format>
+        You can choose to either return the full object data, or just the DXN, type and label.
+        When expecting a lot of results, run with includeContent=false to not pollute the context, and then load specific objects using the load tool.
+
+        You can choose to get the content right away, if you don't expect a lot of results.
+        To load content right away, run with includeContent=true.
+        When loading content, set an appropriate limit on the number of results to avoid overwhelming the context.
+      </output_format>
+
+      <example description="All tasks related to Cyberdyne and Bob">
+        {
+          "typename": "org.dxos.type.task",
+          "text": "cyberdyne bob",
+        }
+      </example>
+
+      <example description="Financial report Q1 2026">
+        {
+          "typename": "org.dxos.type.document",
+          "text": "financial report Q1 2026",
+          "includeContent": true
+          "limit": 3
+        }
+      </example>
+
+      <example description="Emails from specific mailboxes">
+        {
+          "in": [{"/" : "dxn:echo:@:YYYYYY"}, {"/" : "dxn:echo:@:XXXXXXX"}],
+          "typename": "org.dxos.type.email",
+          "includeContent": true,
+          "limit": 20
+        }
+      </example>
+    `,
+  },
+  input: Schema.Struct({
+    in: Schema.optional(
+      Schema.Array(Ref.Ref(Obj.Unknown)).annotations({
+        description:
+          'Scope the query to children of specific objects (transitively). ' +
+          'Use this to query items within containers such as feeds or folders. ' +
+          'For example, to find emails use `in: [mailbox1.feed, mailbox2.feed]`.',
+      }),
+    ),
+    typename: Schema.optional(
+      Schema.String.annotations({
+        description: 'The typename of the objects to list.',
+        example: 'org.dxos.type.task',
+      }),
+    ),
+    text: Schema.optional(
+      Schema.String.annotations({
+        description: 'Full text search query.',
+        example: 'email cyberdyne bob',
+      }),
+    ),
+    includeContent: Schema.optional(
+      Schema.Boolean.annotations({
+        description: 'Include the full object data in the response.',
+        default: false,
+      }),
+    ),
+    limit: Schema.optional(
+      Schema.Number.annotations({
+        description: 'The maximum number of results to return.',
+        default: 10,
+      }),
+    ),
+    includeQueues: Schema.optional(
+      Schema.Boolean.annotations({
+        description: 'Search in queues as well as spaces. Only use this if searching for emails.',
+        default: false,
+      }),
+    ),
+  }),
+  output: Schema.Array(Schema.Unknown),
+  services: [Database.Service],
+});
+
+export const Load = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.load',
+    name: 'Load object',
+    description: trim`
+      Loads the object or relation content.
+      Can load multiple objects at at time.
+      Use the to read the data when you have a DXN.
+      Call this tool with an array of one or more DXNs or object IDs.
+      When use see a reference ({ '/': 'dxn:...' }), you can call this function to load the object.
+      Note that returned data is only a snapshot in time, and might have changed since the object was last loaded.
+    `,
+  },
+  input: Schema.Struct({
+    refs: Schema.Array(Ref.Ref(Obj.Unknown)),
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});
+
+export const ObjectCreate = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.object-create',
+    name: 'Create object',
+    description: trim`
+      Creates a new object and adds it to the current space.
+      Get the schema from the schema-list tool and ensure that the data matches the corresponding schema.
+      References are provided in the following format: { "/": "dxn:..." }.
+      Reference examples: { "/": "dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "dxn:queue:data:01KG7R1ZXWFMWQ4DA1Q6TN1DG4:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
+    `,
+  },
+  input: Schema.Struct({
+    typename: Schema.String,
+    data: Schema.Any,
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});
+
+export const ObjectUpdate = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.object-update',
+    name: 'Update object',
+    description: trim`
+      Updates the object properties.
+      References are provided in the following format: { "/": "dxn:..." }.
+      Reference examples: { "/": "dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "dxn:queue:data:01KG7R1ZXWFMWQ4DA1Q6TN1DG4:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
+    `,
+  },
+  input: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown),
+    properties: Schema.Record({ key: Schema.String, value: Schema.Any }),
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});
+
+export const ObjectDelete = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.object-delete',
+    name: 'Delete object',
+    description: trim`
+      Deletes the object.
+    `,
+  },
+  input: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});
+
+export const SchemaAdd = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.schema-add',
+    name: 'Add schema',
+    description: trim`
+      Adds a schema to the space.
+      The name will be used when displayed to the user.
+    `,
+  },
+  input: Schema.Struct({
+    name: Schema.String,
+    typename: Schema.String.annotations({
+      description: 'The typename of the schema in the format of "com.example.type.type".',
+    }),
+    jsonSchema: Schema.Any,
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});
+
+export const SchemaList = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.schema-list',
+    name: 'List schemas',
+    description: trim`
+      Lists schemas definitions.
+    `,
+  },
+  input: Schema.Struct({
+    limit: Schema.optional(Schema.Number),
+  }),
+  output: Schema.Array(Schema.Unknown),
+  services: [Database.Service],
+});
+
+export const ContextAdd = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.context-add',
+    name: 'Add to context',
+    description: trim`
+      Adds the object to the chat context.
+      Use this it for objects that are useful long-term for the conversation.
+    `,
+  },
+  input: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown).annotations({
+      description: 'Object to add to the chat context.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [AiContextService],
+});
+
+export const ContextRemove = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.context-remove',
+    name: 'Remove from context',
+    description: trim`
+      Removes the object from the chat context.
+      Use this it for objects that are no longer useful for the conversation.
+    `,
+  },
+  input: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown).annotations({
+      description: 'Object to remove from the chat context.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [AiContextService],
+});
+
+export const RelationCreate = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.relation-create',
+    name: 'Create relation',
+    description: trim`
+      Creates a new relation and adds it to the current space.
+      Get the schema from the schema-list tool and ensure that the data matches the corresponding schema.
+    `,
+  },
+  input: Schema.Struct({
+    typename: Schema.String,
+    source: Ref.Ref(Obj.Unknown),
+    target: Ref.Ref(Obj.Unknown),
+    properties: Schema.Any.annotations({
+      description: 'The data to be stored in the relation.',
+    }),
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});
+
+export const RelationDelete = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.relation-delete',
+    name: 'Delete relation',
+    description: trim`
+      Deletes the relation.
+    `,
+  },
+  input: Schema.Struct({
+    rel: Ref.Ref(Relation.Unknown),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});
+
+export const TagAdd = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.tag-add',
+    name: 'Add tag',
+    description: trim`
+      Adds a tag to an object.
+      Tags are objects of type ${Tag.Tag.typename}.
+      You must search database for available tags, or create a new one.
+    `,
+  },
+  input: Schema.Struct({
+    tag: Ref.Ref(Obj.Unknown),
+    obj: Ref.Ref(Obj.Unknown),
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});
+
+export const TagRemove = Operation.make({
+  meta: {
+    key: 'org.dxos.function.database.tag-remove',
+    name: 'Remove tag',
+    description: trim`
+      Removes a tag from an object.
+      Tags are objects of type ${Tag.Tag.typename}.
+    `,
+  },
+  input: Schema.Struct({
+    tag: Ref.Ref(Obj.Unknown),
+    obj: Ref.Ref(Obj.Unknown),
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});

package/src/blueprints/database/functions/index.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const DatabaseHandlers = OperationHandlerSet.lazy(
+  () => import('./context-add'),
+  () => import('./context-remove'),
+  () => import('./load'),
+  () => import('./object-create'),
+  () => import('./object-delete'),
+  () => import('./object-update'),
+  () => import('./query'),
+  () => import('./relation-create'),
+  () => import('./relation-delete'),
+  () => import('./schema-add'),
+  () => import('./schema-list'),
+  () => import('./tag-add'),
+  () => import('./tag-remove'),
+);

package/src/blueprints/database/functions/load.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Array from 'effect/Array';
+import * as Effect from 'effect/Effect';
+
+import { Database, Entity } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { Load } from './definitions';
+
+export default Load.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ refs }) {
+      return yield* Effect.forEach(refs, Database.load).pipe(Effect.map(Array.map(Entity.toJSON)));
+    }),
+  ),
+);

package/src/blueprints/database/functions/object-create.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Entity, Obj, Type } from '@dxos/echo';
+import { EncodedReference } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { deepMapValues } from '@dxos/util';
+
+import { ObjectCreate } from './definitions';
+
+export default ObjectCreate.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ typename, data }) {
+      const { db } = yield* Database.Service;
+      const schema = yield* Effect.promise(() =>
+        db.schemaRegistry.query({ typename, location: ['database', 'runtime'] }).first(),
+      );
+      invariant(Type.isObjectSchema(schema), 'Schema is not an object schema');
+
+      const object = db.add(
+        Obj.make(
+          schema,
+          deepMapValues(data, (value, recurse) => {
+            if (EncodedReference.isEncodedReference(value)) {
+              return db.makeRef(EncodedReference.toDXN(value));
+            }
+            return recurse(value);
+          }),
+        ),
+      );
+      return Entity.toJSON(object);
+    }),
+  ),
+);

package/src/blueprints/database/functions/object-delete.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { ObjectDelete } from './definitions';
+
+export default ObjectDelete.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ obj }) {
+      const { db } = yield* Database.Service;
+      const object = yield* Database.load(obj);
+      db.remove(object);
+    }),
+  ),
+);

package/src/blueprints/database/functions/object-update.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Entity } from '@dxos/echo';
+import { EncodedReference } from '@dxos/echo-protocol';
+import { Operation } from '@dxos/operation';
+
+import { ObjectUpdate } from './definitions';
+
+export default ObjectUpdate.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ obj, properties }) {
+      const { db } = yield* Database.Service;
+      const object = yield* Database.load(obj);
+      Entity.change(object as Entity.Any, (obj) => {
+        for (const [key, value] of Object.entries(properties)) {
+          if (EncodedReference.isEncodedReference(value)) {
+            obj[key] = db.makeRef(EncodedReference.toDXN(value));
+          } else {
+            obj[key] = value;
+          }
+        }
+      });
+      return Entity.toJSON(object);
+    }),
+  ),
+);

package/src/blueprints/database/functions/query.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Entity, Filter, Obj, Query as EchoQuery } from '@dxos/echo';
+import { Database } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { Query } from './definitions';
+
+// TODO(burdon): Move to toolkit (i.e., tool not function).
+export default Query.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ in: parents, typename, text, includeContent = false, limit = 10, includeQueues = false }) {
+      const { db } = yield* Database.Service;
+      let query: EchoQuery.Any;
+      if (text) {
+        query = EchoQuery.all(
+          ...text.split(' ').map((term) => EchoQuery.select(Filter.text(term, { type: 'full-text' }))),
+        );
+        if (typename !== undefined) {
+          const schema = yield* Database.runSchemaQuery({ typename, location: ['database', 'runtime'] });
+          if (schema.length === 0) {
+            return yield* Effect.fail(new Error(`Schema ${typename} not found`));
+          }
+          query = query.select(Filter.type(schema[0]));
+        }
+      } else if (typename) {
+        const schema = yield* Database.runSchemaQuery({ typename, location: ['database', 'runtime'] });
+        if (schema.length === 0) {
+          return yield* Effect.fail(new Error(`Schema ${typename} not found`));
+        }
+        query = EchoQuery.select(Filter.type(schema[0]));
+      } else {
+        query = EchoQuery.select(Filter.everything());
+      }
+
+      if (parents && parents.length > 0) {
+        query = query.select(Filter.childOf(parents));
+      }
+
+      query = query.limit(limit);
+      if (includeQueues) {
+        // Must scope to the current space: `from({ allQueuesFromSpaces: true })` alone has no spaceIds, so the SQL
+        // index returns nothing (see ObjectMetaIndex.buildSourceCondition / early returns when spaceIds are empty).
+        query = query.from(db, { includeFeeds: true });
+      }
+
+      yield* Database.flush();
+      const results = yield* Database.runQuery(query);
+      if (includeContent) {
+        return results.map((obj) => Entity.toJSON(obj));
+      } else {
+        return results.map((obj) => ({
+          dxn: Obj.getDXN(obj).toString(),
+          typename: Obj.getTypename(obj),
+          label: Obj.getLabel(obj),
+        }));
+      }
+    }),
+  ),
+);

package/src/blueprints/database/functions/relation-create.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Entity, Relation, Type } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+
+import { RelationCreate } from './definitions';
+
+export default RelationCreate.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ typename, source, target, properties }) {
+      const { db } = yield* Database.Service;
+      const schema = yield* Effect.promise(() =>
+        db.schemaRegistry.query({ typename, location: ['database', 'runtime'] }).first(),
+      );
+      invariant(Type.isRelationSchema(schema), 'Schema is not a relation schema');
+
+      const sourceObj = yield* Database.load(source);
+      const targetObj = yield* Database.load(target);
+      const relation = db.add(
+        Relation.make(schema, {
+          [Relation.Source]: sourceObj,
+          [Relation.Target]: targetObj,
+          ...properties,
+        }),
+      );
+      return Entity.toJSON(relation);
+    }),
+  ),
+);

package/src/blueprints/database/functions/relation-delete.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { RelationDelete } from './definitions';
+
+export default RelationDelete.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ rel }) {
+      const { db } = yield* Database.Service;
+      const relation = yield* Database.load(rel);
+      // TODO(dmaretskyi): Echo types broken.
+      db.remove(relation as any);
+    }),
+  ),
+);

package/src/blueprints/database/functions/schema-add.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { SchemaAdd } from './definitions';
+
+export default SchemaAdd.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ name, typename, jsonSchema }) {
+      const { db } = yield* Database.Service;
+      yield* Effect.promise(() =>
+        db.schemaRegistry.register([
+          {
+            typename,
+            version: '0.1.0',
+            jsonSchema,
+            name,
+          },
+        ]),
+      );
+    }),
+  ),
+);

package/src/blueprints/database/functions/schema-list.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Prompt, Blueprint } from '@dxos/blueprints';
+import { Database, Feed, JsonSchema, Type, View } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { SchemaList } from './definitions';
+
+// TODO(dmaretskyi): This is a balance between not filling the agent's context with too many types and not excluding important types.
+const EXCLUDED_TYPES = [Type.PersistentType, View.View, Prompt.Prompt, Blueprint.Blueprint, Feed.Feed];
+const excludedTypenames = EXCLUDED_TYPES.map((type) => Type.getTypename(type));
+
+export default SchemaList.pipe(
+  Operation.withHandler(
+    Effect.fn(function* () {
+      const { db } = yield* Database.Service;
+      const schema = yield* Effect.promise(() => db.schemaRegistry.query({ location: ['database', 'runtime'] }).run());
+      return schema
+        .filter((schema) => !excludedTypenames.includes(Type.getTypename(schema)))
+        .map((schema) => {
+          const meta = Type.getMeta(schema);
+          return {
+            typename: Type.getTypename(schema),
+            jsonSchema: JsonSchema.toJsonSchema(schema),
+            kind: meta?.sourceSchema ? 'relation' : 'record',
+          };
+        });
+    }),
+  ),
+);

package/src/blueprints/database/functions/tag-add.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Entity, Obj } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { TagAdd } from './definitions';
+
+export default TagAdd.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ tag, obj }) {
+      const object = yield* Database.load(obj);
+      const tagObj = yield* Database.load(tag);
+      Entity.change(object, (object) => Entity.addTag(object, Obj.getDXN(tagObj).toString()));
+      return Entity.toJSON(object);
+    }),
+  ),
+);

package/src/blueprints/database/functions/tag-remove.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Entity, Obj } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { TagRemove } from './definitions';
+
+export default TagRemove.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ tag, obj }) {
+      const object = yield* Database.load(obj);
+      const tagObj = yield* Database.load(tag);
+      Entity.change(object, (object) => Entity.removeTag(object, Obj.getDXN(tagObj).toString()));
+      return Entity.toJSON(object);
+    }),
+  ),
+);