@dxos/assistant-toolkit 0.8.4-main.bc674ce → 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,14 +7,9 @@ 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 { Database } from '@dxos/echo';
@@ -28,10 +23,9 @@ 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,14 +36,15 @@ describe('Design Blueprint', { timeout: 120_000 }, () => {
         const queue = yield* QueueService.createQueue<Message.Message | ContextBinding>();
         const conversation = yield* acquireReleaseResource(() => new AiConversation({ queue }));
 
-        yield* Database.Service.add(blueprint);
+        const blueprint = DesignBlueprint.make();
+        yield* Database.add(blueprint);
         yield* Effect.promise(() =>
           conversation.context.bind({
             blueprints: [Ref.make(blueprint)],
           }),
         );
 
-        const artifact = yield* Database.Service.add(Markdown.make({ content: 'Hello, world!' }));
+        const artifact = yield* Database.add(Markdown.make({ content: 'Hello, world!' }));
         let prevContent = artifact.content;
 
         {
@@ -84,17 +79,13 @@ 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.mergeAll(ToolExecutionServices, AiService.model('@anthropic/claude-3-5-sonnet-20241022')).pipe(
           Layer.provideMerge(TestDatabaseLayer({ types: [Text.Text, Markdown.Document, Blueprint.Blueprint] })),
-          Layer.provideMerge(AiServiceTestingPreset('direct')),
+          Layer.provideMerge(Layer.mergeAll(GenericToolkit.providerEmpty, AiServiceTestingPreset('direct'))),
           Layer.provideMerge(
-            FunctionInvocationServiceLayerTestMocked({ functions: [Document.read, Document.update] }).pipe(
-              Layer.provideMerge(TracingService.layerNoop),
-            ),
+            FunctionInvocationServiceLayerTestMocked({
+              functions: Object.values(MarkdownFunctions),
+            }).pipe(Layer.provideMerge(TracingService.layerNoop)),
           ),
         ),
       ),

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

@@ -3,12 +3,18 @@
 //
 
 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 { Document } from '../../functions';
+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.
@@ -20,12 +26,21 @@ const instructions = trim`
   Do not announce when you read or write the design spec document.
 `;
 
-export const blueprint = Blueprint.make({
-  key: 'dxos.org/blueprint/design',
-  name: 'Design Spec',
-  description: 'Preserve the conversation in the design spec.',
-  instructions: {
-    source: Ref.make(Text.make(instructions)),
-  },
-  tools: [Document.read, Document.update].map((fn) => ToolId.make(fn.key)),
-});
+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,21 +9,19 @@ 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 { 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),
-).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') }]),

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

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import Fetch from './fetch-messages';
+
+export const DiscordFunctions = {
+  Fetch,
+};

package/src/blueprints/discord/index.ts

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

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

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { default as FetchPrs } from './fetch-prs';
+
+export const GithubFunctions = {
+  FetchPrs,
+};

package/src/blueprints/index.ts

@@ -2,9 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-export { default as DesignBlueprint } from './design';
-export { default as DiscordBlueprint } from './discord';
-export { default as LinearBlueprint } from './linear';
-export { default as PlanningBlueprint } from './planning';
-export { default as ResearchBlueprint } from './research';
-export { default as WebSearchBlueprint, WebSearchToolkit } from './websearch';
+export * from './design';
+export * from './discord';
+export * from './project';
+export * from './linear';
+export * from './markdown';
+export * from './planning';
+export * from './research';
+export * from './websearch';
+export * from './browser';
+export * from './database';

package/src/blueprints/linear/blueprint.ts

@@ -0,0 +1,47 @@
+//
+// 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 { LinearFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'dxos.org/blueprint/linear';
+
+const functions = Object.values(LinearFunctions);
+
+/**
+ * Agent prompt instructions for managing hierarchical task lists.
+ */
+const instructions = trim`
+  You are able to sync Linear workspaces.
+  Sometimes sync does not complete in one go and you need to call the function again.
+
+  Known workspaces:
+
+  DXOS teamId: 1127c63a-6f77-4725-9229-50f6cd47321c
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Linear',
+    description: 'Syncs Linear workspaces.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: functions.map((tool) => ToolId.make(tool.key)),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

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

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { default as Sync } from './sync-issues';
+
+export const LinearFunctions = {
+  Sync,
+};