@dxos/assistant-toolkit 0.8.4-main.bc674ce → 0.8.4-main.c351d160a8

package/src/blueprints/project/functions/qualifier.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Prompt from '@effect/ai/Prompt';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TriggerEvent, defineFunction } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { trim } from '@dxos/util';
+
+import { Plan, Project } from '../../../types';
+
+export default defineFunction({
+  key: 'org.dxos.function.project.qualifier',
+  name: 'Project Qualifier',
+  description:
+    'Qualifier that determines if the event is relevant to the project. Puts the data into the input queue of the project.',
+  inputSchema: Schema.Struct({
+    project: Schema.suspend(() => Ref.Ref(Project.Project)),
+    event: TriggerEvent.TriggerEvent,
+  }),
+  outputSchema: Schema.Void,
+  services: [],
+  handler: Effect.fnUntraced(
+    function* ({ data }) {
+      const project = yield* Database.load(data.project);
+      invariant(Obj.instanceOf(Project.Project, project));
+      invariant(project.chat, 'Project has no chat.');
+
+      const { id, name, queue } = project;
+      if (!queue) {
+        throw new Error('Project has no queue.');
+      }
+
+      const plan = yield* Database.load(project.plan);
+      const spec = yield* Database.load(project.spec);
+
+      const {
+        value: { isRelevant },
+      } = yield* LanguageModel.generateObject({
+        schema: Schema.Struct({
+          isRelevant: Schema.Boolean,
+        }),
+        prompt: Prompt.fromMessages([
+          Prompt.systemMessage({
+            content: trim`
+              You are a qualifying agent that determines if the event is relevant to the project.
+              Respond with true if the event is relevant to the project, false otherwise.
+              If you are not sure, return true.
+              The qualified events will be forwarded to the larger agent that will process them.
+              <project id="${id}" name="${name}">
+                <spec>
+                ${spec.content}
+                </spec>
+                <plan>
+                  ${Plan.formatPlan(plan)}
+                </plan>
+              </project>
+            `,
+          }),
+          Prompt.userMessage({
+            content: [
+              Prompt.makePart('text', {
+                text: trim`
+                  <event>
+                    ${JSON.stringify(data.event, null, 2)}
+                  </event>
+                `,
+              }),
+            ],
+          }),
+        ]),
+      });
+
+      if (isRelevant) {
+        const queueTarget = yield* Database.load(queue);
+        if ('queue' in data.event && data.event.item) {
+          const obj = data.event.item;
+          yield* Effect.promise(() => queueTarget.append([obj]));
+        } else if ('subject' in data.event && Ref.isRef(data.event.subject)) {
+          const obj = yield* Database.load(data.event.subject);
+          yield* Effect.promise(() => queueTarget.append([obj]));
+        } else {
+          throw new Error('Invalid event.');
+        }
+      }
+    },
+    Effect.scoped,
+    Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
+  ),
+});

package/src/blueprints/project/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as ProjectBlueprint } from './blueprint';
+export { ProjectFunctions } from './functions';
+export { syncProjectTriggers } from './sync-triggers';

package/src/blueprints/project/sync-triggers.ts

@@ -0,0 +1,153 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { FunctionDefinition, Trigger } from '@dxos/functions';
+import { FeedAnnotation } from '@dxos/schema';
+
+import { Project } from '../../types';
+
+import { ProjectFunctions } from './functions';
+
+/**
+ * Foreign key {@link PROJECT_TRIGGER_EXTENSION_KEY} => <project id : ObjectId>.
+ */
+const PROJECT_TRIGGER_EXTENSION_KEY = 'org.dxos.extension.ProjectTrigger';
+
+/**
+ * Foreign key {@link PROJECT_TRIGGER_TARGET_EXTENSION_KEY} => <dxn string of subscription target>.
+ */
+const PROJECT_TRIGGER_TARGET_EXTENSION_KEY = 'org.dxos.extension.ProjectTriggerTarget';
+
+/** Checks if an object's schema has the FeedAnnotation. */
+const hasFeedAnnotation = (obj: Obj.Unknown): boolean => {
+  const schema = Obj.getSchema(obj);
+  if (!schema) {
+    return false;
+  }
+  const annotation = FeedAnnotation.get(schema);
+  return Option.isSome(annotation) && annotation.value === true;
+};
+
+/**
+ * Syncs triggers in the database with the project subscriptions.
+ *
+ * @param project - The project whose triggers should be synced.
+ * @returns An Effect that syncs triggers.
+ */
+export const syncProjectTriggers = (project: Project.Project): Effect.Effect<void, never, Database.Service> =>
+  Effect.gen(function* () {
+    const triggers = yield* Database.runQuery(
+      Filter.foreignKeys(Trigger.Trigger, [{ source: PROJECT_TRIGGER_EXTENSION_KEY, id: project.id }]),
+    );
+
+    for (const trigger of triggers) {
+      const target = Obj.getKeys(trigger, PROJECT_TRIGGER_TARGET_EXTENSION_KEY).at(0)?.id;
+
+      const exists = project.subscriptions.find((subscription) => subscription.dxn.toString() === target);
+      if (!exists && !(project.useQualifyingAgent && target === Obj.getDXN(project)?.toString())) {
+        yield* Database.remove(trigger);
+      }
+    }
+
+    for (const subscription of project.subscriptions) {
+      const relevantTrigger = triggers.find((trigger) =>
+        Obj.getKeys(trigger, PROJECT_TRIGGER_TARGET_EXTENSION_KEY).some(
+          (key) => key.id === subscription.dxn.toString(),
+        ),
+      );
+      if (relevantTrigger) {
+        continue;
+      }
+
+      const targetOption = yield* Database.loadOption(subscription);
+      if (Option.isNone(targetOption)) {
+        continue;
+      }
+      const target = targetOption.value;
+
+      let feedObj: Feed.Feed | undefined;
+      if (Obj.instanceOf(Feed.Feed, target)) {
+        feedObj = target;
+      } else if (hasFeedAnnotation(target)) {
+        const feedRef = (target as Obj.Unknown & { feed?: Ref.Ref<Feed.Feed> }).feed;
+        feedObj = feedRef ? Option.getOrUndefined(yield* Database.loadOption(feedRef)) : undefined;
+      }
+
+      const queueDxn = Option.fromNullable(feedObj).pipe(
+        Option.filter(Obj.instanceOf(Feed.Feed)),
+        Option.map(Feed.getQueueDxn),
+        Option.getOrUndefined,
+      );
+      if (!queueDxn) {
+        continue;
+      }
+
+      yield* Database.add(
+        Trigger.make({
+          [Obj.Parent]: project,
+          [Obj.Meta]: {
+            keys: [
+              { source: PROJECT_TRIGGER_EXTENSION_KEY, id: project.id },
+              { source: PROJECT_TRIGGER_TARGET_EXTENSION_KEY, id: subscription.dxn.toString() },
+            ],
+          },
+          enabled: true,
+          spec: {
+            kind: 'queue',
+            queue: queueDxn.toString(),
+          },
+          function: Ref.make(
+            FunctionDefinition.serialize(
+              project.useQualifyingAgent ? ProjectFunctions.Qualifier : ProjectFunctions.Agent,
+            ),
+          ),
+          input: {
+            project: Ref.make(project),
+            event: '{{event}}',
+          },
+          concurrency: project.useQualifyingAgent ? 5 : undefined,
+        }),
+      );
+    }
+
+    if (project.useQualifyingAgent) {
+      const qualifierTrigger = triggers.find((trigger) =>
+        Obj.getKeys(trigger, PROJECT_TRIGGER_TARGET_EXTENSION_KEY).some(
+          (key) => key.id === Obj.getDXN(project)?.toString(),
+        ),
+      );
+      if (!qualifierTrigger && project.queue) {
+        yield* Database.add(
+          Trigger.make({
+            [Obj.Parent]: project,
+            [Obj.Meta]: {
+              keys: [
+                { source: PROJECT_TRIGGER_EXTENSION_KEY, id: project.id },
+                {
+                  source: PROJECT_TRIGGER_TARGET_EXTENSION_KEY,
+                  id: Obj.getDXN(project)?.toString() ?? '',
+                },
+              ],
+            },
+            function: Ref.make(FunctionDefinition.serialize(ProjectFunctions.Agent)),
+            enabled: true,
+            spec: {
+              kind: 'queue',
+              queue: project.queue.dxn.toString(),
+            },
+            input: {
+              project: Ref.make(project),
+              event: '{{event}}',
+            },
+          }),
+        );
+      }
+    }
+
+    yield* Database.flush();
+  });

package/src/blueprints/project-wizard/blueprint.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { ProjectWizardFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.project-wizard';
+
+const functions = Object.values(ProjectWizardFunctions);
+
+/**
+ * Creates the Project blueprint. This is a function to avoid circular dependency issues.
+ */
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Project Wizard',
+    description: 'Help the user create a new project.',
+    instructions: Template.make({
+      source: trim`
+        You are a wizard that helps the user create a new project.
+
+        Projects are goal oriented and autonomously driven by the agent.
+        Each project has a spec - the goal of the project.
+        The spec also typically describes what actions to perform in reaction to events (emails).
+        The project has a number of associated artifacts to work with. 
+        Projects can subscribe to emails.
+
+        IMPORTANT: Before attempting to create a project call the [project-rules] tool to get the rules for creating a project.
+      `,
+    }),
+    tools: Blueprint.toolDefinitions({ functions }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/project-wizard/functions/create-project.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { Obj, Ref } from '@dxos/echo';
+import { Blueprint } from '@dxos/blueprints';
+
+import { defineFunction } from '@dxos/functions';
+
+import { Project } from '../../../types';
+import { ProjectBlueprint, syncProjectTriggers } from '../../project';
+
+// TODO(dmaretskyi): Remove this with proper function typing.
+const fixEffectType = <A, E, R>(
+  eff: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, Exclude<R, Blueprint.RegistryService>> => eff as any;
+
+export default defineFunction({
+  key: 'org.dxos.function.project-wizard.create-project',
+  name: 'Create project',
+  description: 'Creates a new project.',
+  inputSchema: Schema.Struct({
+    name: Schema.String.annotations({
+      description: 'The name of the project to create.',
+    }),
+    spec: Schema.String.annotations({
+      description:
+        'The goal of the project. Be specic but not to verbose. The agent will use this as a core objective and set of rules to follow.',
+    }),
+    blueprints: Schema.Array(Schema.String).annotations({
+      description: 'The keys blueprints to use for the project.',
+      examples: [['org.dxos.blueprint.markdown', 'org.dxos.blueprint.database']],
+    }),
+    subscriptions: Schema.Array(Ref.Ref(Obj.Unknown)).annotations({
+      description: 'The objects to subscribe to for the project. Can be references to mailboxes.',
+    }),
+  }),
+  outputSchema: Project.Project,
+  services: [Blueprint.RegistryService],
+  handler: Effect.fnUntraced(function* ({ data }) {
+    const project = yield* Project.makeInitialized(
+      {
+        name: data.name,
+        spec: data.spec,
+        blueprints: yield* Effect.forEach(data.blueprints, (key) =>
+          Blueprint.upsert(key).pipe(Effect.map(Ref.make), Effect.orDie),
+        ),
+        subscriptions: data.subscriptions,
+      },
+      Obj.clone(ProjectBlueprint.make()),
+    );
+    yield* syncProjectTriggers(project);
+    return project;
+  }, fixEffectType),
+});

package/src/blueprints/project-wizard/functions/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { default as CreateProject } from './create-project';
+import { default as QueryBlueprints } from './query-blueprints';
+import { default as ProjectRules } from './project-rules';
+
+export const ProjectWizardFunctions = {
+  CreateProject,
+  QueryBlueprints,
+  ProjectRules,
+};

package/src/blueprints/project-wizard/functions/project-rules.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'org.dxos.function.project-wizard.project-rules',
+  name: 'Project rules',
+  description: 'Gets the rules for creating a project.',
+  inputSchema: Schema.Struct({}),
+  outputSchema: Schema.String,
+  handler: Effect.fnUntraced(function* ({ data }) {
+    return trim`
+      You can ask the user for qualifying questions about the projects.
+      If projects should actively read incoming emails, query for mailboxes and add a subscription to them.
+      Use [query-blueprints] function to query for available blueprints.
+      Use [create-project] function to create a new project.
+      After creating a project, explicitly remind the user to enable local triggers so the project can be driven autonomously.
+
+      Notable blueprints (query to get their keys):
+
+      - Database -- CRUD on objects in the ECHO database.
+      - Markdown -- Create and edit markdown documents.
+      - Websearch -- Search the web for information.
+      - Browser -- Virtual browser via playwright when simple WebSearch is not enough.
+      - Memory -- Memory to store and retrieve information.
+
+      Experimental blueprints that are discoraged:
+
+      - Research
+      - Design
+      - Project (not wizard) -- those are project internals, they are auto-added to every new project.
+
+      <example_project>
+        ## CRM from your inbox
+
+        Blueprints: database, websearch, browser
+
+        Subscribe to your inboxes.
+        Spec says that on every email we should extract People and Organizations and save them to the database, but first query the database for existing people and organizations to avoid duplicates.
+        Also run a quick research on the web to find more information about the person or organization and save it to the database.
+      </example_project>
+
+      <example_project>
+        ## Parcel tracking
+
+        Blueprints: database
+
+        Based on emails from vendors (amazon, fedex, etc.) track the status of the parcels ordered online and keep a table of orders.
+
+        Before creating a project, use the Database blueprint to create an Order schema:
+          - seller
+          - name
+          - price
+          - status (enum of: pending, shipped, waiting for pickup, delivered, cancelled, returned)
+          - tracking numbers/notes
+          - date of delivery
+          - shipping address
+      </example_project>
+
+      <example_project>
+        ## Comms assistant
+
+        Blueprints: database, markdown, inbox
+
+        Helps user maintain comms with external parites via email.
+        Ask user specifically who they want to communicate with and on what topic.
+        Project should keep a markdown document in artifacts outlining the current state of the comms.
+        Project should propose drafts to follow up on the comms. Only propose sensible drafts, do not propose drafts that are not relevant or actionable.
+      </example_project>
+    `;
+  }),
+});

package/src/blueprints/project-wizard/functions/query-blueprints.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Blueprint } from '@dxos/blueprints';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { defineFunction } from '@dxos/functions';
+
+// TODO(dmaretskyi): Remove this with proper function typing.
+const fixEffectType = <A, E, R>(
+  eff: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, Exclude<R, Blueprint.RegistryService>> => eff as any;
+
+export default defineFunction({
+  key: 'org.dxos.function.project-wizard.query-blueprints',
+  name: 'Query blueprints',
+  description: 'Queries the blueprints.',
+  inputSchema: Schema.Struct({}),
+  outputSchema: Schema.Array(Blueprint.Blueprint),
+  services: [Blueprint.RegistryService],
+  handler: Effect.fnUntraced(function* ({ data }) {
+    const registry = yield* Blueprint.RegistryService;
+    return registry.query();
+  }, fixEffectType),
+});

package/src/blueprints/project-wizard/index.ts

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

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

@@ -3,12 +3,17 @@
 //
 
 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 { Research } from '../../functions';
+import { ResearchFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.research';
+
+const functions = Object.values(ResearchFunctions);
 
 /**
  * Agent prompt instructions for managing hierarchical task lists.
@@ -20,7 +25,7 @@ const instructions = trim`
   Structured data extraction is an experimental feature -- only enable it if the user explicitly requests it in the prompt.
   Prefer updating existing notes instead of creating new ones.
 
-  <strcutured_mode>
+  <structured_mode>
     When you are done, reply with the created objects.
     Do not print the data, instead reply with inline references to the created objects.
     Those will be later substituted with the pills representing the created objects.
@@ -40,12 +45,21 @@ const instructions = trim`
   </unstructured_mode>
 `;
 
-export const blueprint = Blueprint.make({
-  key: 'dxos.org/blueprint/research',
-  name: 'Research',
-  description: 'Researches the web and creates structured data.',
-  instructions: {
-    source: Ref.make(Text.make(instructions)),
-  },
-  tools: [Research.create, Research.research].map((fn) => ToolId.make(fn.key)),
-});
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Research',
+    description: 'Researches the web and creates structured data.',
+    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/{functions/research → blueprints/research/functions}/document-create.ts

@@ -5,9 +5,7 @@
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { ArtifactId } from '@dxos/assistant';
-import { Obj, Relation } from '@dxos/echo';
-import { Database } from '@dxos/echo';
+import { Database, Obj, Ref, Relation } from '@dxos/echo';
 import { TracingService, defineFunction } from '@dxos/functions';
 import { log } from '@dxos/log';
 import { Markdown } from '@dxos/plugin-markdown/types';
@@ -15,11 +13,11 @@ import { HasSubject } from '@dxos/types';
 import { trim } from '@dxos/util';
 
 export default defineFunction({
-  key: 'dxos.org/function/research/document-create',
+  key: 'org.dxos.function.research.document-create',
   name: 'Create research document',
   description: 'Creates a note summarizing the research.',
   inputSchema: Schema.Struct({
-    subject: ArtifactId.annotations({
+    subject: Ref.Ref(Obj.Unknown).annotations({
       description: trim`
         ID of the object (organization, contact, etc.) for which the research was performed. 
       `,
@@ -35,7 +33,7 @@ export default defineFunction({
     }),
   }),
   outputSchema: Schema.Struct({
-    document: ArtifactId.annotations({
+    document: Schema.String.annotations({
       description: 'DXN of the created document.',
     }),
   }),
@@ -43,14 +41,13 @@ export default defineFunction({
     log.info('Creating research document', { subject, name, content });
 
     // TODO(burdon): Auto flush before and after calling function?
-    yield* Database.Service.flush({ indexes: true });
+    yield* Database.flush();
     yield* TracingService.emitStatus({ message: 'Creating research document...' });
 
-    // TODO(burdon): Type check.
-    const target = (yield* Database.Service.resolve(ArtifactId.toDXN(subject))) as Obj.Unknown;
+    const target = yield* Database.load(subject);
 
     // Create document.
-    const object = yield* Database.Service.add(
+    const object = yield* Database.add(
       Markdown.make({
         name,
         content,
@@ -58,7 +55,7 @@ export default defineFunction({
     );
 
     // Create relation.
-    yield* Database.Service.add(
+    yield* Database.add(
       Relation.make(HasSubject.HasSubject, {
         [Relation.Source]: object,
         [Relation.Target]: target,
@@ -66,7 +63,7 @@ export default defineFunction({
       }),
     );
 
-    yield* Database.Service.flush({ indexes: true });
+    yield* Database.flush();
     log.info('Created research document', { subject, object });
 
     return {

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

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import Create from './document-create';
+import Research from './research';
+
+export const ResearchFunctions = {
+  Create,
+  Research,
+};

package/src/{functions/research → blueprints/research/functions}/research-instructions.tpl

@@ -92,11 +92,11 @@ The following objects are already in the database, I will not submit them again,
 
 I will use the following schema to construct new objects:
 
-- type:dxos.org/type/Organization for Alphabet Inc.
-- type:dxos.org/type/Person for Ivan Zhao
-- type:dxos.org/type/Person for Simon Last
-- dxn:type:dxos.org/relation/Employer for Ivan's employer
-- dxn:type:dxos.org/relation/Employer for Simon's employer
+- type:org.dxos.type.organization for Alphabet Inc.
+- type:org.dxos.type.person for Ivan Zhao
+- type:org.dxos.type.person for Simon Last
+- dxn:type:org.dxos.relation.employer for Ivan's employer
+- dxn:type:org.dxos.relation.employer for Simon's employer
 
 <status>Formatting results</status>