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

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

@@ -0,0 +1,75 @@
+//
+// 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,
+  type ContextBinding,
+} from '@dxos/assistant';
+import { Database, Feed, Obj } from '@dxos/echo';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { type Message } from '@dxos/types';
+
+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 queueDxn = Feed.getQueueDxn(chatFeed);
+        invariant(queueDxn, 'Feed queue DXN not found.');
+        const chatQueue = yield* QueueService.getQueue<Message.Message | ContextBinding>(queueDxn);
+        const conversation = yield* acquireReleaseResource(() => new AiConversation({ queue: chatQueue }));
+
+        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.provide(functionInvocationServiceFromOperations),
+        ),
+      ),
+    ),
+  ),
+  Operation.opaqueHandler,
+);

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

@@ -0,0 +1,91 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiService, GenericToolkit } from '@dxos/ai';
+import { AiContextService } from '@dxos/assistant';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { QueueService, TracingService, TriggerEvent } from '@dxos/functions';
+import { Operation } 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,
+    // @deprecated TracingService kept for backward compat with tool handlers.
+    TracingService,
+    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 { GetContext } from './definitions';
+import { Plan, Project } from '../../../types';
+
+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 { Qualifier } from './definitions';
+import { Plan, Project } from '../../../types';
+
+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,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as ProjectBlueprint } from './blueprint';
+export { Agent, Qualifier, GetContext, AddArtifact, ProjectHandlers } from './functions';
+export { syncProjectTriggers } from './sync-triggers';

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

@@ -0,0 +1,149 @@
+//
+// 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, Qualifier } from './functions/definitions';
+import { Project } from '../../types';
+
+/**
+ * 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(Operation.serialize(project.useQualifyingAgent ? Qualifier : 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(Operation.serialize(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,43 @@
+//
+// 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 } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.project-wizard';
+
+/**
+ * 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.',
+    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.
+
+        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] }),
+  });
+
+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 { CreateProject } from './definitions';
+import { Project } from '../../../types';
+import { ProjectBlueprint, syncProjectTriggers } from '../../project';
+
+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* syncProjectTriggers(project);
+      return project;
+    }),
+  ),
+);

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

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Blueprint } from '@dxos/blueprints';
+import { Database, 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],
+});

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

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