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

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

@@ -3,70 +3,67 @@
 //
 
 import * as Effect from 'effect/Effect';
-import * as Schema from 'effect/Schema';
+import * as Layer from 'effect/Layer';
 
 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 { AiSession, ToolExecutionServices } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Feed, Obj } from '@dxos/echo';
 import { acquireReleaseResource } from '@dxos/effect';
-import { TriggerEvent, defineFunction } from '@dxos/functions';
 import { invariant } from '@dxos/invariant';
-import { type Message } from '@dxos/types';
+import { ContentBlock } from '@dxos/types';
 
-import { Project } from '../../../types';
+import { Agent } from '../../../types';
+import { AgentWorker } from './definitions';
 
-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.');
+export default AgentWorker.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ agent: agentRef, prompt, event }) {
+      const agent = yield* Database.load(agentRef).pipe(
+        Effect.catchTag('ObjectNotFoundError', () => Effect.die(new Error('Unable to load agent object.'))),
+      );
+      invariant(Obj.instanceOf(Agent.Agent, agent));
+      invariant(agent.chat, 'Agent has no chat.');
 
-      const chatQueue = yield* project.chat.pipe(
+      const chatFeed = yield* agent.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> }),
+        Effect.flatMap((chat) => Database.load(chat.feed)),
+        Effect.catchTag('ObjectNotFoundError', () => Effect.die(new Error('Unable to load agent chat feed object.'))),
       );
+      invariant(chatFeed, 'Agent chat feed not found.');
+      const runtime = yield* Effect.runtime<Feed.FeedService>();
+      const session = yield* acquireReleaseResource(() => new AiSession({ 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);
+      const agentsInContext = session.context.getObjects().filter(Obj.instanceOf(Agent.Agent));
+      if (agentsInContext.length !== 1) {
+        throw new Error('There should be exactly one agent in context. Got: ' + agentsInContext.length);
       }
 
-      if (!data.prompt && !data.event) {
+      if (!prompt && !event) {
         throw new Error('Either prompt or event must be provided.');
       }
 
-      let input = '';
-      if (data.prompt) {
-        input += `${data.prompt}\n\n`;
+      let input: ContentBlock.Any[] = [];
+      if (prompt) {
+        input.push({ _tag: 'text', text: prompt, disposition: 'synthetic' });
       }
-      if (data.event) {
-        input += `<event>\n${JSON.stringify(data.event, null, 2)}\n</event>\n\n`;
+      if (event) {
+        input.push({ _tag: 'text', text: JSON.stringify(event), disposition: 'synthetic' });
       }
 
-      yield* conversation
+      yield* session
         .createRequest({
           prompt: input,
         })
-        .pipe(Effect.retry({ times: 2 }));
-    },
-    Effect.scoped,
-    Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
-    AiContextService.fixFunctionHandlerType,
-  ) as any,
-});
+        .pipe(
+          Effect.provide(
+            Layer.mergeAll(AiService.model('@anthropic/claude-opus-4-6'), ToolExecutionServices).pipe(
+              Layer.provideMerge(Operation.withInvocationOptions({ conversation: Obj.getDXN(chatFeed).toString() })),
+            ),
+          ),
+          Effect.retry({ times: 2 }),
+        );
+    }, Effect.scoped),
+  ),
+  Operation.opaqueHandler,
+);

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

@@ -0,0 +1,92 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiService, OpaqueToolkit } from '@dxos/ai';
+import { AiContextService } from '@dxos/assistant';
+import { Trace, TriggerEvent, Operation, OperationRegistry } from '@dxos/compute';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { QueueService } from '@dxos/functions';
+
+import { Agent } from '../../../types';
+
+export const AgentWorker = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent.worker',
+    name: 'Agent Worker',
+    description: 'Agentic worker that drives the agent autonomously.',
+  },
+  input: Schema.Struct({
+    agent: Schema.suspend(() => Ref.Ref(Agent.Agent)),
+    prompt: Schema.optional(Schema.String),
+    event: Schema.optional(TriggerEvent.TriggerEvent),
+  }),
+  output: Schema.Void,
+  services: [
+    AiService.AiService,
+    Database.Service,
+    QueueService,
+    Feed.FeedService,
+    OperationRegistry.Service,
+    Trace.TraceService,
+    OpaqueToolkit.OpaqueToolkitProvider,
+  ],
+}).pipe(Operation.intrinsic);
+
+export const Qualifier = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent.qualifier',
+    name: 'Agent Qualifier',
+    description:
+      'Qualifier that determines if the event is relevant to the agent. Puts the data into the input queue of the agent.',
+  },
+  input: Schema.Struct({
+    agent: Schema.suspend(() => Ref.Ref(Agent.Agent)),
+    event: TriggerEvent.TriggerEvent,
+  }),
+  output: Schema.Void,
+  services: [AiService.AiService, Database.Service],
+}).pipe(Operation.intrinsic);
+
+export const GetContext = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent.get-context',
+    name: 'Get Agent Context',
+    description: 'Get the context of an agent.',
+  },
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    instructions: 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],
+}).pipe(Operation.intrinsic);
+
+export const AddArtifact = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent.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],
+}).pipe(Operation.intrinsic);

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

@@ -3,61 +3,44 @@
 //
 
 import * as Effect from 'effect/Effect';
-import * as Schema from 'effect/Schema';
 
-import { AiContextService } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
 import { Database, Obj } from '@dxos/echo';
-import { defineFunction } from '@dxos/functions';
 
-import { Plan, Project } from '../../../types';
+import { Plan, Agent } from '../../../types';
+import { GetContext } from './definitions';
 
-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;
+export default GetContext.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const agent = yield* Agent.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),
-});
+      return {
+        id: agent.id,
+        name: agent.name,
+        instructions: yield* agent.instructions.pipe(Database.load).pipe(
+          Effect.map((_) => _.content),
+          Effect.catchTag('ObjectNotFoundError', () => Effect.succeed('No instructions found.')),
+        ),
+        plan: yield* (
+          agent.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(agent.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

@@ -2,14 +2,13 @@
 // 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';
+import { OperationHandlerSet } from '@dxos/compute';
 
-export const ProjectFunctions = {
-  AddArtifact,
-  Agent,
-  GetContext,
-  Qualifier,
-};
+export * from './definitions';
+
+export const AgentBlueprintHandlers = OperationHandlerSet.lazy(
+  () => import('./add-artifact'),
+  () => import('./agent'),
+  () => import('./get-context'),
+  () => import('./qualifier'),
+);

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

@@ -8,89 +8,83 @@ import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
 import { AiService } from '@dxos/ai';
+import { Operation } from '@dxos/compute';
 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';
+import { Plan, Agent } from '../../../types';
+import { Qualifier } from './definitions';
 
-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.');
+export default Qualifier.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(
+      function* ({ agent: agentRef, event }) {
+        const agent = yield* Database.load(agentRef);
+        invariant(Obj.instanceOf(Agent.Agent, agent));
+        invariant(agent.chat, 'Agent has no chat.');
 
-      const { id, name, queue } = project;
-      if (!queue) {
-        throw new Error('Project has no queue.');
-      }
+        const { id, name, queue } = agent;
+        if (!queue) {
+          throw new Error('Agent has no queue.');
+        }
 
-      const plan = yield* Database.load(project.plan);
-      const spec = yield* Database.load(project.spec);
+        const plan = yield* Database.load(agent.plan);
+        const instructions = yield* Database.load(agent.instructions);
 
-      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>
+        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 agent.
+                  Respond with true if the event is relevant to the agent, false otherwise.
+                  If you are not sure, return true.
+                  The qualified events will be forwarded to the larger agent that will process them.
+                  <agent id="${id}" name="${name}">
+                    <instructions>
+                    ${instructions.content}
+                    </instructions>
+                    <plan>
+                      ${Plan.formatPlan(plan)}
+                    </plan>
+                  </agent>
                 `,
               }),
-            ],
+              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 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.');
+        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.scoped,
-    Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
+      },
+      Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
+    ),
   ),
-});
+);

package/src/blueprints/project/index.ts

@@ -2,5 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-export { default as ProjectBlueprint } from './blueprint';
-export { ProjectFunctions } from './functions';
+export { default as AgentBlueprint } from './blueprint';
+export { AgentWorker, Qualifier, GetContext, AddArtifact, AgentBlueprintHandlers } from './functions';

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

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Blueprint, Template } from '@dxos/compute';
+import { trim } from '@dxos/util';
+
+import { AgentRules, CreateAgent, SyncTriggers } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.agent-wizard';
+
+/**
+ * Creates the Agent Wizard blueprint. This is a function to avoid circular dependency issues.
+ */
+// TODO(dmaretskyi): Combine with Agent Blueprint.
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Agent Wizard',
+    description: 'Help the user create a new agent (subscriptions, optional cron timer, sync-triggers after edits).',
+    agentCanEnable: true,
+    instructions: Template.make({
+      source: trim`
+        You are a wizard that helps the user create a new agent.
+
+        Agents are goal oriented and autonomously driven.
+        Each agent has instructions - the goal of the agent.
+        The instructions also typically describe what actions to perform in reaction to events (emails).
+        The agent has a number of associated artifacts to work with.
+        Agents can subscribe to emails.
+
+        Agents have a \`cron\` field: when set, the agent runs on a timer on that schedule (standard cron syntax).
+        Use \`cron\` when the user wants the agent to run periodically (e.g. "every morning", "once a day", "every 5 minutes").
+        Examples: \`0 9 * * *\` for daily at 09:00, or \`*/5 * * * *\` for every 5 minutes.
+        Timer triggers bypass the qualifier and invoke the agent worker directly on the schedule.
+
+        The agent itself is an ECHO object and can be edited like any other object using the database blueprint.
+        You can edit the agent's instructions, name, and other properties directly.
+        If you edit the agent's \`enabled\` field, \`filterEvents\` field, subscriptions array, or \`cron\` field, you MUST call the sync-triggers function afterward to synchronize the triggers (\`enabled\` is applied to all triggers).
+
+        IMPORTANT: Before attempting to create an agent call the [agent-rules] tool to get the rules for creating an agent.
+      `,
+    }),
+    tools: Blueprint.toolDefinitions({ operations: [AgentRules, CreateAgent, SyncTriggers] }),
+  });
+
+const blueprint: Blueprint.Definition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

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

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

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

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Blueprint, Operation } from '@dxos/compute';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { QueueService } from '@dxos/functions';
+
+import { Agent } from '../../../types';
+
+export const AgentRules = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent-wizard.agent-rules',
+    name: 'Agent rules',
+    description: 'Gets the rules for creating an agent.',
+  },
+  input: Schema.Struct({}),
+  output: Schema.String,
+});
+
+export const CreateAgent = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent-wizard.create-agent',
+    name: 'Create agent',
+    description: 'Creates a new agent.',
+  },
+  input: Schema.Struct({
+    name: Schema.String.annotations({
+      description: 'The name of the agent to create.',
+    }),
+    instructions: Schema.String.annotations({
+      description:
+        'The goal of the agent. Be specific but not too verbose. The agent will use this as a core objective and set of rules to follow.',
+    }),
+    blueprints: Schema.Array(Schema.String).annotations({
+      description: 'The blueprint keys to use for the agent.',
+      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 agent. Can be references to mailboxes.',
+    }),
+  }),
+  output: Agent.Agent,
+  services: [Blueprint.RegistryService, Database.Service, QueueService, Feed.FeedService],
+});
+
+export const SyncTriggers = Operation.make({
+  meta: {
+    key: 'org.dxos.function.agent.sync-triggers',
+    name: 'Sync triggers',
+    description:
+      'Synchronizes triggers with the agent: subscriptions, cron, filter-events, and enabled (copied to every trigger). Call after editing those fields.',
+  },
+  input: Schema.Struct({
+    agent: Ref.Ref(Agent.Agent).annotations({
+      description: 'The agent 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/compute';
+
+export * from './definitions';
+
+export const AgentWizardHandlers = OperationHandlerSet.lazy(
+  () => import('./create-project'),
+  () => import('./project-rules'),
+  () => import('./sync-triggers'),
+);