@dxos/assistant-toolkit 0.8.4-main.66e292d → 0.8.4-main.6fa680abb7

package/src/blueprints/project/blueprint.ts

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { ProjectFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.project';
+
+const functions = [ProjectFunctions.AddArtifact];
+
+/**
+ * Creates the Project blueprint. This is a function to avoid circular dependency issues.
+ */
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Project blueprint',
+    instructions: Template.make({
+      source: trim`
+        You work on an project. Each project has a spec - the goal of the project.
+        The project plan shows the current progress of the project.
+        Project has an number of associated artifacts you can read/write.
+        Spec and plan are also artifacts.
+        You can edit them if necessary.
+
+        IMPORTANT: When create a new artifact, always add it to the project using the add-artifact function.
+
+        {{#with project}}
+        <project id="{{id}}" name="{{name}}">
+          <spec>
+            {{spec}}
+          </spec>
+          <plan>
+            {{plan}}
+          </plan>
+
+          <artifacts>
+          {{#each artifacts}}
+            <artifact type="{{type}}" dxn="{{dxn}}">
+              {{name}}
+            </artifact>
+          {{/each}}
+          </artifacts>
+        </project>
+        {{/with}}
+      `,
+      inputs: [
+        {
+          name: 'project',
+          kind: 'function',
+          function: 'org.dxos.function.project.get-context',
+        },
+      ],
+    }),
+    tools: Blueprint.toolDefinitions({ functions }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/project/functions/add-artifact.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+
+import { Project } from '../../../types';
+
+export default defineFunction({
+  key: 'org.dxos.function.project.add-artifact',
+  name: 'Add artifact',
+  description: 'Adds a new artifact.',
+  inputSchema: Schema.Struct({
+    name: Schema.String.annotations({
+      description: 'The name of the artifact to add.',
+    }),
+    artifact: Ref.Ref(Obj.Unknown).annotations({
+      description: 'The artifact to add. Do NOT guess or try to generate the ID.',
+    }),
+  }),
+  services: [AiContextService],
+  handler: Effect.fnUntraced(function* ({ data }) {
+    if (!(yield* Database.load(data.artifact))) {
+      throw new Error('Artifact not found.');
+    }
+
+    const project = yield* Project.getFromChatContext;
+
+    Obj.change(project, (project) => {
+      project.artifacts.push({
+        name: data.name,
+        data: data.artifact,
+      });
+    });
+  }, AiContextService.fixFunctionHandlerType),
+});

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: 'org.dxos.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: 'org.dxos.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: '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,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as ProjectBlueprint } from './blueprint';
+export { ProjectFunctions } 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 { 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 { 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,14 +45,21 @@ 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: 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,20 +5,19 @@
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { ArtifactId } from '@dxos/assistant';
-import { Obj, Relation } from '@dxos/echo';
-import { DatabaseService, TracingService, defineFunction } from '@dxos/functions';
+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',
+  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. 
       `,
@@ -34,7 +33,7 @@ export default defineFunction({
     }),
   }),
   outputSchema: Schema.Struct({
-    document: ArtifactId.annotations({
+    document: Schema.String.annotations({
       description: 'DXN of the created document.',
     }),
   }),
@@ -42,14 +41,13 @@ export default defineFunction({
     log.info('Creating research document', { subject, name, content });
 
     // TODO(burdon): Auto flush before and after calling function?
-    yield* DatabaseService.flush({ indexes: true });
+    yield* Database.flush({ indexes: true });
     yield* TracingService.emitStatus({ message: 'Creating research document...' });
 
-    // TODO(burdon): Type check.
-    const target = (yield* DatabaseService.resolve(ArtifactId.toDXN(subject))) as Obj.Any;
+    const target = yield* Database.load(subject);
 
     // Create document.
-    const object = yield* DatabaseService.add(
+    const object = yield* Database.add(
       Markdown.make({
         name,
         content,
@@ -57,7 +55,7 @@ export default defineFunction({
     );
 
     // Create relation.
-    yield* DatabaseService.add(
+    yield* Database.add(
       Relation.make(HasSubject.HasSubject, {
         [Relation.Source]: object,
         [Relation.Target]: target,
@@ -65,7 +63,7 @@ export default defineFunction({
       }),
     );
 
-    yield* DatabaseService.flush({ indexes: true });
+    yield* Database.flush({ indexes: true });
     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>