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

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

@@ -0,0 +1,135 @@
+//
+// 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 { Trigger } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+import { FeedAnnotation } from '@dxos/schema';
+
+import { Agent } from '../../../types';
+import { SyncTriggers } from './definitions';
+
+export default SyncTriggers.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ agent: agentRef }) {
+      const agent = yield* Database.load(agentRef);
+      yield* syncAgentTriggers(agent);
+    }),
+  ),
+);
+
+/**
+ * Foreign key {@link AGENT_TRIGGER_EXTENSION_KEY} => <agent id : ObjectId>.
+ */
+const AGENT_TRIGGER_EXTENSION_KEY = 'org.dxos.extension.AgentTrigger';
+
+/**
+ * Foreign key {@link AGENT_TRIGGER_TARGET_EXTENSION_KEY} => <dxn string of subscription target>.
+ */
+const AGENT_TRIGGER_TARGET_EXTENSION_KEY = 'org.dxos.extension.AgentTriggerTarget';
+
+/** 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 agent subscriptions.
+ */
+const syncAgentTriggers = (agent: Agent.Agent): Effect.Effect<void, never, Database.Service> =>
+  Effect.gen(function* () {
+    const triggers = yield* Database.runQuery(
+      Filter.foreignKeys(Trigger.Trigger, [{ source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id }]),
+    );
+
+    // Remove all existing triggers — they will be recreated with the current config.
+    // This ensures operation and concurrency stay in sync when filterEvents is toggled.
+    for (const trigger of triggers) {
+      yield* Database.remove(trigger);
+    }
+
+    // Lazy import to avoid circular dependency issues.
+    const { Qualifier, AgentWorker } = yield* Effect.promise(() => import('../../project'));
+
+    for (const subscription of agent.subscriptions) {
+      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;
+      }
+
+      const filterEvents = agent.filterEvents ?? true;
+
+      yield* Database.add(
+        Trigger.make({
+          [Obj.Parent]: agent,
+          [Obj.Meta]: {
+            keys: [
+              { source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id },
+              { source: AGENT_TRIGGER_TARGET_EXTENSION_KEY, id: subscription.dxn.toString() },
+            ],
+          },
+          enabled: true,
+          spec: Trigger.specQueue(queueDxn.toString()),
+          function: Ref.make(Operation.serialize(filterEvents ? Qualifier : AgentWorker)),
+          input: {
+            agent: Ref.make(agent),
+            event: '{{event}}',
+          },
+          concurrency: filterEvents ? 5 : undefined,
+        }),
+      );
+    }
+
+    if ((agent.filterEvents ?? true) && agent.queue) {
+      yield* Database.add(
+        Trigger.make({
+          [Obj.Parent]: agent,
+          [Obj.Meta]: {
+            keys: [
+              { source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id },
+              {
+                source: AGENT_TRIGGER_TARGET_EXTENSION_KEY,
+                id: Obj.getDXN(agent)?.toString() ?? '',
+              },
+            ],
+          },
+          function: Ref.make(Operation.serialize(AgentWorker)),
+          enabled: true,
+          spec: Trigger.specQueue(agent.queue.dxn.toString()),
+          input: {
+            agent: Ref.make(agent),
+            event: '{{event}}',
+          },
+        }),
+      );
+    }
+
+    yield* Database.flush();
+  });

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

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as AgentWizardBlueprint } from './blueprint';
+export { AgentRules, CreateAgent, SyncTriggers, AgentWizardHandlers } from './functions';

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

@@ -2,13 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { ToolId } from '@dxos/ai';
+import { type AppCapabilities } from '@dxos/app-toolkit';
 import { Blueprint } from '@dxos/blueprints';
-import { Obj, Ref } from '@dxos/echo';
+import { Ref } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
-import { Research } from '../../functions';
+import { Research, DocumentCreate } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.research';
 
 /**
  * Agent prompt instructions for managing hierarchical task lists.
@@ -20,7 +22,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,14 +42,20 @@ const instructions = trim`
   </unstructured_mode>
 `;
 
-export const blueprint: Blueprint.Blueprint = Obj.make(Blueprint.Blueprint, {
-  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: Blueprint.toolDefinitions({ operations: [DocumentCreate, Research] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
 
 export default blueprint;

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

@@ -0,0 +1,87 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { Trace } from '@dxos/functions';
+import { Operation, OperationRegistry } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+export const Research = Operation.make({
+  meta: {
+    key: 'org.dxos.function.research',
+    name: 'Research',
+    description: trim`
+      Search the web to research information about the given subject.
+      Inserts structured data into the research graph. 
+      Creates a research summary and returns the objects created.
+    `,
+  },
+  input: Schema.Struct({
+    query: Schema.String.annotations({
+      description: trim`
+        The search query.
+        If doing research on an object then load it first and pass it as JSON.
+      `,
+    }),
+    instructions: Schema.optional(Schema.String).annotations({
+      description: trim`
+        The instructions for the research agent. 
+      `,
+    }),
+    // TOOD(burdon): Move to context.
+    mockSearch: Schema.optional(Schema.Boolean).annotations({
+      description: 'Whether to use the mock search tool.',
+      default: false,
+    }),
+    entityExtraction: Schema.optional(Schema.Boolean).annotations({
+      description: trim`
+        Whether to extract structured entities from the research. 
+        Experimental feature only enable if user explicitly requests it.
+      `,
+      default: false,
+    }),
+  }),
+  output: Schema.Struct({
+    document: Schema.optional(Schema.String).annotations({
+      description: 'The generated research document.',
+    }),
+    objects: Schema.Array(Schema.Unknown).annotations({
+      description: 'Structured objects created during the research process.',
+    }),
+  }),
+  services: [AiService.AiService, Database.Service, OperationRegistry.Service, Trace.TraceService],
+});
+
+export const DocumentCreate = Operation.make({
+  meta: {
+    key: 'org.dxos.function.research.document-create',
+    name: 'Create research document',
+    description: 'Creates a note summarizing the research.',
+  },
+  input: Schema.Struct({
+    subject: Ref.Ref(Obj.Unknown).annotations({
+      description: trim`
+        ID of the object (organization, contact, etc.) for which the research was performed. 
+      `,
+    }),
+    name: Schema.String.annotations({
+      description: 'Name of the document.',
+    }),
+    content: Schema.String.annotations({
+      description: trim`
+        Content of the note. 
+        Supports (and are prefered) references to research objects using @ syntax and <object> tags (refer to research blueprint instructions).
+      `,
+    }),
+  }),
+  output: Schema.Struct({
+    document: Schema.String.annotations({
+      description: 'DXN of the created document.',
+    }),
+  }),
+  services: [Database.Service, Trace.TraceService],
+});

package/src/blueprints/research/functions/document-create.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Obj, Relation } from '@dxos/echo';
+import { Trace } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+import { Markdown } from '@dxos/plugin-markdown/types';
+import { HasSubject } from '@dxos/types';
+
+import { DocumentCreate } from './definitions';
+
+export default DocumentCreate.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ subject, name, content }) {
+      log.info('Creating research document', { subject, name, content });
+
+      // TODO(burdon): Auto flush before and after calling function?
+      yield* Database.flush();
+      yield* Trace.emitStatus('Creating research document...');
+
+      const target = yield* Database.load(subject);
+
+      const object = yield* Database.add(
+        Markdown.make({
+          name,
+          content,
+        }),
+      );
+
+      yield* Database.add(
+        Relation.make(HasSubject.HasSubject, {
+          [Relation.Source]: object,
+          [Relation.Target]: target,
+          completedAt: new Date().toISOString(),
+        }),
+      );
+
+      yield* Database.flush();
+      log.info('Created research document', { subject, object });
+
+      return {
+        document: Obj.getDXN(object).toString(),
+      };
+    }),
+  ),
+);

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

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const ResearchHandlers = OperationHandlerSet.lazy(
+  () => import('./document-create'),
+  () => import('./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>