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

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

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { AiContextService, AiConversation, type ContextBinding } from '@dxos/assistant';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { type Queue } from '@dxos/echo-db';
+import { acquireReleaseResource } from '@dxos/effect';
+import { TriggerEvent, defineFunction } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { type Message } from '@dxos/types';
+
+import { Project } from '../../../types';
+
+export default defineFunction({
+  key: 'dxos.org/function/project/agent',
+  name: 'Project Agent',
+  description: 'Agentic worker that drives the project autonomously.',
+  inputSchema: Schema.Struct({
+    project: Schema.suspend(() => Ref.Ref(Project.Project)),
+    prompt: Schema.optional(Schema.String),
+    event: Schema.optional(TriggerEvent.TriggerEvent),
+  }),
+  outputSchema: Schema.Void,
+  services: [AiContextService],
+  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 chatQueue = yield* project.chat.pipe(
+        Database.load,
+        Effect.flatMap((chat) => Database.load(chat.queue)),
+      );
+      invariant(chatQueue, 'Project chat queue not found.');
+      const conversation = yield* acquireReleaseResource(
+        () => new AiConversation({ queue: chatQueue as Queue<Message.Message | ContextBinding> }),
+      );
+
+      const iniativesInContext = conversation.context.getObjects().filter(Obj.instanceOf(Project.Project));
+      if (iniativesInContext.length !== 1) {
+        throw new Error('There should be exactly one project in context. Got: ' + iniativesInContext.length);
+      }
+
+      if (!data.prompt && !data.event) {
+        throw new Error('Either prompt or event must be provided.');
+      }
+
+      let input = '';
+      if (data.prompt) {
+        input += `${data.prompt}\n\n`;
+      }
+      if (data.event) {
+        input += `<event>\n${JSON.stringify(data.event, null, 2)}\n</event>\n\n`;
+      }
+
+      yield* conversation
+        .createRequest({
+          prompt: input,
+        })
+        .pipe(Effect.retry({ times: 2 }));
+    },
+    Effect.scoped,
+    Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
+    AiContextService.fixFunctionHandlerType,
+  ) as any,
+});

package/src/blueprints/project/functions/get-context.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Database, Obj } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+
+import { Plan, Project } from '../../../types';
+
+export default defineFunction({
+  key: 'dxos.org/function/project/get-context',
+  name: 'Get Project Context',
+  description: 'Get the context of an project.',
+  inputSchema: Schema.Struct({}),
+  outputSchema: Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    spec: Schema.String,
+    plan: Schema.String,
+    artifacts: Schema.Array(
+      Schema.Struct({
+        name: Schema.String,
+        type: Schema.optional(Schema.String),
+        dxn: Schema.optional(Schema.String),
+      }),
+    ),
+  }),
+  services: [AiContextService],
+  handler: Effect.fnUntraced(function* ({ data: _data }) {
+    const project = yield* Project.getFromChatContext;
+
+    return {
+      id: project.id,
+      name: project.name,
+      spec: yield* project.spec.pipe(Database.load).pipe(
+        Effect.map((_) => _.content),
+        Effect.catchTag('ObjectNotFoundError', () => Effect.succeed('No spec found.')),
+      ),
+      plan: yield* (
+        project.plan?.pipe(Database.load).pipe(
+          Effect.map(Plan.formatPlan),
+          Effect.catchTag('ObjectNotFoundError', () => Effect.succeed('No plan found.')),
+        ) ?? Effect.succeed('No plan found.')
+      ),
+      artifacts: yield* Effect.forEach(project.artifacts, (artifact) =>
+        Effect.gen(function* () {
+          return {
+            name: artifact.name,
+            type: yield* Database.load(artifact.data).pipe(
+              Effect.map(Obj.getTypename),
+              Effect.catchTag('ObjectNotFoundError', () => Effect.succeed('Artifact not found.')),
+            ),
+            dxn: artifact.data.dxn.toString(),
+          };
+        }),
+      ),
+    };
+  }, AiContextService.fixFunctionHandlerType),
+});

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

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { default as AddArtifact } from './add-artifact';
+import { default as Agent } from './agent';
+import { default as GetContext } from './get-context';
+import { default as Qualifier } from './qualifier';
+
+export const ProjectFunctions = {
+  AddArtifact,
+  Agent,
+  GetContext,
+  Qualifier,
+};

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: 'dxos.org/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,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as ProjectBlueprint } from './blueprint';
+export { ProjectFunctions } from './functions';

package/src/blueprints/research/blueprint.ts

@@ -0,0 +1,65 @@
+//
+// 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 { ResearchFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'dxos.org/blueprint/research';
+
+const functions = Object.values(ResearchFunctions);
+
+/**
+ * Agent prompt instructions for managing hierarchical task lists.
+ */
+const instructions = trim`
+  {{! Research }}
+
+  You are an analyst that does research tasks using tools that scrape the web and create structured data.
+  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.
+
+  <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.
+    Print the rest of the created objects as block references after the main note.
+
+    <example>
+      Based on my research, Google was founded by @dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK464FSCKVQJAB2H662M and @dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK46K31DDW62PBW9H2ZQ
+
+      <object><dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK464FSCKVQJAB2H662M</dxn></object>
+      <object><dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK46K31DDW62PBW9H2ZQ</dxn></object>
+      <object><dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK46K31DDW62PBW92333</dxn></object>
+    </example>
+  </structured_mode>
+
+  <unstructured_mode>
+    Reply normally with the text mode of the result of your research.
+  </unstructured_mode>
+`;
+
+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/blueprints/research/functions/document-create.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+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';
+import { HasSubject } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'dxos.org/function/research/document-create',
+  name: 'Create research document',
+  description: 'Creates a note summarizing the research.',
+  inputSchema: 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).
+      `,
+    }),
+  }),
+  outputSchema: Schema.Struct({
+    document: Schema.String.annotations({
+      description: 'DXN of the created document.',
+    }),
+  }),
+  handler: Effect.fnUntraced(function* ({ data: { subject, name, content } }) {
+    log.info('Creating research document', { subject, name, content });
+
+    // TODO(burdon): Auto flush before and after calling function?
+    yield* Database.flush({ indexes: true });
+    yield* TracingService.emitStatus({ message: 'Creating research document...' });
+
+    const target = yield* Database.load(subject);
+
+    // Create document.
+    const object = yield* Database.add(
+      Markdown.make({
+        name,
+        content,
+      }),
+    );
+
+    // Create relation.
+    yield* Database.add(
+      Relation.make(HasSubject.HasSubject, {
+        [Relation.Source]: object,
+        [Relation.Target]: target,
+        completedAt: new Date().toISOString(),
+      }),
+    );
+
+    yield* Database.flush({ indexes: true });
+    log.info('Created research document', { subject, object });
+
+    return {
+      document: Obj.getDXN(object).toString(),
+    };
+  }),
+});

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/instructions-research.tpl → blueprints/research/functions/research-instructions.tpl}

@@ -6,10 +6,11 @@ The Research Agent outputs results in a structured format matching the schema pr
 The Research Agent is equipped with the ability to:
 
 - Generate precise and effective search queries 
-- Request web pages by query (through a `web_search` tool)
-- Read the full content of retrieved pages
+- Request web pages by query.
 - Synthesize accurate, clear, and structured answers using reliable information from the retrieved content
+{{#if entityExtraction}}
 - Search the local database for information using a vector index (through a `local_search` tool)
+{{/if}}
 
 The Research Agent always follows these principles:
 
@@ -19,6 +20,7 @@ The Research Agent always follows these principles:
 - Transparency: The Research Agent mentions which sources were used and explains how it arrived at conclusions.
 - Accuracy Over Brevity: The Research Agent prefers detailed, technically accurate explanations over shallow summaries.
 - The Research Agent admits uncertainty rather than misleading.
+{{#if entityExtraction}}
 - The Research Agent picks the most concrete schema types for extracted information.
 - The Research Agent fills schema fields completely with information it is confident about, and omits fields it is not confident about.
 - When outputting results, the Research Agent adds extra data that fits the schema even if not directly related to the user's question.
@@ -26,6 +28,7 @@ The Research Agent always follows these principles:
 - The Research Agent does not create objects that are already in the database.
 - The Research Agent re-uses existing object IDs as references when enriching existing objects.
 - The Research Agent ALWAYS calls the `graph_writer` at the end to save the data. This conversation will be deleted, so only the data written to the graph will be preserved.
+{{/if}}
 
 The Research Agent may be asked for:
 
@@ -41,8 +44,6 @@ The Research Agent breaks it into sub-questions (if applicable).
 
 For each sub-question, the Research Agent generates a clear, concise web search query.
 
-The Research Agent uses `web_search`(query) to retrieve information.
-
 The Research Agent extracts and synthesizes relevant answers.
 
 The Research Agent's output includes:
@@ -58,23 +59,27 @@ Here's how the Research Agent operates:
 2. The Research Agent performs a web search for each topic.
 3. The Research Agent reads and analyzes results, cross references information from multiple sources, and represents conflicting information as ranges of possible values.
 
+{{#if entityExtraction}}
 4. The Research Agent searches the local database for information using a vector index that might link to the user's question.
 6. The Research Agent creates relations and references between new objects and existing database objects when related, using existing object IDs as references.
 7. The Research Agent selects the most concrete schema types for extracted information, using multiple types as needed, and prints its decision and reasoning.
 5. The Research Agent creates a clear, structured answer to the user's question.
 8. The Research Agent submits results using the specific schema.
+{{/if}}
 
+{{#if entityExtraction}}
 IMPORTANT:
-
 - The Research Agent always runs the `local_search` tool to search the local database at least once before submitting results.
 - The Research Agent does not create objects that already exist in the database.
 - Ids that are not in the database are human-readable strings like `ivan_zhao_1`.
+{{/if}}
 
 Status reporting:
 
 The Research Agent reports its status frequently using the `<status>` tags: <status>Searching for Google Founders</status>
 The Research Agent reports its status in-between each tool call and before submitting results.
 
+{{#if entityExtraction}}
 <example>
 
 Based on my research, I can now provide information about Google and it's founders.
@@ -95,4 +100,7 @@ I will use the following schema to construct new objects:
 
 <status>Formatting results</status>
 
-</example>
+</example>
+{{/if}}
+
+Last content block is the full research note -- the result of the research.