@dxos/assistant-toolkit 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/src/blueprints/project/blueprint.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { AddArtifact } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.project';
+
+/**
+ * Creates the Project blueprint. This is a function to avoid circular dependency issues.
+ */
+// TODO(dmaretskyi): Combine with Project Wizard
+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.
+        You can edit them if necessary.
+
+        IMPORTANT: When creating 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({ operations: [AddArtifact] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

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

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Obj } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { Project } from '../../../types';
+import { AddArtifact } from './definitions';
+
+export default AddArtifact.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ name, artifact }) {
+      if (!(yield* Database.load(artifact))) {
+        throw new Error('Artifact not found.');
+      }
+
+      const project = yield* Project.getFromChatContext;
+
+      Obj.change(project, (project) => {
+        project.artifacts.push({
+          name,
+          data: artifact,
+        });
+      });
+    }) as any,
+  ),
+);

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

@@ -0,0 +1,66 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AiService } from '@dxos/ai';
+import { AiConversation, functionInvocationServiceFromOperations, ToolExecutionServices } from '@dxos/assistant';
+import { Database, Feed, Obj } from '@dxos/echo';
+import { acquireReleaseResource } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+
+import { Project } from '../../../types';
+import { Agent } from './definitions';
+
+export default Agent.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(
+      function* ({ project: projectRef, prompt, event }) {
+        const project = yield* Database.load(projectRef);
+        invariant(Obj.instanceOf(Project.Project, project));
+        invariant(project.chat, 'Project has no chat.');
+
+        const chatFeed = yield* project.chat.pipe(
+          Database.load,
+          Effect.flatMap((chat) => Database.load(chat.feed)),
+        );
+        invariant(chatFeed, 'Project chat feed not found.');
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const conversation = yield* acquireReleaseResource(() => new AiConversation({ feed: chatFeed, runtime }));
+
+        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 (!prompt && !event) {
+          throw new Error('Either prompt or event must be provided.');
+        }
+
+        let input = '';
+        if (prompt) {
+          input += `${prompt}\n\n`;
+        }
+        if (event) {
+          input += `<event>\n${JSON.stringify(event, null, 2)}\n</event>\n\n`;
+        }
+
+        yield* conversation
+          .createRequest({
+            prompt: input,
+          })
+          .pipe(Effect.retry({ times: 2 }));
+      },
+      Effect.scoped,
+      Effect.provide(
+        Layer.mergeAll(AiService.model('@anthropic/claude-opus-4-6'), ToolExecutionServices).pipe(
+          Layer.provideMerge(functionInvocationServiceFromOperations),
+        ),
+      ),
+    ),
+  ),
+  Operation.opaqueHandler,
+);

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

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiService, GenericToolkit } from '@dxos/ai';
+import { AiContextService } from '@dxos/assistant';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { QueueService, TracingService, TriggerEvent } from '@dxos/functions';
+import { Trace } from '@dxos/functions';
+import { Operation, OperationRegistry } from '@dxos/operation';
+
+import { Project } from '../../../types';
+
+export const Agent = Operation.make({
+  meta: {
+    key: 'org.dxos.function.project.agent',
+    name: 'Project Agent',
+    description: 'Agentic worker that drives the project autonomously.',
+  },
+  input: Schema.Struct({
+    project: Schema.suspend(() => Ref.Ref(Project.Project)),
+    prompt: Schema.optional(Schema.String),
+    event: Schema.optional(TriggerEvent.TriggerEvent),
+  }),
+  output: Schema.Void,
+  services: [
+    AiService.AiService,
+    Database.Service,
+    QueueService,
+    Feed.FeedService,
+    OperationRegistry.Service,
+    // @deprecated TracingService kept for backward compat with tool handlers.
+    TracingService,
+    Trace.TraceService,
+    GenericToolkit.GenericToolkitProvider,
+  ],
+});
+
+export const Qualifier = Operation.make({
+  meta: {
+    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.',
+  },
+  input: Schema.Struct({
+    project: Schema.suspend(() => Ref.Ref(Project.Project)),
+    event: TriggerEvent.TriggerEvent,
+  }),
+  output: Schema.Void,
+  services: [AiService.AiService, Database.Service],
+});
+
+export const GetContext = Operation.make({
+  meta: {
+    key: 'org.dxos.function.project.get-context',
+    name: 'Get Project Context',
+    description: 'Get the context of an project.',
+  },
+  input: Schema.Struct({}),
+  output: 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, Database.Service],
+});
+
+export const AddArtifact = Operation.make({
+  meta: {
+    key: 'org.dxos.function.project.add-artifact',
+    name: 'Add artifact',
+    description: 'Adds a new artifact.',
+  },
+  input: 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.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [AiContextService, Database.Service],
+});

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

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Obj } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { Plan, Project } from '../../../types';
+import { GetContext } from './definitions';
+
+export default GetContext.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      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(),
+            };
+          }),
+        ),
+      };
+    }) as any,
+  ),
+);

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

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const ProjectHandlers = OperationHandlerSet.lazy(
+  () => import('./add-artifact'),
+  () => import('./agent'),
+  () => import('./get-context'),
+  () => import('./qualifier'),
+);

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

@@ -0,0 +1,90 @@
+//
+// 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 { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+import { Plan, Project } from '../../../types';
+import { Qualifier } from './definitions';
+
+export default Qualifier.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(
+      function* ({ project: projectRef, event }) {
+        const project = yield* Database.load(projectRef);
+        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 } = yield* Effect.scoped(
+          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(event, null, 2)}
+                      </event>
+                    `,
+                  }),
+                ],
+              }),
+            ]),
+          }),
+        );
+
+        const { isRelevant } = value as { isRelevant: boolean };
+
+        if (isRelevant) {
+          const queueTarget = yield* Database.load(queue);
+          if ('queue' in event && event.item) {
+            const obj = event.item;
+            yield* Effect.promise(() => queueTarget.append([obj]));
+          } else if ('subject' in event && Ref.isRef(event.subject)) {
+            const obj = yield* Database.load(event.subject);
+            yield* Effect.promise(() => queueTarget.append([obj]));
+          } else {
+            throw new Error('Invalid event.');
+          }
+        }
+      },
+      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 { Agent, Qualifier, GetContext, AddArtifact, ProjectHandlers } from './functions';

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

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { ProjectRules, CreateProject, SyncTriggers } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.project-wizard';
+
+/**
+ * Creates the Project blueprint. This is a function to avoid circular dependency issues.
+ */
+// TODO(dmaretskyi): Combine with Project Blueprint
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Project Wizard',
+    description: 'Help the user create a new project.',
+    agentCanEnable: true,
+    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.
+
+        The project itself is an ECHO object and can be edited like any other object using the database blueprint.
+        You can edit the project's spec, name, and other properties directly.
+        If you edit the project's subscriptions array, you MUST call the sync-triggers function afterward to synchronize the triggers.
+
+        IMPORTANT: Before attempting to create a project call the [project-rules] tool to get the rules for creating a project.
+      `,
+    }),
+    tools: Blueprint.toolDefinitions({ operations: [ProjectRules, CreateProject, SyncTriggers] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

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

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Blueprint } from '@dxos/blueprints';
+import { Obj, Ref } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { Project } from '../../../types';
+import { ProjectBlueprint } from '../../project';
+import { CreateProject, SyncTriggers } from './definitions';
+
+export default CreateProject.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ name, spec, blueprints, subscriptions }) {
+      const project = yield* Project.makeInitialized(
+        {
+          name,
+          spec,
+          blueprints: yield* Effect.forEach(blueprints, (key) =>
+            Blueprint.upsert(key).pipe(Effect.map(Ref.make), Effect.orDie),
+          ),
+          subscriptions,
+        },
+        Obj.clone(ProjectBlueprint.make()),
+      );
+      yield* Operation.invoke(SyncTriggers, { project: Ref.make(project) });
+      return project;
+    }),
+  ),
+);

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

@@ -0,0 +1,64 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Blueprint } from '@dxos/blueprints';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { QueueService } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+
+import { Project } from '../../../types';
+
+export const ProjectRules = Operation.make({
+  meta: {
+    key: 'org.dxos.function.project-wizard.project-rules',
+    name: 'Project rules',
+    description: 'Gets the rules for creating a project.',
+  },
+  input: Schema.Struct({}),
+  output: Schema.String,
+});
+
+export const CreateProject = Operation.make({
+  meta: {
+    key: 'org.dxos.function.project-wizard.create-project',
+    name: 'Create project',
+    description: 'Creates a new project.',
+  },
+  input: 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.',
+    }),
+  }),
+  output: Project.Project,
+  services: [Blueprint.RegistryService, Database.Service, QueueService, Feed.FeedService],
+});
+
+export const SyncTriggers = Operation.make({
+  meta: {
+    key: 'org.dxos.function.project.sync-triggers',
+    name: 'Sync triggers',
+    description:
+      'Synchronizes triggers in the database with the project subscriptions. Call this after editing the subscriptions array.',
+  },
+  input: Schema.Struct({
+    project: Ref.Ref(Project.Project).annotations({
+      description: 'The project whose triggers should be synced.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});

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

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const ProjectWizardHandlers = OperationHandlerSet.lazy(
+  () => import('./create-project'),
+  () => import('./project-rules'),
+  () => import('./sync-triggers'),
+);

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

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+import { ProjectRules } from './definitions';
+
+export default ProjectRules.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      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] from the Blueprint Manager to query for available blueprints and their keys.
+        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>
+      `;
+    }),
+  ),
+);