@dxos/assistant-toolkit 0.8.4-main.ae835ea → 0.8.4-main.c85a9c8dae

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

@@ -0,0 +1,126 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Entity, Filter, Obj, Query } from '@dxos/echo';
+import { Database } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+// TODO(burdon): Move to toolkit (i.e., tool not function).
+export default defineFunction({
+  key: 'dxos.org/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": "dxos.org/type/Task",
+          "text": "cyberdyne bob",
+        }
+      </example>
+
+      <example description="Financial report Q1 2026">
+        {
+          "typename": "dxos.org/type/Document",
+          "text": "financial report Q1 2026",
+          "includeContent": true
+          "limit": 3
+        }
+      </example>
+    `,
+  inputSchema: Schema.Struct({
+    typename: Schema.optional(
+      Schema.String.annotations({
+        description: 'The typename of the objects to list.',
+        example: 'dxos.org/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,
+      }),
+    ),
+    // TODO(dmaretskyi): There's a problem with querying queues, that the agent keeps finding message from agent threads.
+    //                   Let's think about a better way to do this.
+    //                   And queues don't have predicatble ids, so queue DXNs blow up the conversation cache.
+    includeQueues: Schema.optional(
+      Schema.Boolean.annotations({
+        description: 'Search in queues as well as spaces. Only use this if searching for emails.',
+        default: false,
+      }),
+    ),
+  }),
+  outputSchema: Schema.Array(Schema.Unknown),
+  handler: Effect.fn(function* ({
+    data: { typename, text, includeContent = false, limit = 10, includeQueues = false },
+  }) {
+    let query: Query.Any;
+    if (text) {
+      query = Query.all(...text.split(' ').map((term) => Query.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`));
+        }
+        // NOTE: Query by typename string doesn't work for dynamic schemas.
+        query = query.select(Filter.type(schema[0]));
+      }
+    } else if (typename) {
+      query = Query.select(Filter.type(typename));
+    } else {
+      query = Query.select(Filter.everything());
+    }
+    query = query.limit(limit);
+    if (includeQueues) {
+      query = query.from({ allQueuesFromSpaces: true });
+    }
+
+    // Update indexes before querying to make sure we get the latest results.
+    yield* Database.flush({ indexes: true });
+    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,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Entity, Obj, Ref, Relation, Type } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/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.
+  `,
+  inputSchema: 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.',
+    }),
+  }),
+  outputSchema: Schema.Unknown,
+  handler: Effect.fn(function* ({ data: { 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,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Ref, Relation } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/function/database/relation-delete',
+  name: 'Delete relation',
+  description: trim`
+    Deletes the relation.
+  `,
+  inputSchema: Schema.Struct({
+    rel: Ref.Ref(Relation.Unknown),
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ data: { 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,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/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.
+  `,
+  inputSchema: Schema.Struct({
+    name: Schema.String,
+    typename: Schema.String.annotations({
+      description: 'The typename of the schema in the format of "example.com/type/Type".',
+    }),
+    jsonSchema: Schema.Any,
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ data: { 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 * as Schema from 'effect/Schema';
+
+import { Database, JsonSchema, Type } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/function/database/schema-list',
+  name: 'List schemas',
+  description: trim`
+    Lists schemas definitions.
+  `,
+  inputSchema: Schema.Struct({
+    limit: Schema.optional(Schema.Number),
+  }),
+  outputSchema: Schema.Array(Schema.Unknown),
+  handler: Effect.fn(function* () {
+    const { db } = yield* Database.Service;
+    const schema = yield* Effect.promise(() => db.schemaRegistry.query({ location: ['database', 'runtime'] }).run());
+    return 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,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Entity, Obj, Ref, Tag } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/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.
+  `,
+  inputSchema: Schema.Struct({
+    tag: Ref.Ref(Obj.Unknown),
+    obj: Ref.Ref(Obj.Unknown),
+  }),
+  outputSchema: Schema.Unknown,
+  handler: Effect.fn(function* ({ data: { tag, obj } }) {
+    const object = yield* Database.load(obj);
+    const tagObj = yield* Database.load(tag);
+    Entity.change(object, (obj) => Entity.addTag(obj, Obj.getDXN(tagObj).toString()));
+    return Entity.toJSON(object);
+  }),
+});

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

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Entity, Obj, Ref, Tag } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/function/database/tag-remove',
+  name: 'Remove tag',
+  description: trim`
+    Removes a tag from an object.
+    Tags are objects of type ${Tag.Tag.typename}.
+  `,
+  inputSchema: Schema.Struct({
+    tag: Ref.Ref(Obj.Unknown),
+    obj: Ref.Ref(Obj.Unknown),
+  }),
+  outputSchema: Schema.Unknown,
+  handler: Effect.fn(function* ({ data: { tag, obj } }) {
+    const object = yield* Database.load(obj);
+    const tagObj = yield* Database.load(tag);
+    Entity.change(object, (obj) => Entity.removeTag(obj, Obj.getDXN(tagObj).toString()));
+    return Entity.toJSON(object);
+  }),
+});

package/src/blueprints/database/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as DatabaseBlueprint } from './blueprint';
+export { DatabaseFunctions } from './functions';

package/src/blueprints/design/{design-blueprint.test.ts → blueprint.test.ts}

@@ -7,34 +7,25 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 
 import { AiService, ConsolePrinter } from '@dxos/ai';
+import { GenericToolkit } from '@dxos/ai';
 import { AiServiceTestingPreset } from '@dxos/ai/testing';
-import {
-  AiConversation,
-  type ContextBinding,
-  GenerationObserver,
-  makeToolExecutionServiceFromFunctions,
-  makeToolResolverFromFunctions,
-} from '@dxos/assistant';
+import { AiConversation, type ContextBinding, GenerationObserver, ToolExecutionServices } from '@dxos/assistant';
 import { Blueprint } from '@dxos/blueprints';
 import { Obj, Ref } from '@dxos/echo';
-import { TestHelpers, acquireReleaseResource } from '@dxos/effect';
-import {
-  ComputeEventLogger,
-  DatabaseService,
-  FunctionInvocationService,
-  QueueService,
-  TracingService,
-} from '@dxos/functions';
-import { TestDatabaseLayer } from '@dxos/functions/testing';
+import { Database } from '@dxos/echo';
+import { acquireReleaseResource } from '@dxos/effect';
+import { TestHelpers } from '@dxos/effect/testing';
+import { QueueService, TracingService } from '@dxos/functions';
+import { FunctionInvocationServiceLayerTestMocked, TestDatabaseLayer } from '@dxos/functions-runtime/testing';
 import { log } from '@dxos/log';
 import { Markdown } from '@dxos/plugin-markdown/types';
-import { DataType } from '@dxos/schema';
+import { Text } from '@dxos/schema';
+import { type Message } from '@dxos/types';
 import { trim } from '@dxos/util';
 
-import { Document } from '../../functions';
-import { testToolkit } from '../testing';
+import { MarkdownFunctions } from '../markdown';
 
-import blueprint from './design-blueprint';
+import DesignBlueprint from './blueprint';
 
 describe('Design Blueprint', { timeout: 120_000 }, () => {
   it.scoped(
@@ -42,22 +33,23 @@ describe('Design Blueprint', { timeout: 120_000 }, () => {
     Effect.fn(
       function* ({ expect }) {
         const observer = GenerationObserver.fromPrinter(new ConsolePrinter());
-        const queue = yield* QueueService.createQueue<DataType.Message | ContextBinding>();
-        const conversation = yield* acquireReleaseResource(() => new AiConversation(queue));
+        const queue = yield* QueueService.createQueue<Message.Message | ContextBinding>();
+        const conversation = yield* acquireReleaseResource(() => new AiConversation({ queue }));
 
-        yield* DatabaseService.add(blueprint);
+        const blueprint = DesignBlueprint.make();
+        yield* Database.add(blueprint);
         yield* Effect.promise(() =>
           conversation.context.bind({
             blueprints: [Ref.make(blueprint)],
           }),
         );
 
-        const artifact = yield* DatabaseService.add(Markdown.makeDocument({ content: 'Hello, world!' }));
+        const artifact = yield* Database.add(Markdown.make({ content: 'Hello, world!' }));
         let prevContent = artifact.content;
 
         {
           const prompt = trim`
-            I want to design a new feature for our product. 
+            I want to design a new feature for our product.
 
             We need to add a user profile system with the following requirements:
             1. Users should be able to create and edit their profiles
@@ -77,7 +69,7 @@ describe('Design Blueprint', { timeout: 120_000 }, () => {
 
         {
           const prompt = trim`
-            I want this to be built on top of Durable Objects and SQLite database. 
+            I want this to be built on top of Durable Objects and SQLite database.
             Adjust the spec to reflect this.
           `;
 
@@ -87,21 +79,17 @@ describe('Design Blueprint', { timeout: 120_000 }, () => {
         }
       },
       Effect.provide(
-        Layer.mergeAll(
-          makeToolResolverFromFunctions([Document.read, Document.update], testToolkit),
-          makeToolExecutionServiceFromFunctions(testToolkit, testToolkit.toLayer({}) as any),
-          AiService.model('@anthropic/claude-3-5-sonnet-20241022'),
-        ).pipe(
-          Layer.provideMerge(TestDatabaseLayer({ types: [DataType.Text, Markdown.Document, Blueprint.Blueprint] })),
-          Layer.provideMerge(AiServiceTestingPreset('direct')),
+        Layer.mergeAll(ToolExecutionServices, AiService.model('@anthropic/claude-3-5-sonnet-20241022')).pipe(
+          Layer.provideMerge(TestDatabaseLayer({ types: [Text.Text, Markdown.Document, Blueprint.Blueprint] })),
+          Layer.provideMerge(Layer.mergeAll(GenericToolkit.providerEmpty, AiServiceTestingPreset('direct'))),
           Layer.provideMerge(
-            FunctionInvocationService.layerTestMocked({ functions: [Document.read, Document.update] }).pipe(
-              Layer.provideMerge(ComputeEventLogger.layerFromTracing),
-              Layer.provideMerge(TracingService.layerNoop),
-            ),
+            FunctionInvocationServiceLayerTestMocked({
+              functions: Object.values(MarkdownFunctions),
+            }).pipe(Layer.provideMerge(TracingService.layerNoop)),
           ),
         ),
       ),
+      TestHelpers.provideTestContext,
       TestHelpers.taggedTest('llm'),
     ),
   );

package/src/blueprints/design/blueprint.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ToolId } from '@dxos/ai';
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { MarkdownFunctions } from '../markdown';
+
+const BLUEPRINT_KEY = 'dxos.org/blueprint/design';
+
+// TODO(burdon): Should this expose the functions directly or just reference them? How do we manage cross blueprint function dependencies?
+const functions = Object.values(MarkdownFunctions);
+
+const instructions = trim`
+  You manage a design spec based on the conversation.
+  The design spec is a markdown document that is used to record the tasks.
+  The design spec document follows a hierarchical structure, with nested markdown bulleted sections.
+  Use the appropriate tools to read and write the design spec document.
+  Maintain the document so that it can convey all relevant points from the conversation.
+  When replying to the user, be terse with your comments about design doc handling.
+  Do not announce when you read or write the design spec document.
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Design Spec',
+    description: 'Preserve the conversation in the design spec.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: functions.map((fn) => ToolId.make(fn.key)),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/design/index.ts

@@ -2,6 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-import blueprint from './design-blueprint';
-
-export default blueprint;
+export { default as DesignBlueprint } from './blueprint';

package/src/blueprints/discord/blueprint.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ToolId } from '@dxos/ai';
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { DiscordFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'dxos.org/blueprint/discord';
+
+const functions = Object.values(DiscordFunctions);
+
+/**
+ * Agent prompt instructions for managing hierarchical task lists.
+ */
+const instructions = trim`
+  You are able to fetch messages from Discord servers.
+
+  Known servers:
+
+  DXOS serverId: 837138313172353095
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Discord',
+    description: 'Discord integration.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: [ToolId.make(DiscordFunctions.Fetch.key)],
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

package/src/{functions/discord → blueprints/discord/functions}/fetch-messages.test.ts

@@ -2,7 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Toolkit from '@effect/ai/Toolkit';
 import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
 import { describe, it } from '@effect/vitest';
 import * as Config from 'effect/Config';
@@ -10,29 +9,25 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 
 import { AiService } from '@dxos/ai';
+import { GenericToolkit } from '@dxos/ai';
 import { AiServiceTestingPreset } from '@dxos/ai/testing';
-import { makeToolExecutionServiceFromFunctions, makeToolResolverFromFunctions } from '@dxos/assistant';
-import { TestHelpers } from '@dxos/effect';
-import { ComputeEventLogger, CredentialsService, FunctionInvocationService, TracingService } from '@dxos/functions';
-import { TestDatabaseLayer } from '@dxos/functions/testing';
+import { ToolExecutionServices } from '@dxos/assistant';
+import { TestHelpers } from '@dxos/effect/testing';
+import { CredentialsService, FunctionInvocationService, TracingService } from '@dxos/functions';
+import { FunctionInvocationServiceLayerTestMocked, TestDatabaseLayer } from '@dxos/functions-runtime/testing';
 
 import { default as fetchMessages } from './fetch-messages';
 
-const TestLayer = Layer.mergeAll(
-  AiService.model('@anthropic/claude-opus-4-0'),
-  makeToolResolverFromFunctions([], Toolkit.make()),
-  makeToolExecutionServiceFromFunctions(Toolkit.make() as any, Layer.empty as any),
-  ComputeEventLogger.layerFromTracing,
-).pipe(
+const TestLayer = Layer.mergeAll(AiService.model('@anthropic/claude-opus-4-0'), ToolExecutionServices).pipe(
   Layer.provideMerge(
     Layer.mergeAll(
+      GenericToolkit.providerEmpty,
       AiServiceTestingPreset('direct'),
       TestDatabaseLayer({}),
       CredentialsService.layerConfig([{ service: 'discord.com', apiKey: Config.redacted('DISCORD_TOKEN') }]),
       FetchHttpClient.layer,
-      FunctionInvocationService.layerTestMocked({ functions: [fetchMessages] }).pipe(
-        Layer.provideMerge(ComputeEventLogger.layerFromTracing),
-        Layer.provideMerge(TracingService.layerLogInfo()),
+      FunctionInvocationServiceLayerTestMocked({ functions: [fetchMessages] }).pipe(
+        Layer.provideMerge(TracingService.layerNoop),
       ),
     ),
   ),
@@ -53,6 +48,7 @@ describe('Feed', { timeout: 600_000 }, () => {
         console.log(messages);
       },
       Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
       TestHelpers.taggedTest('sync'),
     ),
   );